yatex
view docs/yatexe.tex @ 441:564510b9caca
Add verbatim package for verbatiminput macro
| author | HIROSE Yuuji <yuuji@gentei.org> |
|---|---|
| date | Sun, 09 Oct 2016 15:58:27 +0859 |
| parents | 781604df4cbd |
| children | d63ba3e187ca |
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 Fri Feb 13 08:15:26 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 (@var{AboveKeyStrokes} after region setting)
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 typesetter
150 @item [prefix] t r
151 @dots{} invoke typesetter on region
152 @item [prefix] t e
153 @dots{} `on-the-fly preview' 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 or paragraph, and then call typeset-region with marked
219 region. This
220 is convenient to quick view of current tabular environment or current
221 editing formulas. If running Emacs has the ability of displaying images,
222 typeset image will be shown in the next window. Further more,
223 if you modify the content within that environment, YaTeX performs
224 `on-the-fly' preview that automatically update preview image as you typed.
226 If your Emacs does not supply on-the-fly preview,
227 keeping previewer window for @file{texput.dvi} is handy
228 for debugging. Since @kbd{[prefix] te} selects the inner-most environment
229 as region, it is not suitable for partial typesetting of doubly or more
230 composed environment. If you want to do partial typesetting for a nested
231 environment, use @kbd{[prefix] tr} for static-region, which is described
232 in the section @xref{%#notation}.
234 @node Calling previewer, Printing out, Calling typesetter, Typesetting
235 @comment node-name, next, previous, up
236 @section Calling previewer
238 @kbd{[prefix] t p} invokes the TeX previewer. And if you are using
239 xdvi-remote, which can be controled from other terminals, @kbd{[prefix] t
240 s} enables you to search current string at the cursor on the running xdvi
241 window.
243 @node Printing out, , Calling previewer, Typesetting
244 @comment node-name, next, previous, up
245 @section Printing out
247 When you type @code{[preifx] t l}, YaTeX asks you the range of
248 dvi-printing by default. You can skip this by invoking it with
249 universal-argument as follows:
251 @example
252 C-u [prefix] tl
253 @end example
255 @node %#notation, Completion, Typesetting, Top
256 @comment node-name, next, previous, up
257 @chapter %# notation
258 @cindex %# notation
260 You can control the typesetting process by describing @code{%#}
261 notations in the source text.
263 @menu
264 * Changing typesetter::
265 * Splitting input files::
266 * Static region for typesetting::
267 * Lpr format::
268 * Controlling which command to invoke::
269 * Editing %# notation::
270 @end menu
272 @node Changing typesetter, Splitting input files, %#notation, %#notation
273 @comment node-name, next, previous, up
274 @section To change the `latex' command or to split a source text.
275 @cindex typesetter
277 To change the typesetting command, write
279 @example
280 %#!latex-big
281 @end example
283 @noindent
284 anywhere in the source text. This is useful for changing
285 typesetter.
287 @node Splitting input files, Static region for typesetting, Changing typesetter, %#notation
288 @comment node-name, next, previous, up
289 @section Splitting input files
291 And if you split the source text and
292 edit subfile that should be included from main text.
294 @example
295 %#!latex main.tex
296 @end example
298 @noindent
299 will be helpful to execute latex on main file from sub text buffer. Since
300 this command line after @kbd{%#!} will be sent to shell literally, next
301 description makes it convenient to use ghostview as dvi-previewer.
303 @example
304 %#!latex main && dvi2ps main.dvi > main
305 @end example
307 @noindent
308 Note that YaTeX assumes the component before the last period of
309 the last word in this line as base name of the main La@TeX{} source.
310 The @code{%f} notation in this line is replaced by main file name, and
311 @code{%r} replaced by root name of main file name. If you specify
312 @code{%f} or @code{%r}, YaTeX always ask you the name of main file at the
313 first typesetting.
315 To make best use of the feature of inter-file jumping by
316 @kbd{[prefix] g} (see @ref{Cursor jump}), take described below into
317 consideration.
319 @itemize
320 @item You can put split texts in sub directory, but not in
321 sub directory of sub directory.
322 @item In the main text, specify the child file name with relative path name
323 such as \include@{chap1/sub@}, when you include the file in
324 a sub-directory.
325 @item In a sub-text, write @code{%#!latex main.tex} even if @file{main.tex}
326 is in the parent directory(not %#!latex ../main.tex).
327 @end itemize
329 @node Static region for typesetting, Lpr format, Splitting input files, %#notation
330 @comment node-name, next, previous, up
331 @section Static region
332 @cindex static region
333 @cindex Fixed region
335 Typeset-region by @kbd{[prefix] tr} passes the region between point and
336 mark to typesetting command by default. But when you want to typeset
337 static region, enclose the region by @code{%#BEGIN} and @code{%#END} as
338 follows.
340 @example
341 %#BEGIN
342 TheRegionYouWantToTypesetManyTimes
343 %#END
344 @end example
346 This is the rule of deciding the region.
348 @enumerate
349 @item
350 If there exists %#BEGIN before point,
352 @enumerate
353 @item
354 If there exists %#END after %#BEGIN,
355 @itemize
356 @item From %#BEGIN to %#END.
357 @end itemize
359 @item
360 If %#END does not exist after %#BEGIN,
361 @itemize
362 @item From %#BEGIN to the end of buffer.
363 @end itemize
364 @end enumerate
366 @item
367 If there does not exist %#BEGIN before point,
368 @itemize
369 @item Between point and mark(standard method of Emacs).
370 @end itemize
371 @end enumerate
373 It is useful to write @code{%#BEGIN} in the previous line of \begin and
374 @code{%#END} in the next line of \@code{end} when you try complex
375 environment such as `tabular' many times. It is also useful to put only
376 @code{%#BEGIN} alone at the middle of very long text. Do not forget to
377 erase @code{%#BEGIN} @code{%#END} pair.
379 @node Lpr format, , Static region for typesetting, %#notation
380 @comment node-name, next, previous, up
381 @section Lpr format
382 @cindex lpr format
384 Lpr format is specified by three Lisp variables. Here are the
385 default values of them.
387 @table @code
388 @item (1)dviprint-command-format
389 @code{"dvi2ps %f %t %s | lpr"}
390 @item (2)dviprint-from-format
391 @code{"-f %b"}
392 @item (3)dviprint-to-format
393 @code{"-t %e"}
394 @end table
396 On YaTeX-lpr, @code{%s} in (1) is replaced by the file name of main
397 text, @code{%f} by contents of (2), %t by contents of (3). At these
398 replacements, @code{%b} in (2) is also replaced by the number of beginning
399 page, @code{%e} in (3) is replaced by the number of ending page. But
400 @code{%f} and @code{%t} are ignored when you omit the range of print-out
401 by @kbd{C-u [prefix] tl}.
403 If you want to change this lpr format temporarily, put a command
404 such as follows somewhere in the text:
406 @example
407 %#LPR dvi2ps %f %t %s | 4up -page 4 | texfix | lpr -Plp2
408 @end example
410 And if you want YaTeX not to ask you the range of printing
411 out, the next example may be helpful.
413 @example
414 %#LPR dvi2ps %s | lpr
415 @end example
417 @node Controlling which command to invoke, Editing %# notation, Lpr format, %#notation
418 @comment node-name, next, previous, up
419 @section Controlling which command to invoke
421 These %# notation below can control which command to invoke for
422 La@TeX{} related process.
424 @table @code
425 @item %#PREVIEW
426 @dots{} Command line for DVI viewing ([prefix] t p)
427 @item %#MAKEINDEX
428 @dots{} Command line for makeindex ([prefix] t i)
429 @item %#BIBTEX
430 @dots{} Command line for bibtex ([prefix] t b)
431 @item %#DVIPDF
432 @dots{} Command line for dvipdf(mx) ([prefix] t b)
433 @item %#LPR
434 @dots{} Command line for printing out([prefix] t l)
435 @item %#PDFVIEW
436 @dots{} Command line for PDF viewing
437 @item %#IMAGEDPI
438 @dots{} DPI value for converting to on-the-fly prewview image
439 @end table
441 If you want to invoke ``makeidx hogehoge'' to update index,
442 put the next line some upper place in the source, for example.
444 @example
445 %#MAKEINDEX makeidx hogehoge
446 @end example
449 @node Editing %# notation, , Controlling which command to invoke, %#notation
450 @comment node-name, next, previous, up
451 @section Editing %# notation
453 To edit @code{%#} notation described above, type
455 @table @kbd
456 @item [prefix] %
457 @dots{} editing %# notation menu
458 @end table
460 @noindent
461 and select one of the entry of the menu as follows.
463 @example
464 !)Edit-%#! B)EGIN-END-region L)Edit-%#LPR
465 @end example
467 @noindent
468 Type @kbd{!} to edit @code{%#!} entry, @code{b} to enclose the region with
469 @code{%#BEGIN} and @code{%#END}, and @code{l} to edit @code{%#LPR} entry.
470 When you type @kbd{b}, all @code{%#BEGIN} and @code{%#END} are
471 automatically erased.
473 @node Completion, Local dictionaries, %#notation, Top
474 @comment node-name, next, previous, up
475 @chapter Completion
476 @cindex completion
478 YaTeX makes it easy to input the La@TeX{} commands. There are several
479 kinds of completion type, begin-type, section-type, large-type, etc...
481 @menu
482 * Begin-type completion::
483 * Section-type completion::
484 * Large-type completion::
485 * Maketitle-type completion::
486 * Arbitrary completion::
487 * End completion::
488 * Accent completion::
489 * Image completion::
490 * Greek letters completion::
491 * Inserting parentheses::
492 @end menu
494 @node Begin-type completion, Section-type completion, Completion, Completion
495 @comment node-name, next, previous, up
496 @section Begin-type completion
497 @cindex begin-type completion
498 @cindex environment
499 @cindex prefix b
501 "Begin-type completion" completes commands of @code{\begin@{env@}} ...
502 @code{\end@{env@}}. All of the begin-type completions begin with this key
503 sequence.
505 @table @kbd
506 @item [prefix] b
507 @dots{} start begin-type completion
508 @end table
510 @noindent
511 An additional key stroke immediately completes a frequently used
512 La@TeX{} @code{\begin@{@}}...@code{\@code{end}@{@}} environment.
514 @table @kbd
515 @item [prefix] b c
516 @dots{} @code{\begin@{center@}...\end@{center@}}
517 @item [prefix] b d
518 @dots{} @code{\begin@{document@}...\end@{document@}}
519 @item [prefix] b D
520 @dots{} @code{\begin@{description@}...\end@{description@}}
521 @item [prefix] b e
522 @dots{} @code{\begin@{enumerate@}...\end@{enumerate@}}
523 @item [prefix] b E
524 @dots{} @code{\begin@{equation@}...\end@{equation@}}
525 @item [prefix] b i
526 @dots{} @code{\begin@{itemize@}...\end@{itemize@}}
527 @item [prefix] b l
528 @dots{} @code{\begin@{flushleft@}...\end@{flushleft@}}
529 @item [prefix] b m
530 @dots{} @code{\begin@{minipage@}...\end@{minipage@}}
531 @item [prefix] b t
532 @dots{} @code{\begin@{tabbing@}...\end@{tabbing@}}
533 @item [prefix] b T
534 @dots{} @code{\begin@{tabular@}...\end@{tabular@}}
535 @item [prefix] b^T
536 @dots{} @code{\begin@{table@}...\end@{table@}}
537 @item [prefix] b p
538 @dots{} @code{\begin@{picture@}...\end@{picture@}}
539 @item [prefix] b q
540 @dots{} @code{\begin@{quote@}...\end@{quote@}}
541 @item [prefix] b Q
542 @dots{} @code{\begin@{quotation@}...\end@{quotation@}}
543 @item [prefix] b r
544 @dots{} @code{\begin@{flushright@}...\end@{flushright@}}
545 @item [prefix] b v
546 @dots{} @code{\begin@{verbatim@}...\end@{verbatim@}}
547 @item [prefix] b V
548 @dots{} @code{\begin@{verse@}...\end@{verse@}}
549 @end table
551 Any other La@TeX{} environments are made by completing-read of the
552 Emacs function.
554 @table @kbd
555 @item [prefix] b SPACE
556 @dots{} begin-type completion
557 @end table
559 @noindent
560 The next message will show up in the minibuffer
562 @example
563 Begin environment(default document):
564 @end example
566 @noindent
567 by typing @kbd{[prefix] b}. Put the wishing environment with completion
568 in the minibuffer, and @code{\begin@{env@}}...\@code{\end@{env@}} will be
569 inserted in the La@TeX{} source text. If the environment you want to put
570 does not exist in the YaTeX completion table, it will be registered in the
571 user completion table. YaTeX automatically saves the user completion
572 table in the user dictionary file at exiting of emacs.
574 At the completion of certain environments, the expected initial entry will
575 automatically inserted such as @code{\item} for @code{itemize}
576 environment. If you don't want the entry, it can be removed by undoing.
578 If you want to enclose some paragraphs which have already been written
579 into environment, invoke the begin-type completion right after region marking.
580 @cindex enclose region into environment
582 If you set @code{transient-mark-mode} to @code{nil} in your
583 @file{~/.emacs}, typing @kbd{C-space} (@code{set-mark-command}) twice
584 turns @code{transient-mark-mode} on temporarily. Then, type call
585 begin-type completion to enclose text into a environment.
588 @node Section-type completion, Large-type completion, Begin-type completion, Completion
589 @comment node-name, next, previous, up
590 @section Section-type completion
591 @cindex section-type completion
592 @cindex prefix s
594 "Section-type completion" completes section-type commands which take an
595 argument or more such as @code{\section@{foo@}}. To invoke section-type
596 completion, type
598 @table @kbd
599 @item [prefix] s
600 @dots{} section-type completion
601 @end table
603 @noindent
604 then the prompt
606 @example
607 (C-v for view) \???@{@} (default documentclass):
608 @end example
610 @noindent
611 will show up in the minibuffer. Section-type La@TeX{} commands are
612 completed by space key, and the default value is selected when you
613 type nothing in the minibuffer.
615 Next,
617 @example
618 \section@{???@}:
619 @end example
621 @noindent
622 prompts you the argument of section-type La@TeX{} command. For
623 example, the following inputs
625 @example
626 \???@{@} (default documentclass): section
627 \section@{???@}: Hello world.
628 @end example
630 @noindent
631 will insert the string
633 @example
634 \section@{Hello world.@}
635 @end example
637 in your La@TeX{} source. When you neglect argument such as
639 @example
640 (C-v for view) \???@{@} (default section): vspace*
641 \vspace*@{???@}:
642 @end example
644 YaTeX puts
646 @example
647 \vspace*@{@}
648 @end example
650 @noindent
651 and move the cursor in the braces.
653 In La@TeX{} command, there are commands which take more than one
654 arguments such as @code{\addtolength@{\topmargin@}@{8mm@}}. To complete these
655 commands, invoke section-type completion with universal argument as,
656 @cindex number of argument
658 @example
659 C-u 2 [prefix] s (or ESC 2 [prefix] s)
660 @end example
662 @noindent
663 and make answers in minibuffer like this.
665 @example
666 (C-v for view) \???@{@} (default vspace*): addtolength
667 \addtolength@{???@}: \topmargin
668 Argument 2: 8mm
669 @end example
671 @code{\addtolength} and the first argument @code{\topmargin} can be typed
672 easily by completing read. Since YaTeX also learns the number of
673 arguments of section-type command and will ask that many arguments in
674 future completion, you had better tell the number of arguments to YaTeX at
675 the first completion of the new word. But you can change the number of
676 arguments by calling the completion with different universal argument
677 again.
680 Invoking section-type completion with @code{[Prefix] S} (Capital `S')
681 includes the region as the first argument of section-type command.
683 The section/large/maketitle type completion can work at the
684 prompt for the argument of other section-type completion.
685 Nested La@TeX{} commands are efficiently read with the recursive
686 completion by typing YaTeX's completion key sequence in the
687 minibuffer.
689 @menu
690 * view-sectioning::
691 @end menu
693 @node view-sectioning, , Section-type completion, Section-type completion
694 @comment node-name, next, previous, up
695 @subsection view-sectioning
696 @cindex view sectioning
697 @cindex outline
699 In the minibuffer at the prompt of section-type command completion,
700 typing @kbd{C-v} shows a list of sectioning commands in source text(The
701 line with @code{<<--} mark is the nearest sectioning command). Then,
702 default sectioning command appears in the minibuffer. You can go up/down
703 sectioning command by typing @kbd{C-p}/@kbd{C-n}, can scrolls up/down the
704 listing buffer by @kbd{C-v}/@kbd{M-v}, and can hide sectioning commands
705 under certain level by 0 through 6. Type @kbd{?} in the minibuffer of
706 sectioning prompt for more information.
708 You can generate this listing buffer (@code{*Sectioning Lines*} buffer)
709 by typing
710 @table @kbd
711 @item M-x YaTeX-section-overview
712 @dots{} Generate *Sectioning Lines* buffer
713 @end table
714 @cindex{Generate the listing of sectioning units}
715 from the LaTeX source buffer. In this listing buffer, typing @kbd{u} on
716 the sectioning command shifts up the corresponding sectioning command in
717 source text and @kbd{d} shifts down. After marking lines in the listing
718 buffer, typing @kbd{U} shifts up all sectioning commands in the region,
719 and @kbd{U} shifts down. Here are all the key bindings of
720 @code{*Sectioning Lines*} buffer.
722 @table @kbd
723 @item SPC
724 @dots{} Jump to corresponding source line
725 @item .
726 @dots{} Display corresponding source line
727 @item u
728 @dots{} Shift up a sectioning line
729 @item d
730 @dots{} Shift down a sectioning line
731 @item U
732 @dots{} Shift up sectioning lines in region
733 @item D
734 @dots{} Shift down sectioning lines in region
735 @item 0@dots{}6
736 @dots{} Hide sectioning commands whose level is lower than n
737 @end table
740 @node Large-type completion, Maketitle-type completion, Section-type completion, Completion
741 @comment node-name, next, previous, up
742 @section Large-type completion
744 "Large-type completion" inputs the font or size changing
745 descriptions such as @code{@{\large @}}. When you type
747 @table @kbd
748 @item [prefix] l
749 @dots{} large-type completion
750 @end table
752 @noindent
753 the message in the minibuffer
755 @example
756 @{\??? @} (default large):
757 @end example
759 prompts prompts you large-type command with completing-read. There are
760 TeX commands to change fonts or sizes, @code{it}, @code{huge} and so on,
761 in the completion table.
763 Region-based completion is also invoked by calling completion
764 after region activated.
766 @node Maketitle-type completion, Arbitrary completion, Large-type completion, Completion
767 @comment node-name, next, previous, up
768 @section Maketitle-type completion
769 @cindex maketitle-type completion
771 We call it "maketitle-type completion" which completes commands such as
772 @code{\maketitle}. Take notice that maketitle-type commands take no
773 arguments. Then, typing
775 @table @kbd
776 @item [prefix] m
777 @dots{} maketitle-type completion
778 @end table
780 @noindent
781 begins maketitle-completion. Above mentioned method is true for
782 maketitle-completion, and there are La@TeX{} commands with no
783 arguments in completion table.
785 @node Arbitrary completion, End completion, Maketitle-type completion, Completion
786 @comment node-name, next, previous, up
787 @section Arbitrary completion
788 @cindex arbitrary completion
790 @noindent
791 You can complete certain La@TeX{} command anywhere without typical
792 completing method as described, by typing
794 @table @kbd
795 @item [prefix] SPC
796 @dots{} arbitrary completion
797 @end table
799 @noindent
800 after the initial string of La@TeX{} command that is preceded by @code{\}.
802 @node End completion, Accent completion, Arbitrary completion, Completion
803 @comment node-name, next, previous, up
804 @section End completion
805 @cindex end completion
807 @noindent
808 YaTeX automatically detects the opened environment and close it with
809 \@code{\end@{environment@}}. Though proficient YaTeX users never fail to
810 make environment with begin-type completion, some may begin an environment
811 manually. In that case, type
813 @table @kbd
814 @item [prefix] e
815 @dots{} @code{end} completion
816 @end table
818 @noindent
819 at the end of the opened environment.
821 @node Accent completion, Image completion, End completion, Completion
822 @comment node-name, next, previous, up
823 @section Accent completion
824 @cindex accent completion
826 When you want to write the European accent marks(like @code{\`@{o@}}),
828 @table @kbd
829 @item [prefix] a
830 @dots{} accent completion
831 @end table
833 @noindent
834 shows the menu
836 @example
837 1:` 2:' 3:^ 4:" 5:~ 6:= 7:. u v H t c d b
838 @end example
840 @noindent
841 in the minibuffer. Chose one character or corresponding numeric,
842 and you will see
844 @example
845 \`@{@}
846 @end example
848 @noindent
849 in the editing buffer with the cursor positioned in braces. Type
850 one more character `o' for example, then
852 @example
853 \`@{o@}
854 @end example
856 @noindent
857 will be completed, and the cursor gets out from braces.
859 @node Image completion, Greek letters completion, Accent completion, Completion
860 @comment node-name, next, previous, up
861 @section Image completion of mathematical sign
862 @cindex image completion
863 @cindex math-mode
864 @cindex sigma
865 @cindex leftarrow
866 @cindex ;
868 Arrow marks, sigma mark and those signs mainly used in the
869 TeX's math environment are completed by key sequences which
870 imitate the corresponding symbols graphically. This completion
871 only works in the math environment. YaTeX automatically detects
872 whether the cursor located in math environment or not, and
873 change the behavior of key strokes @kbd{;} and @kbd{:}.
875 By the way, we often express the leftarrow mark by `<-' for example.
876 Considering such image, you can write @code{\leftarrow} by typing @kbd{<-}
877 after @kbd{;} (semicolon) as a prefix. In the same way,
878 @code{\longleftarrow} (@code{<--}) is completed by typing @kbd{;<--},
879 infinity mark which is imitated by @code{oo} is completed by typing
880 @kbd{;oo}.
882 Here are the sample operations in YaTeX math-mode.
884 @example
885 INPUT Completed La@TeX{} commands
886 ; < - @code{\leftarrow}
887 ; < - - @code{\longleftarrow}
888 ; < - - > @code{\longleftrightarrow}
889 ; o @code{\circ}
890 ; o o @code{\infty}
891 @end example
893 In any case, you can quit from image completion and can move
894 to the next editing operation if the La@TeX{} command you want is
895 shown in the buffer.
897 @code{;} itself in math-environment is inserted by @kbd{;;}. Typing
898 @kbd{TAB} in the midst of image completion shows all of the La@TeX{}
899 commands that start with the same name as string you previously typed in.
900 In this menu buffer, press @kbd{RET} after moving the cursor (by @kbd{n},
901 @kbd{p}, @kbd{b}, @kbd{f}) to insert the La@TeX{} command.
903 To know all of the completion table, type @kbd{TAB} just after @kbd{;}.
904 And here is the sample menu by @kbd{TAB} after @kbd{;<}.
906 @example
907 KEY LaTeX sequence sign
908 < \leq <
909 ~
910 << \ll <<
911 <- \leftarrow <-
912 <= \Leftarrow <=
913 @end example
915 You can define your favorite key-vs-sequence completion table in the
916 Emacs-Lisp variable @code{YaTeX-math-sign-alist-private}. See also
917 @file{yatexmth.el} for the information of the structure of this variable.
919 @node Greek letters completion, Inserting parentheses, Image completion, Completion
920 @comment node-name, next, previous, up
921 @section Greek letters completion
922 @cindex Greek letters completion
923 @cindex :
925 Math-mode of YaTeX provides another image completion, Greek letters
926 completion in the same method. After prefix @kbd{:}, typing @kbd{a} makes
927 @code{\alpha}, @kbd{b} makes @code{\beta} and @kbd{g} makes @code{\gamma}
928 and so on. First, type @kbd{:TAB} to know all the correspondence of
929 alphabets vs. Greek letters.
931 If you will find @kbd{;} or @kbd{:} doesn't work in correct position of
932 math environment, it may be a bug of YaTeX. Please send me a bug report
933 with the configuration of your text, and avoid it temporarily by typing
934 @kbd{;} or @kbd{:} after universal-argument(@kbd{C-u}) which forces
935 @kbd{;} and @kbd{:} to work as math-prefix.
937 @node Inserting parentheses, , Greek letters completion, Completion
938 @section Inserting parentheses
940 Typing opening parenthesis, one of @code{(}, @code{@{ and @code{[}},
941 automatically inserts the closing one. If a opening bracket is typed
942 after @code{\}, @code{\]} is automatically inserted with computed
943 indentation. If you stop automatic insertion, type @kbd{C-q} before
944 opening parenthesis.
946 @node Local dictionaries, Commenting out, Completion, Top
947 @comment node-name, next, previous, up
948 @chapter Local dictionaries
949 @cindex local dictionaries
950 @cindex nervous users
952 Tables for completion consist of three dictionaries; `standard
953 dictionary' built in @file{yatex.el}, `user dictionary' for your common
954 private commands, and `local dictionary' that is effective in a certain
955 directory.
957 When you input the command unknown to YaTeX at a completion in the
958 minibuffer, YaTeX asks you with the following prompt;
960 @example
961 `foo' is not in table. Register into: U)serDic L)ocalDic N)one D)iscard
962 @end example
964 @noindent
965 In this menu, typing @kbd{u} updates your `user dictionary', @kbd{l}
966 updates your local dictionary, @kbd{n} updates only on-memory dictionary
967 which go through only current Emacs session, and @kbd{d} updates no
968 dictionary and throws the new word away.
970 If you find this switching feature meaningless and bothersome, put the
971 next expression into your @file{~/.emacs}
973 @lisp
974 (setq YaTeX-nervous nil)
975 @end lisp
977 @node Commenting out, Cursor jump, Local dictionaries, Top
978 @comment node-name, next, previous, up
979 @chapter Commenting out
980 @cindex commenting out
981 @cindex prefix >
982 @cindex prefix <
983 @cindex prefix ,
984 @cindex prefix .
986 You may want to comment out some region.
988 @table @kbd
989 @item [prefix] >
990 @dots{} comment out region by %
991 @item [prefix] <
992 @dots{} uncomment region
993 @end table
995 @noindent
996 cause an operation to the region between point and mark.
998 @table @kbd
999 @item [prefix] .
1000 @dots{} comment out current paragraph
1001 @item [prefix] ,
1002 @dots{} uncomment current paragraph
1003 @end table
1005 @noindent
1006 comments or uncomments the paragraph where the cursor belongs.
1007 This `paragraph' means the region marked by the function
1008 mark-paragraph, bound to @kbd{ESC h} by default. It is NOT
1009 predictable what will happen when you continuously comment out
1010 some paragraph many times.
1012 You can also comment out an environment between @code{\begin} and
1013 @code{\end}, or a @code{\begin}-\@code{\end} pair themselves, by making the
1014 following key strokes on the line where @code{\begin@{@}} or
1015 @code{\end@{@}} exists.
1017 @table @kbd
1018 @item [prefix] >
1019 @dots{} comment out from \begin to \@code{end}
1020 @item [prefix] <
1021 @dots{} uncomment from \begin to \@code{end}
1022 @end table
1024 @noindent
1025 comment whole the contents of environment. Moreover,
1027 @table @kbd
1028 @item [prefix] .
1029 @dots{} comment out \begin and \@code{end}
1030 @item [prefix] ,
1031 @dots{} uncomment \begin and \@code{end}
1032 @end table
1034 @noindent
1035 (un)comments out only environment declaration: @code{\begin@{@}} and
1036 @code{\end@{@}}. NOTE that even if you intend to comment out some region,
1037 invoking @kbd{[prefix] >} on the @code{\begin},@code{\end} line decides to
1038 work in `commenting out from @code{\begin} to @code{\end}' mode.
1041 @node Cursor jump, Changing and Deleting, Commenting out, Top
1042 @comment node-name, next, previous, up
1043 @chapter Cursor jump
1044 @cindex cursor jump
1045 @cindex prefix g
1048 @menu
1049 * Jump to corresponding object::
1050 * Invoking image processor::
1051 * Jump to main file::
1052 * Jumping around the environment::
1053 * Jumping to last completion position::
1054 @end menu
1056 @node Jump to corresponding object, Invoking image processor, Cursor jump, Cursor jump
1057 @comment node-name, next, previous, up
1058 @section Jump to corresponding object
1060 Typing
1062 @table @kbd
1063 @item [prefix] g
1064 @dots{} go to corresponding object
1065 @end table
1067 @noindent
1068 in a certain place move the cursor to the place corresponding to the
1069 La@TeX{} command of last place. YaTeX recognize the followings as pairs
1070 that have relation each other.
1072 @itemize @bullet
1073 @item @code{\begin@{@}} <-> @code{\end@{@}}
1074 @item @code{%#BEGIN} <-> @code{%#END}
1075 @item On the image-including line -> corresponding viewer or drawing tool
1076 @item @code{\label@{@}} <-> @code{\ref@{@}}
1077 @item @code{\include(\input)} -> included file
1078 @item @code{\bibitem@{@}} <-> @code{\cite@{@}}
1079 @end itemize
1081 On a @code{\begin},@code{\end} line, typing @kbd{[prefix] g} moves the
1082 cursor to the corresponding @code{\end},@code{\begin} line, if its partner
1083 really exists. The behavior on the line @code{%#BEGIN} and @code{%#END}
1084 are the same. Note that if the correspondent of @code{label/ref} or
1085 @code{cite/bibitem} exists in another file, that file have to be opened to
1086 make a round trip between references by @kbd{[prefix] g}.
1088 If you type @code{[prefix] g} on the line of @code{\include@{chap1@}},
1089 typically in the main text, YaTeX switches buffer to @file{chap1.tex}.
1091 @table @kbd
1092 @item [prefix] 4 g
1093 @dots{} go to corresponding object in other window
1094 @end table
1096 @noindent
1097 do the same job as @kbd{[prefix] g} except it's done in other window.
1098 Note that this function doesn't work on @code{begin/end},
1099 @code{%#BEGIN/%#END} pairs because it is meaningless.
1101 @node Invoking image processor, Jump to main file, Jump to corresponding object, Cursor jump
1102 @comment node-name, next, previous, up
1103 @section Invoking image processor
1104 @cindex{Drawing tool invocation}
1106 `image-including line' described above means such lines as
1107 @code{\epsfile@{file=foo.ps@}}. If you type @kbd{[prefix] g} on that
1108 line, YaTeX automatically searches source of `foo.ps' and invokes image
1109 viewer or drawing tool correspoinding to it. For example; if you draw
1110 an image foo.obj with Tgif and enclose its product named foo.eps by
1111 @code{\epsfile} command. Typing @kbd{[prefix] g} on @code{\epsfile} line
1112 make YaTeX invoke @code{tgif foo.obj}. How a processor is choosen is as
1113 follows.
1115 @enumerate
1116 @item
1117 If there is an expression matching with one of the pattern
1118 defined in @code{YaTeX-processed-file-regexp-alist}, extract file name
1119 from regexp group surrounded by \\(\\). (Which group corresponds is
1120 written in the cdr part of each list.) If no matches were found, do
1121 nothing.
1122 @item
1123 If there is a pattern as `%PROCESSOR' which is defined in the variable
1124 @code{YaTeX-file-processor-alist}, call that processor giving the
1125 file name with corresponding extension.
1126 @item
1127 If not, check the existence of each file which is supplied the
1128 extension in the cdr part of each list of
1129 @code{YaTeX-file-processor-alist}. If any, call the corresponding
1130 image viewer or drawing tool.
1131 @end enumerate
1133 @node Jump to main file, Jumping around the environment, Invoking image processor, Cursor jump
1134 @comment node-name, next, previous, up
1135 @section Jump to main file
1137 Typing
1139 @table @kbd
1140 @item [prefix] ^
1141 @dots{} visit main file
1142 @item [prefix] 4^
1143 @dots{} visit main file in other buffer
1144 @end table
1145 @cindex prefix ^
1146 @cindex prefix 4 ^
1148 in a sub text switch the buffer to the main text specified by
1149 @code{%#!} notation.
1151 @node Jumping around the environment, Jumping to last completion position, Jump to main file, Cursor jump
1152 @comment node-name, next, previous, up
1153 @section Jumping around the environment
1155 And these are the functions which work on the current La@TeX{}
1156 environment:
1158 @table @kbd
1159 @item M-C-a
1160 @dots{} beginning of environment
1161 @item M-C-e
1162 @dots{} @code{end} of environment
1163 @item M-C-@@
1164 @dots{} mark environment
1165 @end table
1166 @cindex M-C-a
1167 @cindex M-C-e
1168 @cindex M-C-@@
1170 @node Jumping to last completion position, , Jumping around the environment, Cursor jump
1171 @comment node-name, next, previous, up
1172 @section Jumping to last completion position
1174 YaTeX always memorize the position of completion into register @code{3}.
1175 So every time you make a trip to any other part of text other than you are
1176 writing, you can return to the editing paragraph by calling
1177 register-to-point with argument YaTeX-current-position-register, which is
1178 achieved by typing @kbd{C-x j 3}(by default).
1180 @node Changing and Deleting, Filling, Cursor jump, Top
1181 @comment node-name, next, previous, up
1182 @chapter Changing and Deleting
1184 These functions are for change or deletion of La@TeX{} commands
1185 already entered.
1187 @table @kbd
1188 @item [prefix] c
1189 @dots{} change La@TeX{} command
1190 @item [prefix] k
1191 @dots{} kill La@TeX{} command
1192 @end table
1193 @cindex prefix c
1194 @cindex prefix k
1196 @menu
1197 * Changing LaTeX commands::
1198 * Killing LaTeX commands::
1199 @end menu
1201 @node Changing LaTeX commands, Killing LaTeX commands, Changing and Deleting, Changing and Deleting
1202 @comment node-name, next, previous, up
1203 @section Changing La@TeX{} commands
1205 @kbd{[prefix] c} can change the various (La)@TeX{} commands. This can
1206 change the followings.
1207 @itemize @bullet
1208 @item Environment names
1209 @item Section-type commands
1210 @item Argument of section-type commands
1211 @item Optional parameters (enclosed by []) of section-type commands
1212 @item Font/size designators
1213 @item Math-mode's maketitle-type commands that can be inputted with
1214 image completion
1215 @end itemize
1217 Typing @kbd{[prefix] c} on one of above objects you want to change
1218 brings a suitable reading function sometimes with completion.
1219 Note: If you want to change the argument of section-type command that
1220 contains other La@TeX{} commands, type @kbd{[prefix] c} either of
1221 surrounding braces of the argument in order to make YaTeX ignore the
1222 internal La@TeX{} sequences as an object of changing. Anyway, it is
1223 very difficult to know which argument position the cursor belongs because
1224 the La@TeX{} commands can be nested and braces can freely emerge. So keep
1225 it mind to put the cursor on a brace when you are thinking of changing a
1226 complicated argument.
1228 @node Killing LaTeX commands, , Changing LaTeX commands, Changing and Deleting
1229 @comment node-name, next, previous, up
1230 @section Killing La@TeX{} commands
1231 @cindex Killing La@TeX{} commands
1233 @kbd{[prefix] k} kills the La@TeX{} commands sometimes with their
1234 arguments. Following table illustrates the correspondence of the invoking
1235 position and what is killed.
1237 @example
1238 [Invoking position] [action]
1239 \begin, \end line kill \begin,\end pairs
1240 %#BEGIN, %#END line kill %#BEGIN,%#END pairs
1241 on a Section-type command kill section-type command
1242 on a parenthesis kill parentheses
1243 @end example
1245 Note that when killing @code{\begin, \end} or @code{%#BEGIN, %#END} pair,
1246 the lines @code{\begin, \end} or @code{%#BEGIN, %#END} exist will be
1247 killed entirely. So take care not to create any line that contains more
1248 than one @code{\begin} or so.
1250 While all operations above are to kill `containers' which surround some
1251 text, universal argument (@kbd{C-u}) for these commands kills not only
1252 `containers' but also `contents' of them. See below as a sample.
1254 @example
1255 Original text: [prefix] k C-u [prefix] k
1256 Main \footnote@{note@} here. Main note here. Main here.
1257 ~(cursor)
1258 @end example
1260 @node Filling, Updation of includeonly, Changing and Deleting, Top
1261 @comment node-name, next, previous, up
1262 @chapter Filling
1263 @cindex filling
1265 @section Filling an item
1266 @cindex filling an item
1267 @cindex prefix i
1269 To fill a term (descriptive sentences) of @code{\item}, type
1271 @c @table @kbd
1272 @c @item [prefix] i
1273 @c @dots{} fill item
1274 @c @end table
1275 @table @kbd
1276 @item M-q
1277 @dots{} fill item
1278 @end table
1280 @noindent
1281 on that item.
1283 YaTeX uses the value of the variable @code{YaTeX-item-regexp} as the
1284 regular expression to search item header in itemize environment.
1285 If you make a newcommand to itemize terms(e.g. @code{\underlineitem}), put
1287 @lisp
1288 (setq YaTeX-item-regexp
1289 "\\(\\\\\\(sub\\)*item\\)\\|\\(\\\\underlineitem\\)")
1290 @end lisp
1291 @cindex YaTeX-item-regexp
1293 in your @file{~/.emacs}. If you are not familiar with regular expression
1294 for Emacs-Lisp, name a newcommand for `itemize' beginning with
1295 @code{\item} such as @code{\itembf}, not @code{\bfitem}.
1297 This function reformats the @code{\item} into `hang-indented' style.
1298 For example:
1300 @example
1301 itemize, enumerate environment:
1302 >
1303 >\item[foo] `foo' is the typical word for describing an
1304 > arbitrarily written....
1305 description environment:
1306 > \item[bar] When the word `for' is used as an arbitrarily
1307 > word, `bar' is bound to follow it.
1308 @end example
1310 Note that the indent depth of an @code{\item} word and its descriptive
1311 paragraph are the same in latter case. If you want to use different
1312 depth, invoke fill-paragraph at the beginning of non-whitespace
1313 character(see below).
1315 @section Filling paragraph
1316 @cindex Filling paragraph
1317 @cindex M-q
1319 Fill-paragraph is little bit adapted for La@TeX{} sources. It retains from
1320 filling in certain environments where formatting leads to a disaster such
1321 as verbatim, tabular, or so. And it protects @code{\verb} expressions
1322 from being folded (The variable @code{YaTeX-verb-regexp} controls this).
1323 Besides, putting cursor on the first occurrence of non-whitespace
1324 character on a line changes the fill-prefix temporarily to the depth of
1325 the line.
1327 @node Updation of includeonly, What column, Filling, Top
1328 @comment node-name, next, previous, up
1329 @chapter Updation of @code{\includeonly}
1330 @cindex includeonly
1332 When you edit splitting source texts, the notation
1334 @example
1335 \includeonly@{CurrentEditingFileName@}
1336 @end example
1338 @noindent
1339 in the main file reduces the time of typesetting. If you want
1340 to hack other file a little however, you have to rewrite it to
1342 @example
1343 \includeonly@{OtherFileNameYouWantToFix@}
1344 @end example
1346 @noindent
1347 in the main file. YaTeX automatically detects that the current
1348 edited text is not in includeonly list and prompts you
1350 @example
1351 A)dd R)eplace %)comment?
1352 @end example
1354 in the minibuffer. Type @kbd{a} if you want to add the current file name
1355 to @code{\includeonly} list, @kbd{r} to replace \@code{includeonly} list
1356 with the current file, and type @kbd{%} to comment out the
1357 @code{\includeonly} line.
1359 @node What column, Intelligent newline, Updation of includeonly, Top
1360 @comment node-name, next, previous, up
1361 @chapter What column?
1362 @cindex what column
1363 @cindex complex tabular
1364 @cindex prefix &
1366 We are often get tired of finding the corresponding column in
1367 large tabulars. For example,
1369 @example
1370 \begin@{tabular@}@{|c|c|c|c|c|c|c|c|@}\hline
1371 Name&Position&Post No.&Addr.&Phone No.&FAX No.&
1372 Home Addr.&Home Phone\\ \hline
1373 Thunder Bird & 6 & 223 & LA & xxx-yyy &
1374 zzz-www & Japan & 9876-54321 \\
1375 & 2 & \multicolumn@{2@}@{c|@}@{Unknown@}
1376 &&&(???)
1377 \\ \hline
1378 \end@{tabular@}
1379 @end example
1381 Suppose you have the cursor located at @code{(???)} mark, can you tell
1382 which column it is belonging at once? Maybe no. In such case,
1383 type
1385 @table @kbd
1386 @item [prefix] &
1387 @dots{} What column
1388 @end table
1390 @noindent
1391 in that position. YaTeX tells you the column header of the
1392 current field. Since YaTeX assumes the first line of tabular
1393 environment as a row of column headers, you can create a row of
1394 virtual column headers by putting them in the first line and
1395 commenting that line with @code{%}.
1397 @node Intelligent newline, Usepackage checker, What column, Top
1398 @comment node-name, next, previous, up
1399 @chapter Intelligent newline
1400 @cindex Intelligent newline
1401 @cindex ESC RET
1402 @cindex M-C-m
1404 At the end of begin-type completion of tabular[*], array, itemize,
1405 enumerate or tabbing environment, or typing
1407 @table @kbd
1408 @item ESC RET
1409 @dots{} Intelligent newline
1410 @end table
1412 @noindent
1413 in these environments inserts the contents corresponding to the current
1414 environment in the next line. (At the begin-type completion, this
1415 contents can be removed by `undo'.) In @code{tabular} environment, for
1416 example, @kbd{ESC RET} inserts the certain number of @code{&} and trailing
1417 @code{\\}, and @code{\hline} if other @code{\hline} is found in backward.
1418 Here are the list of contents vs. environments.
1420 @itemize
1421 @item @code{tabular}, @code{tabular*}, @code{array}
1423 Corresponding number of @code{&} and @code{\\}.
1424 And @code{\hline} if needed.
1426 @item @code{tabbing}
1428 The same number of @code{\>} as @code{\=} in the first line.
1430 @item @code{itemize}, @code{enumerate}, @code{description}, @code{list}
1432 @code{\item} or @code{item[]}.
1433 @end itemize
1435 Note that since this function works seeing the contents of the first
1436 line, please call this after the second line if possible.
1438 If you want to apply these trick to other environments, @code{foo}
1439 environment for example, define the function named
1440 @code{YaTeX-intelligent-newline-foo} to insert corresponding contents.
1441 That function will be called at the beginning of the next line after the
1442 newline is inserted to the current line. Since the function
1443 @code{YaTeX-indent-line} is designed to indent the current line properly,
1444 calling this function before your code to insert certain contents must be
1445 useful. See the definition of the function
1446 @code{YaTeX-intelligent-newline-itemize} as an example.
1448 @node Usepackage checker, Online help, Intelligent newline, Top
1449 @comment node-name, next, previous, up
1450 @chapter Usepackage checker
1451 @cindex usepackage
1453 When you input begint-type, section-type, maketitle-type macros with
1454 completion, and it requires some LaTeX2e package, YaTeX examines
1455 the existence of correct @code{\usepackage}. If not, YaTeX inserts
1456 the @code{\usepackage@{@}} declaration corresponding to input macro.
1458 To activate the package completion for your favarite package,
1459 set the variable @code{YaTeX-package-alist-private} correctly.
1460 Please refere the value of @code{YaTeX-package-alist-default} as an
1461 example.
1463 @node Online help, Browsing file hierarchy, Usepackage checker, Top
1464 @comment node-name, next, previous, up
1465 @chapter Online help
1466 @cindex online help
1467 @cindex prefix ?
1468 @cindex prefix /
1469 @cindex apropos
1470 @cindex keyword search
1472 YaTeX provides you the online help with popular La@TeX{} commands.
1474 Here are the key strokes for the online help.
1476 @table @kbd
1477 @item [prefix] ?
1478 @dots{} Online help
1479 @item [prefix] /
1480 @dots{} Online apropos
1481 @end table
1483 @section Online help
1485 `Online help' shows the documentation for the popular La@TeX{}
1486 commands(defaults to the commands on the cursor) in the next buffer.
1487 There are two help file, `global help' and `private help'. The former
1488 file contains the descriptions on the standard La@TeX{} command and is
1489 specified its name by variable @code{YaTeX-help-file}. Usually, the
1490 global help file should be located in public space (@code{$EMACSEXECPATH}
1491 by default) and should be world writable so that anyone can update it to
1492 enrich its contents. The latter file contains descriptions on
1493 non-standard or personal command definitions and is specified by
1494 @code{YaTeX-help-file-private}. This file should be put into private
1495 directory.
1497 @section Online apropos
1499 `Online apropos' is an equivalent of GNU Emacs's apropos. It
1500 shows all the documentations that contains the keyword entered by
1501 the user.
1503 @section When no descriptions are found...
1505 If there is no description on a command in help files, YaTeX
1506 requires you to write a description on that command. If you are
1507 willing to do, determine which help file to add and write the
1508 description on it referring your manual of (La)TeX. Please send
1509 me your additional descriptions if you describe the help on some
1510 standard commands. I might want to include it in the next
1511 distribution.
1513 @node Browsing file hierarchy, Cooperation with other packages, Online help, Top
1514 @comment node-name, next, previous, up
1515 @chapter Browsing file hierarchy
1516 @cindex hierarchy
1517 @cindex browsing
1519 When you are editing multi-file source, typing
1521 @table @kbd
1522 @item [prefix] d
1523 @dots{} browse file hierarchy
1524 @end table
1526 @noindent
1527 asks you the parent-most file (which may be defaulted) and displays the
1528 documentation hierarchy in the next window. In this buffer, the following
1529 commands are available.
1531 @table @kbd
1532 @item n
1533 @dots{} move to the next line and show its contents
1534 @item p
1535 @dots{} move to the previous line and show its contents
1536 @item N
1537 @dots{} move to the next file in the same inclusion level
1538 @item P
1539 @dots{} move to the previous file in the same inclusion level
1540 @item j
1541 @dots{} move to the next line
1542 @item k
1543 @dots{} move to the previous line
1544 @item u
1545 @dots{} move to the parent file
1546 @item .
1547 @dots{} show the current files contents in the next window
1548 @item SPC
1549 @dots{} scroll up the current file window
1550 @item DEL, b
1551 @dots{} scroll down the current file window
1552 @item <
1553 @dots{} show the beginning of the current file
1554 @item >
1555 @dots{} show the end of the current file
1556 @item >
1557 @dots{} return to the previous postion after @kbd{<} or @kbd{>}
1558 @item RET, g
1559 @dots{} open the current file in the next window
1560 @item mouse-2
1561 @dots{} same as RET(available only with window system)
1562 @item o
1563 @dots{} other window
1564 @item 1
1565 @dots{} delete other windows
1566 @item -
1567 @dots{} shrink hierarchy buffer window
1568 @item +
1569 @dots{} enlarge hierarchy buffer window
1570 @item ?
1571 @dots{} describe mode
1572 @item q
1573 @dots{} quit
1574 @end table
1576 Note that operations on the file contents in the next window do not work
1577 correctly when you close the corresponding file.
1579 @node Cooperation with other packages, Customizations, Browsing file hierarchy, Top
1580 @comment node-name, next, previous, up
1581 @chapter Cooperation with other packages
1583 YaTeX works better with other brilliant packages.
1585 @section gmhist
1586 @cindex gmhist
1587 @cindex command history
1588 @cindex minibuffer history
1590 When you are loading @file{gmhist.el} and @file{gmhist-mh.el}, you can
1591 use independent command history list at the prompt of preview command
1592 (@kbd{[prefix] tp}) and print command (@kbd{[prefix] tl}). On each
1593 prompt, you can enter the previous command line string repeatedly by
1594 typing @kbd{M-p}.
1596 @section min-out
1597 @cindex min-out
1599 @file{min-out}, the outline minor mode, can be used in yatex-mode
1600 buffers. If you want to use it with YaTeX, please refer the
1601 file @file{yatexm-o.el} as an example.
1603 @node Customizations, Etcetera, Cooperation with other packages, Top
1604 @comment node-name, next, previous, up
1605 @chapter Customizations
1606 @cindex customizations
1608 You can customize YaTeX by setting Emacs-Lisp variables and by making
1609 add-in functions.
1611 @menu
1612 * Lisp variables::
1613 * Add-in functions::
1614 * Add-in generator::
1615 @end menu
1617 @node Lisp variables, Add-in functions, Customizations, Customizations
1618 @comment node-name, next, previous, up
1619 @section Lisp variables
1620 @cindex customizable variables
1622 You can change the key assignments or make completion more comfortable
1623 by setting the values of various variables which control the movement of
1624 yatex-mode.
1626 For example, if you want to change the prefix key stroke from @kbd{C-c}
1627 to any other sequence, set YaTeX-prefix to whatever you want to use. If
1628 you don't want to use the key sequence @kbd{C-c letter} which is assumed
1629 to be the user reserved sequence in Emacs world, set
1630 @code{YaTeX-inhibit-prefix-letter} to @code{t}, and all of the default key
1631 bind of @kbd{C-c letter} will turn to the corresponding @kbd{C-c C-letter}
1632 (but the region based completions that is invoked with @kbd{C-c
1633 Capital-letter} remain valid, if you want to disable those bindings, set
1634 that variable to 1 instead of @code{t}).
1636 @menu
1637 * All customizable variables::
1638 * Sample definitions::
1639 * Hook variables::
1640 * Hook file::
1641 @end menu
1643 @node All customizable variables, Sample definitions, Lisp variables, Lisp variables
1644 @comment node-name, next, previous, up
1645 @subsection All customizable variables
1646 @cindex all customizable variables
1648 Here are the customizable variables of yatex-mode. Each value setq-ed
1649 in @file{~/.emacs} is preferred and that of defined in @file{yatex.el} is
1650 neglected. Parenthesized contents stands for the default value. When you
1651 are to change some of these variables, see more detailed documentation of
1652 the variable by @kbd{M-x describe-variable}.
1654 @defvar YaTeX-japan
1655 Set this nil to produce all messages in English
1656 (@code{Depends on Japanese feature of Emacs})
1657 @end defvar
1659 @defvar YaTeX-kanji-code
1660 Default buffer-file-coding-system for YaTeX modes' buffer.
1661 Set this 0 to no language conversion. Nil to preserve original
1662 coding-system. 1=Shift JIS, 2=JIS, 3=EUC, 4=UTF-8 (@code{1 or 2})
1663 @end defvar
1665 @defvar YaTeX-prefix
1666 Prefix key stroke (@kbd{C-c})
1667 @end defvar
1669 @defvar YaTeX-inhibit-prefix-letter
1670 Change key stroke from @kbd{C-c letter} to @kbd{C-c C-letter} (@code{nil})
1671 @end defvar
1673 @defvar YaTeX-fill-prefix
1674 Fill-prefix used in yatex-mode (@code{nil})
1675 @end defvar
1677 @defvar YaTeX-user-completion-table
1678 Name of user dictionary where learned completion table will be stored.
1679 (@code{"~/.yatexrc"})
1680 @end defvar
1682 @defvar tex-command
1683 La@TeX{} typesetter command (@code{"latex"})
1684 @end defvar
1686 @defvar dvi2-command
1687 Preview command (@code{"xdvi -geo +0+0 -s 4"})
1688 @end defvar
1690 @defvar dviprint-command-format
1691 Command format to print dvi file (@code{"dvi2ps %f %t %s | lpr"})
1692 @end defvar
1694 @defvar dviprint-from-format
1695 Start page format of above %f. %b will turn to start page (@code{"-f %b"})
1696 @end defvar
1698 @defvar dviprint-to-format
1699 End page format of above %t. %e will turn to @code{end} page (@code{"-t %e"})
1700 @end defvar
1702 @defvar makeindex-command
1703 Default makeindex command (@code{"makeindex"} (@code{"makeind"} on MS-DOS))
1704 @end defvar
1706 @defvar YaTeX-dvipdf-command
1707 Default command name to convert .dvi to PDF (@code{"dvipdfmx"})
1708 @end defvar
1710 @defvar YaTeX-on-the-fly-preview-interval
1711 Interval time in seconds of idle to trigger on-the-fly preview of
1712 environment by @kbd{[prefix] t e}(0.9).
1713 @code{Nil} disables on-the-fly preview.
1714 @end defvar
1716 @defvar YaTeX-on-the-fly-math-preview-engine
1717 Function symbol to use on-the-fly preview of MATH environment
1718 started by @kbd{[prefix] t e} (@code{'YaTeX-typeset-environment-by-lmp}
1719 which calls latex-math-preview-expression function if latex-math-preview
1720 is available, otherwise @code{'YaTeX-typeset-environment-by-builtin} which
1721 alls built-in function).
1723 @code{Nil} disables on-the-fly preview.
1724 @end defvar
1726 @defvar YaTeX-cmd-gimp
1727 Command name of GIMP (code{"gimp"})
1728 @end defvar
1729 @defvar YaTeX-cmd-tgif
1730 Command name of tgif (code{"tgif"})
1731 @end defvar
1732 @defvar YaTeX-cmd-inkscape
1733 Command name of Inkscape (code{"inkscape"})
1734 @end defvar
1735 @defvar YaTeX-cmd-dia
1736 Command name of Dia (code{"dia"})
1737 @end defvar
1738 @defvar YaTeX-cmd-ooo
1739 Command name of OpenOffice.org/LibreOffice (code{"soffice"})
1740 @end defvar
1741 @defvar YaTeX-cmd-gs
1742 Command name of Ghostscript (code{"gs"})
1743 @end defvar
1744 @defvar YaTeX-cmd-dvips
1745 Command name of dvips (code{"dvips"})
1746 @end defvar
1747 @defvar YaTeX-cmd-displayline
1748 Command name of displayline
1749 (code{"/Applications/Skim.app/Contents/SharedSupport/displayline"})
1750 @end defvar
1751 @defvar YaTeX-cmd-edit-ps
1752 Command name for editing PostScript files(Value of code{"YaTeX-cmd-gimp"})
1753 @end defvar
1754 @defvar YaTeX-cmd-edit-pdf
1755 Command name for editing PDF files(Value of code{"YaTeX-cmd-ooo"})
1756 @end defvar
1757 @defvar YaTeX-cmd-edit-ai
1758 Command name for editing `.ai' files(Value of code{"YaTeX-cmd-inkscape"})
1759 @end defvar
1760 @defvar YaTeX-cmd-edit-svg
1761 Command name for editing SVG files(Value of code{"YaTeX-cmd-inkscape"})
1762 @end defvar
1763 @defvar YaTeX-cmd-edit-images
1764 Command name for editing image files(Value of code{"YaTeX-cmd-gimp"})
1765 @end defvar
1767 @defvar YaTeX-need-nonstop
1768 Put @code{\nonstopmode@{@}} or not (@code{nil})
1769 @end defvar
1771 @defvar latex-warning-regexp
1772 Regular expression of warning message latex command puts out
1773 (@code{"line.* [0-9]*"})
1774 @end defvar
1776 @defvar latex-error-regexp
1777 Regular expression of error message (@code{"l\\.[1-9][0-9]*"})
1778 @end defvar
1780 @defvar latex-dos-emergency-message
1781 Message latex command running on DOS puts at abort (@code{"Emergency stop"})
1782 @end defvar
1784 @defvar YaTeX-item-regexp
1785 Regular expression of item command (@code{"\\\\item"})
1786 @end defvar
1788 @defvar YaTeX-verb-regexp
1789 Regexp of verb family. Omit \\\\. (@code{"verb\\*?\\|path"})
1790 @end defvar
1792 @defvar YaTeX-nervous
1793 T for using local dictionary (@code{t})
1794 @end defvar
1796 @defvar YaTeX-sectioning-regexp
1797 Regexp of La@TeX{} sectioning command
1798 (@code{"\\(part\\|chapter\\*?\\|\\(sub\\)*\\(section\\|paragraph\\)\\*?\\)\\b"})
1799 @end defvar
1801 @defvar YaTeX-fill-inhibit-environments
1802 Inhibit fill in these environments
1803 (@code{'("tabular" "tabular*" "array" "picture" "eqnarray" "eqnarray*" "equation" "math" "displaymath" "verbatim" "verbatim*")})
1804 @end defvar
1806 @defvar YaTeX-uncomment-once
1807 T for deleting all preceding @code{%} (@code{nil})
1808 @end defvar
1810 @defvar YaTeX-close-paren-always
1811 T for always close all parenthesis automatically, @code{nil} for only eol
1812 (@code{t})
1813 @end defvar
1815 @defvar YaTeX-auto-math-mode
1816 Switch math-mode automatically (@code{t})
1817 @end defvar
1819 @defvar YaTeX-math-key-list-private
1820 User defined alist, math-mode-prefix vs completion alist
1821 used in image completion (@code{nil}). See @file{yatexmth.el}
1822 for the information about how to define a completion alist.
1823 @end defvar
1825 @defvar YaTeX-default-pop-window-height
1826 Initial height of typesetting buffer when one-window.
1827 Number for the lines of the buffer, numerical string for
1828 the percentage of the screen-height. @code{nil} for half height (10)
1829 @end defvar
1831 @defvar YaTeX-help-file
1832 Global online help file name (@file{$doc-directory/../../site-lisp/YATEXHLP.eng})
1833 @end defvar
1835 @defvar YaTeX-help-file-private
1836 Private online help file name (@file{"~/YATEXHLP.eng"})
1837 @end defvar
1839 @defvar YaTeX-no-begend-shortcut
1840 Disable [prefix] b ?? shortcut (@code{nil)}
1841 @end defvar
1843 @defvar YaTeX-hilit-pattern-adjustment-private
1844 List of the list that contain the regular expression and the symbol of
1845 logical meaning of the string that matches the pattern. See also the
1846 value from @code{(assq 'yatex-mode hilit-patterns-alist)} and the value of
1847 @code{YaTeX-hilit-pattern-adjustment-default} (and even the document of
1848 hilit19.el).
1849 @end defvar
1851 @defvar YaTeX-sectioning-level
1852 Alist of LaTeX's sectioning command vs its height.
1853 @end defvar
1855 @defvar YaTeX-hierarchy-ignore-heading-regexp
1856 @code{YaTeX-display-hierarchy} searches for sectioning command first, and
1857 comment line secondary as a file headings. In latter case, ignore lines
1858 that match with regular expression of this variable. Default value of
1859 this variable is RCS header expressions and mode specifying line `-*- xxxx
1860 -*'.
1861 @end defvar
1863 @defvar YaTeX-skip-default-reader
1864 Non-nil for this variable skips the default argument reader of
1865 section-type command when add-in function for it is not defined
1866 (@code{nil})
1867 @end defvar
1869 @defvar YaTeX-create-file-prefix-g
1870 When typing @kbd{prefix g} on the @code{\include} line,
1871 open the target file even if the file doesn't exist (@code{nil})
1872 @end defvar
1874 @defvar YaTeX-simple-messages
1875 Simplyfy messages of various completions (@code{nil})
1876 @end defvar
1878 @defvar YaTeX-hilit-sectioning-face
1879 When hilit19 and yatex19 is active, YaTeX colors the sectioning commands.
1880 This variable specifies the foreground and background color of
1881 @code{\part} macro. The default value is @code{'(yellow/dodgerblue
1882 yellow/slateblue)}. The first element of this list is for the screen when
1883 @code{hilit-background-mode} is @code{'light}, and the second element is
1884 for @code{'dark}. You should specify both color as `forecolor/backcolor'.
1885 @end defvar
1887 @defvar YaTeX-hilit-sectioning-attenuation-rate
1888 When color mode, this variable specifies how much attenuate the color
1889 density of @code{\subparagraph} compared with that of @code{\chapter}
1890 (@code{'(15 40)}) See also @code{YaTeX-hilit-sectioning-face}.
1891 @end defvar
1893 @defvar YaTeX-use-AMS-LaTeX
1894 If you use AMS-LaTeX, set to @code{t} (@code{nil})
1895 @end defvar
1897 @defvar YaTeX-use-LaTeX2e
1898 If you use LaTeX2e, set to @code{t} (@code{t})
1899 @end defvar
1901 @defvar YaTeX-template-file
1902 File name which is automatically inserted at creation
1903 (@code{~/work/template.tex})
1904 @end defvar
1906 @defvar YaTeX-search-file-from-top-directory
1907 Non-nil means to search input-files from the directory where main file exists
1908 (@code{t})
1909 @end defvar
1911 @defvar YaTeX-use-font-lock
1912 Use font-lock to fontify buffer or not (@code{(featurep 'font-lock)}
1913 @end defvar
1915 @defvar YaTeX-use-hilit19
1916 Use hilit19 to highlight buffer or not (@code{(featurep 'hilit19)}
1917 @end defvar
1919 @defvar YaTeX-use-italic-bold
1920 YaTeX tries to search italic, bold fontsets or not
1921 (@code{t} if Emacs-20 or later). This variable is effective only when
1922 font-lock is used.
1923 (@code{(featurep 'hilit19)}
1924 @end defvar
1926 @defvar YaTeX-singlecmd-suffix
1927 Suffix which is always inserted after maketitle-type macros.
1928 @code{"@{@}"} is recommended.
1929 @end defvar
1931 @defvar YaTeX-package-alist-private
1932 Alist of LaTeX2e-package name vs. lists of macros in it.
1933 Set this alist properly and YaTeX automatically check the declaratiion of
1934 `usepackage' for corresponding macro, when you input that macro with
1935 completion. If required `usepackage' is not found, YaTeX also
1936 automatically inserts `\usepackage'. Alist is as follows;
1937 @lisp
1938 '((PackageName1
1939 (completionType ListOfMacro)
1940 (completionType ListOfMacro))
1941 (PackageName2
1942 (completionType ListOfMacro)
1943 (completionType ListOfMacro...))....)
1944 @end lisp
1945 completionType is one of @code{env, section, maketitle}.
1946 Consult the value of @code{YaTeX-package-alist-default} as an example.
1947 @end defvar
1949 @defvar YaTeX-tabular-indentation
1950 At indentation by @kbd{C-i} in tabular or array environment,
1951 YaTeX put the additional spaces to the normail indentation depth.
1952 The number of additional spaces is the product of YaTeX-tabular-indentation
1953 and the number of column position in tabular.
1954 @end defvar
1956 @defvar YaTeX-noindent-env-regexp
1957 Regexp of environment names that should begin with no indentation.
1958 All verbatime-like environment name should match with.
1959 @end defvar
1961 @defvar YaTeX-electric-indent-mode
1962 Emacs 24.4 introduces automatic indentation of current and new lines.
1963 This might be annoying for some people. Pass this value to the function
1964 'electric-indent-local-mode. If you prefer to stop electric-indent-mode
1965 in yatex-mode, set `-1' to this variable.
1966 @end defvar
1968 @defvar YaTeX-ref-default-label-string
1969 Default \\ref time string format.
1970 This format is like strftime(3) but allowed conversion char are as follows;
1971 %y -> Last 2 digit of year, %b -> Month name, %m -> Monthe number(1-12),
1972 %d -> Day, %H -> Hour, %M -> Minute, %S -> Second,
1973 %qx -> alphabetical-decimal conversion of yymmdd.
1974 %qX -> alphabetical-decimal conversion of HHMMSS.
1975 Beware defualt label-string should be always unique. So this format string
1976 should have both time part (%H+%M+%S or %qX) and date
1977 part (%y+(%b|%m)+%d or %qx).
1978 @end defvar
1980 @defvar YaTeX-ref-generate-label-function
1981 Function to generate default label string for unnamed \\label@{@}s.
1982 The function pointed to this value should take two arguments.
1983 First argument is LaTeX macro's name, second is macro's argument.
1984 Here is an example for using this value.
1985 @lisp
1986 (setq YaTeX-ref-generate-label-function 'my-yatex-generate-label)
1987 (defun my-yatex-generate-label (command value)
1988 (and (string= command "caption")
1989 (re-search-backward "\\\\begin@{\\(figure\\|table\\)@}" nil t)
1990 (setq command (match-string 1)))
1991 (let ((alist '(("chapter" . "chap")
1992 ("section" . "sec")
1993 ("subsection" . "subsec")
1994 ("figure" . "fig")
1995 ("table" . "tbl"))))
1996 (if (setq command (cdr (assoc command alist)))
1997 (concat command ":" value)
1998 (YaTeX::ref-generate-label nil nil))))
1999 @end lisp
2000 @end defvar
2003 @node Sample definitions, Hook variables, All customizable variables, Lisp variables
2004 @comment node-name, next, previous, up
2005 @subsection Sample definitions
2006 @cindex prefix key stroke
2007 @cindex fill-prefix
2009 For instance, to change the prefix key stroke to @kbd{ESC}, and name of
2010 the user dictionary @file{~/src/emacs/yatexrc}, and set @code{fill-prefix}
2011 to single TAB character, add the following @code{setq} to @file{~/.emacs}.
2013 @lisp
2014 (setq YaTeX-prefix "\e"
2015 YaTeX-user-completion-table "~/src/emacs/yatexrc"
2016 YaTeX-fill-prefix " ")
2017 @end lisp
2019 @node Hook variables, Hook file, Sample definitions, Lisp variables
2020 @comment node-name, next, previous, up
2021 @subsection Hook variables
2022 @cindex hook variables
2024 More customizations will be done by the hook-function defined in
2025 hook-variable @code{yatex-mode-hook}. This is useful to define a shortcut
2026 key sequence to enter some environments other than @code{document} and
2027 @code{enumerate} etc. The following statement defines @code{[prefix] ba}
2028 to enter @code{\begin@{abstract@}} ... @code{=end@{abstract@}}
2029 immediately.
2031 @lisp
2032 (setq yatex-mode-hook
2033 '(lambda() (YaTeX-define-begend-key "ba" "abstract")))
2034 @end lisp
2036 You should use functions @code{YaTeX-define-key}, or
2037 @code{YaTeX-define-begend-key} to define all the key sequences of
2038 yatex-mode.
2040 @node Hook file, , Hook variables, Lisp variables
2041 @comment node-name, next, previous, up
2042 @subsection Hook file
2043 @cindex hook file
2045 You can stuff all of YaTeX related expressions into a file named
2046 @file{yatexhks.el} if you have a lot of codes. YaTeX automatically load
2047 this file at the initialization of itself. Using @file{yatexhks.el}
2048 makes @code{yatex-mode-load-hook} unnecessary.
2050 @node Add-in functions, Add-in generator, Lisp variables, Customizations
2051 @comment node-name, next, previous, up
2052 @section Add-in functions
2053 @cindex add-in functions
2054 @cindex yatexadd.el
2056 You can easily define a function to input detailed arguments
2057 with completion according to La@TeX{} environments or commands.
2059 @c @node What is add-in functions?, , Add-in functions, Add-in functions
2060 @comment node-name, next, previous, up
2061 @subsection What is add-in functions?
2062 @cindex tabular
2064 When you input @code{tabular} environment, don't you think ``I want
2065 YaTeX to complete its argument toward my favorite one such as
2066 @code{@{|c|c|c|@}}...''? Yes, you can define the function to complete
2067 arguments for any environment and any La@TeX{} commands.
2069 @subsection Procedure
2071 Here is the procedure to define add-in functions.
2072 @enumerate
2073 @item
2074 Define the function
2075 @item
2076 Put the function into @file{yatexhks.el}
2077 @end enumerate
2079 @menu
2080 * How the add-in function works::
2081 * How the function is called::
2082 * Useful functions for creating add-in::
2083 * Contribution::
2084 @end menu
2086 @node How the add-in function works, How the function is called, Add-in functions, Add-in functions
2087 @comment node-name, next, previous, up
2088 @subsection How the add-in function works
2090 There are three types of add-in.
2092 @enumerate
2093 @item
2094 Option add-in
2095 @item
2096 argument add-in
2097 @item
2098 enclosing add-in
2099 @end enumerate
2101 @dfn{Option add-in} returns the
2102 La@TeX{}'s optional parameters such as optional strings after
2103 @code{\begin@{ENV@}}, optional strings between a section-type command
2104 and its first argument, and optional strings just after type
2105 maketitle-type command. The following illustrates the name of add-in
2106 functions, where underlined strings are generated by add-in functions.
2108 @display
2109 \begin@{table@}[ht] (Function name: YaTeX:table)
2110 ~~~~
2111 \put(100,200)@{@} (Function name: YaTeX:put)
2112 ~~~~~~~~~
2113 \sum_@{i=0@}^@{n@} (Function name: YaTeX:sum)
2114 ~~~~~~~~~~
2115 @end display
2117 Obviously, the function name is decided by concatenating the prefix
2118 `YaTeX:' and La@TeX{} command's name.
2120 Another add-in type is @dfn{argument add-in}, which completes arguments
2121 for section-type commands.
2123 @display
2124 \newcommand@{\foo@}@{bar@} (Function name: YaTeX::newcommand)
2125 ~~~~ ~~~
2126 @end display
2128 When the section-type command is inputted, the function named by
2129 concatenating `YaTeX::' and section-type command, is called automatically
2130 with an integer argument which indicates which argument of section-type
2131 command is being read. Thus the add-in should determine the
2132 job referring the value of its argument.
2134 @dfn{enclosing add-in} is for modifying and/or checking the region that
2135 will be enclosed by section-type commands via @kbd{[prefix] S}. An
2136 enclosing add-in function will be called with two arguments, beginning of
2137 the enclosed region and end of the region. Suppose you want to enclose
2138 the existing text @code{(a+b)/c} by @code{\frac@{@}}.
2140 @display
2141 a/c
2142 | |
2143 A B
2144 @end display
2146 You do set-mark-command at point A and then move to point B. Typing
2147 @kbd{[prefix] S} and input @code{frac} enclose the region like this;
2149 @display
2150 \frac@{a/c@}
2151 @end display
2153 Normally, the expression @code{a/c} is translated to
2154 @code{\frac@{a@}@{c@}}. An enclosing add-in is useful for modifying
2155 @code{/} to @code{@}@{}.
2157 @menu
2158 * Defining option-add-in::
2159 * Defining argument-add-in::
2160 * Defining enclosing-add-in::
2161 @end menu
2163 @node Defining option-add-in, Defining argument-add-in, How the add-in function works, How the add-in function works
2164 @comment node-name, next, previous, up
2165 @subsubsection Defining `option add-in'
2167 If you want @code{@{|c|c|c|@}} for all @code{tabular} environment,
2169 @lisp
2170 (defun YaTeX:tabular ()
2171 "@{|c|c|c|@}")
2172 @end lisp
2174 @noindent
2175 is enough. If you want more complicated format, define as below.
2177 @lisp
2178 (defun YaTeX:tabular ()
2179 "@{@@@{\\vrule width 1pt\\ @}|||@@@{\\ \\vrule width 1pt@}@}")
2180 @end lisp
2182 @noindent
2183 Note that the character @code{\} must be described as @code{\\} in
2184 Emacs-Lisp. The next example reads the tabular format from keyboard.
2185 @lisp
2186 (defun YaTeX:tabular ()
2187 (concat "@{" (read-string "Rule: ") "@}"))
2188 @end lisp
2190 @node Defining argument-add-in, Defining enclosing-add-in, Defining option-add-in, How the add-in function works
2191 @comment node-name, next, previous, up
2192 @subsubsection Defining `argument add-in'
2194 This section describes how to define the add-in function for
2195 @code{\newcommand}.
2197 The first argument of @code{\newcommand} begins always with @code{\}.
2198 The second argument is usually so complex that we can not edit them in the
2199 minibuffer. Here is the created function considering this.
2201 @lisp
2202 (defun YaTeX::newcommand (n) ;n is argument position
2203 (cond
2204 ((= n 1) ;1st argument is macro name
2205 (read-string "Command: " "\\")) ;initial input `\'
2206 ((= n 2) "") ;do nothing when reading arg#2
2207 (t nil)))
2208 @end lisp
2210 Note that when the `argument add-in' function return `nil', normal
2211 argument reader will be called.
2213 @node Defining enclosing-add-in, , Defining argument-add-in, How the add-in function works
2214 @comment node-name, next, previous, up
2215 @subsubsection Defining `enclosing add-in'
2217 This section describes how to define the add-in function for
2218 text enclosed by @code{\frac@{@}}.
2220 When enclosing the text @code{5/3} by @code{\frac@{@}}, you might want to
2221 replace @code{/} with @code{@}@{}. Enclosing function
2222 @code{YaTeX::frac-region} is called with two arguments, beginning of
2223 enclosed text and end of enclosed text. The function is expected to
2224 replace @code{/} with @code{@}@{}. Here is an example expression.
2226 @lisp
2227 (defun YaTeX::frac-region (beg end)
2228 (catch 'done
2229 (while (search-forward "/" end t)
2230 (goto-char (match-beginning 0))
2231 (if (y-or-n-p "Replace this slash(/) with `@}@{'")
2232 (throw 'done (replace-match "@}@{")))
2233 (goto-char (match-end 0)))))
2234 @end lisp
2236 @node How the function is called, Useful functions for creating add-in, How the add-in function works, Add-in functions
2237 @comment node-name, next, previous, up
2238 @subsection How the function is called
2240 YaTeX calls the add-in functions for specified begin-type, section-type,
2241 and maketitle-type command, if any. `Option add-in' functions for
2242 begin-type are called when @code{\begin@{ENV@}} has been inserted,
2243 functions for section-type are called just before input of the first
2244 argument, and functions for maketitle-type is called after maketitle-type
2245 command has been inserted. `Argument add-in' functions are called at each
2246 entry of arguments for section-type commands.
2248 @node Useful functions for creating add-in, Contribution, How the function is called, Add-in functions
2249 @comment node-name, next, previous, up
2250 @subsection Useful functions for creating add-in
2252 Many add-in functions for typical La@TeX{} commands are defined in
2253 @file{yatexadd.el}. Those are also useful as references. Here are the
2254 short descriptions on useful functions, where [F] means function, [A]
2255 means arguments, [D] means description.
2257 @table @kbd
2258 @item [F]
2259 YaTeX:read-position
2260 @itemx [A]
2261 Character list which can show up in the brackets
2262 @itemx [D]
2263 Return the location specifier such as `[htb]'. When
2264 nothing is entered, omit [] itself. If the possible characters
2265 are "htbp", call this function as
2266 @code{(YaTeX:read-position "htbp")}
2268 @item [F]
2269 YaTeX:read-coordinates
2270 @itemx [A]
2271 Base prompt, X-axis prompt, Y-axis prompt (each optional)
2272 @itemx [D]
2273 Read the coordinates with the prompt ``BasePrompt X-axisPrompt:'' for
2274 X-axis, ``BasePrompt Y-axisPrompt:'' for Y-axis, and return it in the form
2275 of ``(X,Y)''. The default prompts are @code{Dimension}, @code{X},
2276 @code{Y} respectively.
2278 @item [F]
2279 YaTeX:check-completion-type
2280 @itemx [A]
2281 One of the symbols: 'begin, 'section, or 'maketitle
2282 @itemx [D]
2283 Check the current completion type is specified one and cause error if
2284 not. The variable @code{YaTeX-current-completion-type} holds the symbol
2285 according to the current completion type.
2286 @end table
2288 @node Contribution, , Useful functions for creating add-in, Add-in functions
2289 @comment node-name, next, previous, up
2290 @subsection Contribution
2292 If you make your own pretty function and you let it be in public, please
2293 send me the function. I'm going to include it in the next release.
2295 @node Add-in generator, , Add-in functions, Customizations
2296 @comment node-name, next, previous, up
2297 @section Add-in generator
2299 First, don't forget to read the section of add-in functions @ref{Add-in
2300 functions}. If you easily understand how to define them, there's no need
2301 to read this section. But being not familiar with Emacs-Lisp, when you
2302 don't have clear idea what to do, this section describes how to get YaTeX
2303 make add-in function.
2305 There are two methods of generation. One is for fully interactive
2306 generator for beginners and another requires little knowledge of
2307 Emacs-Lisp.
2309 @subsection Generator for beginners
2310 The former generator is called by
2311 @center @kbd{M-x YaTeX-generate}
2313 @noindent
2314 strokes. All you have to do is follow the guidances. Defying them may cases
2315 the disaster (I wonder what is it???). So when you make some mistake, it
2316 is recommendable to type @kbd{C-g} and start afresh.
2318 @subsection Simple generator
2320 The latter generator is invoked by the next sequence.
2321 @center @kbd{M-x YaTeX-generate-simple}
2322 This generator can make both ``option add-in'' and ``argument add-in''
2323 (@emph{refer the section add-in functions}
2324 @ref{How the add-in function works}), whereas @code{YaTeX-generate}
2325 cannot make ``argument addin''.
2327 For example, assume you have the LaTeX command as follows.
2329 @example
2330 \epsinput[t](250,50)@{hoge.eps@}@{plain@}@{Picture of foo@}
2331 (A) (B) (1) (2) (3)
2332 (A)Optional parameter to specify the position
2333 One of t(top), b(bottom), l(left), r(right)
2334 (B)Maximum size of frame
2335 (1)1st argument is filename of EPS file
2336 (2)2nd argument indicates
2337 plain do nothing
2338 frame make frame around image
2339 dframe make double-frame around image
2340 for included EPS file.
2341 (3)Caption for the picture
2342 @end example
2344 Now get start with generation. Typing @kbd{M-x YaTeX-generate-simple}
2345 brings the prompt:
2346 @display
2347 (O)ption? (A)rgument?
2348 @end display
2350 @subsubsection Generating ``option add-in''
2351 @cindex option add-in
2353 Since (A), (B) above are optional argument, all we have to do to
2354 complete them is define the option add-in for them. Let's generate the
2355 function to complete (A).
2357 @display
2358 M-x YaTeX-generate-simple RET
2359 epsinput RET
2360 o
2361 @end display
2363 @noindent
2364 Typing as above leads the next prompt.
2366 @display
2367 Read type(1): (S)tring (C)omplete (F)ile ([)option (P)osition co(O)rd. (q)uit
2368 @end display
2370 @noindent
2371 This asks that ``Which type is the completion style of 1st argument?''.
2372 Here are the possible completion style.
2374 @table @code
2375 @item String
2376 read plain string
2377 @item Complete
2378 read with completion
2379 @item File
2380 read file name
2381 @item Option
2382 read optional string (if string omitted, omit [] too)
2383 @item Position
2384 read positional option (like [htbp])
2385 @item Coord.
2386 read coordinates
2387 @item Quit
2388 quit from generating
2389 @end table
2391 Since (A) is the optional argument to specify the location of included
2392 EPS file, the completion style is @code{Position}, and the possible
2393 characters are t, b, l, and r. To tell these information to generator,
2394 operate as follows.
2396 @display
2397 Read type(1).... p
2398 Acceptable characters: tblr RET
2399 @end display
2401 (B) is coordinate. So its completion style is coOrd. We want a prompt
2402 meaning ``Maximum size'' when completion.
2404 @display
2405 Read type(2).... o
2406 Prompt for coordinates: Max size RET
2407 @end display
2409 That's all for optional argument. Select quit.
2411 @display
2412 Read type(3).... q
2413 @end display
2415 Then the generated option add-in function for \epsinput will be shown in
2416 the next window.
2418 @subsubsection Generating ``argument add-in''
2419 @cindex argument add-in
2421 Next, create the argument add-in. The arguments for \epsinput are EPS
2422 file name, framing style, and caption string in sequence.
2424 @display
2425 M-x YaTeX-generate-simple RET
2426 epsinput RET
2427 a
2428 @end display
2430 Above key strokes bring the prompt that asks the number of argument.
2431 Answer it with 3.
2433 @display
2434 How many arguments?: 3 RET
2435 @end display
2437 Then the generator asks the completion style and prompt for completion.
2438 Answer them. @kbd{f} for FileName and prompt string.
2440 @display
2441 Read type(1).... f
2442 Prompt for argument#1 EPS file name RET
2443 @end display
2445 The second argument is one of selected symbol. So the completion type
2446 is @code{Completion}.
2448 @display
2449 Read type(2).... c
2450 Prompt for argument#2 Include style RET
2451 @end display
2453 Then all the candidates ready to be read. Type single RET after
2454 entering all.
2456 @display
2457 Item[1](RET to exit): plain RET
2458 Item[2](RET to exit): frame RET
2459 Item[3](RET to exit): dframe RET
2460 Item[4](RET to exit): RET
2461 @end display
2463 The following prompt asks whether the entered string must belong to
2464 candidates or not. In this case, since the argument must be one of
2465 @code{plain}, @code{frame}, and @code{dframe}, type @code{y}.
2467 @display
2468 Require match? (y or n) y
2469 @end display
2471 The last argument is the caption string for which any completion is
2472 needed.
2474 @display
2475 Read type(3).... s
2476 Prompt for argument#3 Caption RET
2477 default: Figure of RET
2478 @end display
2480 Finally we'll get the argument add-in in the next window.
2482 @subsection Contribution
2484 If you get your own pretty function and you let it be in public, please
2485 steel yourself in the happy atmosphere and do not send me the function.
2486 I do know it is not fine because it is generated by yatexgen:-p.
2488 @node Etcetera, Copying, Customizations, Top
2489 @comment node-name, next, previous, up
2490 @chapter Etcetera
2492 The standard completion tables provided in @file{yatex.el} contain a
2493 few La@TeX{} commands I frequently use. This is to lessen the key
2494 strokes to complete entire word, because too many candidates
2495 rarely used often cause too many hits. Therefore always try to
2496 use completion in order to enrich your dictionary, and you will
2497 also find `Wild Bird' growing suitable for your La@TeX{} style.
2499 The package name `Wild Bird' is the English translation of Japanese
2500 title `Yachou', which is a trick on words of Japanese.
2502 @node Copying, , Etcetera, Top
2503 @comment node-name, next, previous, up
2504 @chapter Copying
2506 This program is distributed as a free software. You can
2507 use/copy/modify/redistribute this software freely but with NO warranty to
2508 anything as a result of using this software. Adopting code from this
2509 program is also free. But I would not do contract act.
2511 Any reports and suggestions are welcome as long as I feel interests in
2512 this software. My possible e-mail address is `yuuji@@yatex.org'. (as of
2513 Jan.2004) And there is mailing list for YaTeX. Although the common
2514 language is Japanese, questions in English will be welcome. To join the
2515 ML, send the mail whose subject is `append' to the address
2516 `yatex@@yatex.org. If you have some question, please ask to
2517 `yatex-admin@@yatex.org'.
2519 The specification of this software will be surely modified
2520 (depending on my feelings) without notice :-p.
2523 @flushright
2524 HIROSE Yuuji
2525 @end flushright
2526 @bye
2528 Local variables:
2529 mode: texinfo
2530 fill-prefix: nil
2531 fill-column: 74
2532 End: