yatex
view docs/yatexe.tex @ 379:09a2b5a3b3d8
Describe about [prefix] t d and [prefix] t e and so on.
| author | HIROSE Yuuji <yuuji@gentei.org> |
|---|---|
| date | Sun, 04 Jan 2015 21:06:32 +0900 |
| parents | f7ae3e4be0bb |
| children | c44910b36b95 |
line source
1 \def\lang{jp} % -*- texinfo -*-
2 \input texinfo.tex
3 @setfilename yatexe
4 @settitle Yet Another tex-mode for Emacs
5 @direntry
6 * YaTeX-e: (yatexe). Yet Another tex-mode for Emacs (English).
7 @end direntry
9 @iftex
10 @c @syncodeindex fn cp
11 @c Last modified Sun Jan 4 18:17:02 2015 on firestorm
12 @syncodeindex vr cp
13 @end iftex
15 @titlepage
16 @sp 10
17 @center
18 @subtitle Yet Another tex-mode for emacs
19 @title Wild Bird
20 @subtitle // YaTeX //
21 @author @copyright{} 1991-2012 by HIROSE, Yuuji [yuuji@@yatex.org]
22 @end titlepage
24 @node Top, What is YaTeX?, (dir), (dir)
25 @comment node-name, next, previous, up
26 @cindex Demacs
27 @cindex Mule
28 @cindex LaTeX
29 @cindex YaTeX
31 @menu
32 * What is YaTeX?::
33 * Main features:: What YaTeX can do
34 * Installation:: Guide to install
35 * Typesetting:: Call typesetting processes
36 * %#notation:: Meta-keyword `%#'
37 * Completion:: Input LaTeX commands with completion
38 * Local dictionaries:: Directory dependent completion
39 * Commenting out:: Commenting/uncommenting text
40 * Cursor jump:: Jumping to related position
41 * Changing and Deleting:: Changing/deleting certain unit of text
42 * Filling:: Filling an item or paragraph
43 * Updation of includeonly:: Free from maintaining includeonly
44 * What column:: Check what table-column the cursor belong
45 * Intelligent newline:: Guess requisites of new line
46 * Usepackage checker:: Selecting correct \usepackage is YaTeX's job
47 * Online help:: On-line documentation of LaTeX
48 * Browsing file hierarchy:: Walking through file hierarchy
49 * Cooperation with other packages:: Work well with gmhist, min-out
50 * Customizations:: How to breed `Wild Bird'
51 * Etcetera:: YaTeX is acquisitive.
52 * Copying:: Redistribution
54 @end menu
56 @node What is YaTeX?, Main features, Top, Top
57 @comment node-name, next, previous, up
58 @chapter What is YaTeX?
60 YaTeX automates typesetting and previewing of LaTeX and enables
61 completing input of LaTeX mark-up command such as
62 @code{\begin@{@}}..@code{\end@{@}}.
64 YaTeX also supports Demacs which runs on MS-DOS(386), Mule (Multi
65 Language Enhancement to GNU Emacs), and latex on DOS.
67 @node Main features, Installation, What is YaTeX?, Top
68 @comment node-name, next, previous, up
69 @chapter Main features
71 @itemize
72 @item Invocation of typesetter, previewer and related programs(@kbd{C-c t})
73 @item Typesetting on static region which is independent from point
74 @item Semiautomatic replacing of @code{\includeonly}
75 @item Jumping to error line(@kbd{C-c '})
76 @item Completing-read of La@TeX{} commands such as @code{\begin@{@}},
77 @code{\section} etc.
78 (@kbd{C-c b}, @kbd{C-c s}, @kbd{C-c l}, @kbd{C-c m})
79 @item Enclosing text into La@TeX{} environments or commands
80 (@kbd{C-u} @var{AboveKeyStrokes})
81 @item Displaying the structure of text at entering sectioning commands
82 @item Lump shifting of sectioning commands (@ref{view-sectioning})
83 @item Learning unknown/new La@TeX{} commands for the next completion
84 @item Argument reading with a guide for complicated La@TeX{} commands
85 @item Generating argument-readers for new/unsupported commands(@file{yatexgen})
86 @item Quick changing or deleting of La@TeX{} commands(@kbd{C-c c}, @kbd{C-c k})
87 @item Jumping from and to inter-file, begin<->end, ref<->label(@kbd{C-c g})
88 @item Blanket commenting out or uncommenting
89 (@kbd{C-c >}, @kbd{C-c <}, @kbd{C-c ,}, @kbd{C-c .})
90 @item Easy input of accent mark, math-mode's commands and Greek letters
91 (@kbd{C-c a}, @kbd{;}, @kbd{:})
92 @item Online help for the popular La@TeX{} commands
93 (@kbd{C-c ?}, @kbd{C-c /})
94 @item Document files hierarchy browser (@kbd{C-c d})
95 @item Adding automatically \usepackage corresponding to inputting LaTeX
96 macro with completion
97 @item Allow you to forget creating \label@{@}s, \ref@{@} or \cite@{@}
98 completion automatically generate labels.
99 @end itemize
101 @node Installation, Typesetting, Main features, Top
102 @comment node-name, next, previous, up
103 @chapter Installation
104 @cindex installation
105 @cindex .emacs
106 @cindex auto-mode-alist
107 @cindex autoload
109 Put next two expressions into your @file{~/.emacs}.
111 @lisp
112 (setq auto-mode-alist
113 (cons (cons "\\.tex$" 'yatex-mode) auto-mode-alist))
114 (autoload 'yatex-mode "yatex" "Yet Another La@TeX{} mode" t)
115 @end lisp
117 Next, add certain path name where you put files of YaTeX to your
118 load-path. If you want to put them in @file{~/src/emacs}, write
120 @lisp
121 (setq load-path
122 (cons (expand-file-name "~/src/emacs") load-path))
123 @end lisp
125 @noindent
126 in your @file{~/.emacs}
128 Then, yatex-mode will be automatically loaded when you visit a
129 file which has extension @file{.tex}. If yatex-mode is successfully
130 loaded, mode string on mode line will be turned to "YaTeX".
133 @node Typesetting, %#notation, Installation, Top
134 @comment node-name, next, previous, up
135 @chapter Typesetting
136 @cindex typesetting
137 @cindex previewer
138 @cindex typesetter
139 @cindex latex
140 @cindex printing out
142 The prefix key stroke of yatex-mode is @kbd{C-c} (Press 'C' with Control
143 key) by default. If you don't intend to change the prefix key stroke,
144 assume all @kbd{[prefix]} as @kbd{C-c} in this document. These key
145 strokes execute typeset or preview command.
147 @table @kbd
148 @item [prefix] t j
149 @dots{} invoke latex
150 @item [prefix] t r
151 @dots{} invoke latex on region
152 @item [prefix] t e
153 @dots{} invoke latex on current environment or whole
154 portion of current formulas in math-mode.
155 @item [prefix] t d
156 @dots{} invoke dvipdfmx after successful typesetting
157 @item [prefix] t k
158 @dots{} kill current typesetting process
159 @item [prefix] t b
160 @dots{} invoke bibtex
161 @item [prefix] t i
162 @dots{} invoke makeindex
163 @item [prefix] t d
164 @dots{} invoke latex && dvipdfmx
165 @item [prefix] t p
166 @dots{} preview
167 @item [prefix] t l
168 @dots{} lpr dvi-file
169 @item [prefix] t s
170 @dots{} search current string on xdvi-remote
171 @end table
173 @menu
174 * Calling typesetter::
175 * Calling previewer::
176 * Printing out::
177 @end menu
179 @node Calling typesetter, Calling previewer, Typesetting, Typesetting
180 @comment node-name, next, previous, up
181 @section Calling typesetter
183 Typing @kbd{[prefix] t j}, the current editing window will be divided
184 horizontally when you invoke latex command, and log message of La@TeX{}
185 typesetting will be displayed in the other window; called typesetting
186 buffer. The typesetting buffer automatically scrolls up and traces
187 La@TeX{} warnings and error messages. If you see latex stopping by an
188 error, you can send string to latex in the typesetting buffer.
190 If an error stops the La@TeX{} typesetting, this key stroke will
191 move the cursor to the line where La@TeX{} error is detected.
193 @table @kbd
194 @item [prefix] '
195 @itemx ([prefix]+single quotation)
197 @dots{} jump to the previous error or warning
198 @end table
200 If you find a noticeable error, move to the typesetting buffer and move
201 the cursor on the line of error message and type @kbd{SPACE} key. This
202 makes the cursor move to corresponding source line.
204 YaTeX-typeset-region invoked by @kbd{[prefix] tr} call typesetter
205 for region. The region is specified by standard point and mark, or
206 by @code{%#BEGIN} and @code{%#END} marks. Selected region will be
207 copied to the temporary file @file{texput.tex} with the same preamble
208 as the main file of current editing sources. Be sure to put
209 all local macro settings in preamble, not after @code{\begin@{document@}}.
210 The method of specification of the region is shown in the
211 section @xref{%#notation}.
213 The documentclass for typeset-region is the same as that of editing
214 file if you edit one file, and is the same as main file's if you
215 edit splitting files.
217 The @kbd{[prefix] te} key automatically marks current inner environment
218 or inner math mode and then call typeset-region with marked region. This
219 is convenient to quick view of current tabular environment or current
220 editing formulas. Keeping previewer window for @file{texput.dvi} is handy
221 for debugging. Since @kbd{[prefix] te} selects the inner-most environment
222 as region, it is not suitable for partial typesetting of doubly or more
223 composed environment. If you want to do partial typesetting for a nested
224 environment, use @kbd{[prefix] tr} for static-region, which is described
225 in the section @xref{%#notation}.
227 @node Calling previewer, Printing out, Calling typesetter, Typesetting
228 @comment node-name, next, previous, up
229 @section Calling previewer
231 @kbd{[prefix] t p} invokes the TeX previewer. And if you are using
232 xdvi-remote, which can be controled from other terminals, @kbd{[prefix] t
233 s} enables you to search current string at the cursor on the running xdvi
234 window.
236 @node Printing out, , Calling previewer, Typesetting
237 @comment node-name, next, previous, up
238 @section Printing out
240 When you type @code{[preifx] t l}, YaTeX asks you the range of
241 dvi-printing by default. You can skip this by invoking it with
242 universal-argument as follows:
244 @example
245 C-u [prefix] tl
246 @end example
248 @node %#notation, Completion, Typesetting, Top
249 @comment node-name, next, previous, up
250 @chapter %# notation
251 @cindex %# notation
253 You can control the typesetting process by describing @code{%#}
254 notations in the source text.
256 @menu
257 * Changing typesetter::
258 * Splitting input files::
259 * Static region for typesetting::
260 * Lpr format::
261 * Controlling which command to invoke::
262 * Editing %# notation::
263 @end menu
265 @node Changing typesetter, Splitting input files, %#notation, %#notation
266 @comment node-name, next, previous, up
267 @section To change the `latex' command or to split a source text.
268 @cindex typesetter
270 To change the typesetting command, write
272 @example
273 %#!latex-big
274 @end example
276 @noindent
277 anywhere in the source text. This is useful for changing
278 typesetter.
280 @node Splitting input files, Static region for typesetting, Changing typesetter, %#notation
281 @comment node-name, next, previous, up
282 @section Splitting input files
284 And if you split the source text and
285 edit subfile that should be included from main text.
287 @example
288 %#!latex main.tex
289 @end example
291 @noindent
292 will be helpful to execute latex on main file from sub text buffer. Since
293 this command line after @kbd{%#!} will be sent to shell literally, next
294 description makes it convenient to use ghostview as dvi-previewer.
296 @example
297 %#!latex main && dvi2ps main.dvi > main
298 @end example
300 @noindent
301 Note that YaTeX assumes the component before the last period of
302 the last word in this line as base name of the main La@TeX{} source.
303 The @code{%f} notation in this line is replaced by main file name, and
304 @code{%r} replaced by root name of main file name. If you specify
305 @code{%f} or @code{%r}, YaTeX always ask you the name of main file at the
306 first typesetting.
308 To make best use of the feature of inter-file jumping by
309 @kbd{[prefix] g} (see @ref{Cursor jump}), take described below into
310 consideration.
312 @itemize
313 @item You can put split texts in sub directory, but not in
314 sub directory of sub directory.
315 @item In the main text, specify the child file name with relative path name
316 such as \include@{chap1/sub@}, when you include the file in
317 a sub-directory.
318 @item In a sub-text, write @code{%#!latex main.tex} even if @file{main.tex}
319 is in the parent directory(not %#!latex ../main.tex).
320 @end itemize
322 @node Static region for typesetting, Lpr format, Splitting input files, %#notation
323 @comment node-name, next, previous, up
324 @section Static region
325 @cindex static region
326 @cindex Fixed region
328 Typeset-region by @kbd{[prefix] tr} passes the region between point and
329 mark to typesetting command by default. But when you want to typeset
330 static region, enclose the region by @code{%#BEGIN} and @code{%#END} as
331 follows.
333 @example
334 %#BEGIN
335 TheRegionYouWantToTypesetManyTimes
336 %#END
337 @end example
339 This is the rule of deciding the region.
341 @enumerate
342 @item
343 If there exists %#BEGIN before point,
345 @enumerate
346 @item
347 If there exists %#END after %#BEGIN,
348 @itemize
349 @item From %#BEGIN to %#END.
350 @end itemize
352 @item
353 If %#END does not exist after %#BEGIN,
354 @itemize
355 @item From %#BEGIN to the end of buffer.
356 @end itemize
357 @end enumerate
359 @item
360 If there does not exist %#BEGIN before point,
361 @itemize
362 @item Between point and mark(standard method of Emacs).
363 @end itemize
364 @end enumerate
366 It is useful to write @code{%#BEGIN} in the previous line of \begin and
367 @code{%#END} in the next line of \@code{end} when you try complex
368 environment such as `tabular' many times. It is also useful to put only
369 @code{%#BEGIN} alone at the middle of very long text. Do not forget to
370 erase @code{%#BEGIN} @code{%#END} pair.
372 @node Lpr format, Controlling which command to invoke, Static region for typesetting, %#notation
373 @comment node-name, next, previous, up
374 @section Lpr format
375 @cindex lpr format
377 Lpr format is specified by three Lisp variables. Here are the
378 default values of them.
380 @table @code
381 @item (1)dviprint-command-format
382 @code{"dvi2ps %f %t %s | lpr"}
383 @item (2)dviprint-from-format
384 @code{"-f %b"}
385 @item (3)dviprint-to-format
386 @code{"-t %e"}
387 @end table
389 On YaTeX-lpr, @code{%s} in (1) is replaced by the file name of main
390 text, @code{%f} by contents of (2), %t by contents of (3). At these
391 replacements, @code{%b} in (2) is also replaced by the number of beginning
392 page, @code{%e} in (3) is replaced by the number of ending page. But
393 @code{%f} and @code{%t} are ignored when you omit the range of print-out
394 by @kbd{C-u [prefix] tl}.
396 If you want to change this lpr format temporarily, put a command
397 such as follows somewhere in the text:
399 @example
400 %#LPR dvi2ps %f %t %s | 4up -page 4 | texfix | lpr -Plp2
401 @end example
403 And if you want YaTeX not to ask you the range of printing
404 out, the next example may be helpful.
406 @example
407 %#LPR dvi2ps %s | lpr
408 @end example
410 @node Controlling which command to invoke, Editing %# notation, Lpr format, %#notation
411 @comment node-name, next, previous, up
412 @section Controlling which command to invoke
414 These %# notation below can control which command to invoke for
415 La@TeX{} related process.
417 @table @code
418 @item %#BIBTEX
419 @dots{} Command line for makeindex ([prefix] t i)
420 @item %#MAKEINDEX
421 @dots{} Command line for bibtex ([prefix] t b)
422 @item %#DVIPDF
423 @dots{} Command line for dvipdf(mx) ([prefix] t b)
424 @end table
426 If you want to invoke ``makeidx hogehoge'' to update index,
427 put the next line some upper place in the source, for example.
429 @example
430 %#MAKEINDEX makeidx hogehoge
431 @end example
434 @node Editing %# notation, , Controlling which command to invoke, %#notation
435 @comment node-name, next, previous, up
436 @section Editing %# notation
438 To edit @code{%#} notation described above, type
440 @table @kbd
441 @item [prefix] %
442 @dots{} editing %# notation menu
443 @end table
445 @noindent
446 and select one of the entry of the menu as follows.
448 @example
449 !)Edit-%#! B)EGIN-END-region L)Edit-%#LPR
450 @end example
452 @noindent
453 Type @kbd{!} to edit @code{%#!} entry, @code{b} to enclose the region with
454 @code{%#BEGIN} and @code{%#END}, and @code{l} to edit @code{%#LPR} entry.
455 When you type @kbd{b}, all @code{%#BEGIN} and @code{%#END} are
456 automatically erased.
458 @node Completion, Local dictionaries, %#notation, Top
459 @comment node-name, next, previous, up
460 @chapter Completion
461 @cindex completion
463 YaTeX makes it easy to input the La@TeX{} commands. There are several
464 kinds of completion type, begin-type, section-type, large-type, etc...
466 @menu
467 * Begin-type completion::
468 * Section-type completion::
469 * Large-type completion::
470 * Maketitle-type completion::
471 * Arbitrary completion::
472 * End completion::
473 * Accent completion::
474 * Image completion::
475 * Greek letters completion::
476 @end menu
478 @node Begin-type completion, Section-type completion, Completion, Completion
479 @comment node-name, next, previous, up
480 @section Begin-type completion
481 @cindex begin-type completion
482 @cindex environment
483 @cindex prefix b
485 "Begin-type completion" completes commands of @code{\begin@{env@}} ...
486 @code{\end@{env@}}. All of the begin-type completions begin with this key
487 sequence.
489 @table @kbd
490 @item [prefix] b
491 @dots{} start begin-type completion
492 @end table
494 @noindent
495 An additional key stroke immediately completes a frequently used
496 La@TeX{} @code{\begin@{@}}...@code{\@code{end}@{@}} environment.
498 @table @kbd
499 @item [prefix] b c
500 @dots{} @code{\begin@{center@}...\end@{center@}}
501 @item [prefix] b d
502 @dots{} @code{\begin@{document@}...\end@{document@}}
503 @item [prefix] b D
504 @dots{} @code{\begin@{description@}...\end@{description@}}
505 @item [prefix] b e
506 @dots{} @code{\begin@{enumerate@}...\end@{enumerate@}}
507 @item [prefix] b E
508 @dots{} @code{\begin@{equation@}...\end@{equation@}}
509 @item [prefix] b i
510 @dots{} @code{\begin@{itemize@}...\end@{itemize@}}
511 @item [prefix] b l
512 @dots{} @code{\begin@{flushleft@}...\end@{flushleft@}}
513 @item [prefix] b m
514 @dots{} @code{\begin@{minipage@}...\end@{minipage@}}
515 @item [prefix] b t
516 @dots{} @code{\begin@{tabbing@}...\end@{tabbing@}}
517 @item [prefix] b T
518 @dots{} @code{\begin@{tabular@}...\end@{tabular@}}
519 @item [prefix] b^T
520 @dots{} @code{\begin@{table@}...\end@{table@}}
521 @item [prefix] b p
522 @dots{} @code{\begin@{picture@}...\end@{picture@}}
523 @item [prefix] b q
524 @dots{} @code{\begin@{quote@}...\end@{quote@}}
525 @item [prefix] b Q
526 @dots{} @code{\begin@{quotation@}...\end@{quotation@}}
527 @item [prefix] b r
528 @dots{} @code{\begin@{flushright@}...\end@{flushright@}}
529 @item [prefix] b v
530 @dots{} @code{\begin@{verbatim@}...\end@{verbatim@}}
531 @item [prefix] b V
532 @dots{} @code{\begin@{verse@}...\end@{verse@}}
533 @end table
535 Any other La@TeX{} environments are made by completing-read of the
536 Emacs function.
538 @table @kbd
539 @item [prefix] b SPACE
540 @dots{} begin-type completion
541 @end table
543 @noindent
544 The next message will show up in the minibuffer
546 @example
547 Begin environment(default document):
548 @end example
550 @noindent
551 by typing @kbd{[prefix] b}. Put the wishing environment with completion
552 in the minibuffer, and @code{\begin@{env@}}...\@code{\end@{env@}} will be
553 inserted in the La@TeX{} source text. If the environment you want to put
554 does not exist in the YaTeX completion table, it will be registered in the
555 user completion table. YaTeX automatically saves the user completion
556 table in the user dictionary file at exiting of emacs.
558 At the completion of certain environments, the expected initial entry will
559 automatically inserted such as @code{\item} for @code{itemize}
560 environment. If you don't want the entry, it can be removed by undoing.
562 If you want to enclose some paragraphs which have already been
563 written, invoke the begin-type completion with changing the case
564 of @kbd{b} of key sequence upper(or invoke it with universal argument
565 by @kbd{C-u} prefix).
566 @cindex enclose region into environment
568 The following example encloses a region with `description'
569 environment.
571 @table @kbd
572 @item [prefix] B D
573 @itemx (or ESC 1 [prefix] b D)
574 @itemx (or C-u [prefix] b D)
576 @dots{} begin-type completion for region
577 @end table
579 This enclosing holds good for the completing input by @kbd{[prefix] b
580 SPC}. @kbd{[prefix] B SPC} enclose a region with the environment selected
581 by completing-read.
583 @node Section-type completion, Large-type completion, Begin-type completion, Completion
584 @comment node-name, next, previous, up
585 @section Section-type completion
586 @cindex section-type completion
587 @cindex prefix s
589 "Section-type completion" completes section-type commands which take an
590 argument or more such as @code{\section@{foo@}}. To invoke section-type
591 completion, type
593 @table @kbd
594 @item [prefix] s
595 @dots{} section-type completion
596 @end table
598 @noindent
599 then the prompt
601 @example
602 (C-v for view) \???@{@} (default documentclass):
603 @end example
605 @noindent
606 will show up in the minibuffer. Section-type La@TeX{} commands are
607 completed by space key, and the default value is selected when you
608 type nothing in the minibuffer.
610 Next,
612 @example
613 \section@{???@}:
614 @end example
616 @noindent
617 prompts you the argument of section-type La@TeX{} command. For
618 example, the following inputs
620 @example
621 \???@{@} (default documentclass): section
622 \section@{???@}: Hello world.
623 @end example
625 @noindent
626 will insert the string
628 @example
629 \section@{Hello world.@}
630 @end example
632 in your La@TeX{} source. When you neglect argument such as
634 @example
635 (C-v for view) \???@{@} (default section): vspace*
636 \vspace*@{???@}:
637 @end example
639 YaTeX puts
641 @example
642 \vspace*@{@}
643 @end example
645 @noindent
646 and move the cursor in the braces.
648 In La@TeX{} command, there are commands which take more than one
649 arguments such as @code{\addtolength@{\topmargin@}@{8mm@}}. To complete these
650 commands, invoke section-type completion with universal argument as,
651 @cindex number of argument
653 @example
654 C-u 2 [prefix] s (or ESC 2 [prefix] s)
655 @end example
657 @noindent
658 and make answers in minibuffer like this.
660 @example
661 (C-v for view) \???@{@} (default vspace*): addtolength
662 \addtolength@{???@}: \topmargin
663 Argument 2: 8mm
664 @end example
666 @code{\addtolength} and the first argument @code{\topmargin} can be typed
667 easily by completing read. Since YaTeX also learns the number of
668 arguments of section-type command and will ask that many arguments in
669 future completion, you had better tell the number of arguments to YaTeX at
670 the first completion of the new word. But you can change the number of
671 arguments by calling the completion with different universal argument
672 again.
675 Invoking section-type completion with @code{[Prefix] S} (Capital `S')
676 includes the region as the first argument of section-type command.
678 The section/large/maketitle type completion can work at the
679 prompt for the argument of other section-type completion.
680 Nested La@TeX{} commands are efficiently read with the recursive
681 completion by typing YaTeX's completion key sequence in the
682 minibuffer.
684 @menu
685 * view-sectioning::
686 @end menu
688 @node view-sectioning, , Section-type completion, Section-type completion
689 @comment node-name, next, previous, up
690 @subsection view-sectioning
691 @cindex view sectioning
692 @cindex outline
694 In the minibuffer at the prompt of section-type command completion,
695 typing @kbd{C-v} shows a list of sectioning commands in source text(The
696 line with @code{<<--} mark is the nearest sectioning command). Then,
697 default sectioning command appears in the minibuffer. You can go up/down
698 sectioning command by typing @kbd{C-p}/@kbd{C-n}, can scrolls up/down the
699 listing buffer by @kbd{C-v}/@kbd{M-v}, and can hide sectioning commands
700 under certain level by 0 through 6. Type @kbd{?} in the minibuffer of
701 sectioning prompt for more information.
703 You can generate this listing buffer (@code{*Sectioning Lines*} buffer)
704 by typing
705 @table @kbd
706 @item M-x YaTeX-section-overview
707 @dots{} Generate *Sectioning Lines* buffer
708 @end table
709 @cindex{Generate the listing of sectioning units}
710 from the LaTeX source buffer. In this listing buffer, typing @kbd{u} on
711 the sectioning command shifts up the corresponding sectioning command in
712 source text and @kbd{d} shifts down. After marking lines in the listing
713 buffer, typing @kbd{U} shifts up all sectioning commands in the region,
714 and @kbd{U} shifts down. Here are all the key bindings of
715 @code{*Sectioning Lines*} buffer.
717 @table @kbd
718 @item SPC
719 @dots{} Jump to corresponding source line
720 @item .
721 @dots{} Display corresponding source line
722 @item u
723 @dots{} Shift up a sectioning line
724 @item d
725 @dots{} Shift down a sectioning line
726 @item U
727 @dots{} Shift up sectioning lines in region
728 @item D
729 @dots{} Shift down sectioning lines in region
730 @item 0@dots{}6
731 @dots{} Hide sectioning commands whose level is lower than n
732 @end table
735 @node Large-type completion, Maketitle-type completion, Section-type completion, Completion
736 @comment node-name, next, previous, up
737 @section Large-type completion
739 "Large-type completion" inputs the font or size changing
740 descriptions such as @code{@{\large @}}. When you type
742 @table @kbd
743 @item [prefix] l
744 @dots{} large-type completion
745 @end table
747 @noindent
748 the message in the minibuffer
750 @example
751 @{\??? @} (default large):
752 @end example
754 prompts prompts you large-type command with completing-read. There are
755 TeX commands to change fonts or sizes, @code{it}, @code{huge} and so on,
756 in the completion table.
758 Region-based completion is also invoked by changing the letter after
759 prefix key stroke as @kbd{[prefix] L}. It encloses the region by braces
760 with large-type command.
762 @node Maketitle-type completion, Arbitrary completion, Large-type completion, Completion
763 @comment node-name, next, previous, up
764 @section Maketitle-type completion
765 @cindex maketitle-type completion
767 We call it "maketitle-type completion" which completes commands such as
768 @code{\maketitle}. Take notice that maketitle-type commands take no
769 arguments. Then, typing
771 @table @kbd
772 @item [prefix] m
773 @dots{} maketitle-type completion
774 @end table
776 @noindent
777 begins maketitle-completion. Above mentioned method is true for
778 maketitle-completion, and there are La@TeX{} commands with no
779 arguments in completion table.
781 @node Arbitrary completion, End completion, Maketitle-type completion, Completion
782 @comment node-name, next, previous, up
783 @section Arbitrary completion
784 @cindex arbitrary completion
786 @noindent
787 You can complete certain La@TeX{} command anywhere without typical
788 completing method as described, by typing
790 @table @kbd
791 @item [prefix] SPC
792 @dots{} arbitrary completion
793 @end table
795 @noindent
796 after the initial string of La@TeX{} command that is preceded by @code{\}.
798 @node End completion, Accent completion, Arbitrary completion, Completion
799 @comment node-name, next, previous, up
800 @section End completion
801 @cindex end completion
803 @noindent
804 YaTeX automatically detects the opened environment and close it with
805 \@code{\end@{environment@}}. Though proficient YaTeX users never fail to
806 make environment with begin-type completion, some may begin an environment
807 manually. In that case, type
809 @table @kbd
810 @item [prefix] e
811 @dots{} @code{end} completion
812 @end table
814 @noindent
815 at the end of the opened environment.
817 @node Accent completion, Image completion, End completion, Completion
818 @comment node-name, next, previous, up
819 @section Accent completion
820 @cindex accent completion
822 When you want to write the European accent marks(like @code{\`@{o@}}),
824 @table @kbd
825 @item [prefix] a
826 @dots{} accent completion
827 @end table
829 @noindent
830 shows the menu
832 @example
833 1:` 2:' 3:^ 4:" 5:~ 6:= 7:. u v H t c d b
834 @end example
836 @noindent
837 in the minibuffer. Chose one character or corresponding numeric,
838 and you will see
840 @example
841 \`@{@}
842 @end example
844 @noindent
845 in the editing buffer with the cursor positioned in braces. Type
846 one more character `o' for example, then
848 @example
849 \`@{o@}
850 @end example
852 @noindent
853 will be completed, and the cursor gets out from braces.
855 @node Image completion, Greek letters completion, Accent completion, Completion
856 @comment node-name, next, previous, up
857 @section Image completion of mathematical sign
858 @cindex image completion
859 @cindex math-mode
860 @cindex sigma
861 @cindex leftarrow
862 @cindex ;
864 Arrow marks, sigma mark and those signs mainly used in the
865 TeX's math environment are completed by key sequences which
866 imitate the corresponding symbols graphically. This completion
867 only works in the math environment. YaTeX automatically detects
868 whether the cursor located in math environment or not, and
869 change the behavior of key strokes @kbd{;} and @kbd{:}.
871 By the way, we often express the leftarrow mark by `<-' for example.
872 Considering such image, you can write @code{\leftarrow} by typing @kbd{<-}
873 after @kbd{;} (semicolon) as a prefix. In the same way,
874 @code{\longleftarrow} (@code{<--}) is completed by typing @kbd{;<--},
875 infinity mark which is imitated by @code{oo} is completed by typing
876 @kbd{;oo}.
878 Here are the sample operations in YaTeX math-mode.
880 @example
881 INPUT Completed La@TeX{} commands
882 ; < - @code{\leftarrow}
883 ; < - - @code{\longleftarrow}
884 ; < - - > @code{\longleftrightarrow}
885 ; o @code{\circ}
886 ; o o @code{\infty}
887 @end example
889 In any case, you can quit from image completion and can move
890 to the next editing operation if the La@TeX{} command you want is
891 shown in the buffer.
893 @code{;} itself in math-environment is inserted by @kbd{;;}. Typing
894 @kbd{TAB} in the midst of image completion shows all of the La@TeX{}
895 commands that start with the same name as string you previously typed in.
896 In this menu buffer, press @kbd{RET} after moving the cursor (by @kbd{n},
897 @kbd{p}, @kbd{b}, @kbd{f}) to insert the La@TeX{} command.
899 To know all of the completion table, type @kbd{TAB} just after @kbd{;}.
900 And here is the sample menu by @kbd{TAB} after @kbd{;<}.
902 @example
903 KEY LaTeX sequence sign
904 < \leq <
905 ~
906 << \ll <<
907 <- \leftarrow <-
908 <= \Leftarrow <=
909 @end example
911 You can define your favorite key-vs-sequence completion table in the
912 Emacs-Lisp variable @code{YaTeX-math-sign-alist-private}. See also
913 @file{yatexmth.el} for the information of the structure of this variable.
915 @node Greek letters completion, , Image completion, Completion
916 @comment node-name, next, previous, up
917 @section Greek letters completion
918 @cindex Greek letters completion
919 @cindex :
921 Math-mode of YaTeX provides another image completion, Greek letters
922 completion in the same method. After prefix @kbd{:}, typing @kbd{a} makes
923 @code{\alpha}, @kbd{b} makes @code{\beta} and @kbd{g} makes @code{\gamma}
924 and so on. First, type @kbd{:TAB} to know all the correspondence of
925 alphabets vs. Greek letters.
927 If you will find @kbd{;} or @kbd{:} doesn't work in correct position of
928 math environment, it may be a bug of YaTeX. Please send me a bug report
929 with the configuration of your text, and avoid it temporarily by typing
930 @kbd{;} or @kbd{:} after universal-argument(@kbd{C-u}) which forces
931 @kbd{;} and @kbd{:} to work as math-prefix.
933 @node Local dictionaries, Commenting out, Completion, Top
934 @comment node-name, next, previous, up
935 @chapter Local dictionaries
936 @cindex local dictionaries
937 @cindex nervous users
939 Tables for completion consist of three dictionaries; `standard
940 dictionary' built in @file{yatex.el}, `user dictionary' for your common
941 private commands, and `local dictionary' that is effective in a certain
942 directory.
944 When you input the command unknown to YaTeX at a completion in the
945 minibuffer, YaTeX asks you with the following prompt;
947 @example
948 `foo' is not in table. Register into: U)serDic L)ocalDic N)one D)iscard
949 @end example
951 @noindent
952 In this menu, typing @kbd{u} updates your `user dictionary', @kbd{l}
953 updates your local dictionary, @kbd{n} updates only on-memory dictionary
954 which go through only current Emacs session, and @kbd{d} updates no
955 dictionary and throws the new word away.
957 If you find this switching feature meaningless and bothersome, put the
958 next expression into your @file{~/.emacs}
960 @lisp
961 (setq YaTeX-nervous nil)
962 @end lisp
964 @node Commenting out, Cursor jump, Local dictionaries, Top
965 @comment node-name, next, previous, up
966 @chapter Commenting out
967 @cindex commenting out
968 @cindex prefix >
969 @cindex prefix <
970 @cindex prefix ,
971 @cindex prefix .
973 You may want to comment out some region.
975 @table @kbd
976 @item [prefix] >
977 @dots{} comment out region by %
978 @item [prefix] <
979 @dots{} uncomment region
980 @end table
982 @noindent
983 cause an operation to the region between point and mark.
985 @table @kbd
986 @item [prefix] .
987 @dots{} comment out current paragraph
988 @item [prefix] ,
989 @dots{} uncomment current paragraph
990 @end table
992 @noindent
993 comments or uncomments the paragraph where the cursor belongs.
994 This `paragraph' means the region marked by the function
995 mark-paragraph, bound to @kbd{ESC h} by default. It is NOT
996 predictable what will happen when you continuously comment out
997 some paragraph many times.
999 You can also comment out an environment between @code{\begin} and
1000 @code{\end}, or a @code{\begin}-\@code{\end} pair themselves, by making the
1001 following key strokes on the line where @code{\begin@{@}} or
1002 @code{\end@{@}} exists.
1004 @table @kbd
1005 @item [prefix] >
1006 @dots{} comment out from \begin to \@code{end}
1007 @item [prefix] <
1008 @dots{} uncomment from \begin to \@code{end}
1009 @end table
1011 @noindent
1012 comment whole the contents of environment. Moreover,
1014 @table @kbd
1015 @item [prefix] .
1016 @dots{} comment out \begin and \@code{end}
1017 @item [prefix] ,
1018 @dots{} uncomment \begin and \@code{end}
1019 @end table
1021 @noindent
1022 (un)comments out only environment declaration: @code{\begin@{@}} and
1023 @code{\end@{@}}. NOTE that even if you intend to comment out some region,
1024 invoking @kbd{[prefix] >} on the @code{\begin},@code{\end} line decides to
1025 work in `commenting out from @code{\begin} to @code{\end}' mode.
1028 @node Cursor jump, Changing and Deleting, Commenting out, Top
1029 @comment node-name, next, previous, up
1030 @chapter Cursor jump
1031 @cindex cursor jump
1032 @cindex prefix g
1035 @menu
1036 * Jump to corresponding object::
1037 * Invoking image processor::
1038 * Jump to main file::
1039 * Jumping around the environment::
1040 * Jumping to last completion position::
1041 @end menu
1043 @node Jump to corresponding object, Invoking image processor, Cursor jump, Cursor jump
1044 @comment node-name, next, previous, up
1045 @section Jump to corresponding object
1047 Typing
1049 @table @kbd
1050 @item [prefix] g
1051 @dots{} go to corresponding object
1052 @end table
1054 @noindent
1055 in a certain place move the cursor to the place corresponding to the
1056 La@TeX{} command of last place. YaTeX recognize the followings as pairs
1057 that have relation each other.
1059 @itemize @bullet
1060 @item @code{\begin@{@}} <-> @code{\end@{@}}
1061 @item @code{%#BEGIN} <-> @code{%#END}
1062 @item On the image-including line -> corresponding viewer or drawing tool
1063 @item @code{\label@{@}} <-> @code{\ref@{@}}
1064 @item @code{\include(\input)} -> included file
1065 @item @code{\bibitem@{@}} <-> @code{\cite@{@}}
1066 @end itemize
1068 On a @code{\begin},@code{\end} line, typing @kbd{[prefix] g} moves the
1069 cursor to the corresponding @code{\end},@code{\begin} line, if its partner
1070 really exists. The behavior on the line @code{%#BEGIN} and @code{%#END}
1071 are the same. Note that if the correspondent of @code{label/ref} or
1072 @code{cite/bibitem} exists in another file, that file have to be opened to
1073 make a round trip between references by @kbd{[prefix] g}.
1075 If you type @code{[prefix] g} on the line of @code{\include@{chap1@}},
1076 typically in the main text, YaTeX switches buffer to @file{chap1.tex}.
1078 @table @kbd
1079 @item [prefix] 4 g
1080 @dots{} go to corresponding object in other window
1081 @end table
1083 @noindent
1084 do the same job as @kbd{[prefix] g} except it's done in other window.
1085 Note that this function doesn't work on @code{begin/end},
1086 @code{%#BEGIN/%#END} pairs because it is meaningless.
1088 @node Invoking image processor, Jump to main file, Jump to corresponding object, Cursor jump
1089 @comment node-name, next, previous, up
1090 @section Invoking image processor
1091 @cindex{Drawing tool invocation}
1093 `image-including line' described above means such lines as
1094 @code{\epsfile@{file=foo.ps@}}. If you type @kbd{[prefix] g} on that
1095 line, YaTeX automatically searches source of `foo.ps' and invokes image
1096 viewer or drawing tool correspoinding to it. For example; if you draw
1097 an image foo.obj with Tgif and enclose its product named foo.eps by
1098 @code{\epsfile} command. Typing @kbd{[prefix] g} on @code{\epsfile} line
1099 make YaTeX invoke @code{tgif foo.obj}. How a processor is choosen is as
1100 follows.
1102 @enumerate
1103 @item
1104 If there is an expression matching with one of the pattern
1105 defined in @code{YaTeX-processed-file-regexp-alist}, extract file name
1106 from regexp group surrounded by \\(\\). (Which group corresponds is
1107 written in the cdr part of each list.) If no matches were found, do
1108 nothing.
1109 @item
1110 If there is a pattern as `%PROCESSOR' which is defined in the variable
1111 @code{YaTeX-file-processor-alist}, call that processor giving the
1112 file name with corresponding extension.
1113 @item
1114 If not, check the existence of each file which is supplied the
1115 extension in the cdr part of each list of
1116 @code{YaTeX-file-processor-alist}. If any, call the corresponding
1117 image viewer or drawing tool.
1118 @end enumerate
1120 @node Jump to main file, Jumping around the environment, Invoking image processor, Cursor jump
1121 @comment node-name, next, previous, up
1122 @section Jump to main file
1124 Typing
1126 @table @kbd
1127 @item [prefix] ^
1128 @dots{} visit main file
1129 @item [prefix] 4^
1130 @dots{} visit main file in other buffer
1131 @end table
1132 @cindex prefix ^
1133 @cindex prefix 4 ^
1135 in a sub text switch the buffer to the main text specified by
1136 @code{%#!} notation.
1138 @node Jumping around the environment, Jumping to last completion position, Jump to main file, Cursor jump
1139 @comment node-name, next, previous, up
1140 @section Jumping around the environment
1142 And these are the functions which work on the current La@TeX{}
1143 environment:
1145 @table @kbd
1146 @item M-C-a
1147 @dots{} beginning of environment
1148 @item M-C-e
1149 @dots{} @code{end} of environment
1150 @item M-C-@@
1151 @dots{} mark environment
1152 @end table
1153 @cindex M-C-a
1154 @cindex M-C-e
1155 @cindex M-C-@@
1157 @node Jumping to last completion position, , Jumping around the environment, Cursor jump
1158 @comment node-name, next, previous, up
1159 @section Jumping to last completion position
1161 YaTeX always memorize the position of completion into register @code{3}.
1162 So every time you make a trip to any other part of text other than you are
1163 writing, you can return to the editing paragraph by calling
1164 register-to-point with argument YaTeX-current-position-register, which is
1165 achieved by typing @kbd{C-x j 3}(by default).
1167 @node Changing and Deleting, Filling, Cursor jump, Top
1168 @comment node-name, next, previous, up
1169 @chapter Changing and Deleting
1171 These functions are for change or deletion of La@TeX{} commands
1172 already entered.
1174 @table @kbd
1175 @item [prefix] c
1176 @dots{} change La@TeX{} command
1177 @item [prefix] k
1178 @dots{} kill La@TeX{} command
1179 @end table
1180 @cindex prefix c
1181 @cindex prefix k
1183 @menu
1184 * Changing LaTeX commands::
1185 * Killing LaTeX commands::
1186 @end menu
1188 @node Changing LaTeX commands, Killing LaTeX commands, Changing and Deleting, Changing and Deleting
1189 @comment node-name, next, previous, up
1190 @section Changing La@TeX{} commands
1192 @kbd{[prefix] c} can change the various (La)@TeX{} commands. This can
1193 change the followings.
1194 @itemize @bullet
1195 @item Environment names
1196 @item Section-type commands
1197 @item Argument of section-type commands
1198 @item Optional parameters (enclosed by []) of section-type commands
1199 @item Font/size designators
1200 @item Math-mode's maketitle-type commands that can be inputted with
1201 image completion
1202 @end itemize
1204 Typing @kbd{[prefix] c} on one of above objects you want to change
1205 brings a suitable reading function sometimes with completion.
1206 Note: If you want to change the argument of section-type command that
1207 contains other La@TeX{} commands, type @kbd{[prefix] c} either of
1208 surrounding braces of the argument in order to make YaTeX ignore the
1209 internal La@TeX{} sequences as an object of changing. Anyway, it is
1210 very difficult to know which argument position the cursor belongs because
1211 the La@TeX{} commands can be nested and braces can freely emerge. So keep
1212 it mind to put the cursor on a brace when you are thinking of changing a
1213 complicated argument.
1215 @node Killing LaTeX commands, , Changing LaTeX commands, Changing and Deleting
1216 @comment node-name, next, previous, up
1217 @section Killing La@TeX{} commands
1218 @cindex Killing La@TeX{} commands
1220 @kbd{[prefix] k} kills the La@TeX{} commands sometimes with their
1221 arguments. Following table illustrates the correspondence of the invoking
1222 position and what is killed.
1224 @example
1225 [Invoking position] [action]
1226 \begin, \end line kill \begin,\end pairs
1227 %#BEGIN, %#END line kill %#BEGIN,%#END pairs
1228 on a Section-type command kill section-type command
1229 on a parenthesis kill parentheses
1230 @end example
1232 Note that when killing @code{\begin, \end} or @code{%#BEGIN, %#END} pair,
1233 the lines @code{\begin, \end} or @code{%#BEGIN, %#END} exist will be
1234 killed entirely. So take care not to create any line that contains more
1235 than one @code{\begin} or so.
1237 While all operations above are to kill `containers' which surround some
1238 text, universal argument (@kbd{C-u}) for these commands kills not only
1239 `containers' but also `contents' of them. See below as a sample.
1241 @example
1242 Original text: [prefix] k C-u [prefix] k
1243 Main \footnote@{note@} here. Main note here. Main here.
1244 ~(cursor)
1245 @end example
1247 @node Filling, Updation of includeonly, Changing and Deleting, Top
1248 @comment node-name, next, previous, up
1249 @chapter Filling
1250 @cindex filling
1252 @section Filling an item
1253 @cindex filling an item
1254 @cindex prefix i
1256 To fill a term (descriptive sentences) of @code{\item}, type
1258 @c @table @kbd
1259 @c @item [prefix] i
1260 @c @dots{} fill item
1261 @c @end table
1262 @table @kbd
1263 @item M-q
1264 @dots{} fill item
1265 @end table
1267 @noindent
1268 on that item.
1270 YaTeX uses the value of the variable @code{YaTeX-item-regexp} as the
1271 regular expression to search item header in itemize environment.
1272 If you make a newcommand to itemize terms(e.g. @code{\underlineitem}), put
1274 @lisp
1275 (setq YaTeX-item-regexp
1276 "\\(\\\\\\(sub\\)*item\\)\\|\\(\\\\underlineitem\\)")
1277 @end lisp
1278 @cindex YaTeX-item-regexp
1280 in your @file{~/.emacs}. If you are not familiar with regular expression
1281 for Emacs-Lisp, name a newcommand for `itemize' beginning with
1282 @code{\item} such as @code{\itembf}, not @code{\bfitem}.
1284 This function reformats the @code{\item} into `hang-indented' style.
1285 For example:
1287 @example
1288 itemize, enumerate environment:
1289 >
1290 >\item[foo] `foo' is the typical word for describing an
1291 > arbitrarily written....
1292 description environment:
1293 > \item[bar] When the word `for' is used as an arbitrarily
1294 > word, `bar' is bound to follow it.
1295 @end example
1297 Note that the indent depth of an @code{\item} word and its descriptive
1298 paragraph are the same in latter case. If you want to use different
1299 depth, invoke fill-paragraph at the beginning of non-whitespace
1300 character(see below).
1302 @section Filling paragraph
1303 @cindex Filling paragraph
1304 @cindex M-q
1306 Fill-paragraph is little bit adapted for La@TeX{} sources. It retains from
1307 filling in certain environments where formatting leads to a disaster such
1308 as verbatim, tabular, or so. And it protects @code{\verb} expressions
1309 from being folded (The variable @code{YaTeX-verb-regexp} controls this).
1310 Besides, putting cursor on the first occurrence of non-whitespace
1311 character on a line changes the fill-prefix temporarily to the depth of
1312 the line.
1314 @node Updation of includeonly, What column, Filling, Top
1315 @comment node-name, next, previous, up
1316 @chapter Updation of @code{\includeonly}
1317 @cindex includeonly
1319 When you edit splitting source texts, the notation
1321 @example
1322 \includeonly@{CurrentEditingFileName@}
1323 @end example
1325 @noindent
1326 in the main file reduces the time of typesetting. If you want
1327 to hack other file a little however, you have to rewrite it to
1329 @example
1330 \includeonly@{OtherFileNameYouWantToFix@}
1331 @end example
1333 @noindent
1334 in the main file. YaTeX automatically detects that the current
1335 edited text is not in includeonly list and prompts you
1337 @example
1338 A)dd R)eplace %)comment?
1339 @end example
1341 in the minibuffer. Type @kbd{a} if you want to add the current file name
1342 to @code{\includeonly} list, @kbd{r} to replace \@code{includeonly} list
1343 with the current file, and type @kbd{%} to comment out the
1344 @code{\includeonly} line.
1346 @node What column, Intelligent newline, Updation of includeonly, Top
1347 @comment node-name, next, previous, up
1348 @chapter What column?
1349 @cindex what column
1350 @cindex complex tabular
1351 @cindex prefix &
1353 We are often get tired of finding the corresponding column in
1354 large tabulars. For example,
1356 @example
1357 \begin@{tabular@}@{|c|c|c|c|c|c|c|c|@}\hline
1358 Name&Position&Post No.&Addr.&Phone No.&FAX No.&
1359 Home Addr.&Home Phone\\ \hline
1360 Thunder Bird & 6 & 223 & LA & xxx-yyy &
1361 zzz-www & Japan & 9876-54321 \\
1362 & 2 & \multicolumn@{2@}@{c|@}@{Unknown@}
1363 &&&(???)
1364 \\ \hline
1365 \end@{tabular@}
1366 @end example
1368 Suppose you have the cursor located at @code{(???)} mark, can you tell
1369 which column it is belonging at once? Maybe no. In such case,
1370 type
1372 @table @kbd
1373 @item [prefix] &
1374 @dots{} What column
1375 @end table
1377 @noindent
1378 in that position. YaTeX tells you the column header of the
1379 current field. Since YaTeX assumes the first line of tabular
1380 environment as a row of column headers, you can create a row of
1381 virtual column headers by putting them in the first line and
1382 commenting that line with @code{%}.
1384 @node Intelligent newline, Usepackage checker, What column, Top
1385 @comment node-name, next, previous, up
1386 @chapter Intelligent newline
1387 @cindex Intelligent newline
1388 @cindex ESC RET
1389 @cindex M-C-m
1391 At the end of begin-type completion of tabular[*], array, itemize,
1392 enumerate or tabbing environment, or typing
1394 @table @kbd
1395 @item ESC RET
1396 @dots{} Intelligent newline
1397 @end table
1399 @noindent
1400 in these environments inserts the contents corresponding to the current
1401 environment in the next line. (At the begin-type completion, this
1402 contents can be removed by `undo'.) In @code{tabular} environment, for
1403 example, @kbd{ESC RET} inserts the certain number of @code{&} and trailing
1404 @code{\\}, and @code{\hline} if other @code{\hline} is found in backward.
1405 Here are the list of contents vs. environments.
1407 @itemize
1408 @item @code{tabular}, @code{tabular*}, @code{array}
1410 Corresponding number of @code{&} and @code{\\}.
1411 And @code{\hline} if needed.
1413 @item @code{tabbing}
1415 The same number of @code{\>} as @code{\=} in the first line.
1417 @item @code{itemize}, @code{enumerate}, @code{description}, @code{list}
1419 @code{\item} or @code{item[]}.
1420 @end itemize
1422 Note that since this function works seeing the contents of the first
1423 line, please call this after the second line if possible.
1425 If you want to apply these trick to other environments, @code{foo}
1426 environment for example, define the function named
1427 @code{YaTeX-intelligent-newline-foo} to insert corresponding contents.
1428 That function will be called at the beginning of the next line after the
1429 newline is inserted to the current line. Since the function
1430 @code{YaTeX-indent-line} is designed to indent the current line properly,
1431 calling this function before your code to insert certain contents must be
1432 useful. See the definition of the function
1433 @code{YaTeX-intelligent-newline-itemize} as an example.
1435 @node Usepackage checker, Online help, Intelligent newline, Top
1436 @comment node-name, next, previous, up
1437 @chapter Usepackage checker
1438 @cindex usepackage
1440 When you input begint-type, section-type, maketitle-type macros with
1441 completion, and it requires some LaTeX2e package, YaTeX examines
1442 the existence of correct @code{\usepackage}. If not, YaTeX inserts
1443 the @code{\usepackage@{@}} declaration corresponding to input macro.
1445 To activate the package completion for your favarite package,
1446 set the variable @code{YaTeX-package-alist-private} correctly.
1447 Please refere the value of @code{YaTeX-package-alist-default} as an
1448 example.
1450 @node Online help, Browsing file hierarchy, Usepackage checker, Top
1451 @comment node-name, next, previous, up
1452 @chapter Online help
1453 @cindex online help
1454 @cindex prefix ?
1455 @cindex prefix /
1456 @cindex apropos
1457 @cindex keyword search
1459 YaTeX provides you the online help with popular La@TeX{} commands.
1461 Here are the key strokes for the online help.
1463 @table @kbd
1464 @item [prefix] ?
1465 @dots{} Online help
1466 @item [prefix] /
1467 @dots{} Online apropos
1468 @end table
1470 @section Online help
1472 `Online help' shows the documentation for the popular La@TeX{}
1473 commands(defaults to the commands on the cursor) in the next buffer.
1474 There are two help file, `global help' and `private help'. The former
1475 file contains the descriptions on the standard La@TeX{} command and is
1476 specified its name by variable @code{YaTeX-help-file}. Usually, the
1477 global help file should be located in public space (@code{$EMACSEXECPATH}
1478 by default) and should be world writable so that anyone can update it to
1479 enrich its contents. The latter file contains descriptions on
1480 non-standard or personal command definitions and is specified by
1481 @code{YaTeX-help-file-private}. This file should be put into private
1482 directory.
1484 @section Online apropos
1486 `Online apropos' is an equivalent of GNU Emacs's apropos. It
1487 shows all the documentations that contains the keyword entered by
1488 the user.
1490 @section When no descriptions are found...
1492 If there is no description on a command in help files, YaTeX
1493 requires you to write a description on that command. If you are
1494 willing to do, determine which help file to add and write the
1495 description on it referring your manual of (La)TeX. Please send
1496 me your additional descriptions if you describe the help on some
1497 standard commands. I might want to include it in the next
1498 distribution.
1500 @node Browsing file hierarchy, Cooperation with other packages, Online help, Top
1501 @comment node-name, next, previous, up
1502 @chapter Browsing file hierarchy
1503 @cindex hierarchy
1504 @cindex browsing
1506 When you are editing multi-file source, typing
1508 @table @kbd
1509 @item [prefix] d
1510 @dots{} browse file hierarchy
1511 @end table
1513 @noindent
1514 asks you the parent-most file (which may be defaulted) and displays the
1515 documentation hierarchy in the next window. In this buffer, the following
1516 commands are available.
1518 @table @kbd
1519 @item n
1520 @dots{} move to the next line and show its contents
1521 @item p
1522 @dots{} move to the previous line and show its contents
1523 @item N
1524 @dots{} move to the next file in the same inclusion level
1525 @item P
1526 @dots{} move to the previous file in the same inclusion level
1527 @item j
1528 @dots{} move to the next line
1529 @item k
1530 @dots{} move to the previous line
1531 @item u
1532 @dots{} move to the parent file
1533 @item .
1534 @dots{} show the current files contents in the next window
1535 @item SPC
1536 @dots{} scroll up the current file window
1537 @item DEL, b
1538 @dots{} scroll down the current file window
1539 @item <
1540 @dots{} show the beginning of the current file
1541 @item >
1542 @dots{} show the end of the current file
1543 @item >
1544 @dots{} return to the previous postion after @kbd{<} or @kbd{>}
1545 @item RET, g
1546 @dots{} open the current file in the next window
1547 @item mouse-2
1548 @dots{} same as RET(available only with window system)
1549 @item o
1550 @dots{} other window
1551 @item 1
1552 @dots{} delete other windows
1553 @item -
1554 @dots{} shrink hierarchy buffer window
1555 @item +
1556 @dots{} enlarge hierarchy buffer window
1557 @item ?
1558 @dots{} describe mode
1559 @item q
1560 @dots{} quit
1561 @end table
1563 Note that operations on the file contents in the next window do not work
1564 correctly when you close the corresponding file.
1566 @node Cooperation with other packages, Customizations, Browsing file hierarchy, Top
1567 @comment node-name, next, previous, up
1568 @chapter Cooperation with other packages
1570 YaTeX works better with other brilliant packages.
1572 @section gmhist
1573 @cindex gmhist
1574 @cindex command history
1575 @cindex minibuffer history
1577 When you are loading @file{gmhist.el} and @file{gmhist-mh.el}, you can
1578 use independent command history list at the prompt of preview command
1579 (@kbd{[prefix] tp}) and print command (@kbd{[prefix] tl}). On each
1580 prompt, you can enter the previous command line string repeatedly by
1581 typing @kbd{M-p}.
1583 @section min-out
1584 @cindex min-out
1586 @file{min-out}, the outline minor mode, can be used in yatex-mode
1587 buffers. If you want to use it with YaTeX, please refer the
1588 file @file{yatexm-o.el} as an example.
1590 @node Customizations, Etcetera, Cooperation with other packages, Top
1591 @comment node-name, next, previous, up
1592 @chapter Customizations
1593 @cindex customizations
1595 You can customize YaTeX by setting Emacs-Lisp variables and by making
1596 add-in functions.
1598 @menu
1599 * Lisp variables::
1600 * Add-in functions::
1601 * Add-in generator::
1602 @end menu
1604 @node Lisp variables, Add-in functions, Customizations, Customizations
1605 @comment node-name, next, previous, up
1606 @section Lisp variables
1607 @cindex customizable variables
1609 You can change the key assignments or make completion more comfortable
1610 by setting the values of various variables which control the movement of
1611 yatex-mode.
1613 For example, if you want to change the prefix key stroke from @kbd{C-c}
1614 to any other sequence, set YaTeX-prefix to whatever you want to use. If
1615 you don't want to use the key sequence @kbd{C-c letter} which is assumed
1616 to be the user reserved sequence in Emacs world, set
1617 @code{YaTeX-inhibit-prefix-letter} to @code{t}, and all of the default key
1618 bind of @kbd{C-c letter} will turn to the corresponding @kbd{C-c C-letter}
1619 (but the region based completions that is invoked with @kbd{C-c
1620 Capital-letter} remain valid, if you want to disable those bindings, set
1621 that variable to 1 instead of @code{t}).
1623 @menu
1624 * All customizable variables::
1625 * Sample definitions::
1626 * Hook variables::
1627 * Hook file::
1628 @end menu
1630 @node All customizable variables, Sample definitions, Lisp variables, Lisp variables
1631 @comment node-name, next, previous, up
1632 @subsection All customizable variables
1633 @cindex all customizable variables
1635 Here are the customizable variables of yatex-mode. Each value setq-ed
1636 in @file{~/.emacs} is preferred and that of defined in @file{yatex.el} is
1637 neglected. Parenthesized contents stands for the default value. When you
1638 are to change some of these variables, see more detailed documentation of
1639 the variable by @kbd{M-x describe-variable}.
1641 @defvar YaTeX-japan
1642 Set this nil to produce all messages in English
1643 (@code{Depends on Japanese feature of Emacs})
1644 @end defvar
1646 @defvar YaTeX-kanji-code
1647 Default buffer-file-coding-system for YaTeX modes' buffer.
1648 Set this 0 to no language conversion. Nil to preserve original
1649 coding-system. 1=Shift JIS, 2=JIS, 3=EUC, 4=UTF-8 (@code{1 or 2})
1650 @end defvar
1652 @defvar YaTeX-prefix
1653 Prefix key stroke (@kbd{C-c})
1654 @end defvar
1656 @defvar YaTeX-inhibit-prefix-letter
1657 Change key stroke from @kbd{C-c letter} to @kbd{C-c C-letter} (@code{nil})
1658 @end defvar
1660 @defvar YaTeX-fill-prefix
1661 Fill-prefix used in yatex-mode (@code{nil})
1662 @end defvar
1664 @defvar YaTeX-user-completion-table
1665 Name of user dictionary where learned completion table will be stored.
1666 (@code{"~/.yatexrc"})
1667 @end defvar
1669 @defvar tex-command
1670 La@TeX{} typesetter command (@code{"latex"})
1671 @end defvar
1673 @defvar dvi2-command
1674 Preview command (@code{"xdvi -geo +0+0 -s 4"})
1675 @end defvar
1677 @defvar dviprint-command-format
1678 Command format to print dvi file (@code{"dvi2ps %f %t %s | lpr"})
1679 @end defvar
1681 @defvar dviprint-from-format
1682 Start page format of above %f. %b will turn to start page (@code{"-f %b"})
1683 @end defvar
1685 @defvar dviprint-to-format
1686 End page format of above %t. %e will turn to @code{end} page (@code{"-t %e"})
1687 @end defvar
1689 @defvar makeindex-command
1690 Default makeindex command (@code{"makeindex"} (@code{"makeind"} on MS-DOS))
1691 @end defvar
1693 @defvar YaTeX-dvipdf-command
1694 Default command name to convert .dvi to PDF (@code{"dvipdfmx"})
1695 @end defvar
1697 @defvar YaTeX-on-the-fly-preview-interval
1698 Interval time in seconds of idle to trigger on-the-fly preview of
1699 environment by @kbd{[prefix] t e}(0.9).
1700 @code{Nil} disables on-the-fly preview.
1701 @end defvar
1703 @defvar YaTeX-cmd-gimp
1704 Command name of GIMP (code{"gimp"})
1705 @end defvar
1706 @defvar YaTeX-cmd-tgif
1707 Command name of tgif (code{"tgif"})
1708 @end defvar
1709 @defvar YaTeX-cmd-inkscape
1710 Command name of Inkscape (code{"inkscape"})
1711 @end defvar
1712 @defvar YaTeX-cmd-dia
1713 Command name of Dia (code{"dia"})
1714 @end defvar
1715 @defvar YaTeX-cmd-ooo
1716 Command name of OpenOffice.org/LibreOffice (code{"soffice"})
1717 @end defvar
1718 @defvar YaTeX-cmd-gs
1719 Command name of Ghostscript (code{"gs"})
1720 @end defvar
1721 @defvar YaTeX-cmd-dvips
1722 Command name of dvips (code{"dvips"})
1723 @end defvar
1724 @defvar YaTeX-cmd-displayline
1725 Command name of displayline
1726 (code{"/Applications/Skim.app/Contents/SharedSupport/displayline"})
1727 @end defvar
1728 @defvar YaTeX-cmd-edit-ps
1729 Command name for editing PostScript files(Value of code{"YaTeX-cmd-gimp"})
1730 @end defvar
1731 @defvar YaTeX-cmd-edit-pdf
1732 Command name for editing PDF files(Value of code{"YaTeX-cmd-ooo"})
1733 @end defvar
1734 @defvar YaTeX-cmd-edit-ai
1735 Command name for editing `.ai' files(Value of code{"YaTeX-cmd-inkscape"})
1736 @end defvar
1737 @defvar YaTeX-cmd-edit-svg
1738 Command name for editing SVG files(Value of code{"YaTeX-cmd-inkscape"})
1739 @end defvar
1740 @defvar YaTeX-cmd-edit-images
1741 Command name for editing image files(Value of code{"YaTeX-cmd-gimp"})
1742 @end defvar
1744 @defvar YaTeX-need-nonstop
1745 Put @code{\nonstopmode@{@}} or not (@code{nil})
1746 @end defvar
1748 @defvar latex-warning-regexp
1749 Regular expression of warning message latex command puts out
1750 (@code{"line.* [0-9]*"})
1751 @end defvar
1753 @defvar latex-error-regexp
1754 Regular expression of error message (@code{"l\\.[1-9][0-9]*"})
1755 @end defvar
1757 @defvar latex-dos-emergency-message
1758 Message latex command running on DOS puts at abort (@code{"Emergency stop"})
1759 @end defvar
1761 @defvar YaTeX-item-regexp
1762 Regular expression of item command (@code{"\\\\item"})
1763 @end defvar
1765 @defvar YaTeX-verb-regexp
1766 Regexp of verb family. Omit \\\\. (@code{"verb\\*?\\|path"})
1767 @end defvar
1769 @defvar YaTeX-nervous
1770 T for using local dictionary (@code{t})
1771 @end defvar
1773 @defvar YaTeX-sectioning-regexp
1774 Regexp of La@TeX{} sectioning command
1775 (@code{"\\(part\\|chapter\\*?\\|\\(sub\\)*\\(section\\|paragraph\\)\\*?\\)\\b"})
1776 @end defvar
1778 @defvar YaTeX-fill-inhibit-environments
1779 Inhibit fill in these environments
1780 (@code{'("tabular" "tabular*" "array" "picture" "eqnarray" "eqnarray*" "equation" "math" "displaymath" "verbatim" "verbatim*")})
1781 @end defvar
1783 @defvar YaTeX-uncomment-once
1784 T for deleting all preceding @code{%} (@code{nil})
1785 @end defvar
1787 @defvar YaTeX-close-paren-always
1788 T for always close all parenthesis automatically, @code{nil} for only eol
1789 (@code{t})
1790 @end defvar
1792 @defvar YaTeX-auto-math-mode
1793 Switch math-mode automatically (@code{t})
1794 @end defvar
1796 @defvar YaTeX-math-key-list-private
1797 User defined alist, math-mode-prefix vs completion alist
1798 used in image completion (@code{nil}). See @file{yatexmth.el}
1799 for the information about how to define a completion alist.
1800 @end defvar
1802 @defvar YaTeX-default-pop-window-height
1803 Initial height of typesetting buffer when one-window.
1804 Number for the lines of the buffer, numerical string for
1805 the percentage of the screen-height. @code{nil} for half height (10)
1806 @end defvar
1808 @defvar YaTeX-help-file
1809 Global online help file name (@file{$doc-directory/../../site-lisp/YATEXHLP.eng})
1810 @end defvar
1812 @defvar YaTeX-help-file-private
1813 Private online help file name (@file{"~/YATEXHLP.eng"})
1814 @end defvar
1816 @defvar YaTeX-no-begend-shortcut
1817 Disable [prefix] b ?? shortcut (@code{nil)}
1818 @end defvar
1820 @defvar YaTeX-hilit-pattern-adjustment-private
1821 List of the list that contain the regular expression and the symbol of
1822 logical meaning of the string that matches the pattern. See also the
1823 value from @code{(assq 'yatex-mode hilit-patterns-alist)} and the value of
1824 @code{YaTeX-hilit-pattern-adjustment-default} (and even the document of
1825 hilit19.el).
1826 @end defvar
1828 @defvar YaTeX-sectioning-level
1829 Alist of LaTeX's sectioning command vs its height.
1830 @end defvar
1832 @defvar YaTeX-hierarchy-ignore-heading-regexp
1833 @code{YaTeX-display-hierarchy} searches for sectioning command first, and
1834 comment line secondary as a file headings. In latter case, ignore lines
1835 that match with regular expression of this variable. Default value of
1836 this variable is RCS header expressions and mode specifying line `-*- xxxx
1837 -*'.
1838 @end defvar
1840 @defvar YaTeX-skip-default-reader
1841 Non-nil for this variable skips the default argument reader of
1842 section-type command when add-in function for it is not defined
1843 (@code{nil})
1844 @end defvar
1846 @defvar YaTeX-create-file-prefix-g
1847 When typing @kbd{prefix g} on the @code{\include} line,
1848 open the target file even if the file doesn't exist (@code{nil})
1849 @end defvar
1851 @defvar YaTeX-simple-messages
1852 Simplyfy messages of various completions (@code{nil})
1853 @end defvar
1855 @defvar YaTeX-hilit-sectioning-face
1856 When hilit19 and yatex19 is active, YaTeX colors the sectioning commands.
1857 This variable specifies the foreground and background color of
1858 @code{\part} macro. The default value is @code{'(yellow/dodgerblue
1859 yellow/slateblue)}. The first element of this list is for the screen when
1860 @code{hilit-background-mode} is @code{'light}, and the second element is
1861 for @code{'dark}. You should specify both color as `forecolor/backcolor'.
1862 @end defvar
1864 @defvar YaTeX-hilit-sectioning-attenuation-rate
1865 When color mode, this variable specifies how much attenuate the color
1866 density of @code{\subparagraph} compared with that of @code{\chapter}
1867 (@code{'(15 40)}) See also @code{YaTeX-hilit-sectioning-face}.
1868 @end defvar
1870 @defvar YaTeX-use-AMS-LaTeX
1871 If you use AMS-LaTeX, set to @code{t} (@code{nil})
1872 @end defvar
1874 @defvar YaTeX-use-LaTeX2e
1875 If you use LaTeX2e, set to @code{t} (@code{t})
1876 @end defvar
1878 @defvar YaTeX-template-file
1879 File name which is automatically inserted at creation
1880 (@code{~/work/template.tex})
1881 @end defvar
1883 @defvar YaTeX-search-file-from-top-directory
1884 Non-nil means to search input-files from the directory where main file exists
1885 (@code{t})
1886 @end defvar
1888 @defvar YaTeX-use-font-lock
1889 Use font-lock to fontify buffer or not (@code{(featurep 'font-lock)}
1890 @end defvar
1892 @defvar YaTeX-use-hilit19
1893 Use hilit19 to highlight buffer or not (@code{(featurep 'hilit19)}
1894 @end defvar
1896 @defvar YaTeX-use-italic-bold
1897 YaTeX tries to search italic, bold fontsets or not
1898 (@code{t} if Emacs-20 or later). This variable is effective only when
1899 font-lock is used.
1900 (@code{(featurep 'hilit19)}
1901 @end defvar
1903 @defvar YaTeX-singlecmd-suffix
1904 Suffix which is always inserted after maketitle-type macros.
1905 @code{"@{@}"} is recommended.
1906 @end defvar
1908 @defvar YaTeX-package-alist-private
1909 Alist of LaTeX2e-package name vs. lists of macros in it.
1910 Set this alist properly and YaTeX automatically check the declaratiion of
1911 `usepackage' for corresponding macro, when you input that macro with
1912 completion. If required `usepackage' is not found, YaTeX also
1913 automatically inserts `\usepackage'. Alist is as follows;
1914 @lisp
1915 '((PackageName1
1916 (completionType ListOfMacro)
1917 (completionType ListOfMacro))
1918 (PackageName2
1919 (completionType ListOfMacro)
1920 (completionType ListOfMacro...))....)
1921 @end lisp
1922 completionType is one of @code{env, section, maketitle}.
1923 Consult the value of @code{YaTeX-package-alist-default} as an example.
1924 @end defvar
1926 @defvar YaTeX-tabular-indentation
1927 At indentation by @kbd{C-i} in tabular or array environment,
1928 YaTeX put the additional spaces to the normail indentation depth.
1929 The number of additional spaces is the product of YaTeX-tabular-indentation
1930 and the number of column position in tabular.
1931 @end defvar
1933 @defvar YaTeX-noindent-env-regexp
1934 Regexp of environment names that should begin with no indentation.
1935 All verbatime-like environment name should match with.
1936 @end defvar
1938 @defvar YaTeX-ref-default-label-string
1939 Default \\ref time string format.
1940 This format is like strftime(3) but allowed conversion char are as follows;
1941 %y -> Last 2 digit of year, %b -> Month name, %m -> Monthe number(1-12),
1942 %d -> Day, %H -> Hour, %M -> Minute, %S -> Second,
1943 %qx -> alphabetical-decimal conversion of yymmdd.
1944 %qX -> alphabetical-decimal conversion of HHMMSS.
1945 Beware defualt label-string should be always unique. So this format string
1946 should have both time part (%H+%M+%S or %qX) and date
1947 part (%y+(%b|%m)+%d or %qx).
1948 @end defvar
1950 @defvar YaTeX-ref-generate-label-function
1951 Function to generate default label string for unnamed \\label@{@}s.
1952 The function pointed to this value should take two arguments.
1953 First argument is LaTeX macro's name, second is macro's argument.
1954 Here is an example for using this value.
1955 @lisp
1956 (setq YaTeX-ref-generate-label-function 'my-yatex-generate-label)
1957 (defun my-yatex-generate-label (command value)
1958 (and (string= command "caption")
1959 (re-search-backward "\\\\begin@{\\(figure\\|table\\)@}" nil t)
1960 (setq command (match-string 1)))
1961 (let ((alist '(("chapter" . "chap")
1962 ("section" . "sec")
1963 ("subsection" . "subsec")
1964 ("figure" . "fig")
1965 ("table" . "tbl"))))
1966 (if (setq command (cdr (assoc command alist)))
1967 (concat command ":" value)
1968 (YaTeX::ref-generate-label nil nil))))
1969 @end lisp
1970 @end defvar
1973 @node Sample definitions, Hook variables, All customizable variables, Lisp variables
1974 @comment node-name, next, previous, up
1975 @subsection Sample definitions
1976 @cindex prefix key stroke
1977 @cindex fill-prefix
1979 For instance, to change the prefix key stroke to @kbd{ESC}, and name of
1980 the user dictionary @file{~/src/emacs/yatexrc}, and set @code{fill-prefix}
1981 to single TAB character, add the following @code{setq} to @file{~/.emacs}.
1983 @lisp
1984 (setq YaTeX-prefix "\e"
1985 YaTeX-user-completion-table "~/src/emacs/yatexrc"
1986 YaTeX-fill-prefix " ")
1987 @end lisp
1989 @node Hook variables, Hook file, Sample definitions, Lisp variables
1990 @comment node-name, next, previous, up
1991 @subsection Hook variables
1992 @cindex hook variables
1994 More customizations will be done by the hook-function defined in
1995 hook-variable @code{yatex-mode-hook}. This is useful to define a shortcut
1996 key sequence to enter some environments other than @code{document} and
1997 @code{enumerate} etc. The following statement defines @code{[prefix] ba}
1998 to enter @code{\begin@{abstract@}} ... @code{=end@{abstract@}}
1999 immediately.
2001 @lisp
2002 (setq yatex-mode-hook
2003 '(lambda() (YaTeX-define-begend-key "ba" "abstract")))
2004 @end lisp
2006 You should use functions @code{YaTeX-define-key}, or
2007 @code{YaTeX-define-begend-key} to define all the key sequences of
2008 yatex-mode.
2010 @node Hook file, , Hook variables, Lisp variables
2011 @comment node-name, next, previous, up
2012 @subsection Hook file
2013 @cindex hook file
2015 You can stuff all of YaTeX related expressions into a file named
2016 @file{yatexhks.el} if you have a lot of codes. YaTeX automatically load
2017 this file at the initialization of itself. Using @file{yatexhks.el}
2018 makes @code{yatex-mode-load-hook} unnecessary.
2020 @node Add-in functions, Add-in generator, Lisp variables, Customizations
2021 @comment node-name, next, previous, up
2022 @section Add-in functions
2023 @cindex add-in functions
2024 @cindex yatexadd.el
2026 You can easily define a function to input detailed arguments
2027 with completion according to La@TeX{} environments or commands.
2029 @c @node What is add-in functions?, , Add-in functions, Add-in functions
2030 @comment node-name, next, previous, up
2031 @subsection What is add-in functions?
2032 @cindex tabular
2034 When you input @code{tabular} environment, don't you think ``I want
2035 YaTeX to complete its argument toward my favorite one such as
2036 @code{@{|c|c|c|@}}...''? Yes, you can define the function to complete
2037 arguments for any environment and any La@TeX{} commands.
2039 @subsection Procedure
2041 Here is the procedure to define add-in functions.
2042 @enumerate
2043 @item
2044 Define the function
2045 @item
2046 Put the function into @file{yatexhks.el}
2047 @end enumerate
2049 @menu
2050 * How the add-in function works::
2051 * How the function is called::
2052 * Useful functions for creating add-in::
2053 * Contribution::
2054 @end menu
2056 @node How the add-in function works, How the function is called, Add-in functions, Add-in functions
2057 @comment node-name, next, previous, up
2058 @subsection How the add-in function works
2060 There are three types of add-in.
2062 @enumerate
2063 @item
2064 Option add-in
2065 @item
2066 argument add-in
2067 @item
2068 enclosing add-in
2069 @end enumerate
2071 @dfn{Option add-in} returns the
2072 La@TeX{}'s optional parameters such as optional strings after
2073 @code{\begin@{ENV@}}, optional strings between a section-type command
2074 and its first argument, and optional strings just after type
2075 maketitle-type command. The following illustrates the name of add-in
2076 functions, where underlined strings are generated by add-in functions.
2078 @display
2079 \begin@{table@}[ht] (Function name: YaTeX:table)
2080 ~~~~
2081 \put(100,200)@{@} (Function name: YaTeX:put)
2082 ~~~~~~~~~
2083 \sum_@{i=0@}^@{n@} (Function name: YaTeX:sum)
2084 ~~~~~~~~~~
2085 @end display
2087 Obviously, the function name is decided by concatenating the prefix
2088 `YaTeX:' and La@TeX{} command's name.
2090 Another add-in type is @dfn{argument add-in}, which completes arguments
2091 for section-type commands.
2093 @display
2094 \newcommand@{\foo@}@{bar@} (Function name: YaTeX::newcommand)
2095 ~~~~ ~~~
2096 @end display
2098 When the section-type command is inputted, the function named by
2099 concatenating `YaTeX::' and section-type command, is called automatically
2100 with an integer argument which indicates which argument of section-type
2101 command is being read. Thus the add-in should determine the
2102 job referring the value of its argument.
2104 @dfn{enclosing add-in} is for modifying and/or checking the region that
2105 will be enclosed by section-type commands via @kbd{[prefix] S}. An
2106 enclosing add-in function will be called with two arguments, beginning of
2107 the enclosed region and end of the region. Suppose you want to enclose
2108 the existing text @code{(a+b)/c} by @code{\frac@{@}}.
2110 @display
2111 a/c
2112 | |
2113 A B
2114 @end display
2116 You do set-mark-command at point A and then move to point B. Typing
2117 @kbd{[prefix] S} and input @code{frac} enclose the region like this;
2119 @display
2120 \frac@{a/c@}
2121 @end display
2123 Normally, the expression @code{a/c} is translated to
2124 @code{\frac@{a@}@{c@}}. An enclosing add-in is useful for modifying
2125 @code{/} to @code{@}@{}.
2127 @menu
2128 * Defining option-add-in::
2129 * Defining argument-add-in::
2130 * Defining enclosing-add-in::
2131 @end menu
2133 @node Defining option-add-in, Defining argument-add-in, How the add-in function works, How the add-in function works
2134 @comment node-name, next, previous, up
2135 @subsubsection Defining `option add-in'
2137 If you want @code{@{|c|c|c|@}} for all @code{tabular} environment,
2139 @lisp
2140 (defun YaTeX:tabular ()
2141 "@{|c|c|c|@}")
2142 @end lisp
2144 @noindent
2145 is enough. If you want more complicated format, define as below.
2147 @lisp
2148 (defun YaTeX:tabular ()
2149 "@{@@@{\\vrule width 1pt\\ @}|||@@@{\\ \\vrule width 1pt@}@}")
2150 @end lisp
2152 @noindent
2153 Note that the character @code{\} must be described as @code{\\} in
2154 Emacs-Lisp. The next example reads the tabular format from keyboard.
2155 @lisp
2156 (defun YaTeX:tabular ()
2157 (concat "@{" (read-string "Rule: ") "@}"))
2158 @end lisp
2160 @node Defining argument-add-in, Defining enclosing-add-in, Defining option-add-in, How the add-in function works
2161 @comment node-name, next, previous, up
2162 @subsubsection Defining `argument add-in'
2164 This section describes how to define the add-in function for
2165 @code{\newcommand}.
2167 The first argument of @code{\newcommand} begins always with @code{\}.
2168 The second argument is usually so complex that we can not edit them in the
2169 minibuffer. Here is the created function considering this.
2171 @lisp
2172 (defun YaTeX::newcommand (n) ;n is argument position
2173 (cond
2174 ((= n 1) ;1st argument is macro name
2175 (read-string "Command: " "\\")) ;initial input `\'
2176 ((= n 2) "") ;do nothing when reading arg#2
2177 (t nil)))
2178 @end lisp
2180 Note that when the `argument add-in' function return `nil', normal
2181 argument reader will be called.
2183 @node Defining enclosing-add-in, , Defining argument-add-in, How the add-in function works
2184 @comment node-name, next, previous, up
2185 @subsubsection Defining `enclosing add-in'
2187 This section describes how to define the add-in function for
2188 text enclosed by @code{\frac@{@}}.
2190 When enclosing the text @code{5/3} by @code{\frac@{@}}, you might want to
2191 replace @code{/} with @code{@}@{}. Enclosing function
2192 @code{YaTeX::frac-region} is called with two arguments, beginning of
2193 enclosed text and end of enclosed text. The function is expected to
2194 replace @code{/} with @code{@}@{}. Here is an example expression.
2196 @lisp
2197 (defun YaTeX::frac-region (beg end)
2198 (catch 'done
2199 (while (search-forward "/" end t)
2200 (goto-char (match-beginning 0))
2201 (if (y-or-n-p "Replace this slash(/) with `@}@{'")
2202 (throw 'done (replace-match "@}@{")))
2203 (goto-char (match-end 0)))))
2204 @end lisp
2206 @node How the function is called, Useful functions for creating add-in, How the add-in function works, Add-in functions
2207 @comment node-name, next, previous, up
2208 @subsection How the function is called
2210 YaTeX calls the add-in functions for specified begin-type, section-type,
2211 and maketitle-type command, if any. `Option add-in' functions for
2212 begin-type are called when @code{\begin@{ENV@}} has been inserted,
2213 functions for section-type are called just before input of the first
2214 argument, and functions for maketitle-type is called after maketitle-type
2215 command has been inserted. `Argument add-in' functions are called at each
2216 entry of arguments for section-type commands.
2218 @node Useful functions for creating add-in, Contribution, How the function is called, Add-in functions
2219 @comment node-name, next, previous, up
2220 @subsection Useful functions for creating add-in
2222 Many add-in functions for typical La@TeX{} commands are defined in
2223 @file{yatexadd.el}. Those are also useful as references. Here are the
2224 short descriptions on useful functions, where [F] means function, [A]
2225 means arguments, [D] means description.
2227 @table @kbd
2228 @item [F]
2229 YaTeX:read-position
2230 @itemx [A]
2231 Character list which can show up in the brackets
2232 @itemx [D]
2233 Return the location specifier such as `[htb]'. When
2234 nothing is entered, omit [] itself. If the possible characters
2235 are "htbp", call this function as
2236 @code{(YaTeX:read-position "htbp")}
2238 @item [F]
2239 YaTeX:read-coordinates
2240 @itemx [A]
2241 Base prompt, X-axis prompt, Y-axis prompt (each optional)
2242 @itemx [D]
2243 Read the coordinates with the prompt ``BasePrompt X-axisPrompt:'' for
2244 X-axis, ``BasePrompt Y-axisPrompt:'' for Y-axis, and return it in the form
2245 of ``(X,Y)''. The default prompts are @code{Dimension}, @code{X},
2246 @code{Y} respectively.
2248 @item [F]
2249 YaTeX:check-completion-type
2250 @itemx [A]
2251 One of the symbols: 'begin, 'section, or 'maketitle
2252 @itemx [D]
2253 Check the current completion type is specified one and cause error if
2254 not. The variable @code{YaTeX-current-completion-type} holds the symbol
2255 according to the current completion type.
2256 @end table
2258 @node Contribution, , Useful functions for creating add-in, Add-in functions
2259 @comment node-name, next, previous, up
2260 @subsection Contribution
2262 If you make your own pretty function and you let it be in public, please
2263 send me the function. I'm going to include it in the next release.
2265 @node Add-in generator, , Add-in functions, Customizations
2266 @comment node-name, next, previous, up
2267 @section Add-in generator
2269 First, don't forget to read the section of add-in functions @ref{Add-in
2270 functions}. If you easily understand how to define them, there's no need
2271 to read this section. But being not familiar with Emacs-Lisp, when you
2272 don't have clear idea what to do, this section describes how to get YaTeX
2273 make add-in function.
2275 There are two methods of generation. One is for fully interactive
2276 generator for beginners and another requires little knowledge of
2277 Emacs-Lisp.
2279 @subsection Generator for beginners
2280 The former generator is called by
2281 @center @kbd{M-x YaTeX-generate}
2283 @noindent
2284 strokes. All you have to do is follow the guidances. Defying them may cases
2285 the disaster (I wonder what is it???). So when you make some mistake, it
2286 is recommendable to type @kbd{C-g} and start afresh.
2288 @subsection Simple generator
2290 The latter generator is invoked by the next sequence.
2291 @center @kbd{M-x YaTeX-generate-simple}
2292 This generator can make both ``option add-in'' and ``argument add-in''
2293 (@emph{refer the section add-in functions}
2294 @ref{How the add-in function works}), whereas @code{YaTeX-generate}
2295 cannot make ``argument addin''.
2297 For example, assume you have the LaTeX command as follows.
2299 @example
2300 \epsinput[t](250,50)@{hoge.eps@}@{plain@}@{Picture of foo@}
2301 (A) (B) (1) (2) (3)
2302 (A)Optional parameter to specify the position
2303 One of t(top), b(bottom), l(left), r(right)
2304 (B)Maximum size of frame
2305 (1)1st argument is filename of EPS file
2306 (2)2nd argument indicates
2307 plain do nothing
2308 frame make frame around image
2309 dframe make double-frame around image
2310 for included EPS file.
2311 (3)Caption for the picture
2312 @end example
2314 Now get start with generation. Typing @kbd{M-x YaTeX-generate-simple}
2315 brings the prompt:
2316 @display
2317 (O)ption? (A)rgument?
2318 @end display
2320 @subsubsection Generating ``option add-in''
2321 @cindex option add-in
2323 Since (A), (B) above are optional argument, all we have to do to
2324 complete them is define the option add-in for them. Let's generate the
2325 function to complete (A).
2327 @display
2328 M-x YaTeX-generate-simple RET
2329 epsinput RET
2330 o
2331 @end display
2333 @noindent
2334 Typing as above leads the next prompt.
2336 @display
2337 Read type(1): (S)tring (C)omplete (F)ile ([)option (P)osition co(O)rd. (q)uit
2338 @end display
2340 @noindent
2341 This asks that ``Which type is the completion style of 1st argument?''.
2342 Here are the possible completion style.
2344 @table @code
2345 @item String
2346 read plain string
2347 @item Complete
2348 read with completion
2349 @item File
2350 read file name
2351 @item Option
2352 read optional string (if string omitted, omit [] too)
2353 @item Position
2354 read positional option (like [htbp])
2355 @item Coord.
2356 read coordinates
2357 @item Quit
2358 quit from generating
2359 @end table
2361 Since (A) is the optional argument to specify the location of included
2362 EPS file, the completion style is @code{Position}, and the possible
2363 characters are t, b, l, and r. To tell these information to generator,
2364 operate as follows.
2366 @display
2367 Read type(1).... p
2368 Acceptable characters: tblr RET
2369 @end display
2371 (B) is coordinate. So its completion style is coOrd. We want a prompt
2372 meaning ``Maximum size'' when completion.
2374 @display
2375 Read type(2).... o
2376 Prompt for coordinates: Max size RET
2377 @end display
2379 That's all for optional argument. Select quit.
2381 @display
2382 Read type(3).... q
2383 @end display
2385 Then the generated option add-in function for \epsinput will be shown in
2386 the next window.
2388 @subsubsection Generating ``argument add-in''
2389 @cindex argument add-in
2391 Next, create the argument add-in. The arguments for \epsinput are EPS
2392 file name, framing style, and caption string in sequence.
2394 @display
2395 M-x YaTeX-generate-simple RET
2396 epsinput RET
2397 a
2398 @end display
2400 Above key strokes bring the prompt that asks the number of argument.
2401 Answer it with 3.
2403 @display
2404 How many arguments?: 3 RET
2405 @end display
2407 Then the generator asks the completion style and prompt for completion.
2408 Answer them. @kbd{f} for FileName and prompt string.
2410 @display
2411 Read type(1).... f
2412 Prompt for argument#1 EPS file name RET
2413 @end display
2415 The second argument is one of selected symbol. So the completion type
2416 is @code{Completion}.
2418 @display
2419 Read type(2).... c
2420 Prompt for argument#2 Include style RET
2421 @end display
2423 Then all the candidates ready to be read. Type single RET after
2424 entering all.
2426 @display
2427 Item[1](RET to exit): plain RET
2428 Item[2](RET to exit): frame RET
2429 Item[3](RET to exit): dframe RET
2430 Item[4](RET to exit): RET
2431 @end display
2433 The following prompt asks whether the entered string must belong to
2434 candidates or not. In this case, since the argument must be one of
2435 @code{plain}, @code{frame}, and @code{dframe}, type @code{y}.
2437 @display
2438 Require match? (y or n) y
2439 @end display
2441 The last argument is the caption string for which any completion is
2442 needed.
2444 @display
2445 Read type(3).... s
2446 Prompt for argument#3 Caption RET
2447 default: Figure of RET
2448 @end display
2450 Finally we'll get the argument add-in in the next window.
2452 @subsection Contribution
2454 If you get your own pretty function and you let it be in public, please
2455 steel yourself in the happy atmosphere and do not send me the function.
2456 I do know it is not fine because it is generated by yatexgen:-p.
2458 @node Etcetera, Copying, Customizations, Top
2459 @comment node-name, next, previous, up
2460 @chapter Etcetera
2462 The standard completion tables provided in @file{yatex.el} contain a
2463 few La@TeX{} commands I frequently use. This is to lessen the key
2464 strokes to complete entire word, because too many candidates
2465 rarely used often cause too many hits. Therefore always try to
2466 use completion in order to enrich your dictionary, and you will
2467 also find `Wild Bird' growing suitable for your La@TeX{} style.
2469 The package name `Wild Bird' is the English translation of Japanese
2470 title `Yachou', which is a trick on words of Japanese.
2472 @node Copying, , Etcetera, Top
2473 @comment node-name, next, previous, up
2474 @chapter Copying
2476 This program is distributed as a free software. You can
2477 use/copy/modify/redistribute this software freely but with NO warranty to
2478 anything as a result of using this software. Adopting code from this
2479 program is also free. But I would not do contract act.
2481 Any reports and suggestions are welcome as long as I feel interests in
2482 this software. My possible e-mail address is `yuuji@@yatex.org'. (as of
2483 Jan.2004) And there is mailing list for YaTeX. Although the common
2484 language is Japanese, questions in English will be welcome. To join the
2485 ML, send the mail whose subject is `append' to the address
2486 `yatex@@yatex.org. If you have some question, please ask to
2487 `yatex-admin@@yatex.org'.
2489 The specification of this software will be surely modified
2490 (depending on my feelings) without notice :-p.
2493 @flushright
2494 HIROSE Yuuji
2495 @end flushright
2496 @bye
2498 Local variables:
2499 mode: texinfo
2500 fill-prefix: nil
2501 fill-column: 74
2502 End: