yatex
view docs/yatexe.tex @ 126:91bf68eeefe8
Add documentation for latex+p(D)f and YaTeX-dvipdf-command.
| author | yuuji@gentei.org |
|---|---|
| date | Thu, 27 May 2010 10:34:34 +0900 |
| parents | e1693ffc64cc |
| children | 8703f090c628 |
line source
1 \def\lang{jp} % -*- texinfo -*-
2 \input texinfo.tex
3 @setfilename yatexe
4 @settitle Yet Another tex-mode for Emacs
6 @iftex
7 @c @syncodeindex fn cp
8 @c Last modified Thu May 27 10:33:22 2010 on firestorm
9 @syncodeindex vr cp
10 @end iftex
12 @titlepage
13 @sp 10
14 @center
15 @subtitle Yet Another tex-mode for emacs
16 @title Wild Bird
17 @subtitle // YaTeX //
18 @author @copyright{} 1991-2003 by HIROSE, Yuuji [yuuji@@yatex.org]
19 @end titlepage
21 @node Top, What is YaTeX?, (dir), (dir)
22 @comment node-name, next, previous, up
23 @cindex Demacs
24 @cindex Mule
25 @cindex LaTeX
26 @cindex YaTeX
28 @menu
29 * What is YaTeX?::
30 * Main features:: What YaTeX can do
31 * Installation:: Guide to install
32 * Typesetting:: Call typesetting processes
33 * %#notation:: Meta-keyword `%#'
34 * Completion:: Input LaTeX commands with completion
35 * Local dictionaries:: Directory dependent completion
36 * Commenting out:: Commenting/uncommenting text
37 * Cursor jump:: Jumping to related position
38 * Changing and Deleting:: Changing/deleting certain unit of text
39 * Filling:: Filling an item or paragraph
40 * Updation of includeonly:: Free from maintaining includeonly
41 * What column:: Check what table-column the cursor belong
42 * Intelligent newline:: Guess requisites of new line
43 * Usepackage checker:: Selecting correct \usepackage is YaTeX's job
44 * Online help:: On-line documentation of LaTeX
45 * Browsing file hierarchy:: Walking through file hierarchy
46 * Cooperation with other packages:: Work well with gmhist, min-out
47 * Customizations:: How to breed `Wild Bird'
48 * Etcetera:: YaTeX is acquisitive.
49 * Copying:: Redistribution
52 @node What is YaTeX?, Main features, Top, Top
53 @comment node-name, next, previous, up
54 @chapter What is YaTeX?
56 YaTeX automates typesetting and previewing of LaTeX and enables
57 completing input of LaTeX mark-up command such as
58 @code{\begin@{@}}..@code{\end@{@}}.
60 YaTeX also supports Demacs which runs on MS-DOS(386), Mule (Multi
61 Language Enhancement to GNU Emacs), and latex on DOS.
63 @node Main features, Installation, What is YaTeX?, Top
64 @comment node-name, next, previous, up
65 @chapter Main features
67 @itemize
68 @item Invocation of typesetter, previewer and related programs(@kbd{C-c t})
69 @item Typesetting on static region which is independent from point
70 @item Semiautomatic replacing of @code{\includeonly}
71 @item Jumping to error line(@kbd{C-c '})
72 @item Completing-read of La@TeX{} commands such as @code{\begin@{@}},
73 @code{\section} etc.
74 (@kbd{C-c b}, @kbd{C-c s}, @kbd{C-c l}, @kbd{C-c m})
75 @item Enclosing text into La@TeX{} environments or commands
76 (@kbd{C-u} @var{AboveKeyStrokes})
77 @item Displaying the structure of text at entering sectioning commands
78 @item Lump shifting of sectioning commands (@ref{view-sectioning})
79 @item Learning unknown/new La@TeX{} commands for the next completion
80 @item Argument reading with a guide for complicated La@TeX{} commands
81 @item Generating argument-readers for new/unsupported commands(@file{yatexgen})
82 @item Quick changing or deleting of La@TeX{} commands(@kbd{C-c c}, @kbd{C-c k})
83 @item Jumping from and to inter-file, begin<->end, ref<->label(@kbd{C-c g})
84 @item Blanket commenting out or uncommenting
85 (@kbd{C-c >}, @kbd{C-c <}, @kbd{C-c ,}, @kbd{C-c .})
86 @item Easy input of accent mark, math-mode's commands and Greek letters
87 (@kbd{C-c a}, @kbd{;}, @kbd{:})
88 @item Online help for the popular La@TeX{} commands
89 (@kbd{C-c ?}, @kbd{C-c /})
90 @item Document files hierarchy browser (@kbd{C-c d})
91 @item Adding automatically \usepackage corresponding to inputting LaTeX
92 macro with completion
93 @item Allow you to forget creating \label{}s, \ref or \cite completion
94 automatically generate labels.
95 @end itemize
97 @node Installation, Typesetting, Main features, Top
98 @comment node-name, next, previous, up
99 @chapter Installation
100 @cindex installation
101 @cindex .emacs
102 @cindex auto-mode-alist
103 @cindex autoload
105 Put next two expressions into your @file{~/.emacs}.
107 @lisp
108 (setq auto-mode-alist
109 (cons (cons "\\.tex$" 'yatex-mode) auto-mode-alist))
110 (autoload 'yatex-mode "yatex" "Yet Another La@TeX{} mode" t)
111 @end lisp
113 Next, add certain path name where you put files of YaTeX to your
114 load-path. If you want to put them in @file{~/src/emacs}, write
116 @lisp
117 (setq load-path
118 (cons (expand-file-name "~/src/emacs") load-path))
119 @end lisp
121 @noindent
122 in your @file{~/.emacs}
124 Then, yatex-mode will be automatically loaded when you visit a
125 file which has extension @file{.tex}. If yatex-mode is successfully
126 loaded, mode string on mode line will be turned to "YaTeX".
129 @node Typesetting, %#notation, Installation, Top
130 @comment node-name, next, previous, up
131 @chapter Typesetting
132 @cindex typesetting
133 @cindex previewer
134 @cindex typesetter
135 @cindex latex
136 @cindex printing out
138 The prefix key stroke of yatex-mode is @kbd{C-c} (Press 'C' with Control
139 key) by default. If you don't intend to change the prefix key stroke,
140 assume all @kbd{[prefix]} as @kbd{C-c} in this document. These key
141 strokes execute typeset or preview command.
143 @table @kbd
144 @item [prefix] t j
145 @dots{} invoke latex
146 @item [prefix] t r
147 @dots{} invoke latex on region
148 @item [prefix] t k
149 @dots{} kill current typesetting process
150 @item [prefix] t b
151 @dots{} invoke bibtex
152 @item [prefix] t i
153 @dots{} invoke makeindex
154 @item [prefix] t d
155 @dots{} invoke latex && dvipdfmx
156 @item [prefix] t p
157 @dots{} preview
158 @item [prefix] t l
159 @dots{} lpr dvi-file
160 @item [prefix] t s
161 @dots{} search current string on xdvi-remote
162 @end table
164 @menu
165 * Calling typesetter::
166 * Calling previewer::
167 * Printing out::
168 @end menu
170 @node Calling typesetter, Calling previewer, Typesetting, Typesetting
171 @comment node-name, next, previous, up
172 @section Calling typesetter
174 Typing @kbd{[prefix] t j}, the current editing window will be divided
175 horizontally when you invoke latex command, and log message of La@TeX{}
176 typesetting will be displayed in the other window; called typesetting
177 buffer. The typesetting buffer automatically scrolls up and traces
178 La@TeX{} warnings and error messages. If you see latex stopping by an
179 error, you can send string to latex in the typesetting buffer.
181 If an error stops the La@TeX{} typesetting, this key stroke will
182 move the cursor to the line where La@TeX{} error is detected.
184 @table @kbd
185 @item [prefix] '
186 @itemx ([prefix]+single quotation)
188 @dots{} jump to the previous error or warning
189 @end table
191 If you find a noticeable error, move to the typesetting buffer and move
192 the cursor on the line of error message and type @kbd{SPACE} key. This
193 makes the cursor move to corresponding source line.
195 Since @kbd{[prefix] tr} pastes the region into the file
196 @file{texput.tex} in the current directory, you should be careful of
197 overwriting. The method of specification of the region is shown in the
198 section @xref{%#notation}.
200 The documentclass for typeset-region is the same as that of editing
201 file if you edit one file, and is the same as main file's if you
202 edit splitting files.
204 @node Calling previewer, Printing out, Calling typesetter, Typesetting
205 @comment node-name, next, previous, up
206 @section Calling previewer
208 @kbd{[prefix] t p} invokes the TeX previewer. And if you are using
209 xdvi-remote, which can be controled from other terminals, @kbd{[prefix] t
210 s} enables you to search current string at the cursor on the running xdvi
211 window.
213 @node Printing out, , Calling previewer, Typesetting
214 @comment node-name, next, previous, up
215 @section Printing out
217 When you type @code{[preifx] t l}, YaTeX asks you the range of
218 dvi-printing by default. You can skip this by invoking it with
219 universal-argument as follows:
221 @example
222 C-u [prefix] tl
223 @end example
225 @node %#notation, Completion, Typesetting, Top
226 @comment node-name, next, previous, up
227 @chapter %# notation
228 @cindex %# notation
230 You can control the typesetting process by describing @code{%#}
231 notations in the source text.
233 @menu
234 * Changing typesetter::
235 * Splitting input files::
236 * Static region for typesetting::
237 * Lpr format::
238 * Editing %# notation::
239 @end menu
241 @node Changing typesetter, Splitting input files, %#notation, %#notation
242 @comment node-name, next, previous, up
243 @section To change the `latex' command or to split a source text.
244 @cindex typesetter
246 To change the typesetting command, write
248 @example
249 %#!latex-big
250 @end example
252 @noindent
253 anywhere in the source text. This is useful for changing
254 typesetter.
256 @node Splitting input files, Static region for typesetting, Changing typesetter, %#notation
257 @comment node-name, next, previous, up
258 @section Splitting input files
260 And if you split the source text and
261 edit subfile that should be included from main text.
263 @example
264 %#!latex main.tex
265 @end example
267 @noindent
268 will be helpful to execute latex on main file from sub text buffer. Since
269 this command line after @kbd{%#!} will be sent to shell literally, next
270 description makes it convenient to use ghostview as dvi-previewer.
272 @example
273 %#!latex main ; dvi2ps main.dvi > main
274 @end example
276 @noindent
277 Note that YaTeX assumes the component before the last period of
278 the last word in this line as base name of the main La@TeX{} source.
279 The @code{%f} notation in this line is replaced by main file name, and
280 @code{%r} replaced by root name of main file name. If you specify
281 @code{%f} or @code{%r}, YaTeX always ask you the name of main file at the
282 first typesetting.
284 To make best use of the feature of inter-file jumping by
285 @kbd{[prefix] g} (see @ref{Cursor jump}), take described below into
286 consideration.
288 @itemize
289 @item You can put split texts in sub directory, but not in
290 sub directory of sub directory.
291 @item In the main text, specify the child file name with relative path name
292 such as \include@{chap1/sub@}, when you include the file in
293 a sub-directory.
294 @item In a sub-text, write @code{%#!latex main.tex} even if @file{main.tex}
295 is in the parent directory(not %#!latex ../main.tex).
296 @end itemize
298 @node Static region for typesetting, Lpr format, Splitting input files, %#notation
299 @comment node-name, next, previous, up
300 @section Static region
301 @cindex static region
302 @cindex Fixed region
304 Typeset-region by @kbd{[prefix] tr} passes the region between point and
305 mark to typesetting command by default. But when you want to typeset
306 static region, enclose the region by @code{%#BEGIN} and @code{%#END} as
307 follows.
309 @example
310 %#BEGIN
311 TheRegionYouWantToTypesetManyTimes
312 %#END
313 @end example
315 This is the rule of deciding the region.
317 @enumerate
318 @item
319 If there exists %#BEGIN before point,
321 @enumerate
322 @item
323 If there exists %#END after %#BEGIN,
324 @itemize
325 @item From %#BEGIN to %#END.
326 @end itemize
328 @item
329 If %#END does not exist after %#BEGIN,
330 @itemize
331 @item From %#BEGIN to the end of buffer.
332 @end itemize
333 @end enumerate
335 @item
336 If there does not exist %#BEGIN before point,
337 @itemize
338 @item Between point and mark(standard method of Emacs).
339 @end itemize
340 @end enumerate
342 It is useful to write @code{%#BEGIN} in the previous line of \begin and
343 @code{%#END} in the next line of \@code{end} when you try complex
344 environment such as `tabular' many times. It is also useful to put only
345 @code{%#BEGIN} alone at the middle of very long text. Do not forget to
346 erase @code{%#BEGIN} @code{%#END} pair.
348 @node Lpr format, Editing %# notation, Static region for typesetting, %#notation
349 @comment node-name, next, previous, up
350 @section Lpr format
351 @cindex lpr format
353 Lpr format is specified by three Lisp variables. Here are the
354 default values of them.
356 @table @code
357 @item (1)dviprint-command-format
358 @code{"dvi2ps %f %t %s | lpr"}
359 @item (2)dviprint-from-format
360 @code{"-f %b"}
361 @item (3)dviprint-to-format
362 @code{"-t %e"}
363 @end table
365 On YaTeX-lpr, @code{%s} in (1) is replaced by the file name of main
366 text, @code{%f} by contents of (2), %t by contents of (3). At these
367 replacements, @code{%b} in (2) is also replaced by the number of beginning
368 page, @code{%e} in (3) is replaced by the number of ending page. But
369 @code{%f} and @code{%t} are ignored when you omit the range of print-out
370 by @kbd{C-u [prefix] tl}.
372 If you want to change this lpr format temporarily, put a command
373 such as follows somewhere in the text:
375 @example
376 %#LPR dvi2ps %f %t %s | 4up -page 4 | texfix | lpr -Plp2
377 @end example
379 And if you want YaTeX not to ask you the range of printing
380 out, the next example may be helpful.
382 @example
383 %#LPR dvi2ps %s | lpr
384 @end example
386 @node Editing %# notation, , Lpr format, %#notation
387 @comment node-name, next, previous, up
388 @section Editing %# notation
390 To edit @code{%#} notation described above, type
392 @table @kbd
393 @item [prefix] %
394 @dots{} editing %# notation menu
395 @end table
397 @noindent
398 and select one of the entry of the menu as follows.
400 @example
401 !)Edit-%#! B)EGIN-END-region L)Edit-%#LPR
402 @end example
404 @noindent
405 Type @kbd{!} to edit @code{%#!} entry, @code{b} to enclose the region with
406 @code{%#BEGIN} and @code{%#END}, and @code{l} to edit @code{%#LPR} entry.
407 When you type @kbd{b}, all @code{%#BEGIN} and @code{%#END} are
408 automatically erased.
410 @node Completion, Local dictionaries, %#notation, Top
411 @comment node-name, next, previous, up
412 @chapter Completion
413 @cindex completion
415 YaTeX makes it easy to input the La@TeX{} commands. There are several
416 kinds of completion type, begin-type, section-type, large-type, etc...
418 @menu
419 * Begin-type completion::
420 * Section-type completion::
421 * Large-type completion::
422 * Maketitle-type completion::
423 * Arbitrary completion::
424 * End completion::
425 * Accent completion::
426 * Image completion::
427 * Greek letters completion::
428 @end menu
430 @node Begin-type completion, Section-type completion, Completion, Completion
431 @comment node-name, next, previous, up
432 @section Begin-type completion
433 @cindex begin-type completion
434 @cindex environment
435 @cindex prefix b
437 "Begin-type completion" completes commands of @code{\begin@{env@}} ...
438 @code{\end@{env@}}. All of the begin-type completions begin with this key
439 sequence.
441 @table @kbd
442 @item [prefix] b
443 @dots{} start begin-type completion
444 @end table
446 @noindent
447 An additional key stroke immediately completes a frequently used
448 La@TeX{} @code{\begin@{@}}...@code{\@code{end}@{@}} environment.
450 @table @kbd
451 @item [prefix] b c
452 @dots{} @code{\begin@{center@}...\end@{center@}}
453 @item [prefix] b d
454 @dots{} @code{\begin@{document@}...\end@{document@}}
455 @item [prefix] b D
456 @dots{} @code{\begin@{description@}...\end@{description@}}
457 @item [prefix] b e
458 @dots{} @code{\begin@{enumerate@}...\end@{enumerate@}}
459 @item [prefix] b E
460 @dots{} @code{\begin@{equation@}...\end@{equation@}}
461 @item [prefix] b i
462 @dots{} @code{\begin@{itemize@}...\end@{itemize@}}
463 @item [prefix] b l
464 @dots{} @code{\begin@{flushleft@}...\end@{flushleft@}}
465 @item [prefix] b m
466 @dots{} @code{\begin@{minipage@}...\end@{minipage@}}
467 @item [prefix] b t
468 @dots{} @code{\begin@{tabbing@}...\end@{tabbing@}}
469 @item [prefix] b T
470 @dots{} @code{\begin@{tabular@}...\end@{tabular@}}
471 @item [prefix] b^T
472 @dots{} @code{\begin@{table@}...\end@{table@}}
473 @item [prefix] b p
474 @dots{} @code{\begin@{picture@}...\end@{picture@}}
475 @item [prefix] b q
476 @dots{} @code{\begin@{quote@}...\end@{quote@}}
477 @item [prefix] b Q
478 @dots{} @code{\begin@{quotation@}...\end@{quotation@}}
479 @item [prefix] b r
480 @dots{} @code{\begin@{flushright@}...\end@{flushright@}}
481 @item [prefix] b v
482 @dots{} @code{\begin@{verbatim@}...\end@{verbatim@}}
483 @item [prefix] b V
484 @dots{} @code{\begin@{verse@}...\end@{verse@}}
485 @end table
487 Any other La@TeX{} environments are made by completing-read of the
488 Emacs function.
490 @table @kbd
491 @item [prefix] b SPACE
492 @dots{} begin-type completion
493 @end table
495 @noindent
496 The next message will show up in the minibuffer
498 @example
499 Begin environment(default document):
500 @end example
502 @noindent
503 by typing @kbd{[prefix] b}. Put the wishing environment with completion
504 in the minibuffer, and @code{\begin@{env@}}...\@code{\end@{env@}} will be
505 inserted in the La@TeX{} source text. If the environment you want to put
506 does not exist in the YaTeX completion table, it will be registered in the
507 user completion table. YaTeX automatically saves the user completion
508 table in the user dictionary file at exiting of emacs.
510 At the completion of certain environments, the expected initial entry will
511 automatically inserted such as @code{\item} for @code{itemize}
512 environment. If you don't want the entry, it can be removed by undoing.
514 If you want to enclose some paragraphs which have already been
515 written, invoke the begin-type completion with changing the case
516 of @kbd{b} of key sequence upper(or invoke it with universal argument
517 by @kbd{C-u} prefix).
518 @cindex enclose region into environment
520 The following example encloses a region with `description'
521 environment.
523 @table @kbd
524 @item [prefix] B D
525 @itemx (or ESC 1 [prefix] b D)
526 @itemx (or C-u [prefix] b D)
528 @dots{} begin-type completion for region
529 @end table
531 This enclosing holds good for the completing input by @kbd{[prefix] b
532 SPC}. @kbd{[prefix] B SPC} enclose a region with the environment selected
533 by completing-read.
535 @node Section-type completion, Large-type completion, Begin-type completion, Completion
536 @comment node-name, next, previous, up
537 @section Section-type completion
538 @cindex section-type completion
539 @cindex prefix s
541 "Section-type completion" completes section-type commands which take an
542 argument or more such as @code{\section@{foo@}}. To invoke section-type
543 completion, type
545 @table @kbd
546 @item [prefix] s
547 @dots{} section-type completion
548 @end table
550 @noindent
551 then the prompt
553 @example
554 (C-v for view) \???@{@} (default documentclass):
555 @end example
557 @noindent
558 will show up in the minibuffer. Section-type La@TeX{} commands are
559 completed by space key, and the default value is selected when you
560 type nothing in the minibuffer.
562 Next,
564 @example
565 \section@{???@}:
566 @end example
568 @noindent
569 prompts you the argument of section-type La@TeX{} command. For
570 example, the following inputs
572 @example
573 \???@{@} (default documentclass): section
574 \section@{???@}: Hello world.
575 @end example
577 @noindent
578 will insert the string
580 @example
581 \section@{Hello world.@}
582 @end example
584 in your La@TeX{} source. When you neglect argument such as
586 @example
587 (C-v for view) \???@{@} (default section): vspace*
588 \vspace*@{???@}:
589 @end example
591 YaTeX puts
593 @example
594 \vspace*@{@}
595 @end example
597 @noindent
598 and move the cursor in the braces.
600 In La@TeX{} command, there are commands which take more than one
601 arguments such as @code{\addtolength@{\topmargin@}@{8mm@}}. To complete these
602 commands, invoke section-type completion with universal argument as,
603 @cindex number of argument
605 @example
606 C-u 2 [prefix] s (or ESC 2 [prefix] s)
607 @end example
609 @noindent
610 and make answers in minibuffer like this.
612 @example
613 (C-v for view) \???@{@} (default vspace*): addtolength
614 \addtolength@{???@}: \topmargin
615 Argument 2: 8mm
616 @end example
618 @code{\addtolength} and the first argument @code{\topmargin} can be typed
619 easily by completing read. Since YaTeX also learns the number of
620 arguments of section-type command and will ask that many arguments in
621 future completion, you had better tell the number of arguments to YaTeX at
622 the first completion of the new word. But you can change the number of
623 arguments by calling the completion with different universal argument
624 again.
627 Invoking section-type completion with @code{[Prefix] S} (Capital `S')
628 includes the region as the first argument of section-type command.
630 The section/large/maketitle type completion can work at the
631 prompt for the argument of other section-type completion.
632 Nested La@TeX{} commands are efficiently read with the recursive
633 completion by typing YaTeX's completion key sequence in the
634 minibuffer.
636 @menu
637 * view-sectioning::
638 @end menu
640 @node view-sectioning, , Section-type completion, Section-type completion
641 @comment node-name, next, previous, up
642 @subsection view-sectioning
643 @cindex view sectioning
644 @cindex outline
646 In the minibuffer at the prompt of section-type command completion,
647 typing @kbd{C-v} shows a list of sectioning commands in source text(The
648 line with @code{<<--} mark is the nearest sectioning command). Then,
649 default sectioning command appears in the minibuffer. You can go up/down
650 sectioning command by typing @kbd{C-p}/@kbd{C-n}, can scrolls up/down the
651 listing buffer by @kbd{C-v}/@kbd{M-v}, and can hide sectioning commands
652 under certain level by 0 through 6. Type @kbd{?} in the minibuffer of
653 sectioning prompt for more information.
655 You can generate this listing buffer (@code{*Sectioning Lines*} buffer)
656 by typing
657 @table @kbd
658 @item M-x YaTeX-section-overview
659 @dots{} Generate *Sectioning Lines* buffer
660 @end table
661 @cindex{Generate the listing of sectioning units}
662 from the LaTeX source buffer. In this listing buffer, typing @kbd{u} on
663 the sectioning command shifts up the corresponding sectioning command in
664 source text and @kbd{d} shifts down. After marking lines in the listing
665 buffer, typing @kbd{U} shifts up all sectioning commands in the region,
666 and @kbd{U} shifts down. Here are all the key bindings of
667 @code{*Sectioning Lines*} buffer.
669 @table @kbd
670 @item SPC
671 @dots{} Jump to corresponding source line
672 @item .
673 @dots{} Display corresponding source line
674 @item u
675 @dots{} Shift up a sectioning line
676 @item d
677 @dots{} Shift down a sectioning line
678 @item U
679 @dots{} Shift up sectioning lines in region
680 @item D
681 @dots{} Shift down sectioning lines in region
682 @item 0@dots{}6
683 @dots{} Hide sectioning commands whose level is lower than n
684 @end table
687 @node Large-type completion, Maketitle-type completion, Section-type completion, Completion
688 @comment node-name, next, previous, up
689 @section Large-type completion
691 "Large-type completion" inputs the font or size changing
692 descriptions such as @code{@{\large @}}. When you type
694 @table @kbd
695 @item [prefix] l
696 @dots{} large-type completion
697 @end table
699 @noindent
700 the message in the minibuffer
702 @example
703 @{\??? @} (default large):
704 @end example
706 prompts prompts you large-type command with completing-read. There are
707 TeX commands to change fonts or sizes, @code{it}, @code{huge} and so on,
708 in the completion table.
710 Region-based completion is also invoked by changing the letter after
711 prefix key stroke as @kbd{[prefix] L}. It encloses the region by braces
712 with large-type command.
714 @node Maketitle-type completion, Arbitrary completion, Large-type completion, Completion
715 @comment node-name, next, previous, up
716 @section Maketitle-type completion
717 @cindex maketitle-type completion
719 We call it "maketitle-type completion" which completes commands such as
720 @code{\maketitle}. Take notice that maketitle-type commands take no
721 arguments. Then, typing
723 @table @kbd
724 @item [prefix] m
725 @dots{} maketitle-type completion
726 @end table
728 @noindent
729 begins maketitle-completion. Above mentioned method is true for
730 maketitle-completion, and there are La@TeX{} commands with no
731 arguments in completion table.
733 @node Arbitrary completion, End completion, Maketitle-type completion, Completion
734 @comment node-name, next, previous, up
735 @section Arbitrary completion
736 @cindex arbitrary completion
738 @noindent
739 You can complete certain La@TeX{} command anywhere without typical
740 completing method as described, by typing
742 @table @kbd
743 @item [prefix] SPC
744 @dots{} arbitrary completion
745 @end table
747 @noindent
748 after the initial string of La@TeX{} command that is preceded by @code{\}.
750 @node End completion, Accent completion, Arbitrary completion, Completion
751 @comment node-name, next, previous, up
752 @section End completion
753 @cindex end completion
755 @noindent
756 YaTeX automatically detects the opened environment and close it with
757 \@code{\end@{environment@}}. Though proficient YaTeX users never fail to
758 make environment with begin-type completion, some may begin an environment
759 manually. In that case, type
761 @table @kbd
762 @item [prefix] e
763 @dots{} @code{end} completion
764 @end table
766 @noindent
767 at the end of the opened environment.
769 @node Accent completion, Image completion, End completion, Completion
770 @comment node-name, next, previous, up
771 @section Accent completion
772 @cindex accent completion
774 When you want to write the European accent marks(like @code{\`@{o@}}),
776 @table @kbd
777 @item [prefix] a
778 @dots{} accent completion
779 @end table
781 @noindent
782 shows the menu
784 @example
785 1:` 2:' 3:^ 4:" 5:~ 6:= 7:. u v H t c d b
786 @end example
788 @noindent
789 in the minibuffer. Chose one character or corresponding numeric,
790 and you will see
792 @example
793 \`@{@}
794 @end example
796 @noindent
797 in the editing buffer with the cursor positioned in braces. Type
798 one more character `o' for example, then
800 @example
801 \`@{o@}
802 @end example
804 @noindent
805 will be completed, and the cursor gets out from braces.
807 @node Image completion, Greek letters completion, Accent completion, Completion
808 @comment node-name, next, previous, up
809 @section Image completion of mathematical sign
810 @cindex image completion
811 @cindex math-mode
812 @cindex sigma
813 @cindex leftarrow
814 @cindex ;
816 Arrow marks, sigma mark and those signs mainly used in the
817 TeX's math environment are completed by key sequences which
818 imitate the corresponding symbols graphically. This completion
819 only works in the math environment. YaTeX automatically detects
820 whether the cursor located in math environment or not, and
821 change the behavior of key strokes @kbd{;} and @kbd{:}.
823 By the way, we often express the leftarrow mark by `<-' for example.
824 Considering such image, you can write @code{\leftarrow} by typing @kbd{<-}
825 after @kbd{;} (semicolon) as a prefix. In the same way,
826 @code{\longleftarrow} (@code{<--}) is completed by typing @kbd{;<--},
827 infinity mark which is imitated by @code{oo} is completed by typing
828 @kbd{;oo}.
830 Here are the sample operations in YaTeX math-mode.
832 @example
833 INPUT Completed La@TeX{} commands
834 ; < - @code{\leftarrow}
835 ; < - - @code{\longleftarrow}
836 ; < - - > @code{\longleftrightarrow}
837 ; o @code{\circ}
838 ; o o @code{\infty}
839 @end example
841 In any case, you can quit from image completion and can move
842 to the next editing operation if the La@TeX{} command you want is
843 shown in the buffer.
845 @code{;} itself in math-environment is inserted by @kbd{;;}. Typing
846 @kbd{TAB} in the midst of image completion shows all of the La@TeX{}
847 commands that start with the same name as string you previously typed in.
848 In this menu buffer, press @kbd{RET} after moving the cursor (by @kbd{n},
849 @kbd{p}, @kbd{b}, @kbd{f}) to insert the La@TeX{} command.
851 To know all of the completion table, type @kbd{TAB} just after @kbd{;}.
852 And here is the sample menu by @kbd{TAB} after @kbd{;<}.
854 @example
855 KEY LaTeX sequence sign
856 < \leq <
857 ~
858 << \ll <<
859 <- \leftarrow <-
860 <= \Leftarrow <=
861 @end example
863 You can define your favorite key-vs-sequence completion table in the
864 Emacs-Lisp variable @code{YaTeX-math-sign-alist-private}. See also
865 @file{yatexmth.el} for the information of the structure of this variable.
867 @node Greek letters completion, , Image completion, Completion
868 @comment node-name, next, previous, up
869 @section Greek letters completion
870 @cindex Greek letters completion
871 @cindex :
873 Math-mode of YaTeX provides another image completion, Greek letters
874 completion in the same method. After prefix @kbd{:}, typing @kbd{a} makes
875 @code{\alpha}, @kbd{b} makes @code{\beta} and @kbd{g} makes @code{\gamma}
876 and so on. First, type @kbd{:TAB} to know all the correspondence of
877 alphabets vs. Greek letters.
879 If you will find @kbd{;} or @kbd{:} doesn't work in correct position of
880 math environment, it may be a bug of YaTeX. Please send me a bug report
881 with the configuration of your text, and avoid it temporarily by typing
882 @kbd{;} or @kbd{:} after universal-argument(@kbd{C-u}) which forces
883 @kbd{;} and @kbd{:} to work as math-prefix.
885 @node Local dictionaries, Commenting out, Completion, Top
886 @comment node-name, next, previous, up
887 @chapter Local dictionaries
888 @cindex local dictionaries
889 @cindex nervous users
891 Tables for completion consist of three dictionaries; `standard
892 dictionary' built in @file{yatex.el}, `user dictionary' for your common
893 private commands, and `local dictionary' that is effective in a certain
894 directory.
896 When you input the command unknown to YaTeX at a completion in the
897 minibuffer, YaTeX asks you with the following prompt;
899 @example
900 `foo' is not in table. Register into: U)serDic L)ocalDic N)one D)iscard
901 @end example
903 @noindent
904 In this menu, typing @kbd{u} updates your `user dictionary', @kbd{l}
905 updates your local dictionary, @kbd{n} updates only on-memory dictionary
906 which go through only current Emacs session, and @kbd{d} updates no
907 dictionary and throws the new word away.
909 If you find this switching feature meaningless and bothersome, put the
910 next expression into your @file{~/.emacs}
912 @lisp
913 (setq YaTeX-nervous nil)
914 @end lisp
916 @node Commenting out, Cursor jump, Local dictionaries, Top
917 @comment node-name, next, previous, up
918 @chapter Commenting out
919 @cindex commenting out
920 @cindex prefix >
921 @cindex prefix <
922 @cindex prefix ,
923 @cindex prefix .
925 You may want to comment out some region.
927 @table @kbd
928 @item [prefix] >
929 @dots{} comment out region by %
930 @item [prefix] <
931 @dots{} uncomment region
932 @end table
934 @noindent
935 cause an operation to the region between point and mark.
937 @table @kbd
938 @item [prefix] .
939 @dots{} comment out current paragraph
940 @item [prefix] ,
941 @dots{} uncomment current paragraph
942 @end table
944 @noindent
945 comments or uncomments the paragraph where the cursor belongs.
946 This `paragraph' means the region marked by the function
947 mark-paragraph, bound to @kbd{ESC h} by default. It is NOT
948 predictable what will happen when you continuously comment out
949 some paragraph many times.
951 You can also comment out an environment between @code{\begin} and
952 @code{\end}, or a @code{\begin}-\@code{\end} pair themselves, by making the
953 following key strokes on the line where @code{\begin@{@}} or
954 @code{\end@{@}} exists.
956 @table @kbd
957 @item [prefix] >
958 @dots{} comment out from \begin to \@code{end}
959 @item [prefix] <
960 @dots{} uncomment from \begin to \@code{end}
961 @end table
963 @noindent
964 comment whole the contents of environment. Moreover,
966 @table @kbd
967 @item [prefix] .
968 @dots{} comment out \begin and \@code{end}
969 @item [prefix] ,
970 @dots{} uncomment \begin and \@code{end}
971 @end table
973 @noindent
974 (un)comments out only environment declaration: @code{\begin@{@}} and
975 @code{\end@{@}}. NOTE that even if you intend to comment out some region,
976 invoking @kbd{[prefix] >} on the @code{\begin},@code{\end} line decides to
977 work in `commenting out from @code{\begin} to @code{\end}' mode.
980 @node Cursor jump, Changing and Deleting, Commenting out, Top
981 @comment node-name, next, previous, up
982 @chapter Cursor jump
983 @cindex cursor jump
984 @cindex prefix g
987 @menu
988 * Jump to corresponding object::
989 * Invoking image processor::
990 * Jump to main file::
991 * Jumping around the environment::
992 * Jumping to last completion position::
993 @end menu
995 @node Jump to corresponding object, Invoking image processor, Cursor jump, Cursor jump
996 @comment node-name, next, previous, up
997 @section Jump to corresponding object
999 Typing
1001 @table @kbd
1002 @item [prefix] g
1003 @dots{} go to corresponding object
1004 @end table
1006 @noindent
1007 in a certain place move the cursor to the place corresponding to the
1008 La@TeX{} command of last place. YaTeX recognize the followings as pairs
1009 that have relation each other.
1011 @itemize @bullet
1012 @item @code{\begin@{@}} <-> @code{\end@{@}}
1013 @item @code{%#BEGIN} <-> @code{%#END}
1014 @item On the image-including line -> corresponding viewer or drawing tool
1015 @item @code{\label@{@}} <-> @code{\ref@{@}}
1016 @item @code{\include(\input)} -> included file
1017 @item @code{\bibitem@{@}} <-> @code{\cite@{@}}
1018 @end itemize
1020 On a @code{\begin},@code{\end} line, typing @kbd{[prefix] g} moves the
1021 cursor to the corresponding @code{\end},@code{\begin} line, if its partner
1022 really exists. The behavior on the line @code{%#BEGIN} and @code{%#END}
1023 are the same. Note that if the correspondent of @code{label/ref} or
1024 @code{cite/bibitem} exists in another file, that file have to be opened to
1025 make a round trip between references by @kbd{[prefix] g}.
1027 If you type @code{[prefix] g} on the line of @code{\include@{chap1@}},
1028 typically in the main text, YaTeX switches buffer to @file{chap1.tex}.
1030 @table @kbd
1031 @item [prefix] 4 g
1032 @dots{} go to corresponding object in other window
1033 @end table
1035 @noindent
1036 do the same job as @kbd{[prefix] g} except it's done in other window.
1037 Note that this function doesn't work on @code{begin/end},
1038 @code{%#BEGIN/%#END} pairs because it is meaningless.
1040 @node Invoking image processor, Jump to main file, Jump to corresponding object, Cursor jump
1041 @comment node-name, next, previous, up
1042 @section Invoking image processor
1043 @cindex{Drawing tool invocation}
1045 `image-including line' described above means such lines as
1046 @code{\epsfile@{file=foo.ps@}}. If you type @kbd{[prefix] g} on that
1047 line, YaTeX automatically searches source of `foo.ps' and invokes image
1048 viewer or drawing tool correspoinding to it. For example; if you draw
1049 an image foo.obj with Tgif and enclose its product named foo.eps by
1050 @code{\epsfile} command. Typing @kbd{[prefix] g} on @code{\epsfile} line
1051 make YaTeX invoke @code{tgif foo.obj}. How a processor is choosen is as
1052 follows.
1054 @enumerate
1055 @item
1056 If there is an expression matching with one of the pattern
1057 defined in @code{YaTeX-processed-file-regexp-alist}, extract file name
1058 from regexp group surrounded by \\(\\). (Which group corresponds is
1059 written in the cdr part of each list.) If no matches were found, do
1060 nothing.
1061 @item
1062 If there is a pattern as `%PROCESSOR' which is defined in the variable
1063 @code{YaTeX-file-processor-alist}, call that processor giving the
1064 file name with corresponding extension.
1065 @item
1066 If not, check the existence of each file which is supplied the
1067 extension in the cdr part of each list of
1068 @code{YaTeX-file-processor-alist}. If any, call the corresponding
1069 image viewer or drawing tool.
1070 @end enumerate
1072 @node Jump to main file, Jumping around the environment, Invoking image processor, Cursor jump
1073 @comment node-name, next, previous, up
1074 @section Jump to main file
1076 Typing
1078 @table @kbd
1079 @item [prefix] ^
1080 @dots{} visit main file
1081 @item [prefix] 4^
1082 @dots{} visit main file in other buffer
1083 @end table
1084 @cindex prefix ^
1085 @cindex prefix 4 ^
1087 in a sub text switch the buffer to the main text specified by
1088 @code{%#!} notation.
1090 @node Jumping around the environment, Jumping to last completion position, Jump to main file, Cursor jump
1091 @comment node-name, next, previous, up
1092 @section Jumping around the environment
1094 And these are the functions which work on the current La@TeX{}
1095 environment:
1097 @table @kbd
1098 @item M-C-a
1099 @dots{} beginning of environment
1100 @item M-C-e
1101 @dots{} @code{end} of environment
1102 @item M-C-@@
1103 @dots{} mark environment
1104 @end table
1105 @cindex M-C-a
1106 @cindex M-C-e
1107 @cindex M-C-@@
1109 @node Jumping to last completion position, , Jumping around the environment, Cursor jump
1110 @comment node-name, next, previous, up
1111 @section Jumping to last completion position
1113 YaTeX always memorize the position of completion into register @code{3}.
1114 So every time you make a trip to any other part of text other than you are
1115 writing, you can return to the editing paragraph by calling
1116 register-to-point with argument YaTeX-current-position-register, which is
1117 achieved by typing @kbd{C-x j 3}(by default).
1119 @node Changing and Deleting, Filling, Cursor jump, Top
1120 @comment node-name, next, previous, up
1121 @chapter Changing and Deleting
1123 These functions are for change or deletion of La@TeX{} commands
1124 already entered.
1126 @table @kbd
1127 @item [prefix] c
1128 @dots{} change La@TeX{} command
1129 @item [prefix] k
1130 @dots{} kill La@TeX{} command
1131 @end table
1132 @cindex prefix c
1133 @cindex prefix k
1135 @menu
1136 * Changing LaTeX commands::
1137 * Killing LaTeX commands::
1138 @end menu
1140 @node Changing LaTeX commands, Killing LaTeX commands, Changing and Deleting, Changing and Deleting
1141 @comment node-name, next, previous, up
1142 @section Changing La@TeX{} commands
1144 @kbd{[prefix] c} can change the various (La)@TeX{} commands. This can
1145 change the followings.
1146 @itemize @bullet
1147 @item Environment names
1148 @item Section-type commands
1149 @item Argument of section-type commands
1150 @item Optional parameters (enclosed by []) of section-type commands
1151 @item Font/size designators
1152 @item Math-mode's maketitle-type commands that can be inputted with
1153 image completion
1154 @end itemize
1156 Typing @kbd{[prefix] c} on one of above objects you want to change
1157 brings a suitable reading function sometimes with completion.
1158 Note: If you want to change the argument of section-type command that
1159 contains other La@TeX{} commands, type @kbd{[prefix] c} either of
1160 surrounding braces of the argument in order to make YaTeX ignore the
1161 internal La@TeX{} sequences as an object of changing. Anyway, it is
1162 very difficult to know which argument position the cursor belongs because
1163 the La@TeX{} commands can be nested and braces can freely emerge. So keep
1164 it mind to put the cursor on a brace when you are thinking of changing a
1165 complicated argument.
1167 @node Killing LaTeX commands, , Changing LaTeX commands, Changing and Deleting
1168 @comment node-name, next, previous, up
1169 @section Killing La@TeX{} commands
1170 @cindex Killing La@TeX{} commands
1172 @kbd{[prefix] k} kills the La@TeX{} commands sometimes with their
1173 arguments. Following table illustrates the correspondence of the invoking
1174 position and what is killed.
1176 @example
1177 [Invoking position] [action]
1178 \begin, \end line kill \begin,\end pairs
1179 %#BEGIN, %#END line kill %#BEGIN,%#END pairs
1180 on a Section-type command kill section-type command
1181 on a parenthesis kill parentheses
1182 @end example
1184 Note that when killing @code{\begin, \end} or @code{%#BEGIN, %#END} pair,
1185 the lines @code{\begin, \end} or @code{%#BEGIN, %#END} exist will be
1186 killed entirely. So take care not to create any line that contains more
1187 than one @code{\begin} or so.
1189 While all operations above are to kill `containers' which surround some
1190 text, universal argument (@kbd{C-u}) for these commands kills not only
1191 `containers' but also `contents' of them. See below as a sample.
1193 @example
1194 Original text: [prefix] k C-u [prefix] k
1195 Main \footnote@{note@} here. Main note here. Main here.
1196 ~(cursor)
1197 @end example
1199 @node Filling, Updation of includeonly, Changing and Deleting, Top
1200 @comment node-name, next, previous, up
1201 @chapter Filling
1202 @cindex filling
1204 @section Filling an item
1205 @cindex filling an item
1206 @cindex prefix i
1208 To fill a term (descriptive sentences) of @code{\item}, type
1210 @c @table @kbd
1211 @c @item [prefix] i
1212 @c @dots{} fill item
1213 @c @end table
1214 @table @kbd
1215 @item M-q
1216 @dots{} fill item
1217 @end table
1219 @noindent
1220 on that item.
1222 YaTeX uses the value of the variable @code{YaTeX-item-regexp} as the
1223 regular expression to search item header in itemize environment.
1224 If you make a newcommand to itemize terms(e.g. @code{\underlineitem}), put
1226 @lisp
1227 (setq YaTeX-item-regexp
1228 "\\(\\\\\\(sub\\)*item\\)\\|\\(\\\\underlineitem\\)")
1229 @end lisp
1230 @cindex YaTeX-item-regexp
1232 in your @file{~/.emacs}. If you are not familiar with regular expression
1233 for Emacs-Lisp, name a newcommand for `itemize' beginning with
1234 @code{\item} such as @code{\itembf}, not @code{\bfitem}.
1236 This function reformats the @code{\item} into `hang-indented' style.
1237 For example:
1239 @example
1240 itemize, enumerate environment:
1241 >
1242 >\item[foo] `foo' is the typical word for describing an
1243 > arbitrarily written....
1244 description environment:
1245 > \item[bar] When the word `for' is used as an arbitrarily
1246 > word, `bar' is bound to follow it.
1247 @end example
1249 Note that the indent depth of an @code{\item} word and its descriptive
1250 paragraph are the same in latter case. If you want to use different
1251 depth, invoke fill-paragraph at the beginning of non-whitespace
1252 character(see below).
1254 @section Filling paragraph
1255 @cindex Filling paragraph
1256 @cindex M-q
1258 Fill-paragraph is little bit adapted for La@TeX{} sources. It retains from
1259 filling in certain environments where formatting leads to a disaster such
1260 as verbatim, tabular, or so. And it protects @code{\verb} expressions
1261 from being folded (The variable @code{YaTeX-verb-regexp} controls this).
1262 Besides, putting cursor on the first occurrence of non-whitespace
1263 character on a line changes the fill-prefix temporarily to the depth of
1264 the line.
1266 @node Updation of includeonly, What column, Filling, Top
1267 @comment node-name, next, previous, up
1268 @chapter Updation of @code{\includeonly}
1269 @cindex includeonly
1271 When you edit splitting source texts, the notation
1273 @example
1274 \includeonly@{CurrentEditingFileName@}
1275 @end example
1277 @noindent
1278 in the main file reduces the time of typesetting. If you want
1279 to hack other file a little however, you have to rewrite it to
1281 @example
1282 \includeonly@{OtherFileNameYouWantToFix@}
1283 @end example
1285 @noindent
1286 in the main file. YaTeX automatically detects that the current
1287 edited text is not in includeonly list and prompts you
1289 @example
1290 A)dd R)eplace %)comment?
1291 @end example
1293 in the minibuffer. Type @kbd{a} if you want to add the current file name
1294 to @code{\includeonly} list, @kbd{r} to replace \@code{includeonly} list
1295 with the current file, and type @kbd{%} to comment out the
1296 @code{\includeonly} line.
1298 @node What column, Intelligent newline, Updation of includeonly, Top
1299 @comment node-name, next, previous, up
1300 @chapter What column?
1301 @cindex what column
1302 @cindex complex tabular
1303 @cindex prefix &
1305 We are often get tired of finding the corresponding column in
1306 large tabulars. For example,
1308 @example
1309 \begin@{tabular@}@{|c|c|c|c|c|c|c|c|@}\hline
1310 Name&Position&Post No.&Addr.&Phone No.&FAX No.&
1311 Home Addr.&Home Phone\\ \hline
1312 Thunder Bird & 6 & 223 & LA & xxx-yyy &
1313 zzz-www & Japan & 9876-54321 \\
1314 & 2 & \multicolumn@{2@}@{c|@}@{Unknown@}
1315 &&&(???)
1316 \\ \hline
1317 \end@{tabular@}
1318 @end example
1320 Suppose you have the cursor located at @code{(???)} mark, can you tell
1321 which column it is belonging at once? Maybe no. In such case,
1322 type
1324 @table @kbd
1325 @item [prefix] &
1326 @dots{} What column
1327 @end table
1329 @noindent
1330 in that position. YaTeX tells you the column header of the
1331 current field. Since YaTeX assumes the first line of tabular
1332 environment as a row of column headers, you can create a row of
1333 virtual column headers by putting them in the first line and
1334 commenting that line with @code{%}.
1336 @node Intelligent newline, Usepackage checker, What column, Top
1337 @comment node-name, next, previous, up
1338 @chapter Intelligent newline
1339 @cindex Intelligent newline
1340 @cindex ESC RET
1341 @cindex M-C-m
1343 At the end of begin-type completion of tabular[*], array, itemize,
1344 enumerate or tabbing environment, or typing
1346 @table @kbd
1347 @item ESC RET
1348 @dots{} Intelligent newline
1349 @end table
1351 @noindent
1352 in these environments inserts the contents corresponding to the current
1353 environment in the next line. (At the begin-type completion, this
1354 contents can be removed by `undo'.) In @code{tabular} environment, for
1355 example, @kbd{ESC RET} inserts the certain number of @code{&} and trailing
1356 @code{\\}, and @code{\hline} if other @code{\hline} is found in backward.
1357 Here are the list of contents vs. environments.
1359 @itemize
1360 @item @code{tabular}, @code{tabular*}, @code{array}
1362 Corresponding number of @code{&} and @code{\\}.
1363 And @code{\hline} if needed.
1365 @item @code{tabbing}
1367 The same number of @code{\>} as @code{\=} in the first line.
1369 @item @code{itemize}, @code{enumerate}, @code{description}, @code{list}
1371 @code{\item} or @code{item[]}.
1372 @end itemize
1374 Note that since this function works seeing the contents of the first
1375 line, please call this after the second line if possible.
1377 If you want to apply these trick to other environments, @code{foo}
1378 environment for example, define the function named
1379 @code{YaTeX-intelligent-newline-foo} to insert corresponding contents.
1380 That function will be called at the beginning of the next line after the
1381 newline is inserted to the current line. Since the function
1382 @code{YaTeX-indent-line} is designed to indent the current line properly,
1383 calling this function before your code to insert certain contents must be
1384 useful. See the definition of the function
1385 @code{YaTeX-intelligent-newline-itemize} as an example.
1387 @node Usepackage checker, Online help, Intelligent newline, Top
1388 @comment node-name, next, previous, up
1389 @chapter Usepackage checker
1390 @cindex usepackage
1392 When you input begint-type, section-type, maketitle-type macros with
1393 completion, and it requires some LaTeX2e package, YaTeX examines
1394 the existence of correct @code{\usepackage}. If not, YaTeX inserts
1395 the @code{\usepackage@{@}} declaration corresponding to input macro.
1397 To activate the package completion for your favarite package,
1398 set the variable @code{YaTeX-package-alist-private} correctly.
1399 Please refere the value of @code{YaTeX-package-alist-default} as an
1400 example.
1402 @node Online help, Browsing file hierarchy, Usepackage checker, Top
1403 @comment node-name, next, previous, up
1404 @chapter Online help
1405 @cindex online help
1406 @cindex prefix ?
1407 @cindex prefix /
1408 @cindex apropos
1409 @cindex keyword search
1411 YaTeX provides you the online help with popular La@TeX{} commands.
1413 Here are the key strokes for the online help.
1415 @table @kbd
1416 @item [prefix] ?
1417 @dots{} Online help
1418 @item [prefix] /
1419 @dots{} Online apropos
1420 @end table
1422 @section Online help
1424 `Online help' shows the documentation for the popular La@TeX{}
1425 commands(defaults to the commands on the cursor) in the next buffer.
1426 There are two help file, `global help' and `private help'. The former
1427 file contains the descriptions on the standard La@TeX{} command and is
1428 specified its name by variable @code{YaTeX-help-file}. Usually, the
1429 global help file should be located in public space (@code{$EMACSEXECPATH}
1430 by default) and should be world writable so that anyone can update it to
1431 enrich its contents. The latter file contains descriptions on
1432 non-standard or personal command definitions and is specified by
1433 @code{YaTeX-help-file-private}. This file should be put into private
1434 directory.
1436 @section Online apropos
1438 `Online apropos' is an equivalent of GNU Emacs's apropos. It
1439 shows all the documentations that contains the keyword entered by
1440 the user.
1442 @section When no descriptions are found...
1444 If there is no description on a command in help files, YaTeX
1445 requires you to write a description on that command. If you are
1446 willing to do, determine which help file to add and write the
1447 description on it referring your manual of (La)TeX. Please send
1448 me your additional descriptions if you describe the help on some
1449 standard commands. I might want to include it in the next
1450 distribution.
1452 @node Browsing file hierarchy, Cooperation with other packages, Online help, Top
1453 @comment node-name, next, previous, up
1454 @chapter Browsing file hierarchy
1455 @cindex hierarchy
1456 @cindex browsing
1458 When you are editing multi-file source, typing
1460 @table @kbd
1461 @item [prefix] d
1462 @dots{} browse file hierarchy
1463 @end table
1465 @noindent
1466 asks you the parent-most file (which may be defaulted) and displays the
1467 documentation hierarchy in the next window. In this buffer, the following
1468 commands are available.
1470 @table @kbd
1471 @item n
1472 @dots{} move to the next line and show its contents
1473 @item p
1474 @dots{} move to the previous line and show its contents
1475 @item N
1476 @dots{} move to the next file in the same inclusion level
1477 @item P
1478 @dots{} move to the previous file in the same inclusion level
1479 @item j
1480 @dots{} move to the next line
1481 @item k
1482 @dots{} move to the previous line
1483 @item u
1484 @dots{} move to the parent file
1485 @item .
1486 @dots{} show the current files contents in the next window
1487 @item SPC
1488 @dots{} scroll up the current file window
1489 @item DEL, b
1490 @dots{} scroll down the current file window
1491 @item <
1492 @dots{} show the beginning of the current file
1493 @item >
1494 @dots{} show the end of the current file
1495 @item >
1496 @dots{} return to the previous postion after @kbd{<} or @kbd{>}
1497 @item RET, g
1498 @dots{} open the current file in the next window
1499 @item mouse-2
1500 @dots{} same as RET(available only with window system)
1501 @item o
1502 @dots{} other window
1503 @item 1
1504 @dots{} delete other windows
1505 @item -
1506 @dots{} shrink hierarchy buffer window
1507 @item +
1508 @dots{} enlarge hierarchy buffer window
1509 @item ?
1510 @dots{} describe mode
1511 @item q
1512 @dots{} quit
1513 @end table
1515 Note that operations on the file contents in the next window do not work
1516 correctly when you close the corresponding file.
1518 @node Cooperation with other packages, Customizations, Browsing file hierarchy, Top
1519 @comment node-name, next, previous, up
1520 @chapter Cooperation with other packages
1522 YaTeX works better with other brilliant packages.
1524 @section gmhist
1525 @cindex gmhist
1526 @cindex command history
1527 @cindex minibuffer history
1529 When you are loading @file{gmhist.el} and @file{gmhist-mh.el}, you can
1530 use independent command history list at the prompt of preview command
1531 (@kbd{[prefix] tp}) and print command (@kbd{[prefix] tl}). On each
1532 prompt, you can enter the previous command line string repeatedly by
1533 typing @kbd{M-p}.
1535 @section min-out
1536 @cindex min-out
1538 @file{min-out}, the outline minor mode, can be used in yatex-mode
1539 buffers. If you want to use it with YaTeX, please refer the
1540 file @file{yatexm-o.el} as an example.
1542 @node Customizations, Etcetera, Cooperation with other packages, Top
1543 @comment node-name, next, previous, up
1544 @chapter Customizations
1545 @cindex customizations
1547 You can customize YaTeX by setting Emacs-Lisp variables and by making
1548 add-in functions.
1550 @menu
1551 * Lisp variables::
1552 * Add-in functions::
1553 * Add-in generator::
1554 @end menu
1556 @node Lisp variables, Add-in functions, Customizations, Customizations
1557 @comment node-name, next, previous, up
1558 @section Lisp variables
1559 @cindex customizable variables
1561 You can change the key assignments or make completion more comfortable
1562 by setting the values of various variables which control the movement of
1563 yatex-mode.
1565 For example, if you want to change the prefix key stroke from @kbd{C-c}
1566 to any other sequence, set YaTeX-prefix to whatever you want to use. If
1567 you don't want to use the key sequence @kbd{C-c letter} which is assumed
1568 to be the user reserved sequence in Emacs world, set
1569 @code{YaTeX-inhibit-prefix-letter} to @code{t}, and all of the default key
1570 bind of @kbd{C-c letter} will turn to the corresponding @kbd{C-c C-letter}
1571 (but the region based completions that is invoked with @kbd{C-c
1572 Capital-letter} remain valid, if you want to disable those bindings, set
1573 that variable to 1 instead of @code{t}).
1575 @menu
1576 * All customizable variables::
1577 * Sample definitions::
1578 * Hook variables::
1579 * Hook file::
1580 @end menu
1582 @node All customizable variables, Sample definitions, Lisp variables, Lisp variables
1583 @comment node-name, next, previous, up
1584 @subsection All customizable variables
1585 @cindex all customizable variables
1587 Here are the customizable variables of yatex-mode. Each value setq-ed
1588 in @file{~/.emacs} is preferred and that of defined in @file{yatex.el} is
1589 neglected. Parenthesized contents stands for the default value. When you
1590 are to change some of these variables, see more detailed documentation of
1591 the variable by @kbd{M-x describe-variable}.
1593 @defvar YaTeX-japan
1594 Set this nil to produce all messages in English
1595 (@code{Depends on Japanese feature of Emacs})
1596 @end defvar
1598 @defvar YaTeX-kanji-code
1599 Default buffer-file-coding-system for YaTeX modes' buffer.
1600 Set this 0 to no language conversion. Nil to preserve original
1601 coding-system. 1=Shift JIS, 2=JIS, 3=EUC, 4=UTF-8 (@code{1 or 2})
1602 @end defvar
1604 @defvar YaTeX-prefix
1605 Prefix key stroke (@kbd{C-c})
1606 @end defvar
1608 @defvar YaTeX-inhibit-prefix-letter
1609 Change key stroke from @kbd{C-c letter} to @kbd{C-c C-letter} (@code{nil})
1610 @end defvar
1612 @defvar YaTeX-fill-prefix
1613 Fill-prefix used in yatex-mode (@code{nil})
1614 @end defvar
1616 @defvar YaTeX-user-completion-table
1617 Name of user dictionary where learned completion table will be stored.
1618 (@code{"~/.yatexrc"})
1619 @end defvar
1621 @defvar tex-command
1622 La@TeX{} typesetter command (@code{"latex"})
1623 @end defvar
1625 @defvar dvi2-command
1626 Preview command (@code{"xdvi -geo +0+0 -s 4"})
1627 @end defvar
1629 @defvar dviprint-command-format
1630 Command format to print dvi file (@code{"dvi2ps %f %t %s | lpr"})
1631 @end defvar
1633 @defvar dviprint-from-format
1634 Start page format of above %f. %b will turn to start page (@code{"-f %b"})
1635 @end defvar
1637 @defvar dviprint-to-format
1638 End page format of above %t. %e will turn to @code{end} page (@code{"-t %e"})
1639 @end defvar
1641 @defvar makeindex-command
1642 Default makeindex command (@code{"makeindex"} (@code{"makeind"} on MS-DOS))
1643 @end defvar
1645 @defvar YaTeX-dvipdf-command
1646 Default command name to convert .dvi to PDF (@code{"dvipdfmx"})
1647 @end defvar
1649 @defvar YaTeX-need-nonstop
1650 Put @code{\nonstopmode@{@}} or not (@code{nil})
1651 @end defvar
1653 @defvar latex-warning-regexp
1654 Regular expression of warning message latex command puts out
1655 (@code{"line.* [0-9]*"})
1656 @end defvar
1658 @defvar latex-error-regexp
1659 Regular expression of error message (@code{"l\\.[1-9][0-9]*"})
1660 @end defvar
1662 @defvar latex-dos-emergency-message
1663 Message latex command running on DOS puts at abort (@code{"Emergency stop"})
1664 @end defvar
1666 @defvar YaTeX-item-regexp
1667 Regular expression of item command (@code{"\\\\item"})
1668 @end defvar
1670 @defvar YaTeX-verb-regexp
1671 Regexp of verb family. Omit \\\\. (@code{"verb\\*?\\|path"})
1672 @end defvar
1674 @defvar YaTeX-nervous
1675 T for using local dictionary (@code{t})
1676 @end defvar
1678 @defvar YaTeX-sectioning-regexp
1679 Regexp of La@TeX{} sectioning command
1680 (@code{"\\(part\\|chapter\\*?\\|\\(sub\\)*\\(section\\|paragraph\\)\\*?\\)\\b"})
1681 @end defvar
1683 @defvar YaTeX-fill-inhibit-environments
1684 Inhibit fill in these environments
1685 (@code{'("tabular" "tabular*" "array" "picture" "eqnarray" "eqnarray*" "equation" "math" "displaymath" "verbatim" "verbatim*")})
1686 @end defvar
1688 @defvar YaTeX-uncomment-once
1689 T for deleting all preceding @code{%} (@code{nil})
1690 @end defvar
1692 @defvar YaTeX-close-paren-always
1693 T for always close all parenthesis automatically, @code{nil} for only eol
1694 (@code{t})
1695 @end defvar
1697 @defvar YaTeX-auto-math-mode
1698 Switch math-mode automatically (@code{t})
1699 @end defvar
1701 @defvar YaTeX-math-key-list-private
1702 User defined alist, math-mode-prefix vs completion alist
1703 used in image completion (@code{nil}). See @file{yatexmth.el}
1704 for the information about how to define a completion alist.
1705 @end defvar
1707 @defvar YaTeX-default-pop-window-height
1708 Initial height of typesetting buffer when one-window.
1709 Number for the lines of the buffer, numerical string for
1710 the percentage of the screen-height. @code{nil} for half height (10)
1711 @end defvar
1713 @defvar YaTeX-help-file
1714 Global online help file name (@file{$doc-directory/../../site-lisp/YATEXHLP.eng})
1715 @end defvar
1717 @defvar YaTeX-help-file-private
1718 Private online help file name (@file{"~/YATEXHLP.eng"})
1719 @end defvar
1721 @defvar YaTeX-no-begend-shortcut
1722 Disable [prefix] b ?? shortcut (@code{nil)}
1723 @end defvar
1725 @defvar YaTeX-hilit-pattern-adjustment-private
1726 List of the list that contain the regular expression and the symbol of
1727 logical meaning of the string that matches the pattern. See also the
1728 value from @code{(assq 'yatex-mode hilit-patterns-alist)} and the value of
1729 @code{YaTeX-hilit-pattern-adjustment-default} (and even the document of
1730 hilit19.el).
1731 @end defvar
1733 @defvar YaTeX-sectioning-level
1734 Alist of LaTeX's sectioning command vs its height.
1735 @end defvar
1737 @defvar YaTeX-hierarchy-ignore-heading-regexp
1738 @code{YaTeX-display-hierarchy} searches for sectioning command first, and
1739 comment line secondary as a file headings. In latter case, ignore lines
1740 that match with regular expression of this variable. Default value of
1741 this variable is RCS header expressions and mode specifying line `-*- xxxx
1742 -*'.
1743 @end defvar
1745 @defvar YaTeX-skip-default-reader
1746 Non-nil for this variable skips the default argument reader of
1747 section-type command when add-in function for it is not defined
1748 (@code{nil})
1749 @end defvar
1751 @defvar YaTeX-create-file-prefix-g
1752 When typing @kbd{prefix g} on the @code{\include} line,
1753 open the target file even if the file doesn't exist (@code{nil})
1754 @end defvar
1756 @defvar YaTeX-simple-messages
1757 Simplyfy messages of various completions (@code{nil})
1758 @end defvar
1760 @defvar YaTeX-hilit-sectioning-face
1761 When hilit19 and yatex19 is active, YaTeX colors the sectioning commands.
1762 This variable specifies the foreground and background color of
1763 @code{\part} macro. The default value is @code{'(yellow/dodgerblue
1764 yellow/slateblue)}. The first element of this list is for the screen when
1765 @code{hilit-background-mode} is @code{'light}, and the second element is
1766 for @code{'dark}. You should specify both color as `forecolor/backcolor'.
1767 @end defvar
1769 @defvar YaTeX-hilit-sectioning-attenuation-rate
1770 When color mode, this variable specifies how much attenuate the color
1771 density of @code{\subparagraph} compared with that of @code{\chapter}
1772 (@code{'(15 40)}) See also @code{YaTeX-hilit-sectioning-face}.
1773 @end defvar
1775 @defvar YaTeX-use-AMS-LaTeX
1776 If you use AMS-LaTeX, set to @code{t} (@code{nil})
1777 @end defvar
1779 @defvar YaTeX-use-LaTeX2e
1780 If you use LaTeX2e, set to @code{t} (@code{t})
1781 @end defvar
1783 @defvar YaTeX-template-file
1784 File name which is automatically inserted at creation
1785 (@code{~/work/template.tex})
1786 @end defvar
1788 @defvar YaTeX-search-file-from-top-directory
1789 Non-nil means to search input-files from the directory where main file exists
1790 (@code{t})
1791 @end defvar
1793 @defvar YaTeX-use-font-lock
1794 Use font-lock to fontify buffer or not (@code{(featurep 'font-lock)}
1795 @end defvar
1797 @defvar YaTeX-use-hilit19
1798 Use hilit19 to highlight buffer or not (@code{(featurep 'hilit19)}
1799 @end defvar
1801 @defvar YaTeX-use-italic-bold
1802 YaTeX tries to search italic, bold fontsets or not
1803 (@code{t} if Emacs-20 or later). This variable is effective only when
1804 font-lock is used.
1805 (@code{(featurep 'hilit19)}
1806 @end defvar
1808 @defvar YaTeX-singlecmd-suffix
1809 Suffix which is always inserted after maketitle-type macros.
1810 @code{"{}"} is recommended.
1811 @end defvar
1813 @defvar YaTeX-package-alist-private
1814 Alist of LaTeX2e-package name vs. lists of macros in it.
1815 Set this alist properly and YaTeX automatically check the declaratiion of
1816 `usepackage' for corresponding macro, when you input that macro with
1817 completion. If required `usepackage' is not found, YaTeX also
1818 automatically inserts `\usepackage'. Alist is as follows;
1819 @lisp
1820 '((PackageName1
1821 (completionType ListOfMacro)
1822 (completionType ListOfMacro))
1823 (PackageName2
1824 (completionType ListOfMacro)
1825 (completionType ListOfMacro...))....)
1826 @end lisp
1827 completionType is one of @code{env, section, maketitle}.
1828 Consult the value of @code{YaTeX-package-alist-default} as an example.
1829 @end defvar
1831 @defvar YaTeX-tabular-indentation
1832 At indentation by @kbd{C-i} in tabular or array environment,
1833 YaTeX put the additional spaces to the normail indentation depth.
1834 The number of additional spaces is the product of YaTeX-tabular-indentation
1835 and the number of column position in tabular.
1836 @end defvar
1838 @defvar YaTeX-noindent-env-regexp
1839 Regexp of environment names that should begin with no indentation.
1840 All verbatime-like environment name should match with.
1841 @end defvar
1843 @defvar YaTeX-ref-default-label-string
1844 Default \\ref time string format.
1845 This format is like strftime(3) but allowed conversion char are as follows;
1846 %y -> Last 2 digit of year, %b -> Month name, %m -> Monthe number(1-12),
1847 %d -> Day, %H -> Hour, %M -> Minute, %S -> Second,
1848 %qx -> alphabetical-decimal conversion of yymmdd.
1849 %qX -> alphabetical-decimal conversion of HHMMSS.
1850 Beware defualt label-string should be always unique. So this format string
1851 should have both time part (%H+%M+%S or %qX) and date
1852 part (%y+(%b|%m)+%d or %qx).
1853 @end defvar
1855 @defvar YaTeX-ref-generate-label-function
1856 Function to generate default label string for unnamed \\label{}s.
1857 The function pointed to this value should take two arguments.
1858 First argument is LaTeX macro's name, second is macro's argument.
1859 Here is an example for using this value.
1860 @lisp
1861 (setq YaTeX-ref-generate-label-function 'my-yatex-generate-label)
1862 (defun my-yatex-generate-label (command value)
1863 (and (string= command "caption")
1864 (re-search-backward "\\\\begin{\\(figure\\|table\\)}" nil t)
1865 (setq command (match-string 1)))
1866 (let ((alist '(("chapter" . "chap")
1867 ("section" . "sec")
1868 ("subsection" . "subsec")
1869 ("figure" . "fig")
1870 ("table" . "tbl"))))
1871 (if (setq command (cdr (assoc command alist)))
1872 (concat command ":" value)
1873 (YaTeX::ref-generate-label nil nil))))
1874 @end lisp
1875 @end defvar
1878 @node Sample definitions, Hook variables, All customizable variables, Lisp variables
1879 @comment node-name, next, previous, up
1880 @subsection Sample definitions
1881 @cindex prefix key stroke
1882 @cindex fill-prefix
1884 For instance, to change the prefix key stroke to @kbd{ESC}, and name of
1885 the user dictionary @file{~/src/emacs/yatexrc}, and set @code{fill-prefix}
1886 to single TAB character, add the following @code{setq} to @file{~/.emacs}.
1888 @lisp
1889 (setq YaTeX-prefix "\e"
1890 YaTeX-user-completion-table "~/src/emacs/yatexrc"
1891 YaTeX-fill-prefix " ")
1892 @end lisp
1894 @node Hook variables, Hook file, Sample definitions, Lisp variables
1895 @comment node-name, next, previous, up
1896 @subsection Hook variables
1897 @cindex hook variables
1899 More customizations will be done by the hook-function defined in
1900 hook-variable @code{yatex-mode-hook}. This is useful to define a shortcut
1901 key sequence to enter some environments other than @code{document} and
1902 @code{enumerate} etc. The following statement defines @code{[prefix] ba}
1903 to enter @code{\begin@{abstract@}} ... @code{=end@{abstract@}}
1904 immediately.
1906 @lisp
1907 (setq yatex-mode-hook
1908 '(lambda() (YaTeX-define-begend-key "ba" "abstract")))
1909 @end lisp
1911 You should use functions @code{YaTeX-define-key}, or
1912 @code{YaTeX-define-begend-key} to define all the key sequences of
1913 yatex-mode.
1915 @node Hook file, , Hook variables, Lisp variables
1916 @comment node-name, next, previous, up
1917 @subsection Hook file
1918 @cindex hook file
1920 You can stuff all of YaTeX related expressions into a file named
1921 @file{yatexhks.el} if you have a lot of codes. YaTeX automatically load
1922 this file at the initialization of itself. Using @file{yatexhks.el}
1923 makes @code{yatex-mode-load-hook} unnecessary.
1925 @node Add-in functions, Add-in generator, Lisp variables, Customizations
1926 @comment node-name, next, previous, up
1927 @section Add-in functions
1928 @cindex add-in functions
1929 @cindex yatexadd.el
1931 You can easily define a function to input detailed arguments
1932 with completion according to La@TeX{} environments or commands.
1934 @c @node What is add-in functions?, , Add-in functions, Add-in functions
1935 @comment node-name, next, previous, up
1936 @subsection What is add-in functions?
1937 @cindex tabular
1939 When you input @code{tabular} environment, don't you think ``I want
1940 YaTeX to complete its argument toward my favorite one such as
1941 @code{@{|c|c|c|@}}...''? Yes, you can define the function to complete
1942 arguments for any environment and any La@TeX{} commands.
1944 @subsection Procedure
1946 Here is the procedure to define add-in functions.
1947 @enumerate
1948 @item
1949 Define the function
1950 @item
1951 Put the function into @file{yatexhks.el}
1952 @end enumerate
1954 @menu
1955 * How the add-in function works::
1956 * How the function is called::
1957 * Useful functions for creating add-in::
1958 * Contribution::
1959 @end menu
1961 @node How the add-in function works, How the function is called, Add-in functions, Add-in functions
1962 @comment node-name, next, previous, up
1963 @subsection How the add-in function works
1965 There are three types of add-in.
1967 @enumerate
1968 @item
1969 Option add-in
1970 @item
1971 argument add-in
1972 @item
1973 enclosing add-in
1974 @end enumerate
1976 @dfn{Option add-in} returns the
1977 La@TeX{}'s optional parameters such as optional strings after
1978 @code{\begin@{ENV@}}, optional strings between a section-type command
1979 and its first argument, and optional strings just after type
1980 maketitle-type command. The following illustrates the name of add-in
1981 functions, where underlined strings are generated by add-in functions.
1983 @display
1984 \begin@{table@}[ht] (Function name: YaTeX:table)
1985 ~~~~
1986 \put(100,200)@{@} (Function name: YaTeX:put)
1987 ~~~~~~~~~
1988 \sum_@{i=0@}^@{n@} (Function name: YaTeX:sum)
1989 ~~~~~~~~~~
1990 @end display
1992 Obviously, the function name is decided by concatenating the prefix
1993 `YaTeX:' and La@TeX{} command's name.
1995 Another add-in type is @dfn{argument add-in}, which completes arguments
1996 for section-type commands.
1998 @display
1999 \newcommand@{\foo@}@{bar@} (Function name: YaTeX::newcommand)
2000 ~~~~ ~~~
2001 @end display
2003 When the section-type command is inputted, the function named by
2004 concatenating `YaTeX::' and section-type command, is called automatically
2005 with an integer argument which indicates which argument of section-type
2006 command is being read. Thus the add-in should determine the
2007 job referring the value of its argument.
2009 @dfn{enclosing add-in} is for modifying and/or checking the region that
2010 will be enclosed by section-type commands via @kbd{[prefix] S}. An
2011 enclosing add-in function will be called with two arguments, beginning of
2012 the enclosed region and end of the region. Suppose you want to enclose
2013 the existing text @code{(a+b)/c} by @code{\frac{}}.
2015 @display
2016 a/c
2017 | |
2018 A B
2019 @end display
2021 You do set-mark-command at point A and then move to point B. Typing
2022 @kbd{[prefix] S} and input @code{frac} enclose the region like this;
2024 @display
2025 \frac{a/c}
2026 @end display
2028 Normally, the expression @code{a/c} is translated to
2029 @code{\frac@{a@}@{c@}}. An enclosing add-in is useful for modifying
2030 @code{/} to @code{@}@{}.
2032 @menu
2033 * Defining option-add-in::
2034 * Defining argument-add-in::
2035 * Defining enclosing-add-in::
2036 @end menu
2038 @node Defining option-add-in, Defining argument-add-in, How the add-in function works, How the add-in function works
2039 @comment node-name, next, previous, up
2040 @subsubsection Defining `option add-in'
2042 If you want @code{@{|c|c|c|@}} for all @code{tabular} environment,
2044 @lisp
2045 (defun YaTeX:tabular ()
2046 "@{|c|c|c|@}")
2047 @end lisp
2049 @noindent
2050 is enough. If you want more complicated format, define as below.
2052 @lisp
2053 (defun YaTeX:tabular ()
2054 "@{@@@{\\vrule width 1pt\\ @}|||@@@{\\ \\vrule width 1pt@}@}")
2055 @end lisp
2057 @noindent
2058 Note that the character @code{\} must be described as @code{\\} in
2059 Emacs-Lisp. The next example reads the tabular format from keyboard.
2060 @lisp
2061 (defun YaTeX:tabular ()
2062 (concat "@{" (read-string "Rule: ") "@}"))
2063 @end lisp
2065 @node Defining argument-add-in, Defining enclosing-add-in, Defining option-add-in, How the add-in function works
2066 @comment node-name, next, previous, up
2067 @subsubsection Defining `argument add-in'
2069 This section describes how to define the add-in function for
2070 @code{\newcommand}.
2072 The first argument of @code{\newcommand} begins always with @code{\}.
2073 The second argument is usually so complex that we can not edit them in the
2074 minibuffer. Here is the created function considering this.
2076 @lisp
2077 (defun YaTeX::newcommand (n) ;n is argument position
2078 (cond
2079 ((= n 1) ;1st argument is macro name
2080 (read-string "Command: " "\\")) ;initial input `\'
2081 ((= n 2) "") ;do nothing when reading arg#2
2082 (t nil)))
2083 @end lisp
2085 Note that when the `argument add-in' function return `nil', normal
2086 argument reader will be called.
2088 @node Defining enclosing-add-in, , Defining argument-add-in, How the add-in function works
2089 @comment node-name, next, previous, up
2090 @subsubsection Defining `enclosing add-in'
2092 This section describes how to define the add-in function for
2093 text enclosed by @code{\frac@{@}}.
2095 When enclosing the text @code{5/3} by @code{\frac@{@}}, you might want to
2096 replace @code{/} with @code{@}@{}. Enclosing function
2097 @code{YaTeX::frac-region} is called with two arguments, beginning of
2098 enclosed text and end of enclosed text. The function is expected to
2099 replace @code{/} with @code{@}@{}. Here is an example expression.
2101 @lisp
2102 (defun YaTeX::frac-region (beg end)
2103 (catch 'done
2104 (while (search-forward "/" end t)
2105 (goto-char (match-beginning 0))
2106 (if (y-or-n-p "Replace this slash(/) with `}{'")
2107 (throw 'done (replace-match "}{")))
2108 (goto-char (match-end 0)))))
2109 @end lisp
2111 @node How the function is called, Useful functions for creating add-in, How the add-in function works, Add-in functions
2112 @comment node-name, next, previous, up
2113 @subsection How the function is called
2115 YaTeX calls the add-in functions for specified begin-type, section-type,
2116 and maketitle-type command, if any. `Option add-in' functions for
2117 begin-type are called when @code{\begin@{ENV@}} has been inserted,
2118 functions for section-type are called just before input of the first
2119 argument, and functions for maketitle-type is called after maketitle-type
2120 command has been inserted. `Argument add-in' functions are called at each
2121 entry of arguments for section-type commands.
2123 @node Useful functions for creating add-in, Contribution, How the function is called, Add-in functions
2124 @comment node-name, next, previous, up
2125 @subsection Useful functions for creating add-in
2127 Many add-in functions for typical La@TeX{} commands are defined in
2128 @file{yatexadd.el}. Those are also useful as references. Here are the
2129 short descriptions on useful functions, where [F] means function, [A]
2130 means arguments, [D] means description.
2132 @table @kbd
2133 @item [F]
2134 YaTeX:read-position
2135 @itemx [A]
2136 Character list which can show up in the brackets
2137 @itemx [D]
2138 Return the location specifier such as `[htb]'. When
2139 nothing is entered, omit [] itself. If the possible characters
2140 are "htbp", call this function as
2141 @code{(YaTeX:read-position "htbp")}
2143 @item [F]
2144 YaTeX:read-coordinates
2145 @itemx [A]
2146 Base prompt, X-axis prompt, Y-axis prompt (each optional)
2147 @itemx [D]
2148 Read the coordinates with the prompt ``BasePrompt X-axisPrompt:'' for
2149 X-axis, ``BasePrompt Y-axisPrompt:'' for Y-axis, and return it in the form
2150 of ``(X,Y)''. The default prompts are @code{Dimension}, @code{X},
2151 @code{Y} respectively.
2153 @item [F]
2154 YaTeX:check-completion-type
2155 @itemx [A]
2156 One of the symbols: 'begin, 'section, or 'maketitle
2157 @itemx [D]
2158 Check the current completion type is specified one and cause error if
2159 not. The variable @code{YaTeX-current-completion-type} holds the symbol
2160 according to the current completion type.
2161 @end table
2163 @node Contribution, , Useful functions for creating add-in, Add-in functions
2164 @comment node-name, next, previous, up
2165 @subsection Contribution
2167 If you make your own pretty function and you let it be in public, please
2168 send me the function. I'm going to include it in the next release.
2170 @node Add-in generator, , Add-in functions, Customizations
2171 @comment node-name, next, previous, up
2172 @section Add-in generator
2174 First, don't forget to read the section of add-in functions @ref{Add-in
2175 functions}. If you easily understand how to define them, there's no need
2176 to read this section. But being not familiar with Emacs-Lisp, when you
2177 don't have clear idea what to do, this section describes how to get YaTeX
2178 make add-in function.
2180 There are two methods of generation. One is for fully interactive
2181 generator for beginners and another requires little knowledge of
2182 Emacs-Lisp.
2184 @subsection Generator for beginners
2185 The former generator is called by
2186 @center @kbd{M-x YaTeX-generate}
2188 @noindent
2189 strokes. All you have to do is follow the guidances. Defying them may cases
2190 the disaster (I wonder what is it???). So when you make some mistake, it
2191 is recommendable to type @kbd{C-g} and start afresh.
2193 @subsection Simple generator
2195 The latter generator is invoked by the next sequence.
2196 @center @kbd{M-x YaTeX-generate-simple}
2197 This generator can make both ``option add-in'' and ``argument add-in''
2198 (@emph{refer the section add-in functions}
2199 @ref{How the add-in function works}), whereas @code{YaTeX-generate}
2200 cannot make ``argument addin''.
2202 For example, assume you have the LaTeX command as follows.
2204 @example
2205 \epsinput[t](250,50)@{hoge.eps@}@{plain@}@{Picture of foo@}
2206 (A) (B) (1) (2) (3)
2207 (A)Optional parameter to specify the position
2208 One of t(top), b(bottom), l(left), r(right)
2209 (B)Maximum size of frame
2210 (1)1st argument is filename of EPS file
2211 (2)2nd argument indicates
2212 plain do nothing
2213 frame make frame around image
2214 dframe make double-frame around image
2215 for included EPS file.
2216 (3)Caption for the picture
2217 @end example
2219 Now get start with generation. Typing @kbd{M-x YaTeX-generate-simple}
2220 brings the prompt:
2221 @display
2222 (O)ption? (A)rgument?
2223 @end display
2225 @subsubsection Generating ``option add-in''
2226 @cindex option add-in
2228 Since (A), (B) above are optional argument, all we have to do to
2229 complete them is define the option add-in for them. Let's generate the
2230 function to complete (A).
2232 @display
2233 M-x YaTeX-generate-simple RET
2234 epsinput RET
2235 o
2236 @end display
2238 @noindent
2239 Typing as above leads the next prompt.
2241 @display
2242 Read type(1): (S)tring (C)omplete (F)ile ([)option (P)osition co(O)rd. (q)uit
2243 @end display
2245 @noindent
2246 This asks that ``Which type is the completion style of 1st argument?''.
2247 Here are the possible completion style.
2249 @table @code
2250 @item String
2251 read plain string
2252 @item Complete
2253 read with completion
2254 @item File
2255 read file name
2256 @item Option
2257 read optional string (if string omitted, omit [] too)
2258 @item Position
2259 read positional option (like [htbp])
2260 @item Coord.
2261 read coordinates
2262 @item Quit
2263 quit from generating
2264 @end table
2266 Since (A) is the optional argument to specify the location of included
2267 EPS file, the completion style is @code{Position}, and the possible
2268 characters are t, b, l, and r. To tell these information to generator,
2269 operate as follows.
2271 @display
2272 Read type(1).... p
2273 Acceptable characters: tblr RET
2274 @end display
2276 (B) is coordinate. So its completion style is coOrd. We want a prompt
2277 meaning ``Maximum size'' when completion.
2279 @display
2280 Read type(2).... o
2281 Prompt for coordinates: Max size RET
2282 @end display
2284 That's all for optional argument. Select quit.
2286 @display
2287 Read type(3).... q
2288 @end display
2290 Then the generated option add-in function for \epsinput will be shown in
2291 the next window.
2293 @subsubsection Generating ``argument add-in''
2294 @cindex argument add-in
2296 Next, create the argument add-in. The arguments for \epsinput are EPS
2297 file name, framing style, and caption string in sequence.
2299 @display
2300 M-x YaTeX-generate-simple RET
2301 epsinput RET
2302 a
2303 @end display
2305 Above key strokes bring the prompt that asks the number of argument.
2306 Answer it with 3.
2308 @display
2309 How many arguments?: 3 RET
2310 @end display
2312 Then the generator asks the completion style and prompt for completion.
2313 Answer them. @kbd{f} for FileName and prompt string.
2315 @display
2316 Read type(1).... f
2317 Prompt for argument#1 EPS file name RET
2318 @end display
2320 The second argument is one of selected symbol. So the completion type
2321 is @code{Completion}.
2323 @display
2324 Read type(2).... c
2325 Prompt for argument#2 Include style RET
2326 @end display
2328 Then all the candidates ready to be read. Type single RET after
2329 entering all.
2331 @display
2332 Item[1](RET to exit): plain RET
2333 Item[2](RET to exit): frame RET
2334 Item[3](RET to exit): dframe RET
2335 Item[4](RET to exit): RET
2336 @end display
2338 The following prompt asks whether the entered string must belong to
2339 candidates or not. In this case, since the argument must be one of
2340 @code{plain}, @code{frame}, and @code{dframe}, type @code{y}.
2342 @display
2343 Require match? (y or n) y
2344 @end display
2346 The last argument is the caption string for which any completion is
2347 needed.
2349 @display
2350 Read type(3).... s
2351 Prompt for argument#3 Caption RET
2352 default: Figure of RET
2353 @end display
2355 Finally we'll get the argument add-in in the next window.
2357 @subsection Contribution
2359 If you get your own pretty function and you let it be in public, please
2360 steel yourself in the happy atmosphere and do not send me the function.
2361 I do know it is not fine because it is generated by yatexgen:-p.
2363 @node Etcetera, Copying, Customizations, Top
2364 @comment node-name, next, previous, up
2365 @chapter Etcetera
2367 The standard completion tables provided in @file{yatex.el} contain a
2368 few La@TeX{} commands I frequently use. This is to lessen the key
2369 strokes to complete entire word, because too many candidates
2370 rarely used often cause too many hits. Therefore always try to
2371 use completion in order to enrich your dictionary, and you will
2372 also find `Wild Bird' growing suitable for your La@TeX{} style.
2374 The package name `Wild Bird' is the English translation of Japanese
2375 title `Yachou', which is a trick on words of Japanese.
2377 @node Copying, , Etcetera, Top
2378 @comment node-name, next, previous, up
2379 @chapter Copying
2381 This program is distributed as a free software. You can
2382 use/copy/modify/redistribute this software freely but with NO warranty to
2383 anything as a result of using this software. Adopting code from this
2384 program is also free. But I would not do contract act.
2386 Any reports and suggestions are welcome as long as I feel interests in
2387 this software. My possible e-mail address is `yuuji@@yatex.org'. (as of
2388 Jan.2004) And there is mailing list for YaTeX. Although the common
2389 language is Japanese, questions in English will be welcome. To join the
2390 ML, send the mail whose subject is `append' to the address
2391 `yatex@@yatex.org. If you have some question, please ask to
2392 `yatex-admin@@yatex.org'.
2394 The specification of this software will be surely modified
2395 (depending on my feelings) without notice :-p.
2398 @flushright
2399 HIROSE Yuuji
2400 @end flushright
2401 @bye
2403 Local variables:
2404 mode: texinfo
2405 fill-prefix: nil
2406 fill-column: 74
2407 End: