yatex
view docs/yatexe.tex @ 130:8703f090c628
`[prefix] t e' for YaTeX-typeset-environment.
It automatically mark current inner environment or portion of math mode,
then call typeset-region on that region saving it in texput.tex.
| author | yuuji@gentei.org |
|---|---|
| date | Thu, 27 May 2010 16:37:44 +0900 |
| parents | 91bf68eeefe8 |
| children | bd0a9177e5e7 |
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 16:25:29 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 e
149 @dots{} invoke latex on current environment or whole
150 portion of current formulas in math-mode.
151 @item [prefix] t k
152 @dots{} kill current typesetting process
153 @item [prefix] t b
154 @dots{} invoke bibtex
155 @item [prefix] t i
156 @dots{} invoke makeindex
157 @item [prefix] t d
158 @dots{} invoke latex && dvipdfmx
159 @item [prefix] t p
160 @dots{} preview
161 @item [prefix] t l
162 @dots{} lpr dvi-file
163 @item [prefix] t s
164 @dots{} search current string on xdvi-remote
165 @end table
167 @menu
168 * Calling typesetter::
169 * Calling previewer::
170 * Printing out::
171 @end menu
173 @node Calling typesetter, Calling previewer, Typesetting, Typesetting
174 @comment node-name, next, previous, up
175 @section Calling typesetter
177 Typing @kbd{[prefix] t j}, the current editing window will be divided
178 horizontally when you invoke latex command, and log message of La@TeX{}
179 typesetting will be displayed in the other window; called typesetting
180 buffer. The typesetting buffer automatically scrolls up and traces
181 La@TeX{} warnings and error messages. If you see latex stopping by an
182 error, you can send string to latex in the typesetting buffer.
184 If an error stops the La@TeX{} typesetting, this key stroke will
185 move the cursor to the line where La@TeX{} error is detected.
187 @table @kbd
188 @item [prefix] '
189 @itemx ([prefix]+single quotation)
191 @dots{} jump to the previous error or warning
192 @end table
194 If you find a noticeable error, move to the typesetting buffer and move
195 the cursor on the line of error message and type @kbd{SPACE} key. This
196 makes the cursor move to corresponding source line.
198 Since @kbd{[prefix] tr} pastes the region into the file
199 @file{texput.tex} in the current directory, you should be careful of
200 overwriting. The method of specification of the region is shown in the
201 section @xref{%#notation}.
203 The documentclass for typeset-region is the same as that of editing
204 file if you edit one file, and is the same as main file's if you
205 edit splitting files.
207 The @kbd{[prefix] te} key automatically marks current inner environment
208 or inner math mode and then call typeset-region with marked region. This
209 is convenient to quick view of current tabular environment or current
210 editing formulas. Keeping previewer window for @file{texput.dvi} is
211 handy for debugging.
213 @node Calling previewer, Printing out, Calling typesetter, Typesetting
214 @comment node-name, next, previous, up
215 @section Calling previewer
217 @kbd{[prefix] t p} invokes the TeX previewer. And if you are using
218 xdvi-remote, which can be controled from other terminals, @kbd{[prefix] t
219 s} enables you to search current string at the cursor on the running xdvi
220 window.
222 @node Printing out, , Calling previewer, Typesetting
223 @comment node-name, next, previous, up
224 @section Printing out
226 When you type @code{[preifx] t l}, YaTeX asks you the range of
227 dvi-printing by default. You can skip this by invoking it with
228 universal-argument as follows:
230 @example
231 C-u [prefix] tl
232 @end example
234 @node %#notation, Completion, Typesetting, Top
235 @comment node-name, next, previous, up
236 @chapter %# notation
237 @cindex %# notation
239 You can control the typesetting process by describing @code{%#}
240 notations in the source text.
242 @menu
243 * Changing typesetter::
244 * Splitting input files::
245 * Static region for typesetting::
246 * Lpr format::
247 * Editing %# notation::
248 @end menu
250 @node Changing typesetter, Splitting input files, %#notation, %#notation
251 @comment node-name, next, previous, up
252 @section To change the `latex' command or to split a source text.
253 @cindex typesetter
255 To change the typesetting command, write
257 @example
258 %#!latex-big
259 @end example
261 @noindent
262 anywhere in the source text. This is useful for changing
263 typesetter.
265 @node Splitting input files, Static region for typesetting, Changing typesetter, %#notation
266 @comment node-name, next, previous, up
267 @section Splitting input files
269 And if you split the source text and
270 edit subfile that should be included from main text.
272 @example
273 %#!latex main.tex
274 @end example
276 @noindent
277 will be helpful to execute latex on main file from sub text buffer. Since
278 this command line after @kbd{%#!} will be sent to shell literally, next
279 description makes it convenient to use ghostview as dvi-previewer.
281 @example
282 %#!latex main ; dvi2ps main.dvi > main
283 @end example
285 @noindent
286 Note that YaTeX assumes the component before the last period of
287 the last word in this line as base name of the main La@TeX{} source.
288 The @code{%f} notation in this line is replaced by main file name, and
289 @code{%r} replaced by root name of main file name. If you specify
290 @code{%f} or @code{%r}, YaTeX always ask you the name of main file at the
291 first typesetting.
293 To make best use of the feature of inter-file jumping by
294 @kbd{[prefix] g} (see @ref{Cursor jump}), take described below into
295 consideration.
297 @itemize
298 @item You can put split texts in sub directory, but not in
299 sub directory of sub directory.
300 @item In the main text, specify the child file name with relative path name
301 such as \include@{chap1/sub@}, when you include the file in
302 a sub-directory.
303 @item In a sub-text, write @code{%#!latex main.tex} even if @file{main.tex}
304 is in the parent directory(not %#!latex ../main.tex).
305 @end itemize
307 @node Static region for typesetting, Lpr format, Splitting input files, %#notation
308 @comment node-name, next, previous, up
309 @section Static region
310 @cindex static region
311 @cindex Fixed region
313 Typeset-region by @kbd{[prefix] tr} passes the region between point and
314 mark to typesetting command by default. But when you want to typeset
315 static region, enclose the region by @code{%#BEGIN} and @code{%#END} as
316 follows.
318 @example
319 %#BEGIN
320 TheRegionYouWantToTypesetManyTimes
321 %#END
322 @end example
324 This is the rule of deciding the region.
326 @enumerate
327 @item
328 If there exists %#BEGIN before point,
330 @enumerate
331 @item
332 If there exists %#END after %#BEGIN,
333 @itemize
334 @item From %#BEGIN to %#END.
335 @end itemize
337 @item
338 If %#END does not exist after %#BEGIN,
339 @itemize
340 @item From %#BEGIN to the end of buffer.
341 @end itemize
342 @end enumerate
344 @item
345 If there does not exist %#BEGIN before point,
346 @itemize
347 @item Between point and mark(standard method of Emacs).
348 @end itemize
349 @end enumerate
351 It is useful to write @code{%#BEGIN} in the previous line of \begin and
352 @code{%#END} in the next line of \@code{end} when you try complex
353 environment such as `tabular' many times. It is also useful to put only
354 @code{%#BEGIN} alone at the middle of very long text. Do not forget to
355 erase @code{%#BEGIN} @code{%#END} pair.
357 @node Lpr format, Editing %# notation, Static region for typesetting, %#notation
358 @comment node-name, next, previous, up
359 @section Lpr format
360 @cindex lpr format
362 Lpr format is specified by three Lisp variables. Here are the
363 default values of them.
365 @table @code
366 @item (1)dviprint-command-format
367 @code{"dvi2ps %f %t %s | lpr"}
368 @item (2)dviprint-from-format
369 @code{"-f %b"}
370 @item (3)dviprint-to-format
371 @code{"-t %e"}
372 @end table
374 On YaTeX-lpr, @code{%s} in (1) is replaced by the file name of main
375 text, @code{%f} by contents of (2), %t by contents of (3). At these
376 replacements, @code{%b} in (2) is also replaced by the number of beginning
377 page, @code{%e} in (3) is replaced by the number of ending page. But
378 @code{%f} and @code{%t} are ignored when you omit the range of print-out
379 by @kbd{C-u [prefix] tl}.
381 If you want to change this lpr format temporarily, put a command
382 such as follows somewhere in the text:
384 @example
385 %#LPR dvi2ps %f %t %s | 4up -page 4 | texfix | lpr -Plp2
386 @end example
388 And if you want YaTeX not to ask you the range of printing
389 out, the next example may be helpful.
391 @example
392 %#LPR dvi2ps %s | lpr
393 @end example
395 @node Editing %# notation, , Lpr format, %#notation
396 @comment node-name, next, previous, up
397 @section Editing %# notation
399 To edit @code{%#} notation described above, type
401 @table @kbd
402 @item [prefix] %
403 @dots{} editing %# notation menu
404 @end table
406 @noindent
407 and select one of the entry of the menu as follows.
409 @example
410 !)Edit-%#! B)EGIN-END-region L)Edit-%#LPR
411 @end example
413 @noindent
414 Type @kbd{!} to edit @code{%#!} entry, @code{b} to enclose the region with
415 @code{%#BEGIN} and @code{%#END}, and @code{l} to edit @code{%#LPR} entry.
416 When you type @kbd{b}, all @code{%#BEGIN} and @code{%#END} are
417 automatically erased.
419 @node Completion, Local dictionaries, %#notation, Top
420 @comment node-name, next, previous, up
421 @chapter Completion
422 @cindex completion
424 YaTeX makes it easy to input the La@TeX{} commands. There are several
425 kinds of completion type, begin-type, section-type, large-type, etc...
427 @menu
428 * Begin-type completion::
429 * Section-type completion::
430 * Large-type completion::
431 * Maketitle-type completion::
432 * Arbitrary completion::
433 * End completion::
434 * Accent completion::
435 * Image completion::
436 * Greek letters completion::
437 @end menu
439 @node Begin-type completion, Section-type completion, Completion, Completion
440 @comment node-name, next, previous, up
441 @section Begin-type completion
442 @cindex begin-type completion
443 @cindex environment
444 @cindex prefix b
446 "Begin-type completion" completes commands of @code{\begin@{env@}} ...
447 @code{\end@{env@}}. All of the begin-type completions begin with this key
448 sequence.
450 @table @kbd
451 @item [prefix] b
452 @dots{} start begin-type completion
453 @end table
455 @noindent
456 An additional key stroke immediately completes a frequently used
457 La@TeX{} @code{\begin@{@}}...@code{\@code{end}@{@}} environment.
459 @table @kbd
460 @item [prefix] b c
461 @dots{} @code{\begin@{center@}...\end@{center@}}
462 @item [prefix] b d
463 @dots{} @code{\begin@{document@}...\end@{document@}}
464 @item [prefix] b D
465 @dots{} @code{\begin@{description@}...\end@{description@}}
466 @item [prefix] b e
467 @dots{} @code{\begin@{enumerate@}...\end@{enumerate@}}
468 @item [prefix] b E
469 @dots{} @code{\begin@{equation@}...\end@{equation@}}
470 @item [prefix] b i
471 @dots{} @code{\begin@{itemize@}...\end@{itemize@}}
472 @item [prefix] b l
473 @dots{} @code{\begin@{flushleft@}...\end@{flushleft@}}
474 @item [prefix] b m
475 @dots{} @code{\begin@{minipage@}...\end@{minipage@}}
476 @item [prefix] b t
477 @dots{} @code{\begin@{tabbing@}...\end@{tabbing@}}
478 @item [prefix] b T
479 @dots{} @code{\begin@{tabular@}...\end@{tabular@}}
480 @item [prefix] b^T
481 @dots{} @code{\begin@{table@}...\end@{table@}}
482 @item [prefix] b p
483 @dots{} @code{\begin@{picture@}...\end@{picture@}}
484 @item [prefix] b q
485 @dots{} @code{\begin@{quote@}...\end@{quote@}}
486 @item [prefix] b Q
487 @dots{} @code{\begin@{quotation@}...\end@{quotation@}}
488 @item [prefix] b r
489 @dots{} @code{\begin@{flushright@}...\end@{flushright@}}
490 @item [prefix] b v
491 @dots{} @code{\begin@{verbatim@}...\end@{verbatim@}}
492 @item [prefix] b V
493 @dots{} @code{\begin@{verse@}...\end@{verse@}}
494 @end table
496 Any other La@TeX{} environments are made by completing-read of the
497 Emacs function.
499 @table @kbd
500 @item [prefix] b SPACE
501 @dots{} begin-type completion
502 @end table
504 @noindent
505 The next message will show up in the minibuffer
507 @example
508 Begin environment(default document):
509 @end example
511 @noindent
512 by typing @kbd{[prefix] b}. Put the wishing environment with completion
513 in the minibuffer, and @code{\begin@{env@}}...\@code{\end@{env@}} will be
514 inserted in the La@TeX{} source text. If the environment you want to put
515 does not exist in the YaTeX completion table, it will be registered in the
516 user completion table. YaTeX automatically saves the user completion
517 table in the user dictionary file at exiting of emacs.
519 At the completion of certain environments, the expected initial entry will
520 automatically inserted such as @code{\item} for @code{itemize}
521 environment. If you don't want the entry, it can be removed by undoing.
523 If you want to enclose some paragraphs which have already been
524 written, invoke the begin-type completion with changing the case
525 of @kbd{b} of key sequence upper(or invoke it with universal argument
526 by @kbd{C-u} prefix).
527 @cindex enclose region into environment
529 The following example encloses a region with `description'
530 environment.
532 @table @kbd
533 @item [prefix] B D
534 @itemx (or ESC 1 [prefix] b D)
535 @itemx (or C-u [prefix] b D)
537 @dots{} begin-type completion for region
538 @end table
540 This enclosing holds good for the completing input by @kbd{[prefix] b
541 SPC}. @kbd{[prefix] B SPC} enclose a region with the environment selected
542 by completing-read.
544 @node Section-type completion, Large-type completion, Begin-type completion, Completion
545 @comment node-name, next, previous, up
546 @section Section-type completion
547 @cindex section-type completion
548 @cindex prefix s
550 "Section-type completion" completes section-type commands which take an
551 argument or more such as @code{\section@{foo@}}. To invoke section-type
552 completion, type
554 @table @kbd
555 @item [prefix] s
556 @dots{} section-type completion
557 @end table
559 @noindent
560 then the prompt
562 @example
563 (C-v for view) \???@{@} (default documentclass):
564 @end example
566 @noindent
567 will show up in the minibuffer. Section-type La@TeX{} commands are
568 completed by space key, and the default value is selected when you
569 type nothing in the minibuffer.
571 Next,
573 @example
574 \section@{???@}:
575 @end example
577 @noindent
578 prompts you the argument of section-type La@TeX{} command. For
579 example, the following inputs
581 @example
582 \???@{@} (default documentclass): section
583 \section@{???@}: Hello world.
584 @end example
586 @noindent
587 will insert the string
589 @example
590 \section@{Hello world.@}
591 @end example
593 in your La@TeX{} source. When you neglect argument such as
595 @example
596 (C-v for view) \???@{@} (default section): vspace*
597 \vspace*@{???@}:
598 @end example
600 YaTeX puts
602 @example
603 \vspace*@{@}
604 @end example
606 @noindent
607 and move the cursor in the braces.
609 In La@TeX{} command, there are commands which take more than one
610 arguments such as @code{\addtolength@{\topmargin@}@{8mm@}}. To complete these
611 commands, invoke section-type completion with universal argument as,
612 @cindex number of argument
614 @example
615 C-u 2 [prefix] s (or ESC 2 [prefix] s)
616 @end example
618 @noindent
619 and make answers in minibuffer like this.
621 @example
622 (C-v for view) \???@{@} (default vspace*): addtolength
623 \addtolength@{???@}: \topmargin
624 Argument 2: 8mm
625 @end example
627 @code{\addtolength} and the first argument @code{\topmargin} can be typed
628 easily by completing read. Since YaTeX also learns the number of
629 arguments of section-type command and will ask that many arguments in
630 future completion, you had better tell the number of arguments to YaTeX at
631 the first completion of the new word. But you can change the number of
632 arguments by calling the completion with different universal argument
633 again.
636 Invoking section-type completion with @code{[Prefix] S} (Capital `S')
637 includes the region as the first argument of section-type command.
639 The section/large/maketitle type completion can work at the
640 prompt for the argument of other section-type completion.
641 Nested La@TeX{} commands are efficiently read with the recursive
642 completion by typing YaTeX's completion key sequence in the
643 minibuffer.
645 @menu
646 * view-sectioning::
647 @end menu
649 @node view-sectioning, , Section-type completion, Section-type completion
650 @comment node-name, next, previous, up
651 @subsection view-sectioning
652 @cindex view sectioning
653 @cindex outline
655 In the minibuffer at the prompt of section-type command completion,
656 typing @kbd{C-v} shows a list of sectioning commands in source text(The
657 line with @code{<<--} mark is the nearest sectioning command). Then,
658 default sectioning command appears in the minibuffer. You can go up/down
659 sectioning command by typing @kbd{C-p}/@kbd{C-n}, can scrolls up/down the
660 listing buffer by @kbd{C-v}/@kbd{M-v}, and can hide sectioning commands
661 under certain level by 0 through 6. Type @kbd{?} in the minibuffer of
662 sectioning prompt for more information.
664 You can generate this listing buffer (@code{*Sectioning Lines*} buffer)
665 by typing
666 @table @kbd
667 @item M-x YaTeX-section-overview
668 @dots{} Generate *Sectioning Lines* buffer
669 @end table
670 @cindex{Generate the listing of sectioning units}
671 from the LaTeX source buffer. In this listing buffer, typing @kbd{u} on
672 the sectioning command shifts up the corresponding sectioning command in
673 source text and @kbd{d} shifts down. After marking lines in the listing
674 buffer, typing @kbd{U} shifts up all sectioning commands in the region,
675 and @kbd{U} shifts down. Here are all the key bindings of
676 @code{*Sectioning Lines*} buffer.
678 @table @kbd
679 @item SPC
680 @dots{} Jump to corresponding source line
681 @item .
682 @dots{} Display corresponding source line
683 @item u
684 @dots{} Shift up a sectioning line
685 @item d
686 @dots{} Shift down a sectioning line
687 @item U
688 @dots{} Shift up sectioning lines in region
689 @item D
690 @dots{} Shift down sectioning lines in region
691 @item 0@dots{}6
692 @dots{} Hide sectioning commands whose level is lower than n
693 @end table
696 @node Large-type completion, Maketitle-type completion, Section-type completion, Completion
697 @comment node-name, next, previous, up
698 @section Large-type completion
700 "Large-type completion" inputs the font or size changing
701 descriptions such as @code{@{\large @}}. When you type
703 @table @kbd
704 @item [prefix] l
705 @dots{} large-type completion
706 @end table
708 @noindent
709 the message in the minibuffer
711 @example
712 @{\??? @} (default large):
713 @end example
715 prompts prompts you large-type command with completing-read. There are
716 TeX commands to change fonts or sizes, @code{it}, @code{huge} and so on,
717 in the completion table.
719 Region-based completion is also invoked by changing the letter after
720 prefix key stroke as @kbd{[prefix] L}. It encloses the region by braces
721 with large-type command.
723 @node Maketitle-type completion, Arbitrary completion, Large-type completion, Completion
724 @comment node-name, next, previous, up
725 @section Maketitle-type completion
726 @cindex maketitle-type completion
728 We call it "maketitle-type completion" which completes commands such as
729 @code{\maketitle}. Take notice that maketitle-type commands take no
730 arguments. Then, typing
732 @table @kbd
733 @item [prefix] m
734 @dots{} maketitle-type completion
735 @end table
737 @noindent
738 begins maketitle-completion. Above mentioned method is true for
739 maketitle-completion, and there are La@TeX{} commands with no
740 arguments in completion table.
742 @node Arbitrary completion, End completion, Maketitle-type completion, Completion
743 @comment node-name, next, previous, up
744 @section Arbitrary completion
745 @cindex arbitrary completion
747 @noindent
748 You can complete certain La@TeX{} command anywhere without typical
749 completing method as described, by typing
751 @table @kbd
752 @item [prefix] SPC
753 @dots{} arbitrary completion
754 @end table
756 @noindent
757 after the initial string of La@TeX{} command that is preceded by @code{\}.
759 @node End completion, Accent completion, Arbitrary completion, Completion
760 @comment node-name, next, previous, up
761 @section End completion
762 @cindex end completion
764 @noindent
765 YaTeX automatically detects the opened environment and close it with
766 \@code{\end@{environment@}}. Though proficient YaTeX users never fail to
767 make environment with begin-type completion, some may begin an environment
768 manually. In that case, type
770 @table @kbd
771 @item [prefix] e
772 @dots{} @code{end} completion
773 @end table
775 @noindent
776 at the end of the opened environment.
778 @node Accent completion, Image completion, End completion, Completion
779 @comment node-name, next, previous, up
780 @section Accent completion
781 @cindex accent completion
783 When you want to write the European accent marks(like @code{\`@{o@}}),
785 @table @kbd
786 @item [prefix] a
787 @dots{} accent completion
788 @end table
790 @noindent
791 shows the menu
793 @example
794 1:` 2:' 3:^ 4:" 5:~ 6:= 7:. u v H t c d b
795 @end example
797 @noindent
798 in the minibuffer. Chose one character or corresponding numeric,
799 and you will see
801 @example
802 \`@{@}
803 @end example
805 @noindent
806 in the editing buffer with the cursor positioned in braces. Type
807 one more character `o' for example, then
809 @example
810 \`@{o@}
811 @end example
813 @noindent
814 will be completed, and the cursor gets out from braces.
816 @node Image completion, Greek letters completion, Accent completion, Completion
817 @comment node-name, next, previous, up
818 @section Image completion of mathematical sign
819 @cindex image completion
820 @cindex math-mode
821 @cindex sigma
822 @cindex leftarrow
823 @cindex ;
825 Arrow marks, sigma mark and those signs mainly used in the
826 TeX's math environment are completed by key sequences which
827 imitate the corresponding symbols graphically. This completion
828 only works in the math environment. YaTeX automatically detects
829 whether the cursor located in math environment or not, and
830 change the behavior of key strokes @kbd{;} and @kbd{:}.
832 By the way, we often express the leftarrow mark by `<-' for example.
833 Considering such image, you can write @code{\leftarrow} by typing @kbd{<-}
834 after @kbd{;} (semicolon) as a prefix. In the same way,
835 @code{\longleftarrow} (@code{<--}) is completed by typing @kbd{;<--},
836 infinity mark which is imitated by @code{oo} is completed by typing
837 @kbd{;oo}.
839 Here are the sample operations in YaTeX math-mode.
841 @example
842 INPUT Completed La@TeX{} commands
843 ; < - @code{\leftarrow}
844 ; < - - @code{\longleftarrow}
845 ; < - - > @code{\longleftrightarrow}
846 ; o @code{\circ}
847 ; o o @code{\infty}
848 @end example
850 In any case, you can quit from image completion and can move
851 to the next editing operation if the La@TeX{} command you want is
852 shown in the buffer.
854 @code{;} itself in math-environment is inserted by @kbd{;;}. Typing
855 @kbd{TAB} in the midst of image completion shows all of the La@TeX{}
856 commands that start with the same name as string you previously typed in.
857 In this menu buffer, press @kbd{RET} after moving the cursor (by @kbd{n},
858 @kbd{p}, @kbd{b}, @kbd{f}) to insert the La@TeX{} command.
860 To know all of the completion table, type @kbd{TAB} just after @kbd{;}.
861 And here is the sample menu by @kbd{TAB} after @kbd{;<}.
863 @example
864 KEY LaTeX sequence sign
865 < \leq <
866 ~
867 << \ll <<
868 <- \leftarrow <-
869 <= \Leftarrow <=
870 @end example
872 You can define your favorite key-vs-sequence completion table in the
873 Emacs-Lisp variable @code{YaTeX-math-sign-alist-private}. See also
874 @file{yatexmth.el} for the information of the structure of this variable.
876 @node Greek letters completion, , Image completion, Completion
877 @comment node-name, next, previous, up
878 @section Greek letters completion
879 @cindex Greek letters completion
880 @cindex :
882 Math-mode of YaTeX provides another image completion, Greek letters
883 completion in the same method. After prefix @kbd{:}, typing @kbd{a} makes
884 @code{\alpha}, @kbd{b} makes @code{\beta} and @kbd{g} makes @code{\gamma}
885 and so on. First, type @kbd{:TAB} to know all the correspondence of
886 alphabets vs. Greek letters.
888 If you will find @kbd{;} or @kbd{:} doesn't work in correct position of
889 math environment, it may be a bug of YaTeX. Please send me a bug report
890 with the configuration of your text, and avoid it temporarily by typing
891 @kbd{;} or @kbd{:} after universal-argument(@kbd{C-u}) which forces
892 @kbd{;} and @kbd{:} to work as math-prefix.
894 @node Local dictionaries, Commenting out, Completion, Top
895 @comment node-name, next, previous, up
896 @chapter Local dictionaries
897 @cindex local dictionaries
898 @cindex nervous users
900 Tables for completion consist of three dictionaries; `standard
901 dictionary' built in @file{yatex.el}, `user dictionary' for your common
902 private commands, and `local dictionary' that is effective in a certain
903 directory.
905 When you input the command unknown to YaTeX at a completion in the
906 minibuffer, YaTeX asks you with the following prompt;
908 @example
909 `foo' is not in table. Register into: U)serDic L)ocalDic N)one D)iscard
910 @end example
912 @noindent
913 In this menu, typing @kbd{u} updates your `user dictionary', @kbd{l}
914 updates your local dictionary, @kbd{n} updates only on-memory dictionary
915 which go through only current Emacs session, and @kbd{d} updates no
916 dictionary and throws the new word away.
918 If you find this switching feature meaningless and bothersome, put the
919 next expression into your @file{~/.emacs}
921 @lisp
922 (setq YaTeX-nervous nil)
923 @end lisp
925 @node Commenting out, Cursor jump, Local dictionaries, Top
926 @comment node-name, next, previous, up
927 @chapter Commenting out
928 @cindex commenting out
929 @cindex prefix >
930 @cindex prefix <
931 @cindex prefix ,
932 @cindex prefix .
934 You may want to comment out some region.
936 @table @kbd
937 @item [prefix] >
938 @dots{} comment out region by %
939 @item [prefix] <
940 @dots{} uncomment region
941 @end table
943 @noindent
944 cause an operation to the region between point and mark.
946 @table @kbd
947 @item [prefix] .
948 @dots{} comment out current paragraph
949 @item [prefix] ,
950 @dots{} uncomment current paragraph
951 @end table
953 @noindent
954 comments or uncomments the paragraph where the cursor belongs.
955 This `paragraph' means the region marked by the function
956 mark-paragraph, bound to @kbd{ESC h} by default. It is NOT
957 predictable what will happen when you continuously comment out
958 some paragraph many times.
960 You can also comment out an environment between @code{\begin} and
961 @code{\end}, or a @code{\begin}-\@code{\end} pair themselves, by making the
962 following key strokes on the line where @code{\begin@{@}} or
963 @code{\end@{@}} exists.
965 @table @kbd
966 @item [prefix] >
967 @dots{} comment out from \begin to \@code{end}
968 @item [prefix] <
969 @dots{} uncomment from \begin to \@code{end}
970 @end table
972 @noindent
973 comment whole the contents of environment. Moreover,
975 @table @kbd
976 @item [prefix] .
977 @dots{} comment out \begin and \@code{end}
978 @item [prefix] ,
979 @dots{} uncomment \begin and \@code{end}
980 @end table
982 @noindent
983 (un)comments out only environment declaration: @code{\begin@{@}} and
984 @code{\end@{@}}. NOTE that even if you intend to comment out some region,
985 invoking @kbd{[prefix] >} on the @code{\begin},@code{\end} line decides to
986 work in `commenting out from @code{\begin} to @code{\end}' mode.
989 @node Cursor jump, Changing and Deleting, Commenting out, Top
990 @comment node-name, next, previous, up
991 @chapter Cursor jump
992 @cindex cursor jump
993 @cindex prefix g
996 @menu
997 * Jump to corresponding object::
998 * Invoking image processor::
999 * Jump to main file::
1000 * Jumping around the environment::
1001 * Jumping to last completion position::
1002 @end menu
1004 @node Jump to corresponding object, Invoking image processor, Cursor jump, Cursor jump
1005 @comment node-name, next, previous, up
1006 @section Jump to corresponding object
1008 Typing
1010 @table @kbd
1011 @item [prefix] g
1012 @dots{} go to corresponding object
1013 @end table
1015 @noindent
1016 in a certain place move the cursor to the place corresponding to the
1017 La@TeX{} command of last place. YaTeX recognize the followings as pairs
1018 that have relation each other.
1020 @itemize @bullet
1021 @item @code{\begin@{@}} <-> @code{\end@{@}}
1022 @item @code{%#BEGIN} <-> @code{%#END}
1023 @item On the image-including line -> corresponding viewer or drawing tool
1024 @item @code{\label@{@}} <-> @code{\ref@{@}}
1025 @item @code{\include(\input)} -> included file
1026 @item @code{\bibitem@{@}} <-> @code{\cite@{@}}
1027 @end itemize
1029 On a @code{\begin},@code{\end} line, typing @kbd{[prefix] g} moves the
1030 cursor to the corresponding @code{\end},@code{\begin} line, if its partner
1031 really exists. The behavior on the line @code{%#BEGIN} and @code{%#END}
1032 are the same. Note that if the correspondent of @code{label/ref} or
1033 @code{cite/bibitem} exists in another file, that file have to be opened to
1034 make a round trip between references by @kbd{[prefix] g}.
1036 If you type @code{[prefix] g} on the line of @code{\include@{chap1@}},
1037 typically in the main text, YaTeX switches buffer to @file{chap1.tex}.
1039 @table @kbd
1040 @item [prefix] 4 g
1041 @dots{} go to corresponding object in other window
1042 @end table
1044 @noindent
1045 do the same job as @kbd{[prefix] g} except it's done in other window.
1046 Note that this function doesn't work on @code{begin/end},
1047 @code{%#BEGIN/%#END} pairs because it is meaningless.
1049 @node Invoking image processor, Jump to main file, Jump to corresponding object, Cursor jump
1050 @comment node-name, next, previous, up
1051 @section Invoking image processor
1052 @cindex{Drawing tool invocation}
1054 `image-including line' described above means such lines as
1055 @code{\epsfile@{file=foo.ps@}}. If you type @kbd{[prefix] g} on that
1056 line, YaTeX automatically searches source of `foo.ps' and invokes image
1057 viewer or drawing tool correspoinding to it. For example; if you draw
1058 an image foo.obj with Tgif and enclose its product named foo.eps by
1059 @code{\epsfile} command. Typing @kbd{[prefix] g} on @code{\epsfile} line
1060 make YaTeX invoke @code{tgif foo.obj}. How a processor is choosen is as
1061 follows.
1063 @enumerate
1064 @item
1065 If there is an expression matching with one of the pattern
1066 defined in @code{YaTeX-processed-file-regexp-alist}, extract file name
1067 from regexp group surrounded by \\(\\). (Which group corresponds is
1068 written in the cdr part of each list.) If no matches were found, do
1069 nothing.
1070 @item
1071 If there is a pattern as `%PROCESSOR' which is defined in the variable
1072 @code{YaTeX-file-processor-alist}, call that processor giving the
1073 file name with corresponding extension.
1074 @item
1075 If not, check the existence of each file which is supplied the
1076 extension in the cdr part of each list of
1077 @code{YaTeX-file-processor-alist}. If any, call the corresponding
1078 image viewer or drawing tool.
1079 @end enumerate
1081 @node Jump to main file, Jumping around the environment, Invoking image processor, Cursor jump
1082 @comment node-name, next, previous, up
1083 @section Jump to main file
1085 Typing
1087 @table @kbd
1088 @item [prefix] ^
1089 @dots{} visit main file
1090 @item [prefix] 4^
1091 @dots{} visit main file in other buffer
1092 @end table
1093 @cindex prefix ^
1094 @cindex prefix 4 ^
1096 in a sub text switch the buffer to the main text specified by
1097 @code{%#!} notation.
1099 @node Jumping around the environment, Jumping to last completion position, Jump to main file, Cursor jump
1100 @comment node-name, next, previous, up
1101 @section Jumping around the environment
1103 And these are the functions which work on the current La@TeX{}
1104 environment:
1106 @table @kbd
1107 @item M-C-a
1108 @dots{} beginning of environment
1109 @item M-C-e
1110 @dots{} @code{end} of environment
1111 @item M-C-@@
1112 @dots{} mark environment
1113 @end table
1114 @cindex M-C-a
1115 @cindex M-C-e
1116 @cindex M-C-@@
1118 @node Jumping to last completion position, , Jumping around the environment, Cursor jump
1119 @comment node-name, next, previous, up
1120 @section Jumping to last completion position
1122 YaTeX always memorize the position of completion into register @code{3}.
1123 So every time you make a trip to any other part of text other than you are
1124 writing, you can return to the editing paragraph by calling
1125 register-to-point with argument YaTeX-current-position-register, which is
1126 achieved by typing @kbd{C-x j 3}(by default).
1128 @node Changing and Deleting, Filling, Cursor jump, Top
1129 @comment node-name, next, previous, up
1130 @chapter Changing and Deleting
1132 These functions are for change or deletion of La@TeX{} commands
1133 already entered.
1135 @table @kbd
1136 @item [prefix] c
1137 @dots{} change La@TeX{} command
1138 @item [prefix] k
1139 @dots{} kill La@TeX{} command
1140 @end table
1141 @cindex prefix c
1142 @cindex prefix k
1144 @menu
1145 * Changing LaTeX commands::
1146 * Killing LaTeX commands::
1147 @end menu
1149 @node Changing LaTeX commands, Killing LaTeX commands, Changing and Deleting, Changing and Deleting
1150 @comment node-name, next, previous, up
1151 @section Changing La@TeX{} commands
1153 @kbd{[prefix] c} can change the various (La)@TeX{} commands. This can
1154 change the followings.
1155 @itemize @bullet
1156 @item Environment names
1157 @item Section-type commands
1158 @item Argument of section-type commands
1159 @item Optional parameters (enclosed by []) of section-type commands
1160 @item Font/size designators
1161 @item Math-mode's maketitle-type commands that can be inputted with
1162 image completion
1163 @end itemize
1165 Typing @kbd{[prefix] c} on one of above objects you want to change
1166 brings a suitable reading function sometimes with completion.
1167 Note: If you want to change the argument of section-type command that
1168 contains other La@TeX{} commands, type @kbd{[prefix] c} either of
1169 surrounding braces of the argument in order to make YaTeX ignore the
1170 internal La@TeX{} sequences as an object of changing. Anyway, it is
1171 very difficult to know which argument position the cursor belongs because
1172 the La@TeX{} commands can be nested and braces can freely emerge. So keep
1173 it mind to put the cursor on a brace when you are thinking of changing a
1174 complicated argument.
1176 @node Killing LaTeX commands, , Changing LaTeX commands, Changing and Deleting
1177 @comment node-name, next, previous, up
1178 @section Killing La@TeX{} commands
1179 @cindex Killing La@TeX{} commands
1181 @kbd{[prefix] k} kills the La@TeX{} commands sometimes with their
1182 arguments. Following table illustrates the correspondence of the invoking
1183 position and what is killed.
1185 @example
1186 [Invoking position] [action]
1187 \begin, \end line kill \begin,\end pairs
1188 %#BEGIN, %#END line kill %#BEGIN,%#END pairs
1189 on a Section-type command kill section-type command
1190 on a parenthesis kill parentheses
1191 @end example
1193 Note that when killing @code{\begin, \end} or @code{%#BEGIN, %#END} pair,
1194 the lines @code{\begin, \end} or @code{%#BEGIN, %#END} exist will be
1195 killed entirely. So take care not to create any line that contains more
1196 than one @code{\begin} or so.
1198 While all operations above are to kill `containers' which surround some
1199 text, universal argument (@kbd{C-u}) for these commands kills not only
1200 `containers' but also `contents' of them. See below as a sample.
1202 @example
1203 Original text: [prefix] k C-u [prefix] k
1204 Main \footnote@{note@} here. Main note here. Main here.
1205 ~(cursor)
1206 @end example
1208 @node Filling, Updation of includeonly, Changing and Deleting, Top
1209 @comment node-name, next, previous, up
1210 @chapter Filling
1211 @cindex filling
1213 @section Filling an item
1214 @cindex filling an item
1215 @cindex prefix i
1217 To fill a term (descriptive sentences) of @code{\item}, type
1219 @c @table @kbd
1220 @c @item [prefix] i
1221 @c @dots{} fill item
1222 @c @end table
1223 @table @kbd
1224 @item M-q
1225 @dots{} fill item
1226 @end table
1228 @noindent
1229 on that item.
1231 YaTeX uses the value of the variable @code{YaTeX-item-regexp} as the
1232 regular expression to search item header in itemize environment.
1233 If you make a newcommand to itemize terms(e.g. @code{\underlineitem}), put
1235 @lisp
1236 (setq YaTeX-item-regexp
1237 "\\(\\\\\\(sub\\)*item\\)\\|\\(\\\\underlineitem\\)")
1238 @end lisp
1239 @cindex YaTeX-item-regexp
1241 in your @file{~/.emacs}. If you are not familiar with regular expression
1242 for Emacs-Lisp, name a newcommand for `itemize' beginning with
1243 @code{\item} such as @code{\itembf}, not @code{\bfitem}.
1245 This function reformats the @code{\item} into `hang-indented' style.
1246 For example:
1248 @example
1249 itemize, enumerate environment:
1250 >
1251 >\item[foo] `foo' is the typical word for describing an
1252 > arbitrarily written....
1253 description environment:
1254 > \item[bar] When the word `for' is used as an arbitrarily
1255 > word, `bar' is bound to follow it.
1256 @end example
1258 Note that the indent depth of an @code{\item} word and its descriptive
1259 paragraph are the same in latter case. If you want to use different
1260 depth, invoke fill-paragraph at the beginning of non-whitespace
1261 character(see below).
1263 @section Filling paragraph
1264 @cindex Filling paragraph
1265 @cindex M-q
1267 Fill-paragraph is little bit adapted for La@TeX{} sources. It retains from
1268 filling in certain environments where formatting leads to a disaster such
1269 as verbatim, tabular, or so. And it protects @code{\verb} expressions
1270 from being folded (The variable @code{YaTeX-verb-regexp} controls this).
1271 Besides, putting cursor on the first occurrence of non-whitespace
1272 character on a line changes the fill-prefix temporarily to the depth of
1273 the line.
1275 @node Updation of includeonly, What column, Filling, Top
1276 @comment node-name, next, previous, up
1277 @chapter Updation of @code{\includeonly}
1278 @cindex includeonly
1280 When you edit splitting source texts, the notation
1282 @example
1283 \includeonly@{CurrentEditingFileName@}
1284 @end example
1286 @noindent
1287 in the main file reduces the time of typesetting. If you want
1288 to hack other file a little however, you have to rewrite it to
1290 @example
1291 \includeonly@{OtherFileNameYouWantToFix@}
1292 @end example
1294 @noindent
1295 in the main file. YaTeX automatically detects that the current
1296 edited text is not in includeonly list and prompts you
1298 @example
1299 A)dd R)eplace %)comment?
1300 @end example
1302 in the minibuffer. Type @kbd{a} if you want to add the current file name
1303 to @code{\includeonly} list, @kbd{r} to replace \@code{includeonly} list
1304 with the current file, and type @kbd{%} to comment out the
1305 @code{\includeonly} line.
1307 @node What column, Intelligent newline, Updation of includeonly, Top
1308 @comment node-name, next, previous, up
1309 @chapter What column?
1310 @cindex what column
1311 @cindex complex tabular
1312 @cindex prefix &
1314 We are often get tired of finding the corresponding column in
1315 large tabulars. For example,
1317 @example
1318 \begin@{tabular@}@{|c|c|c|c|c|c|c|c|@}\hline
1319 Name&Position&Post No.&Addr.&Phone No.&FAX No.&
1320 Home Addr.&Home Phone\\ \hline
1321 Thunder Bird & 6 & 223 & LA & xxx-yyy &
1322 zzz-www & Japan & 9876-54321 \\
1323 & 2 & \multicolumn@{2@}@{c|@}@{Unknown@}
1324 &&&(???)
1325 \\ \hline
1326 \end@{tabular@}
1327 @end example
1329 Suppose you have the cursor located at @code{(???)} mark, can you tell
1330 which column it is belonging at once? Maybe no. In such case,
1331 type
1333 @table @kbd
1334 @item [prefix] &
1335 @dots{} What column
1336 @end table
1338 @noindent
1339 in that position. YaTeX tells you the column header of the
1340 current field. Since YaTeX assumes the first line of tabular
1341 environment as a row of column headers, you can create a row of
1342 virtual column headers by putting them in the first line and
1343 commenting that line with @code{%}.
1345 @node Intelligent newline, Usepackage checker, What column, Top
1346 @comment node-name, next, previous, up
1347 @chapter Intelligent newline
1348 @cindex Intelligent newline
1349 @cindex ESC RET
1350 @cindex M-C-m
1352 At the end of begin-type completion of tabular[*], array, itemize,
1353 enumerate or tabbing environment, or typing
1355 @table @kbd
1356 @item ESC RET
1357 @dots{} Intelligent newline
1358 @end table
1360 @noindent
1361 in these environments inserts the contents corresponding to the current
1362 environment in the next line. (At the begin-type completion, this
1363 contents can be removed by `undo'.) In @code{tabular} environment, for
1364 example, @kbd{ESC RET} inserts the certain number of @code{&} and trailing
1365 @code{\\}, and @code{\hline} if other @code{\hline} is found in backward.
1366 Here are the list of contents vs. environments.
1368 @itemize
1369 @item @code{tabular}, @code{tabular*}, @code{array}
1371 Corresponding number of @code{&} and @code{\\}.
1372 And @code{\hline} if needed.
1374 @item @code{tabbing}
1376 The same number of @code{\>} as @code{\=} in the first line.
1378 @item @code{itemize}, @code{enumerate}, @code{description}, @code{list}
1380 @code{\item} or @code{item[]}.
1381 @end itemize
1383 Note that since this function works seeing the contents of the first
1384 line, please call this after the second line if possible.
1386 If you want to apply these trick to other environments, @code{foo}
1387 environment for example, define the function named
1388 @code{YaTeX-intelligent-newline-foo} to insert corresponding contents.
1389 That function will be called at the beginning of the next line after the
1390 newline is inserted to the current line. Since the function
1391 @code{YaTeX-indent-line} is designed to indent the current line properly,
1392 calling this function before your code to insert certain contents must be
1393 useful. See the definition of the function
1394 @code{YaTeX-intelligent-newline-itemize} as an example.
1396 @node Usepackage checker, Online help, Intelligent newline, Top
1397 @comment node-name, next, previous, up
1398 @chapter Usepackage checker
1399 @cindex usepackage
1401 When you input begint-type, section-type, maketitle-type macros with
1402 completion, and it requires some LaTeX2e package, YaTeX examines
1403 the existence of correct @code{\usepackage}. If not, YaTeX inserts
1404 the @code{\usepackage@{@}} declaration corresponding to input macro.
1406 To activate the package completion for your favarite package,
1407 set the variable @code{YaTeX-package-alist-private} correctly.
1408 Please refere the value of @code{YaTeX-package-alist-default} as an
1409 example.
1411 @node Online help, Browsing file hierarchy, Usepackage checker, Top
1412 @comment node-name, next, previous, up
1413 @chapter Online help
1414 @cindex online help
1415 @cindex prefix ?
1416 @cindex prefix /
1417 @cindex apropos
1418 @cindex keyword search
1420 YaTeX provides you the online help with popular La@TeX{} commands.
1422 Here are the key strokes for the online help.
1424 @table @kbd
1425 @item [prefix] ?
1426 @dots{} Online help
1427 @item [prefix] /
1428 @dots{} Online apropos
1429 @end table
1431 @section Online help
1433 `Online help' shows the documentation for the popular La@TeX{}
1434 commands(defaults to the commands on the cursor) in the next buffer.
1435 There are two help file, `global help' and `private help'. The former
1436 file contains the descriptions on the standard La@TeX{} command and is
1437 specified its name by variable @code{YaTeX-help-file}. Usually, the
1438 global help file should be located in public space (@code{$EMACSEXECPATH}
1439 by default) and should be world writable so that anyone can update it to
1440 enrich its contents. The latter file contains descriptions on
1441 non-standard or personal command definitions and is specified by
1442 @code{YaTeX-help-file-private}. This file should be put into private
1443 directory.
1445 @section Online apropos
1447 `Online apropos' is an equivalent of GNU Emacs's apropos. It
1448 shows all the documentations that contains the keyword entered by
1449 the user.
1451 @section When no descriptions are found...
1453 If there is no description on a command in help files, YaTeX
1454 requires you to write a description on that command. If you are
1455 willing to do, determine which help file to add and write the
1456 description on it referring your manual of (La)TeX. Please send
1457 me your additional descriptions if you describe the help on some
1458 standard commands. I might want to include it in the next
1459 distribution.
1461 @node Browsing file hierarchy, Cooperation with other packages, Online help, Top
1462 @comment node-name, next, previous, up
1463 @chapter Browsing file hierarchy
1464 @cindex hierarchy
1465 @cindex browsing
1467 When you are editing multi-file source, typing
1469 @table @kbd
1470 @item [prefix] d
1471 @dots{} browse file hierarchy
1472 @end table
1474 @noindent
1475 asks you the parent-most file (which may be defaulted) and displays the
1476 documentation hierarchy in the next window. In this buffer, the following
1477 commands are available.
1479 @table @kbd
1480 @item n
1481 @dots{} move to the next line and show its contents
1482 @item p
1483 @dots{} move to the previous line and show its contents
1484 @item N
1485 @dots{} move to the next file in the same inclusion level
1486 @item P
1487 @dots{} move to the previous file in the same inclusion level
1488 @item j
1489 @dots{} move to the next line
1490 @item k
1491 @dots{} move to the previous line
1492 @item u
1493 @dots{} move to the parent file
1494 @item .
1495 @dots{} show the current files contents in the next window
1496 @item SPC
1497 @dots{} scroll up the current file window
1498 @item DEL, b
1499 @dots{} scroll down the current file window
1500 @item <
1501 @dots{} show the beginning of the current file
1502 @item >
1503 @dots{} show the end of the current file
1504 @item >
1505 @dots{} return to the previous postion after @kbd{<} or @kbd{>}
1506 @item RET, g
1507 @dots{} open the current file in the next window
1508 @item mouse-2
1509 @dots{} same as RET(available only with window system)
1510 @item o
1511 @dots{} other window
1512 @item 1
1513 @dots{} delete other windows
1514 @item -
1515 @dots{} shrink hierarchy buffer window
1516 @item +
1517 @dots{} enlarge hierarchy buffer window
1518 @item ?
1519 @dots{} describe mode
1520 @item q
1521 @dots{} quit
1522 @end table
1524 Note that operations on the file contents in the next window do not work
1525 correctly when you close the corresponding file.
1527 @node Cooperation with other packages, Customizations, Browsing file hierarchy, Top
1528 @comment node-name, next, previous, up
1529 @chapter Cooperation with other packages
1531 YaTeX works better with other brilliant packages.
1533 @section gmhist
1534 @cindex gmhist
1535 @cindex command history
1536 @cindex minibuffer history
1538 When you are loading @file{gmhist.el} and @file{gmhist-mh.el}, you can
1539 use independent command history list at the prompt of preview command
1540 (@kbd{[prefix] tp}) and print command (@kbd{[prefix] tl}). On each
1541 prompt, you can enter the previous command line string repeatedly by
1542 typing @kbd{M-p}.
1544 @section min-out
1545 @cindex min-out
1547 @file{min-out}, the outline minor mode, can be used in yatex-mode
1548 buffers. If you want to use it with YaTeX, please refer the
1549 file @file{yatexm-o.el} as an example.
1551 @node Customizations, Etcetera, Cooperation with other packages, Top
1552 @comment node-name, next, previous, up
1553 @chapter Customizations
1554 @cindex customizations
1556 You can customize YaTeX by setting Emacs-Lisp variables and by making
1557 add-in functions.
1559 @menu
1560 * Lisp variables::
1561 * Add-in functions::
1562 * Add-in generator::
1563 @end menu
1565 @node Lisp variables, Add-in functions, Customizations, Customizations
1566 @comment node-name, next, previous, up
1567 @section Lisp variables
1568 @cindex customizable variables
1570 You can change the key assignments or make completion more comfortable
1571 by setting the values of various variables which control the movement of
1572 yatex-mode.
1574 For example, if you want to change the prefix key stroke from @kbd{C-c}
1575 to any other sequence, set YaTeX-prefix to whatever you want to use. If
1576 you don't want to use the key sequence @kbd{C-c letter} which is assumed
1577 to be the user reserved sequence in Emacs world, set
1578 @code{YaTeX-inhibit-prefix-letter} to @code{t}, and all of the default key
1579 bind of @kbd{C-c letter} will turn to the corresponding @kbd{C-c C-letter}
1580 (but the region based completions that is invoked with @kbd{C-c
1581 Capital-letter} remain valid, if you want to disable those bindings, set
1582 that variable to 1 instead of @code{t}).
1584 @menu
1585 * All customizable variables::
1586 * Sample definitions::
1587 * Hook variables::
1588 * Hook file::
1589 @end menu
1591 @node All customizable variables, Sample definitions, Lisp variables, Lisp variables
1592 @comment node-name, next, previous, up
1593 @subsection All customizable variables
1594 @cindex all customizable variables
1596 Here are the customizable variables of yatex-mode. Each value setq-ed
1597 in @file{~/.emacs} is preferred and that of defined in @file{yatex.el} is
1598 neglected. Parenthesized contents stands for the default value. When you
1599 are to change some of these variables, see more detailed documentation of
1600 the variable by @kbd{M-x describe-variable}.
1602 @defvar YaTeX-japan
1603 Set this nil to produce all messages in English
1604 (@code{Depends on Japanese feature of Emacs})
1605 @end defvar
1607 @defvar YaTeX-kanji-code
1608 Default buffer-file-coding-system for YaTeX modes' buffer.
1609 Set this 0 to no language conversion. Nil to preserve original
1610 coding-system. 1=Shift JIS, 2=JIS, 3=EUC, 4=UTF-8 (@code{1 or 2})
1611 @end defvar
1613 @defvar YaTeX-prefix
1614 Prefix key stroke (@kbd{C-c})
1615 @end defvar
1617 @defvar YaTeX-inhibit-prefix-letter
1618 Change key stroke from @kbd{C-c letter} to @kbd{C-c C-letter} (@code{nil})
1619 @end defvar
1621 @defvar YaTeX-fill-prefix
1622 Fill-prefix used in yatex-mode (@code{nil})
1623 @end defvar
1625 @defvar YaTeX-user-completion-table
1626 Name of user dictionary where learned completion table will be stored.
1627 (@code{"~/.yatexrc"})
1628 @end defvar
1630 @defvar tex-command
1631 La@TeX{} typesetter command (@code{"latex"})
1632 @end defvar
1634 @defvar dvi2-command
1635 Preview command (@code{"xdvi -geo +0+0 -s 4"})
1636 @end defvar
1638 @defvar dviprint-command-format
1639 Command format to print dvi file (@code{"dvi2ps %f %t %s | lpr"})
1640 @end defvar
1642 @defvar dviprint-from-format
1643 Start page format of above %f. %b will turn to start page (@code{"-f %b"})
1644 @end defvar
1646 @defvar dviprint-to-format
1647 End page format of above %t. %e will turn to @code{end} page (@code{"-t %e"})
1648 @end defvar
1650 @defvar makeindex-command
1651 Default makeindex command (@code{"makeindex"} (@code{"makeind"} on MS-DOS))
1652 @end defvar
1654 @defvar YaTeX-dvipdf-command
1655 Default command name to convert .dvi to PDF (@code{"dvipdfmx"})
1656 @end defvar
1658 @defvar YaTeX-need-nonstop
1659 Put @code{\nonstopmode@{@}} or not (@code{nil})
1660 @end defvar
1662 @defvar latex-warning-regexp
1663 Regular expression of warning message latex command puts out
1664 (@code{"line.* [0-9]*"})
1665 @end defvar
1667 @defvar latex-error-regexp
1668 Regular expression of error message (@code{"l\\.[1-9][0-9]*"})
1669 @end defvar
1671 @defvar latex-dos-emergency-message
1672 Message latex command running on DOS puts at abort (@code{"Emergency stop"})
1673 @end defvar
1675 @defvar YaTeX-item-regexp
1676 Regular expression of item command (@code{"\\\\item"})
1677 @end defvar
1679 @defvar YaTeX-verb-regexp
1680 Regexp of verb family. Omit \\\\. (@code{"verb\\*?\\|path"})
1681 @end defvar
1683 @defvar YaTeX-nervous
1684 T for using local dictionary (@code{t})
1685 @end defvar
1687 @defvar YaTeX-sectioning-regexp
1688 Regexp of La@TeX{} sectioning command
1689 (@code{"\\(part\\|chapter\\*?\\|\\(sub\\)*\\(section\\|paragraph\\)\\*?\\)\\b"})
1690 @end defvar
1692 @defvar YaTeX-fill-inhibit-environments
1693 Inhibit fill in these environments
1694 (@code{'("tabular" "tabular*" "array" "picture" "eqnarray" "eqnarray*" "equation" "math" "displaymath" "verbatim" "verbatim*")})
1695 @end defvar
1697 @defvar YaTeX-uncomment-once
1698 T for deleting all preceding @code{%} (@code{nil})
1699 @end defvar
1701 @defvar YaTeX-close-paren-always
1702 T for always close all parenthesis automatically, @code{nil} for only eol
1703 (@code{t})
1704 @end defvar
1706 @defvar YaTeX-auto-math-mode
1707 Switch math-mode automatically (@code{t})
1708 @end defvar
1710 @defvar YaTeX-math-key-list-private
1711 User defined alist, math-mode-prefix vs completion alist
1712 used in image completion (@code{nil}). See @file{yatexmth.el}
1713 for the information about how to define a completion alist.
1714 @end defvar
1716 @defvar YaTeX-default-pop-window-height
1717 Initial height of typesetting buffer when one-window.
1718 Number for the lines of the buffer, numerical string for
1719 the percentage of the screen-height. @code{nil} for half height (10)
1720 @end defvar
1722 @defvar YaTeX-help-file
1723 Global online help file name (@file{$doc-directory/../../site-lisp/YATEXHLP.eng})
1724 @end defvar
1726 @defvar YaTeX-help-file-private
1727 Private online help file name (@file{"~/YATEXHLP.eng"})
1728 @end defvar
1730 @defvar YaTeX-no-begend-shortcut
1731 Disable [prefix] b ?? shortcut (@code{nil)}
1732 @end defvar
1734 @defvar YaTeX-hilit-pattern-adjustment-private
1735 List of the list that contain the regular expression and the symbol of
1736 logical meaning of the string that matches the pattern. See also the
1737 value from @code{(assq 'yatex-mode hilit-patterns-alist)} and the value of
1738 @code{YaTeX-hilit-pattern-adjustment-default} (and even the document of
1739 hilit19.el).
1740 @end defvar
1742 @defvar YaTeX-sectioning-level
1743 Alist of LaTeX's sectioning command vs its height.
1744 @end defvar
1746 @defvar YaTeX-hierarchy-ignore-heading-regexp
1747 @code{YaTeX-display-hierarchy} searches for sectioning command first, and
1748 comment line secondary as a file headings. In latter case, ignore lines
1749 that match with regular expression of this variable. Default value of
1750 this variable is RCS header expressions and mode specifying line `-*- xxxx
1751 -*'.
1752 @end defvar
1754 @defvar YaTeX-skip-default-reader
1755 Non-nil for this variable skips the default argument reader of
1756 section-type command when add-in function for it is not defined
1757 (@code{nil})
1758 @end defvar
1760 @defvar YaTeX-create-file-prefix-g
1761 When typing @kbd{prefix g} on the @code{\include} line,
1762 open the target file even if the file doesn't exist (@code{nil})
1763 @end defvar
1765 @defvar YaTeX-simple-messages
1766 Simplyfy messages of various completions (@code{nil})
1767 @end defvar
1769 @defvar YaTeX-hilit-sectioning-face
1770 When hilit19 and yatex19 is active, YaTeX colors the sectioning commands.
1771 This variable specifies the foreground and background color of
1772 @code{\part} macro. The default value is @code{'(yellow/dodgerblue
1773 yellow/slateblue)}. The first element of this list is for the screen when
1774 @code{hilit-background-mode} is @code{'light}, and the second element is
1775 for @code{'dark}. You should specify both color as `forecolor/backcolor'.
1776 @end defvar
1778 @defvar YaTeX-hilit-sectioning-attenuation-rate
1779 When color mode, this variable specifies how much attenuate the color
1780 density of @code{\subparagraph} compared with that of @code{\chapter}
1781 (@code{'(15 40)}) See also @code{YaTeX-hilit-sectioning-face}.
1782 @end defvar
1784 @defvar YaTeX-use-AMS-LaTeX
1785 If you use AMS-LaTeX, set to @code{t} (@code{nil})
1786 @end defvar
1788 @defvar YaTeX-use-LaTeX2e
1789 If you use LaTeX2e, set to @code{t} (@code{t})
1790 @end defvar
1792 @defvar YaTeX-template-file
1793 File name which is automatically inserted at creation
1794 (@code{~/work/template.tex})
1795 @end defvar
1797 @defvar YaTeX-search-file-from-top-directory
1798 Non-nil means to search input-files from the directory where main file exists
1799 (@code{t})
1800 @end defvar
1802 @defvar YaTeX-use-font-lock
1803 Use font-lock to fontify buffer or not (@code{(featurep 'font-lock)}
1804 @end defvar
1806 @defvar YaTeX-use-hilit19
1807 Use hilit19 to highlight buffer or not (@code{(featurep 'hilit19)}
1808 @end defvar
1810 @defvar YaTeX-use-italic-bold
1811 YaTeX tries to search italic, bold fontsets or not
1812 (@code{t} if Emacs-20 or later). This variable is effective only when
1813 font-lock is used.
1814 (@code{(featurep 'hilit19)}
1815 @end defvar
1817 @defvar YaTeX-singlecmd-suffix
1818 Suffix which is always inserted after maketitle-type macros.
1819 @code{"{}"} is recommended.
1820 @end defvar
1822 @defvar YaTeX-package-alist-private
1823 Alist of LaTeX2e-package name vs. lists of macros in it.
1824 Set this alist properly and YaTeX automatically check the declaratiion of
1825 `usepackage' for corresponding macro, when you input that macro with
1826 completion. If required `usepackage' is not found, YaTeX also
1827 automatically inserts `\usepackage'. Alist is as follows;
1828 @lisp
1829 '((PackageName1
1830 (completionType ListOfMacro)
1831 (completionType ListOfMacro))
1832 (PackageName2
1833 (completionType ListOfMacro)
1834 (completionType ListOfMacro...))....)
1835 @end lisp
1836 completionType is one of @code{env, section, maketitle}.
1837 Consult the value of @code{YaTeX-package-alist-default} as an example.
1838 @end defvar
1840 @defvar YaTeX-tabular-indentation
1841 At indentation by @kbd{C-i} in tabular or array environment,
1842 YaTeX put the additional spaces to the normail indentation depth.
1843 The number of additional spaces is the product of YaTeX-tabular-indentation
1844 and the number of column position in tabular.
1845 @end defvar
1847 @defvar YaTeX-noindent-env-regexp
1848 Regexp of environment names that should begin with no indentation.
1849 All verbatime-like environment name should match with.
1850 @end defvar
1852 @defvar YaTeX-ref-default-label-string
1853 Default \\ref time string format.
1854 This format is like strftime(3) but allowed conversion char are as follows;
1855 %y -> Last 2 digit of year, %b -> Month name, %m -> Monthe number(1-12),
1856 %d -> Day, %H -> Hour, %M -> Minute, %S -> Second,
1857 %qx -> alphabetical-decimal conversion of yymmdd.
1858 %qX -> alphabetical-decimal conversion of HHMMSS.
1859 Beware defualt label-string should be always unique. So this format string
1860 should have both time part (%H+%M+%S or %qX) and date
1861 part (%y+(%b|%m)+%d or %qx).
1862 @end defvar
1864 @defvar YaTeX-ref-generate-label-function
1865 Function to generate default label string for unnamed \\label{}s.
1866 The function pointed to this value should take two arguments.
1867 First argument is LaTeX macro's name, second is macro's argument.
1868 Here is an example for using this value.
1869 @lisp
1870 (setq YaTeX-ref-generate-label-function 'my-yatex-generate-label)
1871 (defun my-yatex-generate-label (command value)
1872 (and (string= command "caption")
1873 (re-search-backward "\\\\begin{\\(figure\\|table\\)}" nil t)
1874 (setq command (match-string 1)))
1875 (let ((alist '(("chapter" . "chap")
1876 ("section" . "sec")
1877 ("subsection" . "subsec")
1878 ("figure" . "fig")
1879 ("table" . "tbl"))))
1880 (if (setq command (cdr (assoc command alist)))
1881 (concat command ":" value)
1882 (YaTeX::ref-generate-label nil nil))))
1883 @end lisp
1884 @end defvar
1887 @node Sample definitions, Hook variables, All customizable variables, Lisp variables
1888 @comment node-name, next, previous, up
1889 @subsection Sample definitions
1890 @cindex prefix key stroke
1891 @cindex fill-prefix
1893 For instance, to change the prefix key stroke to @kbd{ESC}, and name of
1894 the user dictionary @file{~/src/emacs/yatexrc}, and set @code{fill-prefix}
1895 to single TAB character, add the following @code{setq} to @file{~/.emacs}.
1897 @lisp
1898 (setq YaTeX-prefix "\e"
1899 YaTeX-user-completion-table "~/src/emacs/yatexrc"
1900 YaTeX-fill-prefix " ")
1901 @end lisp
1903 @node Hook variables, Hook file, Sample definitions, Lisp variables
1904 @comment node-name, next, previous, up
1905 @subsection Hook variables
1906 @cindex hook variables
1908 More customizations will be done by the hook-function defined in
1909 hook-variable @code{yatex-mode-hook}. This is useful to define a shortcut
1910 key sequence to enter some environments other than @code{document} and
1911 @code{enumerate} etc. The following statement defines @code{[prefix] ba}
1912 to enter @code{\begin@{abstract@}} ... @code{=end@{abstract@}}
1913 immediately.
1915 @lisp
1916 (setq yatex-mode-hook
1917 '(lambda() (YaTeX-define-begend-key "ba" "abstract")))
1918 @end lisp
1920 You should use functions @code{YaTeX-define-key}, or
1921 @code{YaTeX-define-begend-key} to define all the key sequences of
1922 yatex-mode.
1924 @node Hook file, , Hook variables, Lisp variables
1925 @comment node-name, next, previous, up
1926 @subsection Hook file
1927 @cindex hook file
1929 You can stuff all of YaTeX related expressions into a file named
1930 @file{yatexhks.el} if you have a lot of codes. YaTeX automatically load
1931 this file at the initialization of itself. Using @file{yatexhks.el}
1932 makes @code{yatex-mode-load-hook} unnecessary.
1934 @node Add-in functions, Add-in generator, Lisp variables, Customizations
1935 @comment node-name, next, previous, up
1936 @section Add-in functions
1937 @cindex add-in functions
1938 @cindex yatexadd.el
1940 You can easily define a function to input detailed arguments
1941 with completion according to La@TeX{} environments or commands.
1943 @c @node What is add-in functions?, , Add-in functions, Add-in functions
1944 @comment node-name, next, previous, up
1945 @subsection What is add-in functions?
1946 @cindex tabular
1948 When you input @code{tabular} environment, don't you think ``I want
1949 YaTeX to complete its argument toward my favorite one such as
1950 @code{@{|c|c|c|@}}...''? Yes, you can define the function to complete
1951 arguments for any environment and any La@TeX{} commands.
1953 @subsection Procedure
1955 Here is the procedure to define add-in functions.
1956 @enumerate
1957 @item
1958 Define the function
1959 @item
1960 Put the function into @file{yatexhks.el}
1961 @end enumerate
1963 @menu
1964 * How the add-in function works::
1965 * How the function is called::
1966 * Useful functions for creating add-in::
1967 * Contribution::
1968 @end menu
1970 @node How the add-in function works, How the function is called, Add-in functions, Add-in functions
1971 @comment node-name, next, previous, up
1972 @subsection How the add-in function works
1974 There are three types of add-in.
1976 @enumerate
1977 @item
1978 Option add-in
1979 @item
1980 argument add-in
1981 @item
1982 enclosing add-in
1983 @end enumerate
1985 @dfn{Option add-in} returns the
1986 La@TeX{}'s optional parameters such as optional strings after
1987 @code{\begin@{ENV@}}, optional strings between a section-type command
1988 and its first argument, and optional strings just after type
1989 maketitle-type command. The following illustrates the name of add-in
1990 functions, where underlined strings are generated by add-in functions.
1992 @display
1993 \begin@{table@}[ht] (Function name: YaTeX:table)
1994 ~~~~
1995 \put(100,200)@{@} (Function name: YaTeX:put)
1996 ~~~~~~~~~
1997 \sum_@{i=0@}^@{n@} (Function name: YaTeX:sum)
1998 ~~~~~~~~~~
1999 @end display
2001 Obviously, the function name is decided by concatenating the prefix
2002 `YaTeX:' and La@TeX{} command's name.
2004 Another add-in type is @dfn{argument add-in}, which completes arguments
2005 for section-type commands.
2007 @display
2008 \newcommand@{\foo@}@{bar@} (Function name: YaTeX::newcommand)
2009 ~~~~ ~~~
2010 @end display
2012 When the section-type command is inputted, the function named by
2013 concatenating `YaTeX::' and section-type command, is called automatically
2014 with an integer argument which indicates which argument of section-type
2015 command is being read. Thus the add-in should determine the
2016 job referring the value of its argument.
2018 @dfn{enclosing add-in} is for modifying and/or checking the region that
2019 will be enclosed by section-type commands via @kbd{[prefix] S}. An
2020 enclosing add-in function will be called with two arguments, beginning of
2021 the enclosed region and end of the region. Suppose you want to enclose
2022 the existing text @code{(a+b)/c} by @code{\frac{}}.
2024 @display
2025 a/c
2026 | |
2027 A B
2028 @end display
2030 You do set-mark-command at point A and then move to point B. Typing
2031 @kbd{[prefix] S} and input @code{frac} enclose the region like this;
2033 @display
2034 \frac{a/c}
2035 @end display
2037 Normally, the expression @code{a/c} is translated to
2038 @code{\frac@{a@}@{c@}}. An enclosing add-in is useful for modifying
2039 @code{/} to @code{@}@{}.
2041 @menu
2042 * Defining option-add-in::
2043 * Defining argument-add-in::
2044 * Defining enclosing-add-in::
2045 @end menu
2047 @node Defining option-add-in, Defining argument-add-in, How the add-in function works, How the add-in function works
2048 @comment node-name, next, previous, up
2049 @subsubsection Defining `option add-in'
2051 If you want @code{@{|c|c|c|@}} for all @code{tabular} environment,
2053 @lisp
2054 (defun YaTeX:tabular ()
2055 "@{|c|c|c|@}")
2056 @end lisp
2058 @noindent
2059 is enough. If you want more complicated format, define as below.
2061 @lisp
2062 (defun YaTeX:tabular ()
2063 "@{@@@{\\vrule width 1pt\\ @}|||@@@{\\ \\vrule width 1pt@}@}")
2064 @end lisp
2066 @noindent
2067 Note that the character @code{\} must be described as @code{\\} in
2068 Emacs-Lisp. The next example reads the tabular format from keyboard.
2069 @lisp
2070 (defun YaTeX:tabular ()
2071 (concat "@{" (read-string "Rule: ") "@}"))
2072 @end lisp
2074 @node Defining argument-add-in, Defining enclosing-add-in, Defining option-add-in, How the add-in function works
2075 @comment node-name, next, previous, up
2076 @subsubsection Defining `argument add-in'
2078 This section describes how to define the add-in function for
2079 @code{\newcommand}.
2081 The first argument of @code{\newcommand} begins always with @code{\}.
2082 The second argument is usually so complex that we can not edit them in the
2083 minibuffer. Here is the created function considering this.
2085 @lisp
2086 (defun YaTeX::newcommand (n) ;n is argument position
2087 (cond
2088 ((= n 1) ;1st argument is macro name
2089 (read-string "Command: " "\\")) ;initial input `\'
2090 ((= n 2) "") ;do nothing when reading arg#2
2091 (t nil)))
2092 @end lisp
2094 Note that when the `argument add-in' function return `nil', normal
2095 argument reader will be called.
2097 @node Defining enclosing-add-in, , Defining argument-add-in, How the add-in function works
2098 @comment node-name, next, previous, up
2099 @subsubsection Defining `enclosing add-in'
2101 This section describes how to define the add-in function for
2102 text enclosed by @code{\frac@{@}}.
2104 When enclosing the text @code{5/3} by @code{\frac@{@}}, you might want to
2105 replace @code{/} with @code{@}@{}. Enclosing function
2106 @code{YaTeX::frac-region} is called with two arguments, beginning of
2107 enclosed text and end of enclosed text. The function is expected to
2108 replace @code{/} with @code{@}@{}. Here is an example expression.
2110 @lisp
2111 (defun YaTeX::frac-region (beg end)
2112 (catch 'done
2113 (while (search-forward "/" end t)
2114 (goto-char (match-beginning 0))
2115 (if (y-or-n-p "Replace this slash(/) with `}{'")
2116 (throw 'done (replace-match "}{")))
2117 (goto-char (match-end 0)))))
2118 @end lisp
2120 @node How the function is called, Useful functions for creating add-in, How the add-in function works, Add-in functions
2121 @comment node-name, next, previous, up
2122 @subsection How the function is called
2124 YaTeX calls the add-in functions for specified begin-type, section-type,
2125 and maketitle-type command, if any. `Option add-in' functions for
2126 begin-type are called when @code{\begin@{ENV@}} has been inserted,
2127 functions for section-type are called just before input of the first
2128 argument, and functions for maketitle-type is called after maketitle-type
2129 command has been inserted. `Argument add-in' functions are called at each
2130 entry of arguments for section-type commands.
2132 @node Useful functions for creating add-in, Contribution, How the function is called, Add-in functions
2133 @comment node-name, next, previous, up
2134 @subsection Useful functions for creating add-in
2136 Many add-in functions for typical La@TeX{} commands are defined in
2137 @file{yatexadd.el}. Those are also useful as references. Here are the
2138 short descriptions on useful functions, where [F] means function, [A]
2139 means arguments, [D] means description.
2141 @table @kbd
2142 @item [F]
2143 YaTeX:read-position
2144 @itemx [A]
2145 Character list which can show up in the brackets
2146 @itemx [D]
2147 Return the location specifier such as `[htb]'. When
2148 nothing is entered, omit [] itself. If the possible characters
2149 are "htbp", call this function as
2150 @code{(YaTeX:read-position "htbp")}
2152 @item [F]
2153 YaTeX:read-coordinates
2154 @itemx [A]
2155 Base prompt, X-axis prompt, Y-axis prompt (each optional)
2156 @itemx [D]
2157 Read the coordinates with the prompt ``BasePrompt X-axisPrompt:'' for
2158 X-axis, ``BasePrompt Y-axisPrompt:'' for Y-axis, and return it in the form
2159 of ``(X,Y)''. The default prompts are @code{Dimension}, @code{X},
2160 @code{Y} respectively.
2162 @item [F]
2163 YaTeX:check-completion-type
2164 @itemx [A]
2165 One of the symbols: 'begin, 'section, or 'maketitle
2166 @itemx [D]
2167 Check the current completion type is specified one and cause error if
2168 not. The variable @code{YaTeX-current-completion-type} holds the symbol
2169 according to the current completion type.
2170 @end table
2172 @node Contribution, , Useful functions for creating add-in, Add-in functions
2173 @comment node-name, next, previous, up
2174 @subsection Contribution
2176 If you make your own pretty function and you let it be in public, please
2177 send me the function. I'm going to include it in the next release.
2179 @node Add-in generator, , Add-in functions, Customizations
2180 @comment node-name, next, previous, up
2181 @section Add-in generator
2183 First, don't forget to read the section of add-in functions @ref{Add-in
2184 functions}. If you easily understand how to define them, there's no need
2185 to read this section. But being not familiar with Emacs-Lisp, when you
2186 don't have clear idea what to do, this section describes how to get YaTeX
2187 make add-in function.
2189 There are two methods of generation. One is for fully interactive
2190 generator for beginners and another requires little knowledge of
2191 Emacs-Lisp.
2193 @subsection Generator for beginners
2194 The former generator is called by
2195 @center @kbd{M-x YaTeX-generate}
2197 @noindent
2198 strokes. All you have to do is follow the guidances. Defying them may cases
2199 the disaster (I wonder what is it???). So when you make some mistake, it
2200 is recommendable to type @kbd{C-g} and start afresh.
2202 @subsection Simple generator
2204 The latter generator is invoked by the next sequence.
2205 @center @kbd{M-x YaTeX-generate-simple}
2206 This generator can make both ``option add-in'' and ``argument add-in''
2207 (@emph{refer the section add-in functions}
2208 @ref{How the add-in function works}), whereas @code{YaTeX-generate}
2209 cannot make ``argument addin''.
2211 For example, assume you have the LaTeX command as follows.
2213 @example
2214 \epsinput[t](250,50)@{hoge.eps@}@{plain@}@{Picture of foo@}
2215 (A) (B) (1) (2) (3)
2216 (A)Optional parameter to specify the position
2217 One of t(top), b(bottom), l(left), r(right)
2218 (B)Maximum size of frame
2219 (1)1st argument is filename of EPS file
2220 (2)2nd argument indicates
2221 plain do nothing
2222 frame make frame around image
2223 dframe make double-frame around image
2224 for included EPS file.
2225 (3)Caption for the picture
2226 @end example
2228 Now get start with generation. Typing @kbd{M-x YaTeX-generate-simple}
2229 brings the prompt:
2230 @display
2231 (O)ption? (A)rgument?
2232 @end display
2234 @subsubsection Generating ``option add-in''
2235 @cindex option add-in
2237 Since (A), (B) above are optional argument, all we have to do to
2238 complete them is define the option add-in for them. Let's generate the
2239 function to complete (A).
2241 @display
2242 M-x YaTeX-generate-simple RET
2243 epsinput RET
2244 o
2245 @end display
2247 @noindent
2248 Typing as above leads the next prompt.
2250 @display
2251 Read type(1): (S)tring (C)omplete (F)ile ([)option (P)osition co(O)rd. (q)uit
2252 @end display
2254 @noindent
2255 This asks that ``Which type is the completion style of 1st argument?''.
2256 Here are the possible completion style.
2258 @table @code
2259 @item String
2260 read plain string
2261 @item Complete
2262 read with completion
2263 @item File
2264 read file name
2265 @item Option
2266 read optional string (if string omitted, omit [] too)
2267 @item Position
2268 read positional option (like [htbp])
2269 @item Coord.
2270 read coordinates
2271 @item Quit
2272 quit from generating
2273 @end table
2275 Since (A) is the optional argument to specify the location of included
2276 EPS file, the completion style is @code{Position}, and the possible
2277 characters are t, b, l, and r. To tell these information to generator,
2278 operate as follows.
2280 @display
2281 Read type(1).... p
2282 Acceptable characters: tblr RET
2283 @end display
2285 (B) is coordinate. So its completion style is coOrd. We want a prompt
2286 meaning ``Maximum size'' when completion.
2288 @display
2289 Read type(2).... o
2290 Prompt for coordinates: Max size RET
2291 @end display
2293 That's all for optional argument. Select quit.
2295 @display
2296 Read type(3).... q
2297 @end display
2299 Then the generated option add-in function for \epsinput will be shown in
2300 the next window.
2302 @subsubsection Generating ``argument add-in''
2303 @cindex argument add-in
2305 Next, create the argument add-in. The arguments for \epsinput are EPS
2306 file name, framing style, and caption string in sequence.
2308 @display
2309 M-x YaTeX-generate-simple RET
2310 epsinput RET
2311 a
2312 @end display
2314 Above key strokes bring the prompt that asks the number of argument.
2315 Answer it with 3.
2317 @display
2318 How many arguments?: 3 RET
2319 @end display
2321 Then the generator asks the completion style and prompt for completion.
2322 Answer them. @kbd{f} for FileName and prompt string.
2324 @display
2325 Read type(1).... f
2326 Prompt for argument#1 EPS file name RET
2327 @end display
2329 The second argument is one of selected symbol. So the completion type
2330 is @code{Completion}.
2332 @display
2333 Read type(2).... c
2334 Prompt for argument#2 Include style RET
2335 @end display
2337 Then all the candidates ready to be read. Type single RET after
2338 entering all.
2340 @display
2341 Item[1](RET to exit): plain RET
2342 Item[2](RET to exit): frame RET
2343 Item[3](RET to exit): dframe RET
2344 Item[4](RET to exit): RET
2345 @end display
2347 The following prompt asks whether the entered string must belong to
2348 candidates or not. In this case, since the argument must be one of
2349 @code{plain}, @code{frame}, and @code{dframe}, type @code{y}.
2351 @display
2352 Require match? (y or n) y
2353 @end display
2355 The last argument is the caption string for which any completion is
2356 needed.
2358 @display
2359 Read type(3).... s
2360 Prompt for argument#3 Caption RET
2361 default: Figure of RET
2362 @end display
2364 Finally we'll get the argument add-in in the next window.
2366 @subsection Contribution
2368 If you get your own pretty function and you let it be in public, please
2369 steel yourself in the happy atmosphere and do not send me the function.
2370 I do know it is not fine because it is generated by yatexgen:-p.
2372 @node Etcetera, Copying, Customizations, Top
2373 @comment node-name, next, previous, up
2374 @chapter Etcetera
2376 The standard completion tables provided in @file{yatex.el} contain a
2377 few La@TeX{} commands I frequently use. This is to lessen the key
2378 strokes to complete entire word, because too many candidates
2379 rarely used often cause too many hits. Therefore always try to
2380 use completion in order to enrich your dictionary, and you will
2381 also find `Wild Bird' growing suitable for your La@TeX{} style.
2383 The package name `Wild Bird' is the English translation of Japanese
2384 title `Yachou', which is a trick on words of Japanese.
2386 @node Copying, , Etcetera, Top
2387 @comment node-name, next, previous, up
2388 @chapter Copying
2390 This program is distributed as a free software. You can
2391 use/copy/modify/redistribute this software freely but with NO warranty to
2392 anything as a result of using this software. Adopting code from this
2393 program is also free. But I would not do contract act.
2395 Any reports and suggestions are welcome as long as I feel interests in
2396 this software. My possible e-mail address is `yuuji@@yatex.org'. (as of
2397 Jan.2004) And there is mailing list for YaTeX. Although the common
2398 language is Japanese, questions in English will be welcome. To join the
2399 ML, send the mail whose subject is `append' to the address
2400 `yatex@@yatex.org. If you have some question, please ask to
2401 `yatex-admin@@yatex.org'.
2403 The specification of this software will be surely modified
2404 (depending on my feelings) without notice :-p.
2407 @flushright
2408 HIROSE Yuuji
2409 @end flushright
2410 @bye
2412 Local variables:
2413 mode: texinfo
2414 fill-prefix: nil
2415 fill-column: 74
2416 End: