yatex
view docs/yatexe.tex @ 271:d467c0fb6083
Preparing for 1.76 release
| author | HIROSE Yuuji <yuuji@gentei.org> |
|---|---|
| date | Thu, 10 May 2012 11:40:02 +0900 |
| parents | 032d4c4bf7ac |
| children | 78d0fdc0459c |
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 10 11:12:44 2012 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-2012 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
51 @end menu
53 @node What is YaTeX?, Main features, Top, Top
54 @comment node-name, next, previous, up
55 @chapter What is YaTeX?
57 YaTeX automates typesetting and previewing of LaTeX and enables
58 completing input of LaTeX mark-up command such as
59 @code{\begin@{@}}..@code{\end@{@}}.
61 YaTeX also supports Demacs which runs on MS-DOS(386), Mule (Multi
62 Language Enhancement to GNU Emacs), and latex on DOS.
64 @node Main features, Installation, What is YaTeX?, Top
65 @comment node-name, next, previous, up
66 @chapter Main features
68 @itemize
69 @item Invocation of typesetter, previewer and related programs(@kbd{C-c t})
70 @item Typesetting on static region which is independent from point
71 @item Semiautomatic replacing of @code{\includeonly}
72 @item Jumping to error line(@kbd{C-c '})
73 @item Completing-read of La@TeX{} commands such as @code{\begin@{@}},
74 @code{\section} etc.
75 (@kbd{C-c b}, @kbd{C-c s}, @kbd{C-c l}, @kbd{C-c m})
76 @item Enclosing text into La@TeX{} environments or commands
77 (@kbd{C-u} @var{AboveKeyStrokes})
78 @item Displaying the structure of text at entering sectioning commands
79 @item Lump shifting of sectioning commands (@ref{view-sectioning})
80 @item Learning unknown/new La@TeX{} commands for the next completion
81 @item Argument reading with a guide for complicated La@TeX{} commands
82 @item Generating argument-readers for new/unsupported commands(@file{yatexgen})
83 @item Quick changing or deleting of La@TeX{} commands(@kbd{C-c c}, @kbd{C-c k})
84 @item Jumping from and to inter-file, begin<->end, ref<->label(@kbd{C-c g})
85 @item Blanket commenting out or uncommenting
86 (@kbd{C-c >}, @kbd{C-c <}, @kbd{C-c ,}, @kbd{C-c .})
87 @item Easy input of accent mark, math-mode's commands and Greek letters
88 (@kbd{C-c a}, @kbd{;}, @kbd{:})
89 @item Online help for the popular La@TeX{} commands
90 (@kbd{C-c ?}, @kbd{C-c /})
91 @item Document files hierarchy browser (@kbd{C-c d})
92 @item Adding automatically \usepackage corresponding to inputting LaTeX
93 macro with completion
94 @item Allow you to forget creating \label@{@}s, \ref@{@} or \cite@{@}
95 completion automatically generate labels.
96 @end itemize
98 @node Installation, Typesetting, Main features, Top
99 @comment node-name, next, previous, up
100 @chapter Installation
101 @cindex installation
102 @cindex .emacs
103 @cindex auto-mode-alist
104 @cindex autoload
106 Put next two expressions into your @file{~/.emacs}.
108 @lisp
109 (setq auto-mode-alist
110 (cons (cons "\\.tex$" 'yatex-mode) auto-mode-alist))
111 (autoload 'yatex-mode "yatex" "Yet Another La@TeX{} mode" t)
112 @end lisp
114 Next, add certain path name where you put files of YaTeX to your
115 load-path. If you want to put them in @file{~/src/emacs}, write
117 @lisp
118 (setq load-path
119 (cons (expand-file-name "~/src/emacs") load-path))
120 @end lisp
122 @noindent
123 in your @file{~/.emacs}
125 Then, yatex-mode will be automatically loaded when you visit a
126 file which has extension @file{.tex}. If yatex-mode is successfully
127 loaded, mode string on mode line will be turned to "YaTeX".
130 @node Typesetting, %#notation, Installation, Top
131 @comment node-name, next, previous, up
132 @chapter Typesetting
133 @cindex typesetting
134 @cindex previewer
135 @cindex typesetter
136 @cindex latex
137 @cindex printing out
139 The prefix key stroke of yatex-mode is @kbd{C-c} (Press 'C' with Control
140 key) by default. If you don't intend to change the prefix key stroke,
141 assume all @kbd{[prefix]} as @kbd{C-c} in this document. These key
142 strokes execute typeset or preview command.
144 @table @kbd
145 @item [prefix] t j
146 @dots{} invoke latex
147 @item [prefix] t r
148 @dots{} invoke latex on region
149 @item [prefix] t e
150 @dots{} invoke latex on current environment or whole
151 portion of current formulas in math-mode.
152 @item [prefix] t d
153 @dots{} invoke dvipdfmx after successful typesetting
154 @item [prefix] t k
155 @dots{} kill current typesetting process
156 @item [prefix] t b
157 @dots{} invoke bibtex
158 @item [prefix] t i
159 @dots{} invoke makeindex
160 @item [prefix] t d
161 @dots{} invoke latex && dvipdfmx
162 @item [prefix] t p
163 @dots{} preview
164 @item [prefix] t l
165 @dots{} lpr dvi-file
166 @item [prefix] t s
167 @dots{} search current string on xdvi-remote
168 @end table
170 @menu
171 * Calling typesetter::
172 * Calling previewer::
173 * Printing out::
174 @end menu
176 @node Calling typesetter, Calling previewer, Typesetting, Typesetting
177 @comment node-name, next, previous, up
178 @section Calling typesetter
180 Typing @kbd{[prefix] t j}, the current editing window will be divided
181 horizontally when you invoke latex command, and log message of La@TeX{}
182 typesetting will be displayed in the other window; called typesetting
183 buffer. The typesetting buffer automatically scrolls up and traces
184 La@TeX{} warnings and error messages. If you see latex stopping by an
185 error, you can send string to latex in the typesetting buffer.
187 If an error stops the La@TeX{} typesetting, this key stroke will
188 move the cursor to the line where La@TeX{} error is detected.
190 @table @kbd
191 @item [prefix] '
192 @itemx ([prefix]+single quotation)
194 @dots{} jump to the previous error or warning
195 @end table
197 If you find a noticeable error, move to the typesetting buffer and move
198 the cursor on the line of error message and type @kbd{SPACE} key. This
199 makes the cursor move to corresponding source line.
201 YaTeX-typeset-region invoked by @kbd{[prefix] tr} call typesetter
202 for region. The region is specified by standard point and mark, or
203 by @code{%#BEGIN} and @code{%#END} marks. Selected region will be
204 copied to the temporary file @file{texput.tex} with the same preamble
205 as the main file of current editing sources. Be sure to put
206 all local macro settings in preamble, not after @code{\begin@{document@}}.
207 The method of specification of the region is shown in the
208 section @xref{%#notation}.
210 The documentclass for typeset-region is the same as that of editing
211 file if you edit one file, and is the same as main file's if you
212 edit splitting files.
214 The @kbd{[prefix] te} key automatically marks current inner environment
215 or inner math mode and then call typeset-region with marked region. This
216 is convenient to quick view of current tabular environment or current
217 editing formulas. Keeping previewer window for @file{texput.dvi} is handy
218 for debugging. Since @kbd{[prefix] te} selects the inner-most environment
219 as region, it is not suitable for partial typesetting of doubly or more
220 composed environment. If you want to do partial typesetting for a nested
221 environment, use @kbd{[prefix] tr} for static-region, which is described
222 in the section @xref{%#notation}.
224 @node Calling previewer, Printing out, Calling typesetter, Typesetting
225 @comment node-name, next, previous, up
226 @section Calling previewer
228 @kbd{[prefix] t p} invokes the TeX previewer. And if you are using
229 xdvi-remote, which can be controled from other terminals, @kbd{[prefix] t
230 s} enables you to search current string at the cursor on the running xdvi
231 window.
233 @node Printing out, , Calling previewer, Typesetting
234 @comment node-name, next, previous, up
235 @section Printing out
237 When you type @code{[preifx] t l}, YaTeX asks you the range of
238 dvi-printing by default. You can skip this by invoking it with
239 universal-argument as follows:
241 @example
242 C-u [prefix] tl
243 @end example
245 @node %#notation, Completion, Typesetting, Top
246 @comment node-name, next, previous, up
247 @chapter %# notation
248 @cindex %# notation
250 You can control the typesetting process by describing @code{%#}
251 notations in the source text.
253 @menu
254 * Changing typesetter::
255 * Splitting input files::
256 * Static region for typesetting::
257 * Lpr format::
258 * Controlling which command to invoke::
259 * Editing %# notation::
260 @end menu
262 @node Changing typesetter, Splitting input files, %#notation, %#notation
263 @comment node-name, next, previous, up
264 @section To change the `latex' command or to split a source text.
265 @cindex typesetter
267 To change the typesetting command, write
269 @example
270 %#!latex-big
271 @end example
273 @noindent
274 anywhere in the source text. This is useful for changing
275 typesetter.
277 @node Splitting input files, Static region for typesetting, Changing typesetter, %#notation
278 @comment node-name, next, previous, up
279 @section Splitting input files
281 And if you split the source text and
282 edit subfile that should be included from main text.
284 @example
285 %#!latex main.tex
286 @end example
288 @noindent
289 will be helpful to execute latex on main file from sub text buffer. Since
290 this command line after @kbd{%#!} will be sent to shell literally, next
291 description makes it convenient to use ghostview as dvi-previewer.
293 @example
294 %#!latex main && dvi2ps main.dvi > main
295 @end example
297 @noindent
298 Note that YaTeX assumes the component before the last period of
299 the last word in this line as base name of the main La@TeX{} source.
300 The @code{%f} notation in this line is replaced by main file name, and
301 @code{%r} replaced by root name of main file name. If you specify
302 @code{%f} or @code{%r}, YaTeX always ask you the name of main file at the
303 first typesetting.
305 To make best use of the feature of inter-file jumping by
306 @kbd{[prefix] g} (see @ref{Cursor jump}), take described below into
307 consideration.
309 @itemize
310 @item You can put split texts in sub directory, but not in
311 sub directory of sub directory.
312 @item In the main text, specify the child file name with relative path name
313 such as \include@{chap1/sub@}, when you include the file in
314 a sub-directory.
315 @item In a sub-text, write @code{%#!latex main.tex} even if @file{main.tex}
316 is in the parent directory(not %#!latex ../main.tex).
317 @end itemize
319 @node Static region for typesetting, Lpr format, Splitting input files, %#notation
320 @comment node-name, next, previous, up
321 @section Static region
322 @cindex static region
323 @cindex Fixed region
325 Typeset-region by @kbd{[prefix] tr} passes the region between point and
326 mark to typesetting command by default. But when you want to typeset
327 static region, enclose the region by @code{%#BEGIN} and @code{%#END} as
328 follows.
330 @example
331 %#BEGIN
332 TheRegionYouWantToTypesetManyTimes
333 %#END
334 @end example
336 This is the rule of deciding the region.
338 @enumerate
339 @item
340 If there exists %#BEGIN before point,
342 @enumerate
343 @item
344 If there exists %#END after %#BEGIN,
345 @itemize
346 @item From %#BEGIN to %#END.
347 @end itemize
349 @item
350 If %#END does not exist after %#BEGIN,
351 @itemize
352 @item From %#BEGIN to the end of buffer.
353 @end itemize
354 @end enumerate
356 @item
357 If there does not exist %#BEGIN before point,
358 @itemize
359 @item Between point and mark(standard method of Emacs).
360 @end itemize
361 @end enumerate
363 It is useful to write @code{%#BEGIN} in the previous line of \begin and
364 @code{%#END} in the next line of \@code{end} when you try complex
365 environment such as `tabular' many times. It is also useful to put only
366 @code{%#BEGIN} alone at the middle of very long text. Do not forget to
367 erase @code{%#BEGIN} @code{%#END} pair.
369 @node Lpr format, Controlling which command to invoke, Static region for typesetting, %#notation
370 @comment node-name, next, previous, up
371 @section Lpr format
372 @cindex lpr format
374 Lpr format is specified by three Lisp variables. Here are the
375 default values of them.
377 @table @code
378 @item (1)dviprint-command-format
379 @code{"dvi2ps %f %t %s | lpr"}
380 @item (2)dviprint-from-format
381 @code{"-f %b"}
382 @item (3)dviprint-to-format
383 @code{"-t %e"}
384 @end table
386 On YaTeX-lpr, @code{%s} in (1) is replaced by the file name of main
387 text, @code{%f} by contents of (2), %t by contents of (3). At these
388 replacements, @code{%b} in (2) is also replaced by the number of beginning
389 page, @code{%e} in (3) is replaced by the number of ending page. But
390 @code{%f} and @code{%t} are ignored when you omit the range of print-out
391 by @kbd{C-u [prefix] tl}.
393 If you want to change this lpr format temporarily, put a command
394 such as follows somewhere in the text:
396 @example
397 %#LPR dvi2ps %f %t %s | 4up -page 4 | texfix | lpr -Plp2
398 @end example
400 And if you want YaTeX not to ask you the range of printing
401 out, the next example may be helpful.
403 @example
404 %#LPR dvi2ps %s | lpr
405 @end example
407 @node Controlling which command to invoke, Editing %# notation, Lpr format, %#notation
408 @comment node-name, next, previous, up
409 @section Controlling which command to invoke
411 These %# notation below can control which command to invoke for
412 La@TeX{} related process.
414 @table @code
415 @item %#BIBTEX
416 @dots{} Command line for makeindex ([prefix] t i)
417 @item %#MAKEINDEX
418 @dots{} Command line for bibtex ([prefix] t b)
419 @end table
421 If you want to invoke ``makeidx hogehoge'' to update index,
422 put the next line some upper place in the source, for example.
424 @example
425 %#MAKEINDEX makeidx hogehoge
426 @end example
429 @node Editing %# notation, , Controlling which command to invoke, %#notation
430 @comment node-name, next, previous, up
431 @section Editing %# notation
433 To edit @code{%#} notation described above, type
435 @table @kbd
436 @item [prefix] %
437 @dots{} editing %# notation menu
438 @end table
440 @noindent
441 and select one of the entry of the menu as follows.
443 @example
444 !)Edit-%#! B)EGIN-END-region L)Edit-%#LPR
445 @end example
447 @noindent
448 Type @kbd{!} to edit @code{%#!} entry, @code{b} to enclose the region with
449 @code{%#BEGIN} and @code{%#END}, and @code{l} to edit @code{%#LPR} entry.
450 When you type @kbd{b}, all @code{%#BEGIN} and @code{%#END} are
451 automatically erased.
453 @node Completion, Local dictionaries, %#notation, Top
454 @comment node-name, next, previous, up
455 @chapter Completion
456 @cindex completion
458 YaTeX makes it easy to input the La@TeX{} commands. There are several
459 kinds of completion type, begin-type, section-type, large-type, etc...
461 @menu
462 * Begin-type completion::
463 * Section-type completion::
464 * Large-type completion::
465 * Maketitle-type completion::
466 * Arbitrary completion::
467 * End completion::
468 * Accent completion::
469 * Image completion::
470 * Greek letters completion::
471 @end menu
473 @node Begin-type completion, Section-type completion, Completion, Completion
474 @comment node-name, next, previous, up
475 @section Begin-type completion
476 @cindex begin-type completion
477 @cindex environment
478 @cindex prefix b
480 "Begin-type completion" completes commands of @code{\begin@{env@}} ...
481 @code{\end@{env@}}. All of the begin-type completions begin with this key
482 sequence.
484 @table @kbd
485 @item [prefix] b
486 @dots{} start begin-type completion
487 @end table
489 @noindent
490 An additional key stroke immediately completes a frequently used
491 La@TeX{} @code{\begin@{@}}...@code{\@code{end}@{@}} environment.
493 @table @kbd
494 @item [prefix] b c
495 @dots{} @code{\begin@{center@}...\end@{center@}}
496 @item [prefix] b d
497 @dots{} @code{\begin@{document@}...\end@{document@}}
498 @item [prefix] b D
499 @dots{} @code{\begin@{description@}...\end@{description@}}
500 @item [prefix] b e
501 @dots{} @code{\begin@{enumerate@}...\end@{enumerate@}}
502 @item [prefix] b E
503 @dots{} @code{\begin@{equation@}...\end@{equation@}}
504 @item [prefix] b i
505 @dots{} @code{\begin@{itemize@}...\end@{itemize@}}
506 @item [prefix] b l
507 @dots{} @code{\begin@{flushleft@}...\end@{flushleft@}}
508 @item [prefix] b m
509 @dots{} @code{\begin@{minipage@}...\end@{minipage@}}
510 @item [prefix] b t
511 @dots{} @code{\begin@{tabbing@}...\end@{tabbing@}}
512 @item [prefix] b T
513 @dots{} @code{\begin@{tabular@}...\end@{tabular@}}
514 @item [prefix] b^T
515 @dots{} @code{\begin@{table@}...\end@{table@}}
516 @item [prefix] b p
517 @dots{} @code{\begin@{picture@}...\end@{picture@}}
518 @item [prefix] b q
519 @dots{} @code{\begin@{quote@}...\end@{quote@}}
520 @item [prefix] b Q
521 @dots{} @code{\begin@{quotation@}...\end@{quotation@}}
522 @item [prefix] b r
523 @dots{} @code{\begin@{flushright@}...\end@{flushright@}}
524 @item [prefix] b v
525 @dots{} @code{\begin@{verbatim@}...\end@{verbatim@}}
526 @item [prefix] b V
527 @dots{} @code{\begin@{verse@}...\end@{verse@}}
528 @end table
530 Any other La@TeX{} environments are made by completing-read of the
531 Emacs function.
533 @table @kbd
534 @item [prefix] b SPACE
535 @dots{} begin-type completion
536 @end table
538 @noindent
539 The next message will show up in the minibuffer
541 @example
542 Begin environment(default document):
543 @end example
545 @noindent
546 by typing @kbd{[prefix] b}. Put the wishing environment with completion
547 in the minibuffer, and @code{\begin@{env@}}...\@code{\end@{env@}} will be
548 inserted in the La@TeX{} source text. If the environment you want to put
549 does not exist in the YaTeX completion table, it will be registered in the
550 user completion table. YaTeX automatically saves the user completion
551 table in the user dictionary file at exiting of emacs.
553 At the completion of certain environments, the expected initial entry will
554 automatically inserted such as @code{\item} for @code{itemize}
555 environment. If you don't want the entry, it can be removed by undoing.
557 If you want to enclose some paragraphs which have already been
558 written, invoke the begin-type completion with changing the case
559 of @kbd{b} of key sequence upper(or invoke it with universal argument
560 by @kbd{C-u} prefix).
561 @cindex enclose region into environment
563 The following example encloses a region with `description'
564 environment.
566 @table @kbd
567 @item [prefix] B D
568 @itemx (or ESC 1 [prefix] b D)
569 @itemx (or C-u [prefix] b D)
571 @dots{} begin-type completion for region
572 @end table
574 This enclosing holds good for the completing input by @kbd{[prefix] b
575 SPC}. @kbd{[prefix] B SPC} enclose a region with the environment selected
576 by completing-read.
578 @node Section-type completion, Large-type completion, Begin-type completion, Completion
579 @comment node-name, next, previous, up
580 @section Section-type completion
581 @cindex section-type completion
582 @cindex prefix s
584 "Section-type completion" completes section-type commands which take an
585 argument or more such as @code{\section@{foo@}}. To invoke section-type
586 completion, type
588 @table @kbd
589 @item [prefix] s
590 @dots{} section-type completion
591 @end table
593 @noindent
594 then the prompt
596 @example
597 (C-v for view) \???@{@} (default documentclass):
598 @end example
600 @noindent
601 will show up in the minibuffer. Section-type La@TeX{} commands are
602 completed by space key, and the default value is selected when you
603 type nothing in the minibuffer.
605 Next,
607 @example
608 \section@{???@}:
609 @end example
611 @noindent
612 prompts you the argument of section-type La@TeX{} command. For
613 example, the following inputs
615 @example
616 \???@{@} (default documentclass): section
617 \section@{???@}: Hello world.
618 @end example
620 @noindent
621 will insert the string
623 @example
624 \section@{Hello world.@}
625 @end example
627 in your La@TeX{} source. When you neglect argument such as
629 @example
630 (C-v for view) \???@{@} (default section): vspace*
631 \vspace*@{???@}:
632 @end example
634 YaTeX puts
636 @example
637 \vspace*@{@}
638 @end example
640 @noindent
641 and move the cursor in the braces.
643 In La@TeX{} command, there are commands which take more than one
644 arguments such as @code{\addtolength@{\topmargin@}@{8mm@}}. To complete these
645 commands, invoke section-type completion with universal argument as,
646 @cindex number of argument
648 @example
649 C-u 2 [prefix] s (or ESC 2 [prefix] s)
650 @end example
652 @noindent
653 and make answers in minibuffer like this.
655 @example
656 (C-v for view) \???@{@} (default vspace*): addtolength
657 \addtolength@{???@}: \topmargin
658 Argument 2: 8mm
659 @end example
661 @code{\addtolength} and the first argument @code{\topmargin} can be typed
662 easily by completing read. Since YaTeX also learns the number of
663 arguments of section-type command and will ask that many arguments in
664 future completion, you had better tell the number of arguments to YaTeX at
665 the first completion of the new word. But you can change the number of
666 arguments by calling the completion with different universal argument
667 again.
670 Invoking section-type completion with @code{[Prefix] S} (Capital `S')
671 includes the region as the first argument of section-type command.
673 The section/large/maketitle type completion can work at the
674 prompt for the argument of other section-type completion.
675 Nested La@TeX{} commands are efficiently read with the recursive
676 completion by typing YaTeX's completion key sequence in the
677 minibuffer.
679 @menu
680 * view-sectioning::
681 @end menu
683 @node view-sectioning, , Section-type completion, Section-type completion
684 @comment node-name, next, previous, up
685 @subsection view-sectioning
686 @cindex view sectioning
687 @cindex outline
689 In the minibuffer at the prompt of section-type command completion,
690 typing @kbd{C-v} shows a list of sectioning commands in source text(The
691 line with @code{<<--} mark is the nearest sectioning command). Then,
692 default sectioning command appears in the minibuffer. You can go up/down
693 sectioning command by typing @kbd{C-p}/@kbd{C-n}, can scrolls up/down the
694 listing buffer by @kbd{C-v}/@kbd{M-v}, and can hide sectioning commands
695 under certain level by 0 through 6. Type @kbd{?} in the minibuffer of
696 sectioning prompt for more information.
698 You can generate this listing buffer (@code{*Sectioning Lines*} buffer)
699 by typing
700 @table @kbd
701 @item M-x YaTeX-section-overview
702 @dots{} Generate *Sectioning Lines* buffer
703 @end table
704 @cindex{Generate the listing of sectioning units}
705 from the LaTeX source buffer. In this listing buffer, typing @kbd{u} on
706 the sectioning command shifts up the corresponding sectioning command in
707 source text and @kbd{d} shifts down. After marking lines in the listing
708 buffer, typing @kbd{U} shifts up all sectioning commands in the region,
709 and @kbd{U} shifts down. Here are all the key bindings of
710 @code{*Sectioning Lines*} buffer.
712 @table @kbd
713 @item SPC
714 @dots{} Jump to corresponding source line
715 @item .
716 @dots{} Display corresponding source line
717 @item u
718 @dots{} Shift up a sectioning line
719 @item d
720 @dots{} Shift down a sectioning line
721 @item U
722 @dots{} Shift up sectioning lines in region
723 @item D
724 @dots{} Shift down sectioning lines in region
725 @item 0@dots{}6
726 @dots{} Hide sectioning commands whose level is lower than n
727 @end table
730 @node Large-type completion, Maketitle-type completion, Section-type completion, Completion
731 @comment node-name, next, previous, up
732 @section Large-type completion
734 "Large-type completion" inputs the font or size changing
735 descriptions such as @code{@{\large @}}. When you type
737 @table @kbd
738 @item [prefix] l
739 @dots{} large-type completion
740 @end table
742 @noindent
743 the message in the minibuffer
745 @example
746 @{\??? @} (default large):
747 @end example
749 prompts prompts you large-type command with completing-read. There are
750 TeX commands to change fonts or sizes, @code{it}, @code{huge} and so on,
751 in the completion table.
753 Region-based completion is also invoked by changing the letter after
754 prefix key stroke as @kbd{[prefix] L}. It encloses the region by braces
755 with large-type command.
757 @node Maketitle-type completion, Arbitrary completion, Large-type completion, Completion
758 @comment node-name, next, previous, up
759 @section Maketitle-type completion
760 @cindex maketitle-type completion
762 We call it "maketitle-type completion" which completes commands such as
763 @code{\maketitle}. Take notice that maketitle-type commands take no
764 arguments. Then, typing
766 @table @kbd
767 @item [prefix] m
768 @dots{} maketitle-type completion
769 @end table
771 @noindent
772 begins maketitle-completion. Above mentioned method is true for
773 maketitle-completion, and there are La@TeX{} commands with no
774 arguments in completion table.
776 @node Arbitrary completion, End completion, Maketitle-type completion, Completion
777 @comment node-name, next, previous, up
778 @section Arbitrary completion
779 @cindex arbitrary completion
781 @noindent
782 You can complete certain La@TeX{} command anywhere without typical
783 completing method as described, by typing
785 @table @kbd
786 @item [prefix] SPC
787 @dots{} arbitrary completion
788 @end table
790 @noindent
791 after the initial string of La@TeX{} command that is preceded by @code{\}.
793 @node End completion, Accent completion, Arbitrary completion, Completion
794 @comment node-name, next, previous, up
795 @section End completion
796 @cindex end completion
798 @noindent
799 YaTeX automatically detects the opened environment and close it with
800 \@code{\end@{environment@}}. Though proficient YaTeX users never fail to
801 make environment with begin-type completion, some may begin an environment
802 manually. In that case, type
804 @table @kbd
805 @item [prefix] e
806 @dots{} @code{end} completion
807 @end table
809 @noindent
810 at the end of the opened environment.
812 @node Accent completion, Image completion, End completion, Completion
813 @comment node-name, next, previous, up
814 @section Accent completion
815 @cindex accent completion
817 When you want to write the European accent marks(like @code{\`@{o@}}),
819 @table @kbd
820 @item [prefix] a
821 @dots{} accent completion
822 @end table
824 @noindent
825 shows the menu
827 @example
828 1:` 2:' 3:^ 4:" 5:~ 6:= 7:. u v H t c d b
829 @end example
831 @noindent
832 in the minibuffer. Chose one character or corresponding numeric,
833 and you will see
835 @example
836 \`@{@}
837 @end example
839 @noindent
840 in the editing buffer with the cursor positioned in braces. Type
841 one more character `o' for example, then
843 @example
844 \`@{o@}
845 @end example
847 @noindent
848 will be completed, and the cursor gets out from braces.
850 @node Image completion, Greek letters completion, Accent completion, Completion
851 @comment node-name, next, previous, up
852 @section Image completion of mathematical sign
853 @cindex image completion
854 @cindex math-mode
855 @cindex sigma
856 @cindex leftarrow
857 @cindex ;
859 Arrow marks, sigma mark and those signs mainly used in the
860 TeX's math environment are completed by key sequences which
861 imitate the corresponding symbols graphically. This completion
862 only works in the math environment. YaTeX automatically detects
863 whether the cursor located in math environment or not, and
864 change the behavior of key strokes @kbd{;} and @kbd{:}.
866 By the way, we often express the leftarrow mark by `<-' for example.
867 Considering such image, you can write @code{\leftarrow} by typing @kbd{<-}
868 after @kbd{;} (semicolon) as a prefix. In the same way,
869 @code{\longleftarrow} (@code{<--}) is completed by typing @kbd{;<--},
870 infinity mark which is imitated by @code{oo} is completed by typing
871 @kbd{;oo}.
873 Here are the sample operations in YaTeX math-mode.
875 @example
876 INPUT Completed La@TeX{} commands
877 ; < - @code{\leftarrow}
878 ; < - - @code{\longleftarrow}
879 ; < - - > @code{\longleftrightarrow}
880 ; o @code{\circ}
881 ; o o @code{\infty}
882 @end example
884 In any case, you can quit from image completion and can move
885 to the next editing operation if the La@TeX{} command you want is
886 shown in the buffer.
888 @code{;} itself in math-environment is inserted by @kbd{;;}. Typing
889 @kbd{TAB} in the midst of image completion shows all of the La@TeX{}
890 commands that start with the same name as string you previously typed in.
891 In this menu buffer, press @kbd{RET} after moving the cursor (by @kbd{n},
892 @kbd{p}, @kbd{b}, @kbd{f}) to insert the La@TeX{} command.
894 To know all of the completion table, type @kbd{TAB} just after @kbd{;}.
895 And here is the sample menu by @kbd{TAB} after @kbd{;<}.
897 @example
898 KEY LaTeX sequence sign
899 < \leq <
900 ~
901 << \ll <<
902 <- \leftarrow <-
903 <= \Leftarrow <=
904 @end example
906 You can define your favorite key-vs-sequence completion table in the
907 Emacs-Lisp variable @code{YaTeX-math-sign-alist-private}. See also
908 @file{yatexmth.el} for the information of the structure of this variable.
910 @node Greek letters completion, , Image completion, Completion
911 @comment node-name, next, previous, up
912 @section Greek letters completion
913 @cindex Greek letters completion
914 @cindex :
916 Math-mode of YaTeX provides another image completion, Greek letters
917 completion in the same method. After prefix @kbd{:}, typing @kbd{a} makes
918 @code{\alpha}, @kbd{b} makes @code{\beta} and @kbd{g} makes @code{\gamma}
919 and so on. First, type @kbd{:TAB} to know all the correspondence of
920 alphabets vs. Greek letters.
922 If you will find @kbd{;} or @kbd{:} doesn't work in correct position of
923 math environment, it may be a bug of YaTeX. Please send me a bug report
924 with the configuration of your text, and avoid it temporarily by typing
925 @kbd{;} or @kbd{:} after universal-argument(@kbd{C-u}) which forces
926 @kbd{;} and @kbd{:} to work as math-prefix.
928 @node Local dictionaries, Commenting out, Completion, Top
929 @comment node-name, next, previous, up
930 @chapter Local dictionaries
931 @cindex local dictionaries
932 @cindex nervous users
934 Tables for completion consist of three dictionaries; `standard
935 dictionary' built in @file{yatex.el}, `user dictionary' for your common
936 private commands, and `local dictionary' that is effective in a certain
937 directory.
939 When you input the command unknown to YaTeX at a completion in the
940 minibuffer, YaTeX asks you with the following prompt;
942 @example
943 `foo' is not in table. Register into: U)serDic L)ocalDic N)one D)iscard
944 @end example
946 @noindent
947 In this menu, typing @kbd{u} updates your `user dictionary', @kbd{l}
948 updates your local dictionary, @kbd{n} updates only on-memory dictionary
949 which go through only current Emacs session, and @kbd{d} updates no
950 dictionary and throws the new word away.
952 If you find this switching feature meaningless and bothersome, put the
953 next expression into your @file{~/.emacs}
955 @lisp
956 (setq YaTeX-nervous nil)
957 @end lisp
959 @node Commenting out, Cursor jump, Local dictionaries, Top
960 @comment node-name, next, previous, up
961 @chapter Commenting out
962 @cindex commenting out
963 @cindex prefix >
964 @cindex prefix <
965 @cindex prefix ,
966 @cindex prefix .
968 You may want to comment out some region.
970 @table @kbd
971 @item [prefix] >
972 @dots{} comment out region by %
973 @item [prefix] <
974 @dots{} uncomment region
975 @end table
977 @noindent
978 cause an operation to the region between point and mark.
980 @table @kbd
981 @item [prefix] .
982 @dots{} comment out current paragraph
983 @item [prefix] ,
984 @dots{} uncomment current paragraph
985 @end table
987 @noindent
988 comments or uncomments the paragraph where the cursor belongs.
989 This `paragraph' means the region marked by the function
990 mark-paragraph, bound to @kbd{ESC h} by default. It is NOT
991 predictable what will happen when you continuously comment out
992 some paragraph many times.
994 You can also comment out an environment between @code{\begin} and
995 @code{\end}, or a @code{\begin}-\@code{\end} pair themselves, by making the
996 following key strokes on the line where @code{\begin@{@}} or
997 @code{\end@{@}} exists.
999 @table @kbd
1000 @item [prefix] >
1001 @dots{} comment out from \begin to \@code{end}
1002 @item [prefix] <
1003 @dots{} uncomment from \begin to \@code{end}
1004 @end table
1006 @noindent
1007 comment whole the contents of environment. Moreover,
1009 @table @kbd
1010 @item [prefix] .
1011 @dots{} comment out \begin and \@code{end}
1012 @item [prefix] ,
1013 @dots{} uncomment \begin and \@code{end}
1014 @end table
1016 @noindent
1017 (un)comments out only environment declaration: @code{\begin@{@}} and
1018 @code{\end@{@}}. NOTE that even if you intend to comment out some region,
1019 invoking @kbd{[prefix] >} on the @code{\begin},@code{\end} line decides to
1020 work in `commenting out from @code{\begin} to @code{\end}' mode.
1023 @node Cursor jump, Changing and Deleting, Commenting out, Top
1024 @comment node-name, next, previous, up
1025 @chapter Cursor jump
1026 @cindex cursor jump
1027 @cindex prefix g
1030 @menu
1031 * Jump to corresponding object::
1032 * Invoking image processor::
1033 * Jump to main file::
1034 * Jumping around the environment::
1035 * Jumping to last completion position::
1036 @end menu
1038 @node Jump to corresponding object, Invoking image processor, Cursor jump, Cursor jump
1039 @comment node-name, next, previous, up
1040 @section Jump to corresponding object
1042 Typing
1044 @table @kbd
1045 @item [prefix] g
1046 @dots{} go to corresponding object
1047 @end table
1049 @noindent
1050 in a certain place move the cursor to the place corresponding to the
1051 La@TeX{} command of last place. YaTeX recognize the followings as pairs
1052 that have relation each other.
1054 @itemize @bullet
1055 @item @code{\begin@{@}} <-> @code{\end@{@}}
1056 @item @code{%#BEGIN} <-> @code{%#END}
1057 @item On the image-including line -> corresponding viewer or drawing tool
1058 @item @code{\label@{@}} <-> @code{\ref@{@}}
1059 @item @code{\include(\input)} -> included file
1060 @item @code{\bibitem@{@}} <-> @code{\cite@{@}}
1061 @end itemize
1063 On a @code{\begin},@code{\end} line, typing @kbd{[prefix] g} moves the
1064 cursor to the corresponding @code{\end},@code{\begin} line, if its partner
1065 really exists. The behavior on the line @code{%#BEGIN} and @code{%#END}
1066 are the same. Note that if the correspondent of @code{label/ref} or
1067 @code{cite/bibitem} exists in another file, that file have to be opened to
1068 make a round trip between references by @kbd{[prefix] g}.
1070 If you type @code{[prefix] g} on the line of @code{\include@{chap1@}},
1071 typically in the main text, YaTeX switches buffer to @file{chap1.tex}.
1073 @table @kbd
1074 @item [prefix] 4 g
1075 @dots{} go to corresponding object in other window
1076 @end table
1078 @noindent
1079 do the same job as @kbd{[prefix] g} except it's done in other window.
1080 Note that this function doesn't work on @code{begin/end},
1081 @code{%#BEGIN/%#END} pairs because it is meaningless.
1083 @node Invoking image processor, Jump to main file, Jump to corresponding object, Cursor jump
1084 @comment node-name, next, previous, up
1085 @section Invoking image processor
1086 @cindex{Drawing tool invocation}
1088 `image-including line' described above means such lines as
1089 @code{\epsfile@{file=foo.ps@}}. If you type @kbd{[prefix] g} on that
1090 line, YaTeX automatically searches source of `foo.ps' and invokes image
1091 viewer or drawing tool correspoinding to it. For example; if you draw
1092 an image foo.obj with Tgif and enclose its product named foo.eps by
1093 @code{\epsfile} command. Typing @kbd{[prefix] g} on @code{\epsfile} line
1094 make YaTeX invoke @code{tgif foo.obj}. How a processor is choosen is as
1095 follows.
1097 @enumerate
1098 @item
1099 If there is an expression matching with one of the pattern
1100 defined in @code{YaTeX-processed-file-regexp-alist}, extract file name
1101 from regexp group surrounded by \\(\\). (Which group corresponds is
1102 written in the cdr part of each list.) If no matches were found, do
1103 nothing.
1104 @item
1105 If there is a pattern as `%PROCESSOR' which is defined in the variable
1106 @code{YaTeX-file-processor-alist}, call that processor giving the
1107 file name with corresponding extension.
1108 @item
1109 If not, check the existence of each file which is supplied the
1110 extension in the cdr part of each list of
1111 @code{YaTeX-file-processor-alist}. If any, call the corresponding
1112 image viewer or drawing tool.
1113 @end enumerate
1115 @node Jump to main file, Jumping around the environment, Invoking image processor, Cursor jump
1116 @comment node-name, next, previous, up
1117 @section Jump to main file
1119 Typing
1121 @table @kbd
1122 @item [prefix] ^
1123 @dots{} visit main file
1124 @item [prefix] 4^
1125 @dots{} visit main file in other buffer
1126 @end table
1127 @cindex prefix ^
1128 @cindex prefix 4 ^
1130 in a sub text switch the buffer to the main text specified by
1131 @code{%#!} notation.
1133 @node Jumping around the environment, Jumping to last completion position, Jump to main file, Cursor jump
1134 @comment node-name, next, previous, up
1135 @section Jumping around the environment
1137 And these are the functions which work on the current La@TeX{}
1138 environment:
1140 @table @kbd
1141 @item M-C-a
1142 @dots{} beginning of environment
1143 @item M-C-e
1144 @dots{} @code{end} of environment
1145 @item M-C-@@
1146 @dots{} mark environment
1147 @end table
1148 @cindex M-C-a
1149 @cindex M-C-e
1150 @cindex M-C-@@
1152 @node Jumping to last completion position, , Jumping around the environment, Cursor jump
1153 @comment node-name, next, previous, up
1154 @section Jumping to last completion position
1156 YaTeX always memorize the position of completion into register @code{3}.
1157 So every time you make a trip to any other part of text other than you are
1158 writing, you can return to the editing paragraph by calling
1159 register-to-point with argument YaTeX-current-position-register, which is
1160 achieved by typing @kbd{C-x j 3}(by default).
1162 @node Changing and Deleting, Filling, Cursor jump, Top
1163 @comment node-name, next, previous, up
1164 @chapter Changing and Deleting
1166 These functions are for change or deletion of La@TeX{} commands
1167 already entered.
1169 @table @kbd
1170 @item [prefix] c
1171 @dots{} change La@TeX{} command
1172 @item [prefix] k
1173 @dots{} kill La@TeX{} command
1174 @end table
1175 @cindex prefix c
1176 @cindex prefix k
1178 @menu
1179 * Changing LaTeX commands::
1180 * Killing LaTeX commands::
1181 @end menu
1183 @node Changing LaTeX commands, Killing LaTeX commands, Changing and Deleting, Changing and Deleting
1184 @comment node-name, next, previous, up
1185 @section Changing La@TeX{} commands
1187 @kbd{[prefix] c} can change the various (La)@TeX{} commands. This can
1188 change the followings.
1189 @itemize @bullet
1190 @item Environment names
1191 @item Section-type commands
1192 @item Argument of section-type commands
1193 @item Optional parameters (enclosed by []) of section-type commands
1194 @item Font/size designators
1195 @item Math-mode's maketitle-type commands that can be inputted with
1196 image completion
1197 @end itemize
1199 Typing @kbd{[prefix] c} on one of above objects you want to change
1200 brings a suitable reading function sometimes with completion.
1201 Note: If you want to change the argument of section-type command that
1202 contains other La@TeX{} commands, type @kbd{[prefix] c} either of
1203 surrounding braces of the argument in order to make YaTeX ignore the
1204 internal La@TeX{} sequences as an object of changing. Anyway, it is
1205 very difficult to know which argument position the cursor belongs because
1206 the La@TeX{} commands can be nested and braces can freely emerge. So keep
1207 it mind to put the cursor on a brace when you are thinking of changing a
1208 complicated argument.
1210 @node Killing LaTeX commands, , Changing LaTeX commands, Changing and Deleting
1211 @comment node-name, next, previous, up
1212 @section Killing La@TeX{} commands
1213 @cindex Killing La@TeX{} commands
1215 @kbd{[prefix] k} kills the La@TeX{} commands sometimes with their
1216 arguments. Following table illustrates the correspondence of the invoking
1217 position and what is killed.
1219 @example
1220 [Invoking position] [action]
1221 \begin, \end line kill \begin,\end pairs
1222 %#BEGIN, %#END line kill %#BEGIN,%#END pairs
1223 on a Section-type command kill section-type command
1224 on a parenthesis kill parentheses
1225 @end example
1227 Note that when killing @code{\begin, \end} or @code{%#BEGIN, %#END} pair,
1228 the lines @code{\begin, \end} or @code{%#BEGIN, %#END} exist will be
1229 killed entirely. So take care not to create any line that contains more
1230 than one @code{\begin} or so.
1232 While all operations above are to kill `containers' which surround some
1233 text, universal argument (@kbd{C-u}) for these commands kills not only
1234 `containers' but also `contents' of them. See below as a sample.
1236 @example
1237 Original text: [prefix] k C-u [prefix] k
1238 Main \footnote@{note@} here. Main note here. Main here.
1239 ~(cursor)
1240 @end example
1242 @node Filling, Updation of includeonly, Changing and Deleting, Top
1243 @comment node-name, next, previous, up
1244 @chapter Filling
1245 @cindex filling
1247 @section Filling an item
1248 @cindex filling an item
1249 @cindex prefix i
1251 To fill a term (descriptive sentences) of @code{\item}, type
1253 @c @table @kbd
1254 @c @item [prefix] i
1255 @c @dots{} fill item
1256 @c @end table
1257 @table @kbd
1258 @item M-q
1259 @dots{} fill item
1260 @end table
1262 @noindent
1263 on that item.
1265 YaTeX uses the value of the variable @code{YaTeX-item-regexp} as the
1266 regular expression to search item header in itemize environment.
1267 If you make a newcommand to itemize terms(e.g. @code{\underlineitem}), put
1269 @lisp
1270 (setq YaTeX-item-regexp
1271 "\\(\\\\\\(sub\\)*item\\)\\|\\(\\\\underlineitem\\)")
1272 @end lisp
1273 @cindex YaTeX-item-regexp
1275 in your @file{~/.emacs}. If you are not familiar with regular expression
1276 for Emacs-Lisp, name a newcommand for `itemize' beginning with
1277 @code{\item} such as @code{\itembf}, not @code{\bfitem}.
1279 This function reformats the @code{\item} into `hang-indented' style.
1280 For example:
1282 @example
1283 itemize, enumerate environment:
1284 >
1285 >\item[foo] `foo' is the typical word for describing an
1286 > arbitrarily written....
1287 description environment:
1288 > \item[bar] When the word `for' is used as an arbitrarily
1289 > word, `bar' is bound to follow it.
1290 @end example
1292 Note that the indent depth of an @code{\item} word and its descriptive
1293 paragraph are the same in latter case. If you want to use different
1294 depth, invoke fill-paragraph at the beginning of non-whitespace
1295 character(see below).
1297 @section Filling paragraph
1298 @cindex Filling paragraph
1299 @cindex M-q
1301 Fill-paragraph is little bit adapted for La@TeX{} sources. It retains from
1302 filling in certain environments where formatting leads to a disaster such
1303 as verbatim, tabular, or so. And it protects @code{\verb} expressions
1304 from being folded (The variable @code{YaTeX-verb-regexp} controls this).
1305 Besides, putting cursor on the first occurrence of non-whitespace
1306 character on a line changes the fill-prefix temporarily to the depth of
1307 the line.
1309 @node Updation of includeonly, What column, Filling, Top
1310 @comment node-name, next, previous, up
1311 @chapter Updation of @code{\includeonly}
1312 @cindex includeonly
1314 When you edit splitting source texts, the notation
1316 @example
1317 \includeonly@{CurrentEditingFileName@}
1318 @end example
1320 @noindent
1321 in the main file reduces the time of typesetting. If you want
1322 to hack other file a little however, you have to rewrite it to
1324 @example
1325 \includeonly@{OtherFileNameYouWantToFix@}
1326 @end example
1328 @noindent
1329 in the main file. YaTeX automatically detects that the current
1330 edited text is not in includeonly list and prompts you
1332 @example
1333 A)dd R)eplace %)comment?
1334 @end example
1336 in the minibuffer. Type @kbd{a} if you want to add the current file name
1337 to @code{\includeonly} list, @kbd{r} to replace \@code{includeonly} list
1338 with the current file, and type @kbd{%} to comment out the
1339 @code{\includeonly} line.
1341 @node What column, Intelligent newline, Updation of includeonly, Top
1342 @comment node-name, next, previous, up
1343 @chapter What column?
1344 @cindex what column
1345 @cindex complex tabular
1346 @cindex prefix &
1348 We are often get tired of finding the corresponding column in
1349 large tabulars. For example,
1351 @example
1352 \begin@{tabular@}@{|c|c|c|c|c|c|c|c|@}\hline
1353 Name&Position&Post No.&Addr.&Phone No.&FAX No.&
1354 Home Addr.&Home Phone\\ \hline
1355 Thunder Bird & 6 & 223 & LA & xxx-yyy &
1356 zzz-www & Japan & 9876-54321 \\
1357 & 2 & \multicolumn@{2@}@{c|@}@{Unknown@}
1358 &&&(???)
1359 \\ \hline
1360 \end@{tabular@}
1361 @end example
1363 Suppose you have the cursor located at @code{(???)} mark, can you tell
1364 which column it is belonging at once? Maybe no. In such case,
1365 type
1367 @table @kbd
1368 @item [prefix] &
1369 @dots{} What column
1370 @end table
1372 @noindent
1373 in that position. YaTeX tells you the column header of the
1374 current field. Since YaTeX assumes the first line of tabular
1375 environment as a row of column headers, you can create a row of
1376 virtual column headers by putting them in the first line and
1377 commenting that line with @code{%}.
1379 @node Intelligent newline, Usepackage checker, What column, Top
1380 @comment node-name, next, previous, up
1381 @chapter Intelligent newline
1382 @cindex Intelligent newline
1383 @cindex ESC RET
1384 @cindex M-C-m
1386 At the end of begin-type completion of tabular[*], array, itemize,
1387 enumerate or tabbing environment, or typing
1389 @table @kbd
1390 @item ESC RET
1391 @dots{} Intelligent newline
1392 @end table
1394 @noindent
1395 in these environments inserts the contents corresponding to the current
1396 environment in the next line. (At the begin-type completion, this
1397 contents can be removed by `undo'.) In @code{tabular} environment, for
1398 example, @kbd{ESC RET} inserts the certain number of @code{&} and trailing
1399 @code{\\}, and @code{\hline} if other @code{\hline} is found in backward.
1400 Here are the list of contents vs. environments.
1402 @itemize
1403 @item @code{tabular}, @code{tabular*}, @code{array}
1405 Corresponding number of @code{&} and @code{\\}.
1406 And @code{\hline} if needed.
1408 @item @code{tabbing}
1410 The same number of @code{\>} as @code{\=} in the first line.
1412 @item @code{itemize}, @code{enumerate}, @code{description}, @code{list}
1414 @code{\item} or @code{item[]}.
1415 @end itemize
1417 Note that since this function works seeing the contents of the first
1418 line, please call this after the second line if possible.
1420 If you want to apply these trick to other environments, @code{foo}
1421 environment for example, define the function named
1422 @code{YaTeX-intelligent-newline-foo} to insert corresponding contents.
1423 That function will be called at the beginning of the next line after the
1424 newline is inserted to the current line. Since the function
1425 @code{YaTeX-indent-line} is designed to indent the current line properly,
1426 calling this function before your code to insert certain contents must be
1427 useful. See the definition of the function
1428 @code{YaTeX-intelligent-newline-itemize} as an example.
1430 @node Usepackage checker, Online help, Intelligent newline, Top
1431 @comment node-name, next, previous, up
1432 @chapter Usepackage checker
1433 @cindex usepackage
1435 When you input begint-type, section-type, maketitle-type macros with
1436 completion, and it requires some LaTeX2e package, YaTeX examines
1437 the existence of correct @code{\usepackage}. If not, YaTeX inserts
1438 the @code{\usepackage@{@}} declaration corresponding to input macro.
1440 To activate the package completion for your favarite package,
1441 set the variable @code{YaTeX-package-alist-private} correctly.
1442 Please refere the value of @code{YaTeX-package-alist-default} as an
1443 example.
1445 @node Online help, Browsing file hierarchy, Usepackage checker, Top
1446 @comment node-name, next, previous, up
1447 @chapter Online help
1448 @cindex online help
1449 @cindex prefix ?
1450 @cindex prefix /
1451 @cindex apropos
1452 @cindex keyword search
1454 YaTeX provides you the online help with popular La@TeX{} commands.
1456 Here are the key strokes for the online help.
1458 @table @kbd
1459 @item [prefix] ?
1460 @dots{} Online help
1461 @item [prefix] /
1462 @dots{} Online apropos
1463 @end table
1465 @section Online help
1467 `Online help' shows the documentation for the popular La@TeX{}
1468 commands(defaults to the commands on the cursor) in the next buffer.
1469 There are two help file, `global help' and `private help'. The former
1470 file contains the descriptions on the standard La@TeX{} command and is
1471 specified its name by variable @code{YaTeX-help-file}. Usually, the
1472 global help file should be located in public space (@code{$EMACSEXECPATH}
1473 by default) and should be world writable so that anyone can update it to
1474 enrich its contents. The latter file contains descriptions on
1475 non-standard or personal command definitions and is specified by
1476 @code{YaTeX-help-file-private}. This file should be put into private
1477 directory.
1479 @section Online apropos
1481 `Online apropos' is an equivalent of GNU Emacs's apropos. It
1482 shows all the documentations that contains the keyword entered by
1483 the user.
1485 @section When no descriptions are found...
1487 If there is no description on a command in help files, YaTeX
1488 requires you to write a description on that command. If you are
1489 willing to do, determine which help file to add and write the
1490 description on it referring your manual of (La)TeX. Please send
1491 me your additional descriptions if you describe the help on some
1492 standard commands. I might want to include it in the next
1493 distribution.
1495 @node Browsing file hierarchy, Cooperation with other packages, Online help, Top
1496 @comment node-name, next, previous, up
1497 @chapter Browsing file hierarchy
1498 @cindex hierarchy
1499 @cindex browsing
1501 When you are editing multi-file source, typing
1503 @table @kbd
1504 @item [prefix] d
1505 @dots{} browse file hierarchy
1506 @end table
1508 @noindent
1509 asks you the parent-most file (which may be defaulted) and displays the
1510 documentation hierarchy in the next window. In this buffer, the following
1511 commands are available.
1513 @table @kbd
1514 @item n
1515 @dots{} move to the next line and show its contents
1516 @item p
1517 @dots{} move to the previous line and show its contents
1518 @item N
1519 @dots{} move to the next file in the same inclusion level
1520 @item P
1521 @dots{} move to the previous file in the same inclusion level
1522 @item j
1523 @dots{} move to the next line
1524 @item k
1525 @dots{} move to the previous line
1526 @item u
1527 @dots{} move to the parent file
1528 @item .
1529 @dots{} show the current files contents in the next window
1530 @item SPC
1531 @dots{} scroll up the current file window
1532 @item DEL, b
1533 @dots{} scroll down the current file window
1534 @item <
1535 @dots{} show the beginning of the current file
1536 @item >
1537 @dots{} show the end of the current file
1538 @item >
1539 @dots{} return to the previous postion after @kbd{<} or @kbd{>}
1540 @item RET, g
1541 @dots{} open the current file in the next window
1542 @item mouse-2
1543 @dots{} same as RET(available only with window system)
1544 @item o
1545 @dots{} other window
1546 @item 1
1547 @dots{} delete other windows
1548 @item -
1549 @dots{} shrink hierarchy buffer window
1550 @item +
1551 @dots{} enlarge hierarchy buffer window
1552 @item ?
1553 @dots{} describe mode
1554 @item q
1555 @dots{} quit
1556 @end table
1558 Note that operations on the file contents in the next window do not work
1559 correctly when you close the corresponding file.
1561 @node Cooperation with other packages, Customizations, Browsing file hierarchy, Top
1562 @comment node-name, next, previous, up
1563 @chapter Cooperation with other packages
1565 YaTeX works better with other brilliant packages.
1567 @section gmhist
1568 @cindex gmhist
1569 @cindex command history
1570 @cindex minibuffer history
1572 When you are loading @file{gmhist.el} and @file{gmhist-mh.el}, you can
1573 use independent command history list at the prompt of preview command
1574 (@kbd{[prefix] tp}) and print command (@kbd{[prefix] tl}). On each
1575 prompt, you can enter the previous command line string repeatedly by
1576 typing @kbd{M-p}.
1578 @section min-out
1579 @cindex min-out
1581 @file{min-out}, the outline minor mode, can be used in yatex-mode
1582 buffers. If you want to use it with YaTeX, please refer the
1583 file @file{yatexm-o.el} as an example.
1585 @node Customizations, Etcetera, Cooperation with other packages, Top
1586 @comment node-name, next, previous, up
1587 @chapter Customizations
1588 @cindex customizations
1590 You can customize YaTeX by setting Emacs-Lisp variables and by making
1591 add-in functions.
1593 @menu
1594 * Lisp variables::
1595 * Add-in functions::
1596 * Add-in generator::
1597 @end menu
1599 @node Lisp variables, Add-in functions, Customizations, Customizations
1600 @comment node-name, next, previous, up
1601 @section Lisp variables
1602 @cindex customizable variables
1604 You can change the key assignments or make completion more comfortable
1605 by setting the values of various variables which control the movement of
1606 yatex-mode.
1608 For example, if you want to change the prefix key stroke from @kbd{C-c}
1609 to any other sequence, set YaTeX-prefix to whatever you want to use. If
1610 you don't want to use the key sequence @kbd{C-c letter} which is assumed
1611 to be the user reserved sequence in Emacs world, set
1612 @code{YaTeX-inhibit-prefix-letter} to @code{t}, and all of the default key
1613 bind of @kbd{C-c letter} will turn to the corresponding @kbd{C-c C-letter}
1614 (but the region based completions that is invoked with @kbd{C-c
1615 Capital-letter} remain valid, if you want to disable those bindings, set
1616 that variable to 1 instead of @code{t}).
1618 @menu
1619 * All customizable variables::
1620 * Sample definitions::
1621 * Hook variables::
1622 * Hook file::
1623 @end menu
1625 @node All customizable variables, Sample definitions, Lisp variables, Lisp variables
1626 @comment node-name, next, previous, up
1627 @subsection All customizable variables
1628 @cindex all customizable variables
1630 Here are the customizable variables of yatex-mode. Each value setq-ed
1631 in @file{~/.emacs} is preferred and that of defined in @file{yatex.el} is
1632 neglected. Parenthesized contents stands for the default value. When you
1633 are to change some of these variables, see more detailed documentation of
1634 the variable by @kbd{M-x describe-variable}.
1636 @defvar YaTeX-japan
1637 Set this nil to produce all messages in English
1638 (@code{Depends on Japanese feature of Emacs})
1639 @end defvar
1641 @defvar YaTeX-kanji-code
1642 Default buffer-file-coding-system for YaTeX modes' buffer.
1643 Set this 0 to no language conversion. Nil to preserve original
1644 coding-system. 1=Shift JIS, 2=JIS, 3=EUC, 4=UTF-8 (@code{1 or 2})
1645 @end defvar
1647 @defvar YaTeX-prefix
1648 Prefix key stroke (@kbd{C-c})
1649 @end defvar
1651 @defvar YaTeX-inhibit-prefix-letter
1652 Change key stroke from @kbd{C-c letter} to @kbd{C-c C-letter} (@code{nil})
1653 @end defvar
1655 @defvar YaTeX-fill-prefix
1656 Fill-prefix used in yatex-mode (@code{nil})
1657 @end defvar
1659 @defvar YaTeX-user-completion-table
1660 Name of user dictionary where learned completion table will be stored.
1661 (@code{"~/.yatexrc"})
1662 @end defvar
1664 @defvar tex-command
1665 La@TeX{} typesetter command (@code{"latex"})
1666 @end defvar
1668 @defvar dvi2-command
1669 Preview command (@code{"xdvi -geo +0+0 -s 4"})
1670 @end defvar
1672 @defvar dviprint-command-format
1673 Command format to print dvi file (@code{"dvi2ps %f %t %s | lpr"})
1674 @end defvar
1676 @defvar dviprint-from-format
1677 Start page format of above %f. %b will turn to start page (@code{"-f %b"})
1678 @end defvar
1680 @defvar dviprint-to-format
1681 End page format of above %t. %e will turn to @code{end} page (@code{"-t %e"})
1682 @end defvar
1684 @defvar makeindex-command
1685 Default makeindex command (@code{"makeindex"} (@code{"makeind"} on MS-DOS))
1686 @end defvar
1688 @defvar YaTeX-dvipdf-command
1689 Default command name to convert .dvi to PDF (@code{"dvipdfmx"})
1690 @end defvar
1692 @defvar YaTeX-need-nonstop
1693 Put @code{\nonstopmode@{@}} or not (@code{nil})
1694 @end defvar
1696 @defvar latex-warning-regexp
1697 Regular expression of warning message latex command puts out
1698 (@code{"line.* [0-9]*"})
1699 @end defvar
1701 @defvar latex-error-regexp
1702 Regular expression of error message (@code{"l\\.[1-9][0-9]*"})
1703 @end defvar
1705 @defvar latex-dos-emergency-message
1706 Message latex command running on DOS puts at abort (@code{"Emergency stop"})
1707 @end defvar
1709 @defvar YaTeX-item-regexp
1710 Regular expression of item command (@code{"\\\\item"})
1711 @end defvar
1713 @defvar YaTeX-verb-regexp
1714 Regexp of verb family. Omit \\\\. (@code{"verb\\*?\\|path"})
1715 @end defvar
1717 @defvar YaTeX-nervous
1718 T for using local dictionary (@code{t})
1719 @end defvar
1721 @defvar YaTeX-sectioning-regexp
1722 Regexp of La@TeX{} sectioning command
1723 (@code{"\\(part\\|chapter\\*?\\|\\(sub\\)*\\(section\\|paragraph\\)\\*?\\)\\b"})
1724 @end defvar
1726 @defvar YaTeX-fill-inhibit-environments
1727 Inhibit fill in these environments
1728 (@code{'("tabular" "tabular*" "array" "picture" "eqnarray" "eqnarray*" "equation" "math" "displaymath" "verbatim" "verbatim*")})
1729 @end defvar
1731 @defvar YaTeX-uncomment-once
1732 T for deleting all preceding @code{%} (@code{nil})
1733 @end defvar
1735 @defvar YaTeX-close-paren-always
1736 T for always close all parenthesis automatically, @code{nil} for only eol
1737 (@code{t})
1738 @end defvar
1740 @defvar YaTeX-auto-math-mode
1741 Switch math-mode automatically (@code{t})
1742 @end defvar
1744 @defvar YaTeX-math-key-list-private
1745 User defined alist, math-mode-prefix vs completion alist
1746 used in image completion (@code{nil}). See @file{yatexmth.el}
1747 for the information about how to define a completion alist.
1748 @end defvar
1750 @defvar YaTeX-default-pop-window-height
1751 Initial height of typesetting buffer when one-window.
1752 Number for the lines of the buffer, numerical string for
1753 the percentage of the screen-height. @code{nil} for half height (10)
1754 @end defvar
1756 @defvar YaTeX-help-file
1757 Global online help file name (@file{$doc-directory/../../site-lisp/YATEXHLP.eng})
1758 @end defvar
1760 @defvar YaTeX-help-file-private
1761 Private online help file name (@file{"~/YATEXHLP.eng"})
1762 @end defvar
1764 @defvar YaTeX-no-begend-shortcut
1765 Disable [prefix] b ?? shortcut (@code{nil)}
1766 @end defvar
1768 @defvar YaTeX-hilit-pattern-adjustment-private
1769 List of the list that contain the regular expression and the symbol of
1770 logical meaning of the string that matches the pattern. See also the
1771 value from @code{(assq 'yatex-mode hilit-patterns-alist)} and the value of
1772 @code{YaTeX-hilit-pattern-adjustment-default} (and even the document of
1773 hilit19.el).
1774 @end defvar
1776 @defvar YaTeX-sectioning-level
1777 Alist of LaTeX's sectioning command vs its height.
1778 @end defvar
1780 @defvar YaTeX-hierarchy-ignore-heading-regexp
1781 @code{YaTeX-display-hierarchy} searches for sectioning command first, and
1782 comment line secondary as a file headings. In latter case, ignore lines
1783 that match with regular expression of this variable. Default value of
1784 this variable is RCS header expressions and mode specifying line `-*- xxxx
1785 -*'.
1786 @end defvar
1788 @defvar YaTeX-skip-default-reader
1789 Non-nil for this variable skips the default argument reader of
1790 section-type command when add-in function for it is not defined
1791 (@code{nil})
1792 @end defvar
1794 @defvar YaTeX-create-file-prefix-g
1795 When typing @kbd{prefix g} on the @code{\include} line,
1796 open the target file even if the file doesn't exist (@code{nil})
1797 @end defvar
1799 @defvar YaTeX-simple-messages
1800 Simplyfy messages of various completions (@code{nil})
1801 @end defvar
1803 @defvar YaTeX-hilit-sectioning-face
1804 When hilit19 and yatex19 is active, YaTeX colors the sectioning commands.
1805 This variable specifies the foreground and background color of
1806 @code{\part} macro. The default value is @code{'(yellow/dodgerblue
1807 yellow/slateblue)}. The first element of this list is for the screen when
1808 @code{hilit-background-mode} is @code{'light}, and the second element is
1809 for @code{'dark}. You should specify both color as `forecolor/backcolor'.
1810 @end defvar
1812 @defvar YaTeX-hilit-sectioning-attenuation-rate
1813 When color mode, this variable specifies how much attenuate the color
1814 density of @code{\subparagraph} compared with that of @code{\chapter}
1815 (@code{'(15 40)}) See also @code{YaTeX-hilit-sectioning-face}.
1816 @end defvar
1818 @defvar YaTeX-use-AMS-LaTeX
1819 If you use AMS-LaTeX, set to @code{t} (@code{nil})
1820 @end defvar
1822 @defvar YaTeX-use-LaTeX2e
1823 If you use LaTeX2e, set to @code{t} (@code{t})
1824 @end defvar
1826 @defvar YaTeX-template-file
1827 File name which is automatically inserted at creation
1828 (@code{~/work/template.tex})
1829 @end defvar
1831 @defvar YaTeX-search-file-from-top-directory
1832 Non-nil means to search input-files from the directory where main file exists
1833 (@code{t})
1834 @end defvar
1836 @defvar YaTeX-use-font-lock
1837 Use font-lock to fontify buffer or not (@code{(featurep 'font-lock)}
1838 @end defvar
1840 @defvar YaTeX-use-hilit19
1841 Use hilit19 to highlight buffer or not (@code{(featurep 'hilit19)}
1842 @end defvar
1844 @defvar YaTeX-use-italic-bold
1845 YaTeX tries to search italic, bold fontsets or not
1846 (@code{t} if Emacs-20 or later). This variable is effective only when
1847 font-lock is used.
1848 (@code{(featurep 'hilit19)}
1849 @end defvar
1851 @defvar YaTeX-singlecmd-suffix
1852 Suffix which is always inserted after maketitle-type macros.
1853 @code{"@{@}"} is recommended.
1854 @end defvar
1856 @defvar YaTeX-package-alist-private
1857 Alist of LaTeX2e-package name vs. lists of macros in it.
1858 Set this alist properly and YaTeX automatically check the declaratiion of
1859 `usepackage' for corresponding macro, when you input that macro with
1860 completion. If required `usepackage' is not found, YaTeX also
1861 automatically inserts `\usepackage'. Alist is as follows;
1862 @lisp
1863 '((PackageName1
1864 (completionType ListOfMacro)
1865 (completionType ListOfMacro))
1866 (PackageName2
1867 (completionType ListOfMacro)
1868 (completionType ListOfMacro...))....)
1869 @end lisp
1870 completionType is one of @code{env, section, maketitle}.
1871 Consult the value of @code{YaTeX-package-alist-default} as an example.
1872 @end defvar
1874 @defvar YaTeX-tabular-indentation
1875 At indentation by @kbd{C-i} in tabular or array environment,
1876 YaTeX put the additional spaces to the normail indentation depth.
1877 The number of additional spaces is the product of YaTeX-tabular-indentation
1878 and the number of column position in tabular.
1879 @end defvar
1881 @defvar YaTeX-noindent-env-regexp
1882 Regexp of environment names that should begin with no indentation.
1883 All verbatime-like environment name should match with.
1884 @end defvar
1886 @defvar YaTeX-ref-default-label-string
1887 Default \\ref time string format.
1888 This format is like strftime(3) but allowed conversion char are as follows;
1889 %y -> Last 2 digit of year, %b -> Month name, %m -> Monthe number(1-12),
1890 %d -> Day, %H -> Hour, %M -> Minute, %S -> Second,
1891 %qx -> alphabetical-decimal conversion of yymmdd.
1892 %qX -> alphabetical-decimal conversion of HHMMSS.
1893 Beware defualt label-string should be always unique. So this format string
1894 should have both time part (%H+%M+%S or %qX) and date
1895 part (%y+(%b|%m)+%d or %qx).
1896 @end defvar
1898 @defvar YaTeX-ref-generate-label-function
1899 Function to generate default label string for unnamed \\label@{@}s.
1900 The function pointed to this value should take two arguments.
1901 First argument is LaTeX macro's name, second is macro's argument.
1902 Here is an example for using this value.
1903 @lisp
1904 (setq YaTeX-ref-generate-label-function 'my-yatex-generate-label)
1905 (defun my-yatex-generate-label (command value)
1906 (and (string= command "caption")
1907 (re-search-backward "\\\\begin@{\\(figure\\|table\\)@}" nil t)
1908 (setq command (match-string 1)))
1909 (let ((alist '(("chapter" . "chap")
1910 ("section" . "sec")
1911 ("subsection" . "subsec")
1912 ("figure" . "fig")
1913 ("table" . "tbl"))))
1914 (if (setq command (cdr (assoc command alist)))
1915 (concat command ":" value)
1916 (YaTeX::ref-generate-label nil nil))))
1917 @end lisp
1918 @end defvar
1921 @node Sample definitions, Hook variables, All customizable variables, Lisp variables
1922 @comment node-name, next, previous, up
1923 @subsection Sample definitions
1924 @cindex prefix key stroke
1925 @cindex fill-prefix
1927 For instance, to change the prefix key stroke to @kbd{ESC}, and name of
1928 the user dictionary @file{~/src/emacs/yatexrc}, and set @code{fill-prefix}
1929 to single TAB character, add the following @code{setq} to @file{~/.emacs}.
1931 @lisp
1932 (setq YaTeX-prefix "\e"
1933 YaTeX-user-completion-table "~/src/emacs/yatexrc"
1934 YaTeX-fill-prefix " ")
1935 @end lisp
1937 @node Hook variables, Hook file, Sample definitions, Lisp variables
1938 @comment node-name, next, previous, up
1939 @subsection Hook variables
1940 @cindex hook variables
1942 More customizations will be done by the hook-function defined in
1943 hook-variable @code{yatex-mode-hook}. This is useful to define a shortcut
1944 key sequence to enter some environments other than @code{document} and
1945 @code{enumerate} etc. The following statement defines @code{[prefix] ba}
1946 to enter @code{\begin@{abstract@}} ... @code{=end@{abstract@}}
1947 immediately.
1949 @lisp
1950 (setq yatex-mode-hook
1951 '(lambda() (YaTeX-define-begend-key "ba" "abstract")))
1952 @end lisp
1954 You should use functions @code{YaTeX-define-key}, or
1955 @code{YaTeX-define-begend-key} to define all the key sequences of
1956 yatex-mode.
1958 @node Hook file, , Hook variables, Lisp variables
1959 @comment node-name, next, previous, up
1960 @subsection Hook file
1961 @cindex hook file
1963 You can stuff all of YaTeX related expressions into a file named
1964 @file{yatexhks.el} if you have a lot of codes. YaTeX automatically load
1965 this file at the initialization of itself. Using @file{yatexhks.el}
1966 makes @code{yatex-mode-load-hook} unnecessary.
1968 @node Add-in functions, Add-in generator, Lisp variables, Customizations
1969 @comment node-name, next, previous, up
1970 @section Add-in functions
1971 @cindex add-in functions
1972 @cindex yatexadd.el
1974 You can easily define a function to input detailed arguments
1975 with completion according to La@TeX{} environments or commands.
1977 @c @node What is add-in functions?, , Add-in functions, Add-in functions
1978 @comment node-name, next, previous, up
1979 @subsection What is add-in functions?
1980 @cindex tabular
1982 When you input @code{tabular} environment, don't you think ``I want
1983 YaTeX to complete its argument toward my favorite one such as
1984 @code{@{|c|c|c|@}}...''? Yes, you can define the function to complete
1985 arguments for any environment and any La@TeX{} commands.
1987 @subsection Procedure
1989 Here is the procedure to define add-in functions.
1990 @enumerate
1991 @item
1992 Define the function
1993 @item
1994 Put the function into @file{yatexhks.el}
1995 @end enumerate
1997 @menu
1998 * How the add-in function works::
1999 * How the function is called::
2000 * Useful functions for creating add-in::
2001 * Contribution::
2002 @end menu
2004 @node How the add-in function works, How the function is called, Add-in functions, Add-in functions
2005 @comment node-name, next, previous, up
2006 @subsection How the add-in function works
2008 There are three types of add-in.
2010 @enumerate
2011 @item
2012 Option add-in
2013 @item
2014 argument add-in
2015 @item
2016 enclosing add-in
2017 @end enumerate
2019 @dfn{Option add-in} returns the
2020 La@TeX{}'s optional parameters such as optional strings after
2021 @code{\begin@{ENV@}}, optional strings between a section-type command
2022 and its first argument, and optional strings just after type
2023 maketitle-type command. The following illustrates the name of add-in
2024 functions, where underlined strings are generated by add-in functions.
2026 @display
2027 \begin@{table@}[ht] (Function name: YaTeX:table)
2028 ~~~~
2029 \put(100,200)@{@} (Function name: YaTeX:put)
2030 ~~~~~~~~~
2031 \sum_@{i=0@}^@{n@} (Function name: YaTeX:sum)
2032 ~~~~~~~~~~
2033 @end display
2035 Obviously, the function name is decided by concatenating the prefix
2036 `YaTeX:' and La@TeX{} command's name.
2038 Another add-in type is @dfn{argument add-in}, which completes arguments
2039 for section-type commands.
2041 @display
2042 \newcommand@{\foo@}@{bar@} (Function name: YaTeX::newcommand)
2043 ~~~~ ~~~
2044 @end display
2046 When the section-type command is inputted, the function named by
2047 concatenating `YaTeX::' and section-type command, is called automatically
2048 with an integer argument which indicates which argument of section-type
2049 command is being read. Thus the add-in should determine the
2050 job referring the value of its argument.
2052 @dfn{enclosing add-in} is for modifying and/or checking the region that
2053 will be enclosed by section-type commands via @kbd{[prefix] S}. An
2054 enclosing add-in function will be called with two arguments, beginning of
2055 the enclosed region and end of the region. Suppose you want to enclose
2056 the existing text @code{(a+b)/c} by @code{\frac@{@}}.
2058 @display
2059 a/c
2060 | |
2061 A B
2062 @end display
2064 You do set-mark-command at point A and then move to point B. Typing
2065 @kbd{[prefix] S} and input @code{frac} enclose the region like this;
2067 @display
2068 \frac@{a/c@}
2069 @end display
2071 Normally, the expression @code{a/c} is translated to
2072 @code{\frac@{a@}@{c@}}. An enclosing add-in is useful for modifying
2073 @code{/} to @code{@}@{}.
2075 @menu
2076 * Defining option-add-in::
2077 * Defining argument-add-in::
2078 * Defining enclosing-add-in::
2079 @end menu
2081 @node Defining option-add-in, Defining argument-add-in, How the add-in function works, How the add-in function works
2082 @comment node-name, next, previous, up
2083 @subsubsection Defining `option add-in'
2085 If you want @code{@{|c|c|c|@}} for all @code{tabular} environment,
2087 @lisp
2088 (defun YaTeX:tabular ()
2089 "@{|c|c|c|@}")
2090 @end lisp
2092 @noindent
2093 is enough. If you want more complicated format, define as below.
2095 @lisp
2096 (defun YaTeX:tabular ()
2097 "@{@@@{\\vrule width 1pt\\ @}|||@@@{\\ \\vrule width 1pt@}@}")
2098 @end lisp
2100 @noindent
2101 Note that the character @code{\} must be described as @code{\\} in
2102 Emacs-Lisp. The next example reads the tabular format from keyboard.
2103 @lisp
2104 (defun YaTeX:tabular ()
2105 (concat "@{" (read-string "Rule: ") "@}"))
2106 @end lisp
2108 @node Defining argument-add-in, Defining enclosing-add-in, Defining option-add-in, How the add-in function works
2109 @comment node-name, next, previous, up
2110 @subsubsection Defining `argument add-in'
2112 This section describes how to define the add-in function for
2113 @code{\newcommand}.
2115 The first argument of @code{\newcommand} begins always with @code{\}.
2116 The second argument is usually so complex that we can not edit them in the
2117 minibuffer. Here is the created function considering this.
2119 @lisp
2120 (defun YaTeX::newcommand (n) ;n is argument position
2121 (cond
2122 ((= n 1) ;1st argument is macro name
2123 (read-string "Command: " "\\")) ;initial input `\'
2124 ((= n 2) "") ;do nothing when reading arg#2
2125 (t nil)))
2126 @end lisp
2128 Note that when the `argument add-in' function return `nil', normal
2129 argument reader will be called.
2131 @node Defining enclosing-add-in, , Defining argument-add-in, How the add-in function works
2132 @comment node-name, next, previous, up
2133 @subsubsection Defining `enclosing add-in'
2135 This section describes how to define the add-in function for
2136 text enclosed by @code{\frac@{@}}.
2138 When enclosing the text @code{5/3} by @code{\frac@{@}}, you might want to
2139 replace @code{/} with @code{@}@{}. Enclosing function
2140 @code{YaTeX::frac-region} is called with two arguments, beginning of
2141 enclosed text and end of enclosed text. The function is expected to
2142 replace @code{/} with @code{@}@{}. Here is an example expression.
2144 @lisp
2145 (defun YaTeX::frac-region (beg end)
2146 (catch 'done
2147 (while (search-forward "/" end t)
2148 (goto-char (match-beginning 0))
2149 (if (y-or-n-p "Replace this slash(/) with `@}@{'")
2150 (throw 'done (replace-match "@}@{")))
2151 (goto-char (match-end 0)))))
2152 @end lisp
2154 @node How the function is called, Useful functions for creating add-in, How the add-in function works, Add-in functions
2155 @comment node-name, next, previous, up
2156 @subsection How the function is called
2158 YaTeX calls the add-in functions for specified begin-type, section-type,
2159 and maketitle-type command, if any. `Option add-in' functions for
2160 begin-type are called when @code{\begin@{ENV@}} has been inserted,
2161 functions for section-type are called just before input of the first
2162 argument, and functions for maketitle-type is called after maketitle-type
2163 command has been inserted. `Argument add-in' functions are called at each
2164 entry of arguments for section-type commands.
2166 @node Useful functions for creating add-in, Contribution, How the function is called, Add-in functions
2167 @comment node-name, next, previous, up
2168 @subsection Useful functions for creating add-in
2170 Many add-in functions for typical La@TeX{} commands are defined in
2171 @file{yatexadd.el}. Those are also useful as references. Here are the
2172 short descriptions on useful functions, where [F] means function, [A]
2173 means arguments, [D] means description.
2175 @table @kbd
2176 @item [F]
2177 YaTeX:read-position
2178 @itemx [A]
2179 Character list which can show up in the brackets
2180 @itemx [D]
2181 Return the location specifier such as `[htb]'. When
2182 nothing is entered, omit [] itself. If the possible characters
2183 are "htbp", call this function as
2184 @code{(YaTeX:read-position "htbp")}
2186 @item [F]
2187 YaTeX:read-coordinates
2188 @itemx [A]
2189 Base prompt, X-axis prompt, Y-axis prompt (each optional)
2190 @itemx [D]
2191 Read the coordinates with the prompt ``BasePrompt X-axisPrompt:'' for
2192 X-axis, ``BasePrompt Y-axisPrompt:'' for Y-axis, and return it in the form
2193 of ``(X,Y)''. The default prompts are @code{Dimension}, @code{X},
2194 @code{Y} respectively.
2196 @item [F]
2197 YaTeX:check-completion-type
2198 @itemx [A]
2199 One of the symbols: 'begin, 'section, or 'maketitle
2200 @itemx [D]
2201 Check the current completion type is specified one and cause error if
2202 not. The variable @code{YaTeX-current-completion-type} holds the symbol
2203 according to the current completion type.
2204 @end table
2206 @node Contribution, , Useful functions for creating add-in, Add-in functions
2207 @comment node-name, next, previous, up
2208 @subsection Contribution
2210 If you make your own pretty function and you let it be in public, please
2211 send me the function. I'm going to include it in the next release.
2213 @node Add-in generator, , Add-in functions, Customizations
2214 @comment node-name, next, previous, up
2215 @section Add-in generator
2217 First, don't forget to read the section of add-in functions @ref{Add-in
2218 functions}. If you easily understand how to define them, there's no need
2219 to read this section. But being not familiar with Emacs-Lisp, when you
2220 don't have clear idea what to do, this section describes how to get YaTeX
2221 make add-in function.
2223 There are two methods of generation. One is for fully interactive
2224 generator for beginners and another requires little knowledge of
2225 Emacs-Lisp.
2227 @subsection Generator for beginners
2228 The former generator is called by
2229 @center @kbd{M-x YaTeX-generate}
2231 @noindent
2232 strokes. All you have to do is follow the guidances. Defying them may cases
2233 the disaster (I wonder what is it???). So when you make some mistake, it
2234 is recommendable to type @kbd{C-g} and start afresh.
2236 @subsection Simple generator
2238 The latter generator is invoked by the next sequence.
2239 @center @kbd{M-x YaTeX-generate-simple}
2240 This generator can make both ``option add-in'' and ``argument add-in''
2241 (@emph{refer the section add-in functions}
2242 @ref{How the add-in function works}), whereas @code{YaTeX-generate}
2243 cannot make ``argument addin''.
2245 For example, assume you have the LaTeX command as follows.
2247 @example
2248 \epsinput[t](250,50)@{hoge.eps@}@{plain@}@{Picture of foo@}
2249 (A) (B) (1) (2) (3)
2250 (A)Optional parameter to specify the position
2251 One of t(top), b(bottom), l(left), r(right)
2252 (B)Maximum size of frame
2253 (1)1st argument is filename of EPS file
2254 (2)2nd argument indicates
2255 plain do nothing
2256 frame make frame around image
2257 dframe make double-frame around image
2258 for included EPS file.
2259 (3)Caption for the picture
2260 @end example
2262 Now get start with generation. Typing @kbd{M-x YaTeX-generate-simple}
2263 brings the prompt:
2264 @display
2265 (O)ption? (A)rgument?
2266 @end display
2268 @subsubsection Generating ``option add-in''
2269 @cindex option add-in
2271 Since (A), (B) above are optional argument, all we have to do to
2272 complete them is define the option add-in for them. Let's generate the
2273 function to complete (A).
2275 @display
2276 M-x YaTeX-generate-simple RET
2277 epsinput RET
2278 o
2279 @end display
2281 @noindent
2282 Typing as above leads the next prompt.
2284 @display
2285 Read type(1): (S)tring (C)omplete (F)ile ([)option (P)osition co(O)rd. (q)uit
2286 @end display
2288 @noindent
2289 This asks that ``Which type is the completion style of 1st argument?''.
2290 Here are the possible completion style.
2292 @table @code
2293 @item String
2294 read plain string
2295 @item Complete
2296 read with completion
2297 @item File
2298 read file name
2299 @item Option
2300 read optional string (if string omitted, omit [] too)
2301 @item Position
2302 read positional option (like [htbp])
2303 @item Coord.
2304 read coordinates
2305 @item Quit
2306 quit from generating
2307 @end table
2309 Since (A) is the optional argument to specify the location of included
2310 EPS file, the completion style is @code{Position}, and the possible
2311 characters are t, b, l, and r. To tell these information to generator,
2312 operate as follows.
2314 @display
2315 Read type(1).... p
2316 Acceptable characters: tblr RET
2317 @end display
2319 (B) is coordinate. So its completion style is coOrd. We want a prompt
2320 meaning ``Maximum size'' when completion.
2322 @display
2323 Read type(2).... o
2324 Prompt for coordinates: Max size RET
2325 @end display
2327 That's all for optional argument. Select quit.
2329 @display
2330 Read type(3).... q
2331 @end display
2333 Then the generated option add-in function for \epsinput will be shown in
2334 the next window.
2336 @subsubsection Generating ``argument add-in''
2337 @cindex argument add-in
2339 Next, create the argument add-in. The arguments for \epsinput are EPS
2340 file name, framing style, and caption string in sequence.
2342 @display
2343 M-x YaTeX-generate-simple RET
2344 epsinput RET
2345 a
2346 @end display
2348 Above key strokes bring the prompt that asks the number of argument.
2349 Answer it with 3.
2351 @display
2352 How many arguments?: 3 RET
2353 @end display
2355 Then the generator asks the completion style and prompt for completion.
2356 Answer them. @kbd{f} for FileName and prompt string.
2358 @display
2359 Read type(1).... f
2360 Prompt for argument#1 EPS file name RET
2361 @end display
2363 The second argument is one of selected symbol. So the completion type
2364 is @code{Completion}.
2366 @display
2367 Read type(2).... c
2368 Prompt for argument#2 Include style RET
2369 @end display
2371 Then all the candidates ready to be read. Type single RET after
2372 entering all.
2374 @display
2375 Item[1](RET to exit): plain RET
2376 Item[2](RET to exit): frame RET
2377 Item[3](RET to exit): dframe RET
2378 Item[4](RET to exit): RET
2379 @end display
2381 The following prompt asks whether the entered string must belong to
2382 candidates or not. In this case, since the argument must be one of
2383 @code{plain}, @code{frame}, and @code{dframe}, type @code{y}.
2385 @display
2386 Require match? (y or n) y
2387 @end display
2389 The last argument is the caption string for which any completion is
2390 needed.
2392 @display
2393 Read type(3).... s
2394 Prompt for argument#3 Caption RET
2395 default: Figure of RET
2396 @end display
2398 Finally we'll get the argument add-in in the next window.
2400 @subsection Contribution
2402 If you get your own pretty function and you let it be in public, please
2403 steel yourself in the happy atmosphere and do not send me the function.
2404 I do know it is not fine because it is generated by yatexgen:-p.
2406 @node Etcetera, Copying, Customizations, Top
2407 @comment node-name, next, previous, up
2408 @chapter Etcetera
2410 The standard completion tables provided in @file{yatex.el} contain a
2411 few La@TeX{} commands I frequently use. This is to lessen the key
2412 strokes to complete entire word, because too many candidates
2413 rarely used often cause too many hits. Therefore always try to
2414 use completion in order to enrich your dictionary, and you will
2415 also find `Wild Bird' growing suitable for your La@TeX{} style.
2417 The package name `Wild Bird' is the English translation of Japanese
2418 title `Yachou', which is a trick on words of Japanese.
2420 @node Copying, , Etcetera, Top
2421 @comment node-name, next, previous, up
2422 @chapter Copying
2424 This program is distributed as a free software. You can
2425 use/copy/modify/redistribute this software freely but with NO warranty to
2426 anything as a result of using this software. Adopting code from this
2427 program is also free. But I would not do contract act.
2429 Any reports and suggestions are welcome as long as I feel interests in
2430 this software. My possible e-mail address is `yuuji@@yatex.org'. (as of
2431 Jan.2004) And there is mailing list for YaTeX. Although the common
2432 language is Japanese, questions in English will be welcome. To join the
2433 ML, send the mail whose subject is `append' to the address
2434 `yatex@@yatex.org. If you have some question, please ask to
2435 `yatex-admin@@yatex.org'.
2437 The specification of this software will be surely modified
2438 (depending on my feelings) without notice :-p.
2441 @flushright
2442 HIROSE Yuuji
2443 @end flushright
2444 @bye
2446 Local variables:
2447 mode: texinfo
2448 fill-prefix: nil
2449 fill-column: 74
2450 End: