view docs/yatexe.tex @ 566:2ef9f21dd13b

Add note on YaTeX::usepackage-alist-default
author HIROSE Yuuji <yuuji@gentei.org>
date Thu, 24 Jan 2019 15:19:32 +0900
parents 355b28fc0025
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 Sat Jan 6 23:42:24 2018 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-2017 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 @item \includegraphics by Drag&Drop of image file
100 @end itemize
102 @node Installation, Typesetting, Main features, Top
103 @comment node-name, next, previous, up
104 @chapter Installation
105 @cindex installation
106 @cindex .emacs
107 @cindex auto-mode-alist
108 @cindex autoload
110 Put next two expressions into your @file{~/.emacs}.
112 @lisp
113 (setq auto-mode-alist
114 (cons (cons "\\.tex$" 'yatex-mode) auto-mode-alist))
115 (autoload 'yatex-mode "yatex" "Yet Another La@TeX{} mode" t)
116 @end lisp
118 Next, add certain path name where you put files of YaTeX to your
119 load-path. If you want to put them in @file{~/src/emacs}, write
121 @lisp
122 (setq load-path
123 (cons (expand-file-name "~/src/emacs") load-path))
124 @end lisp
126 @noindent
127 in your @file{~/.emacs}
129 Then, yatex-mode will be automatically loaded when you visit a
130 file which has extension @file{.tex}. If yatex-mode is successfully
131 loaded, mode string on mode line will be turned to "YaTeX".
134 @node Typesetting, %#notation, Installation, Top
135 @comment node-name, next, previous, up
136 @chapter Typesetting
137 @cindex typesetting
138 @cindex previewer
139 @cindex typesetter
140 @cindex latex
141 @cindex printing out
143 The prefix key stroke of yatex-mode is @kbd{C-c} (Press 'C' with Control
144 key) by default. If you don't intend to change the prefix key stroke,
145 assume all @kbd{[prefix]} as @kbd{C-c} in this document. These key
146 strokes execute typeset or preview command.
148 @table @kbd
149 @item [prefix] t j
150 @dots{} invoke typesetter
151 @item [prefix] t r
152 @dots{} invoke typesetter on region
153 @item [prefix] t e
154 @dots{} `on-the-fly preview' on current environment or whole
155 portion of current formulas in math-mode
156 @item [prefix] t d
157 @dots{} invoke dvipdfmx after successful typesetting
158 @item [prefix] t k
159 @dots{} kill current typesetting process
160 @item [prefix] t b
161 @dots{} invoke bibtex
162 @item [prefix] t i
163 @dots{} invoke makeindex
164 @item [prefix] t d
165 @dots{} invoke latex && dvipdfmx
166 @item [prefix] t p
167 @dots{} preview
168 @item [prefix] t l
169 @dots{} lpr dvi-file
170 @item [prefix] t s
171 @dots{} search current string on xdvi-remote
172 @end table
174 @menu
175 * Calling typesetter::
176 * Calling previewer::
177 * Printing out::
178 @end menu
180 @node Calling typesetter, Calling previewer, Typesetting, Typesetting
181 @comment node-name, next, previous, up
182 @section Calling typesetter
184 Typing @kbd{[prefix] t j}, the current editing window will be divided
185 horizontally when you invoke latex command, and log message of La@TeX{}
186 typesetting will be displayed in the other window; called typesetting
187 buffer. The typesetting buffer automatically scrolls up and traces
188 La@TeX{} warnings and error messages. If you see latex stopping by an
189 error, you can send string to latex in the typesetting buffer.
191 If an error stops the La@TeX{} typesetting, this key stroke will
192 move the cursor to the line where La@TeX{} error is detected.
194 @table @kbd
195 @item [prefix] '
196 @itemx ([prefix]+single quotation)
198 @dots{} jump to the previous error or warning
199 @end table
201 If you find a noticeable error, move to the typesetting buffer and move
202 the cursor on the line of error message and type @kbd{SPACE} key. This
203 makes the cursor move to corresponding source line.
205 YaTeX-typeset-region invoked by @kbd{[prefix] tr} call typesetter
206 for region. The region is specified by standard point and mark, or
207 by @code{%#BEGIN} and @code{%#END} marks. Selected region will be
208 copied to the temporary file @file{texput.tex} with the same preamble
209 as the main file of current editing sources. Be sure to put
210 all local macro settings in preamble, not after @code{\begin@{document@}}.
211 The method of specification of the region is shown in the
212 section @xref{%#notation}.
214 The documentclass for typeset-region is the same as that of editing
215 file if you edit one file, and is the same as main file's if you
216 edit splitting files.
218 The @kbd{[prefix] te} key automatically marks current inner environment
219 or inner math mode or paragraph, and then call typeset-region with marked
220 region. This
221 is convenient to quick view of current tabular environment or current
222 editing formulas. If running Emacs has the ability of displaying images,
223 typeset image will be shown in the next window. Further more,
224 if you modify the content within that environment, YaTeX performs
225 `on-the-fly' preview that automatically update preview image as you typed.
227 If your Emacs does not supply on-the-fly preview,
228 keeping previewer window for @file{texput.dvi} is handy
229 for debugging. Since @kbd{[prefix] te} selects the inner-most environment
230 as region, it is not suitable for partial typesetting of doubly or more
231 composed environment. If you want to do partial typesetting for a nested
232 environment, use @kbd{[prefix] tr} for static-region, which is described
233 in the section @xref{%#notation}.
235 @node Calling previewer, Printing out, Calling typesetter, Typesetting
236 @comment node-name, next, previous, up
237 @section Calling previewer
239 @kbd{[prefix] t p} invokes the TeX previewer. And if you are using
240 xdvi-remote, which can be controled from other terminals, @kbd{[prefix] t
241 s} enables you to search current string at the cursor on the running xdvi
242 window.
244 @node Printing out, , Calling previewer, Typesetting
245 @comment node-name, next, previous, up
246 @section Printing out
248 When you type @code{[preifx] t l}, YaTeX asks you the range of
249 dvi-printing by default. You can skip this by invoking it with
250 universal-argument as follows:
252 @example
253 C-u [prefix] tl
254 @end example
256 @node %#notation, Completion, Typesetting, Top
257 @comment node-name, next, previous, up
258 @chapter %# notation
259 @cindex %# notation
261 You can control the typesetting process by describing @code{%#}
262 notations in the source text.
264 @menu
265 * Changing typesetter::
266 * Splitting input files::
267 * Static region for typesetting::
268 * Special Filtering Region::
269 * Lpr format::
270 * Controlling which command to invoke::
271 * Editing %# notation::
272 @end menu
274 @node Changing typesetter, Splitting input files, %#notation, %#notation
275 @comment node-name, next, previous, up
276 @section To change the `latex' command or to split a source text.
277 @cindex typesetter
279 To change the typesetting command, write
281 @example
282 %#!latex-big
283 @end example
285 @noindent
286 anywhere in the source text. This is useful for changing
287 typesetter.
289 @node Splitting input files, Static region for typesetting, Changing typesetter, %#notation
290 @comment node-name, next, previous, up
291 @section Splitting input files
293 And if you split the source text and
294 edit subfile that should be included from main text.
296 @example
297 %#!latex main.tex
298 @end example
300 @noindent
301 will be helpful to execute latex on main file from sub text buffer. Since
302 this command line after @kbd{%#!} will be sent to shell literally, next
303 description makes it convenient to use ghostview as dvi-previewer.
305 @example
306 %#!latex main && dvi2ps main.dvi > main
307 @end example
309 @noindent
310 Note that YaTeX assumes the component before the last period of
311 the last word in this line as base name of the main La@TeX{} source.
312 The @code{%f} notation in this line is replaced by main file name, and
313 @code{%r} replaced by root name of main file name. If you specify
314 @code{%f} or @code{%r}, YaTeX always ask you the name of main file at the
315 first typesetting.
317 To make best use of the feature of inter-file jumping by
318 @kbd{[prefix] g} (see @ref{Cursor jump}), take described below into
319 consideration.
321 @itemize
322 @item You can put split texts in sub directory, but not in
323 sub directory of sub directory.
324 @item In the main text, specify the child file name with relative path name
325 such as \include@{chap1/sub@}, when you include the file in
326 a sub-directory.
327 @item In a sub-text, write @code{%#!latex main.tex} even if @file{main.tex}
328 is in the parent directory(not %#!latex ../main.tex).
329 @end itemize
331 @node Static region for typesetting, Lpr format, Splitting input files, %#notation
332 @comment node-name, next, previous, up
333 @section Static region
334 @cindex static region
335 @cindex Fixed region
337 Typeset-region by @kbd{[prefix] tr} passes the region between point and
338 mark to typesetting command by default. But when you want to typeset
339 static region, enclose the region by @code{%#BEGIN} and @code{%#END} as
340 follows.
342 @example
343 %#BEGIN
344 TheRegionYouWantToTypesetManyTimes
345 %#END
346 @end example
348 This is the rule of deciding the region.
350 @enumerate
351 @item
352 If there exists %#BEGIN before point,
354 @enumerate
355 @item
356 If there exists %#END after %#BEGIN,
357 @itemize
358 @item From %#BEGIN to %#END.
359 @end itemize
361 @item
362 If %#END does not exist after %#BEGIN,
363 @itemize
364 @item From %#BEGIN to the end of buffer.
365 @end itemize
366 @end enumerate
368 @item
369 If there does not exist %#BEGIN before point,
370 @itemize
371 @item Between point and mark(standard method of Emacs).
372 @end itemize
373 @end enumerate
375 It is useful to write @code{%#BEGIN} in the previous line of \begin and
376 @code{%#END} in the next line of \@code{end} when you try complex
377 environment such as `tabular' many times. It is also useful to put only
378 @code{%#BEGIN} alone at the middle of very long text. Do not forget to
379 erase @code{%#BEGIN} @code{%#END} pair.
381 @node Special Filtering Region, Lpr format, Static region for typesetting, %#notation
382 @section Special Filtering Region
383 A region like below will be passed to external filter command.
384 @example
385 %#BEGIN FILTER{foo.pdf}{dot -T %t -o %o}
386 \if0
387 ....blah blah blah...
388 ....blah blah blah...
389 ....blah blah blah...
390 \fi
391 %#END
392 @end example
394 In this case, typing @kbd{[prefix] t e} send three `blah' lines
395 to "dot -T pdf -o foo.pdf" as standard-input. It is useful to
396 have source of text-origin graphic generated by such tools as
397 graphviz or blockdiag, in La@TeX{} source. This special form of region
398 can be inserted via feeding @code{.dot} into environment completion by
399 @kbd{[prefix] t b}.
403 @node Lpr format, Controlling which command to invoke, Static region for typesetting, %#notation
404 @comment node-name, next, previous, up
405 @section Lpr format
406 @cindex lpr format
408 Lpr format is specified by three Lisp variables. Here are the
409 default values of them.
411 @table @code
412 @item (1)dviprint-command-format
413 @code{"dvi2ps %f %t %s | lpr"}
414 @item (2)dviprint-from-format
415 @code{"-f %b"}
416 @item (3)dviprint-to-format
417 @code{"-t %e"}
418 @end table
420 On YaTeX-lpr, @code{%s} in (1) is replaced by the file name of main
421 text, @code{%f} by contents of (2), %t by contents of (3). At these
422 replacements, @code{%b} in (2) is also replaced by the number of beginning
423 page, @code{%e} in (3) is replaced by the number of ending page. But
424 @code{%f} and @code{%t} are ignored when you omit the range of print-out
425 by @kbd{C-u [prefix] tl}.
427 If you want to change this lpr format temporarily, put a command
428 such as follows somewhere in the text:
430 @example
431 %#LPR dvi2ps %f %t %s | 4up -page 4 | texfix | lpr -Plp2
432 @end example
434 And if you want YaTeX not to ask you the range of printing
435 out, the next example may be helpful.
437 @example
438 %#LPR dvi2ps %s | lpr
439 @end example
441 @node Controlling which command to invoke, Editing %# notation, Lpr format, %#notation
442 @comment node-name, next, previous, up
443 @section Controlling which command to invoke
445 These %# notation below can control which command to invoke for
446 La@TeX{} related process.
448 @table @code
449 @item %#PREVIEW
450 @dots{} Command line for DVI viewing ([prefix] t p)
451 @item %#MAKEINDEX
452 @dots{} Command line for makeindex ([prefix] t i)
453 @item %#BIBTEX
454 @dots{} Command line for bibtex ([prefix] t b)
455 @item %#DVIPDF
456 @dots{} Command line for dvipdf(mx) ([prefix] t b)
457 @item %#LPR
458 @dots{} Command line for printing out([prefix] t l)
459 @item %#PDFVIEW
460 @dots{} Command line for PDF viewing
461 @item %#IMAGEDPI
462 @dots{} DPI value for converting to on-the-fly prewview image
463 @end table
465 If you want to invoke ``makeidx hogehoge'' to update index,
466 put the next line some upper place in the source, for example.
468 @example
469 %#MAKEINDEX makeidx hogehoge
470 @end example
473 @node Editing %# notation, , Controlling which command to invoke, %#notation
474 @comment node-name, next, previous, up
475 @section Editing %# notation
477 To edit @code{%#} notation described above, type
479 @table @kbd
480 @item [prefix] %
481 @dots{} editing %# notation menu
482 @end table
484 @noindent
485 and select one of the entry of the menu as follows.
487 @example
488 !)Edit-%#! B)EGIN-END-region L)Edit-%#LPR
489 @end example
491 @noindent
492 Type @kbd{!} to edit @code{%#!} entry, @code{b} to enclose the region with
493 @code{%#BEGIN} and @code{%#END}, and @code{l} to edit @code{%#LPR} entry.
494 When you type @kbd{b}, all @code{%#BEGIN} and @code{%#END} are
495 automatically erased.
497 @node Completion, Local dictionaries, %#notation, Top
498 @comment node-name, next, previous, up
499 @chapter Completion
500 @cindex completion
502 YaTeX makes it easy to input the La@TeX{} commands. There are several
503 kinds of completion type, begin-type, section-type, large-type, etc...
505 @menu
506 * Begin-type completion::
507 * Section-type completion::
508 * Label Generation::
509 * Large-type completion::
510 * Maketitle-type completion::
511 * Arbitrary completion::
512 * End completion::
513 * Accent completion::
514 * Image completion::
515 * Greek letters completion::
516 * Inserting parentheses::
517 @end menu
519 @node Begin-type completion, Section-type completion, Completion, Completion
520 @comment node-name, next, previous, up
521 @section Begin-type completion
522 @cindex begin-type completion
523 @cindex environment
524 @cindex prefix b
526 "Begin-type completion" completes commands of @code{\begin@{env@}} ...
527 @code{\end@{env@}}. All of the begin-type completions begin with this key
528 sequence.
530 @table @kbd
531 @item [prefix] b
532 @dots{} start begin-type completion
533 @end table
535 @noindent
536 An additional key stroke immediately completes a frequently used
537 La@TeX{} @code{\begin@{@}}...@code{\@code{end}@{@}} environment.
539 @table @kbd
540 @item [prefix] b c
541 @dots{} @code{\begin@{center@}...\end@{center@}}
542 @item [prefix] b d
543 @dots{} @code{\begin@{document@}...\end@{document@}}
544 @item [prefix] b D
545 @dots{} @code{\begin@{description@}...\end@{description@}}
546 @item [prefix] b e
547 @dots{} @code{\begin@{enumerate@}...\end@{enumerate@}}
548 @item [prefix] b E
549 @dots{} @code{\begin@{equation@}...\end@{equation@}}
550 @item [prefix] b i
551 @dots{} @code{\begin@{itemize@}...\end@{itemize@}}
552 @item [prefix] b l
553 @dots{} @code{\begin@{flushleft@}...\end@{flushleft@}}
554 @item [prefix] b m
555 @dots{} @code{\begin@{minipage@}...\end@{minipage@}}
556 @item [prefix] b t
557 @dots{} @code{\begin@{tabbing@}...\end@{tabbing@}}
558 @item [prefix] b T
559 @dots{} @code{\begin@{tabular@}...\end@{tabular@}}
560 @item [prefix] b^T
561 @dots{} @code{\begin@{table@}...\end@{table@}}
562 @item [prefix] b p
563 @dots{} @code{\begin@{picture@}...\end@{picture@}}
564 @item [prefix] b q
565 @dots{} @code{\begin@{quote@}...\end@{quote@}}
566 @item [prefix] b Q
567 @dots{} @code{\begin@{quotation@}...\end@{quotation@}}
568 @item [prefix] b r
569 @dots{} @code{\begin@{flushright@}...\end@{flushright@}}
570 @item [prefix] b v
571 @dots{} @code{\begin@{verbatim@}...\end@{verbatim@}}
572 @item [prefix] b V
573 @dots{} @code{\begin@{verse@}...\end@{verse@}}
574 @end table
576 Any other La@TeX{} environments are made by completing-read of the
577 Emacs function.
579 @table @kbd
580 @item [prefix] b SPACE
581 @dots{} begin-type completion
582 @end table
584 @noindent
585 The next message will show up in the minibuffer
587 @example
588 Begin environment(default document):
589 @end example
591 @noindent
592 by typing @kbd{[prefix] b}. Put the wishing environment with completion
593 in the minibuffer, and @code{\begin@{env@}}...\@code{\end@{env@}} will be
594 inserted in the La@TeX{} source text. If the environment you want to put
595 does not exist in the YaTeX completion table, it will be registered in the
596 user completion table. YaTeX automatically saves the user completion
597 table in the user dictionary file at exiting of emacs.
599 At the completion of certain environments, the expected initial entry will
600 automatically inserted such as @code{\item} for @code{itemize}
601 environment. If you don't want the entry, it can be removed by undoing.
603 If you want to enclose some paragraphs which have already been written
604 into environment, invoke the begin-type completion right after region marking.
605 @cindex enclose region into environment
607 If you set @code{transient-mark-mode} to @code{nil} in your
608 @file{~/.emacs}, typing @kbd{C-space} (@code{set-mark-command}) twice
609 turns @code{transient-mark-mode} on temporarily. Then, type call
610 begin-type completion to enclose text into a environment.
613 @node Section-type completion, Label Generation, Begin-type completion, Completion
614 @comment node-name, next, previous, up
615 @section Section-type completion
616 @cindex section-type completion
617 @cindex prefix s
619 "Section-type completion" completes section-type commands which take an
620 argument or more such as @code{\section@{foo@}}. To invoke section-type
621 completion, type
623 @table @kbd
624 @item [prefix] s
625 @dots{} section-type completion
626 @end table
628 @noindent
629 then the prompt
631 @example
632 (C-v for view) \???@{@} (default documentclass):
633 @end example
635 @noindent
636 will show up in the minibuffer. Section-type La@TeX{} commands are
637 completed by space key, and the default value is selected when you
638 type nothing in the minibuffer.
640 Next,
642 @example
643 \section@{???@}:
644 @end example
646 @noindent
647 prompts you the argument of section-type La@TeX{} command. For
648 example, the following inputs
650 @example
651 \???@{@} (default documentclass): section
652 \section@{???@}: Hello world.
653 @end example
655 @noindent
656 will insert the string
658 @example
659 \section@{Hello world.@}
660 @end example
662 in your La@TeX{} source. When you neglect argument such as
664 @example
665 (C-v for view) \???@{@} (default section): vspace*
666 \vspace*@{???@}:
667 @end example
669 YaTeX puts
671 @example
672 \vspace*@{@}
673 @end example
675 @noindent
676 and move the cursor in the braces.
678 In La@TeX{} command, there are commands which take more than one
679 arguments such as @code{\addtolength@{\topmargin@}@{8mm@}}. To complete these
680 commands, invoke section-type completion with universal argument as,
681 @cindex number of argument
683 @example
684 C-u 2 [prefix] s (or ESC 2 [prefix] s)
685 @end example
687 @noindent
688 and make answers in minibuffer like this.
690 @example
691 (C-v for view) \???@{@} (default vspace*): addtolength
692 \addtolength@{???@}: \topmargin
693 Argument 2: 8mm
694 @end example
696 @code{\addtolength} and the first argument @code{\topmargin} can be typed
697 easily by completing read. Since YaTeX also learns the number of
698 arguments of section-type command and will ask that many arguments in
699 future completion, you had better tell the number of arguments to YaTeX at
700 the first completion of the new word. But you can change the number of
701 arguments by calling the completion with different universal argument
702 again.
705 Invoking section-type completion with @code{[Prefix] S} (Capital `S')
706 includes the region as the first argument of section-type command.
708 The section/large/maketitle type completion can work at the
709 prompt for the argument of other section-type completion.
710 Nested La@TeX{} commands are efficiently read with the recursive
711 completion by typing YaTeX's completion key sequence in the
712 minibuffer.
714 @menu
715 * view-sectioning::
716 @end menu
718 @node view-sectioning, , Section-type completion, Section-type completion
719 @comment node-name, next, previous, up
720 @subsection view-sectioning
721 @cindex view sectioning
722 @cindex outline
724 In the minibuffer at the prompt of section-type command completion,
725 typing @kbd{C-v} shows a list of sectioning commands in source text(The
726 line with @code{<<--} mark is the nearest sectioning command). Then,
727 default sectioning command appears in the minibuffer. You can go up/down
728 sectioning command by typing @kbd{C-p}/@kbd{C-n}, can scrolls up/down the
729 listing buffer by @kbd{C-v}/@kbd{M-v}, and can hide sectioning commands
730 under certain level by 0 through 6. Type @kbd{?} in the minibuffer of
731 sectioning prompt for more information.
733 You can generate this listing buffer (@code{*Sectioning Lines*} buffer)
734 by typing
735 @table @kbd
736 @item M-x YaTeX-section-overview
737 @dots{} Generate *Sectioning Lines* buffer
738 @end table
739 @cindex{Generate the listing of sectioning units}
740 from the LaTeX source buffer. In this listing buffer, typing @kbd{u} on
741 the sectioning command shifts up the corresponding sectioning command in
742 source text and @kbd{d} shifts down. After marking lines in the listing
743 buffer, typing @kbd{U} shifts up all sectioning commands in the region,
744 and @kbd{U} shifts down. Here are all the key bindings of
745 @code{*Sectioning Lines*} buffer.
747 @table @kbd
748 @item SPC
749 @dots{} Jump to corresponding source line
750 @item .
751 @dots{} Display corresponding source line
752 @item u
753 @dots{} Shift up a sectioning line
754 @item d
755 @dots{} Shift down a sectioning line
756 @item U
757 @dots{} Shift up sectioning lines in region
758 @item D
759 @dots{} Shift down sectioning lines in region
760 @item 0@dots{}6
761 @dots{} Hide sectioning commands whose level is lower than n
762 @end table
764 @node Label Generation, Large-type completion, Section-type completion, Completion
765 @section Label Generation
766 @comment label generation
767 @cindex label generation
768 @cindex ref label cite
770 When you want to type-in references of @code{\ref} or @code{\cite},
771 all you have to do is type @kbd{[prefix] s ref} without adding labels
772 beforehand. You will see possible La@TeX{}-counters in the next window
773 even if some counter does not have @code{\label}. Selecting the counter
774 will automatically set the label to that counter.
776 All possible counter list in the buffer tends to be large.
777 You can reduce the number of list by filtering type of counters by
778 key-commands as follows.
779 @table @kbd
780 @item M-a
781 @dots{} Show all(disable filtering)
782 @item M-c
783 @dots{} Captions only
784 @item M-e
785 @dots{} equations (with counters) only
786 @item M-i
787 @dots{} numbers items only
788 @item M-s
789 @dots{} sections only
790 @item M-m
791 @dots{} other counters only
792 @end table
795 @node Large-type completion, Maketitle-type completion, Label Generation, Completion
796 @comment node-name, next, previous, up
797 @section Large-type completion
799 "Large-type completion" inputs the font or size changing
800 descriptions such as @code{@{\large @}}. When you type
802 @table @kbd
803 @item [prefix] l
804 @dots{} large-type completion
805 @end table
807 @noindent
808 the message in the minibuffer
810 @example
811 @{\??? @} (default large):
812 @end example
814 prompts prompts you large-type command with completing-read. There are
815 TeX commands to change fonts or sizes, @code{it}, @code{huge} and so on,
816 in the completion table.
818 Region-based completion is also invoked by calling completion
819 after region activated.
821 @node Maketitle-type completion, Arbitrary completion, Large-type completion, Completion
822 @comment node-name, next, previous, up
823 @section Maketitle-type completion
824 @cindex maketitle-type completion
826 We call it "maketitle-type completion" which completes commands such as
827 @code{\maketitle}. Take notice that maketitle-type commands take no
828 arguments. Then, typing
830 @table @kbd
831 @item [prefix] m
832 @dots{} maketitle-type completion
833 @end table
835 @noindent
836 begins maketitle-completion. Above mentioned method is true for
837 maketitle-completion, and there are La@TeX{} commands with no
838 arguments in completion table.
840 @node Arbitrary completion, End completion, Maketitle-type completion, Completion
841 @comment node-name, next, previous, up
842 @section Arbitrary completion
843 @cindex arbitrary completion
845 @noindent
846 You can complete certain La@TeX{} command anywhere without typical
847 completing method as described, by typing
849 @table @kbd
850 @item [prefix] SPC
851 @dots{} arbitrary completion
852 @end table
854 @noindent
855 after the initial string of La@TeX{} command that is preceded by @code{\}.
857 @node End completion, Accent completion, Arbitrary completion, Completion
858 @comment node-name, next, previous, up
859 @section End completion
860 @cindex end completion
862 @noindent
863 YaTeX automatically detects the opened environment and close it with
864 \@code{\end@{environment@}}. Though proficient YaTeX users never fail to
865 make environment with begin-type completion, some may begin an environment
866 manually. In that case, type
868 @table @kbd
869 @item [prefix] e
870 @dots{} @code{end} completion
871 @end table
873 @noindent
874 at the end of the opened environment.
876 @node Accent completion, Image completion, End completion, Completion
877 @comment node-name, next, previous, up
878 @section Accent completion
879 @cindex accent completion
881 When you want to write the European accent marks(like @code{\`@{o@}}),
883 @table @kbd
884 @item [prefix] a
885 @dots{} accent completion
886 @end table
888 @noindent
889 shows the menu
891 @example
892 1:` 2:' 3:^ 4:" 5:~ 6:= 7:. u v H t c d b
893 @end example
895 @noindent
896 in the minibuffer. Chose one character or corresponding numeric,
897 and you will see
899 @example
900 \`@{@}
901 @end example
903 @noindent
904 in the editing buffer with the cursor positioned in braces. Type
905 one more character `o' for example, then
907 @example
908 \`@{o@}
909 @end example
911 @noindent
912 will be completed, and the cursor gets out from braces.
914 @node Image completion, Greek letters completion, Accent completion, Completion
915 @comment node-name, next, previous, up
916 @section Image completion of mathematical sign
917 @cindex image completion
918 @cindex math-mode
919 @cindex sigma
920 @cindex leftarrow
921 @cindex ;
923 Arrow marks, sigma mark and those signs mainly used in the
924 TeX's math environment are completed by key sequences which
925 imitate the corresponding symbols graphically. This completion
926 only works in the math environment. YaTeX automatically detects
927 whether the cursor located in math environment or not, and
928 change the behavior of key strokes @kbd{;} and @kbd{:}.
930 By the way, we often express the leftarrow mark by `<-' for example.
931 Considering such image, you can write @code{\leftarrow} by typing @kbd{<-}
932 after @kbd{;} (semicolon) as a prefix. In the same way,
933 @code{\longleftarrow} (@code{<--}) is completed by typing @kbd{;<--},
934 infinity mark which is imitated by @code{oo} is completed by typing
935 @kbd{;oo}.
937 Here are the sample operations in YaTeX math-mode.
939 @example
940 INPUT Completed La@TeX{} commands
941 ; < - @code{\leftarrow}
942 ; < - - @code{\longleftarrow}
943 ; < - - > @code{\longleftrightarrow}
944 ; o @code{\circ}
945 ; o o @code{\infty}
946 @end example
948 In any case, you can quit from image completion and can move
949 to the next editing operation if the La@TeX{} command you want is
950 shown in the buffer.
952 @code{;} itself in math-environment is inserted by @kbd{;;}. Typing
953 @kbd{TAB} in the midst of image completion shows all of the La@TeX{}
954 commands that start with the same name as string you previously typed in.
955 In this menu buffer, press @kbd{RET} after moving the cursor (by @kbd{n},
956 @kbd{p}, @kbd{b}, @kbd{f}) to insert the La@TeX{} command.
958 To know all of the completion table, type @kbd{TAB} just after @kbd{;}.
959 And here is the sample menu by @kbd{TAB} after @kbd{;<}.
961 @example
962 KEY LaTeX sequence sign
963 < \leq <
964 ~
965 << \ll <<
966 <- \leftarrow <-
967 <= \Leftarrow <=
968 @end example
970 You can define your favorite key-vs-sequence completion table in the
971 Emacs-Lisp variable @code{YaTeX-math-sign-alist-private}. See also
972 @file{yatexmth.el} for the information of the structure of this variable.
974 @node Greek letters completion, Inserting parentheses, Image completion, Completion
975 @comment node-name, next, previous, up
976 @section Greek letters completion
977 @cindex Greek letters completion
978 @cindex :
980 Math-mode of YaTeX provides another image completion, Greek letters
981 completion in the same method. After prefix @kbd{:}, typing @kbd{a} makes
982 @code{\alpha}, @kbd{b} makes @code{\beta} and @kbd{g} makes @code{\gamma}
983 and so on. First, type @kbd{:TAB} to know all the correspondence of
984 alphabets vs. Greek letters.
986 If you will find @kbd{;} or @kbd{:} doesn't work in correct position of
987 math environment, it may be a bug of YaTeX. Please send me a bug report
988 with the configuration of your text, and avoid it temporarily by typing
989 @kbd{;} or @kbd{:} after universal-argument(@kbd{C-u}) which forces
990 @kbd{;} and @kbd{:} to work as math-prefix.
992 @node Inserting parentheses, , Greek letters completion, Completion
993 @section Inserting parentheses
995 Typing opening parenthesis, one of @code{(}, @code{@{ and @code{[}},
996 automatically inserts the closing one. If a opening bracket is typed
997 after @code{\}, @code{\]} is automatically inserted with computed
998 indentation. If you stop automatic insertion, type @kbd{C-q} before
999 opening parenthesis.
1001 @node Local dictionaries, Commenting out, Completion, Top
1002 @comment node-name, next, previous, up
1003 @chapter Local dictionaries
1004 @cindex local dictionaries
1005 @cindex nervous users
1007 Tables for completion consist of three dictionaries; `standard
1008 dictionary' built in @file{yatex.el}, `user dictionary' for your common
1009 private commands, and `local dictionary' that is effective in a certain
1010 directory.
1012 When you input the command unknown to YaTeX at a completion in the
1013 minibuffer, YaTeX asks you with the following prompt;
1015 @example
1016 `foo' is not in table. Register into: U)serDic L)ocalDic N)one D)iscard
1017 @end example
1019 @noindent
1020 In this menu, typing @kbd{u} updates your `user dictionary', @kbd{l}
1021 updates your local dictionary, @kbd{n} updates only on-memory dictionary
1022 which go through only current Emacs session, and @kbd{d} updates no
1023 dictionary and throws the new word away.
1025 If you find this switching feature meaningless and bothersome, put the
1026 next expression into your @file{~/.emacs}
1028 @lisp
1029 (setq YaTeX-nervous nil)
1030 @end lisp
1032 @node Commenting out, Cursor jump, Local dictionaries, Top
1033 @comment node-name, next, previous, up
1034 @chapter Commenting out
1035 @cindex commenting out
1036 @cindex prefix >
1037 @cindex prefix <
1038 @cindex prefix ,
1039 @cindex prefix .
1041 You may want to comment out some region.
1043 @table @kbd
1044 @item [prefix] >
1045 @dots{} comment out region by %
1046 @item [prefix] <
1047 @dots{} uncomment region
1048 @end table
1050 @noindent
1051 cause an operation to the region between point and mark.
1053 @table @kbd
1054 @item [prefix] .
1055 @dots{} comment out current paragraph
1056 @item [prefix] ,
1057 @dots{} uncomment current paragraph
1058 @end table
1060 @noindent
1061 comments or uncomments the paragraph where the cursor belongs.
1062 This `paragraph' means the region marked by the function
1063 mark-paragraph, bound to @kbd{ESC h} by default. It is NOT
1064 predictable what will happen when you continuously comment out
1065 some paragraph many times.
1067 You can also comment out an environment between @code{\begin} and
1068 @code{\end}, or a @code{\begin}-\@code{\end} pair themselves, by making the
1069 following key strokes on the line where @code{\begin@{@}} or
1070 @code{\end@{@}} exists.
1072 @table @kbd
1073 @item [prefix] >
1074 @dots{} comment out from \begin to \@code{end}
1075 @item [prefix] <
1076 @dots{} uncomment from \begin to \@code{end}
1077 @end table
1079 @noindent
1080 comment whole the contents of environment. Moreover,
1082 @table @kbd
1083 @item [prefix] .
1084 @dots{} comment out \begin and \@code{end}
1085 @item [prefix] ,
1086 @dots{} uncomment \begin and \@code{end}
1087 @end table
1089 @noindent
1090 (un)comments out only environment declaration: @code{\begin@{@}} and
1091 @code{\end@{@}}. NOTE that even if you intend to comment out some region,
1092 invoking @kbd{[prefix] >} on the @code{\begin},@code{\end} line decides to
1093 work in `commenting out from @code{\begin} to @code{\end}' mode.
1096 @node Cursor jump, Changing and Deleting, Commenting out, Top
1097 @comment node-name, next, previous, up
1098 @chapter Cursor jump
1099 @cindex cursor jump
1100 @cindex prefix g
1103 @menu
1104 * Jump to corresponding object::
1105 * Invoking image processor::
1106 * Jump to main file::
1107 * Jumping around the environment::
1108 * Jumping to last completion position::
1109 @end menu
1111 @node Jump to corresponding object, Invoking image processor, Cursor jump, Cursor jump
1112 @comment node-name, next, previous, up
1113 @section Jump to corresponding object
1115 Typing
1117 @table @kbd
1118 @item [prefix] g
1119 @dots{} go to corresponding object
1120 @end table
1122 @noindent
1123 in a certain place move the cursor to the place corresponding to the
1124 La@TeX{} command of last place. YaTeX recognize the followings as pairs
1125 that have relation each other.
1127 @itemize @bullet
1128 @item @code{\begin@{@}} <-> @code{\end@{@}}
1129 @item @code{%#BEGIN} <-> @code{%#END}
1130 @item On the image-including line -> corresponding viewer or drawing tool
1131 @item @code{\label@{@}} <-> @code{\ref@{@}}
1132 @item @code{\include(\input)} -> included file
1133 @item @code{\bibitem@{@}} <-> @code{\cite@{@}}
1134 @end itemize
1136 On a @code{\begin},@code{\end} line, typing @kbd{[prefix] g} moves the
1137 cursor to the corresponding @code{\end},@code{\begin} line, if its partner
1138 really exists. The behavior on the line @code{%#BEGIN} and @code{%#END}
1139 are the same. Note that if the correspondent of @code{label/ref} or
1140 @code{cite/bibitem} exists in another file, that file have to be opened to
1141 make a round trip between references by @kbd{[prefix] g}.
1143 If you type @code{[prefix] g} on the line of @code{\include@{chap1@}},
1144 typically in the main text, YaTeX switches buffer to @file{chap1.tex}.
1146 @table @kbd
1147 @item [prefix] 4 g
1148 @dots{} go to corresponding object in other window
1149 @end table
1151 @noindent
1152 do the same job as @kbd{[prefix] g} except it's done in other window.
1153 Note that this function doesn't work on @code{begin/end},
1154 @code{%#BEGIN/%#END} pairs because it is meaningless.
1156 @node Invoking image processor, Jump to main file, Jump to corresponding object, Cursor jump
1157 @comment node-name, next, previous, up
1158 @section Invoking image processor
1159 @cindex{Drawing tool invocation}
1161 `image-including line' described above means such lines as
1162 @code{\epsfile@{file=foo.ps@}}. If you type @kbd{[prefix] g} on that
1163 line, YaTeX automatically searches source of `foo.ps' and invokes image
1164 viewer or drawing tool correspoinding to it. For example; if you draw
1165 an image foo.obj with Tgif and enclose its product named foo.eps by
1166 @code{\epsfile} command. Typing @kbd{[prefix] g} on @code{\epsfile} line
1167 make YaTeX invoke @code{tgif foo.obj}. How a processor is choosen is as
1168 follows.
1170 @enumerate
1171 @item
1172 If there is an expression matching with one of the pattern
1173 defined in @code{YaTeX-processed-file-regexp-alist}, extract file name
1174 from regexp group surrounded by \\(\\). (Which group corresponds is
1175 written in the cdr part of each list.) If no matches were found, do
1176 nothing.
1177 @item
1178 If there is a pattern as `%PROCESSOR' which is defined in the variable
1179 @code{YaTeX-file-processor-alist}, call that processor giving the
1180 file name with corresponding extension.
1181 @item
1182 If not, check the existence of each file which is supplied the
1183 extension in the cdr part of each list of
1184 @code{YaTeX-file-processor-alist}. If any, call the corresponding
1185 image viewer or drawing tool.
1186 @end enumerate
1188 @node Jump to main file, Jumping around the environment, Invoking image processor, Cursor jump
1189 @comment node-name, next, previous, up
1190 @section Jump to main file
1192 Typing
1194 @table @kbd
1195 @item [prefix] ^
1196 @dots{} visit main file
1197 @item [prefix] 4^
1198 @dots{} visit main file in other buffer
1199 @end table
1200 @cindex prefix ^
1201 @cindex prefix 4 ^
1203 in a sub text switch the buffer to the main text specified by
1204 @code{%#!} notation.
1206 @node Jumping around the environment, Jumping to last completion position, Jump to main file, Cursor jump
1207 @comment node-name, next, previous, up
1208 @section Jumping around the environment
1210 And these are the functions which work on the current La@TeX{}
1211 environment:
1213 @table @kbd
1214 @item M-C-a
1215 @dots{} beginning of environment
1216 @item M-C-e
1217 @dots{} @code{end} of environment
1218 @item M-C-@@
1219 @dots{} mark environment
1220 @end table
1221 @cindex M-C-a
1222 @cindex M-C-e
1223 @cindex M-C-@@
1225 @node Jumping to last completion position, , Jumping around the environment, Cursor jump
1226 @comment node-name, next, previous, up
1227 @section Jumping to last completion position
1229 YaTeX always memorize the position of completion into register @code{3}.
1230 So every time you make a trip to any other part of text other than you are
1231 writing, you can return to the editing paragraph by calling
1232 register-to-point with argument YaTeX-current-position-register, which is
1233 achieved by typing @kbd{C-x j 3}(by default).
1235 @node Changing and Deleting, Filling, Cursor jump, Top
1236 @comment node-name, next, previous, up
1237 @chapter Changing and Deleting
1239 These functions are for change or deletion of La@TeX{} commands
1240 already entered.
1242 @table @kbd
1243 @item [prefix] c
1244 @dots{} change La@TeX{} command
1245 @item [prefix] k
1246 @dots{} kill La@TeX{} command
1247 @end table
1248 @cindex prefix c
1249 @cindex prefix k
1251 @menu
1252 * Changing LaTeX commands::
1253 * Killing LaTeX commands::
1254 @end menu
1256 @node Changing LaTeX commands, Killing LaTeX commands, Changing and Deleting, Changing and Deleting
1257 @comment node-name, next, previous, up
1258 @section Changing La@TeX{} commands
1260 @kbd{[prefix] c} can change the various (La)@TeX{} commands. This can
1261 change the followings.
1262 @itemize @bullet
1263 @item Environment names
1264 @item Section-type commands
1265 @item Argument of section-type commands
1266 @item Optional parameters (enclosed by []) of section-type commands
1267 @item Font/size designators
1268 @item Math-mode's maketitle-type commands that can be inputted with
1269 image completion
1270 @end itemize
1272 Typing @kbd{[prefix] c} on one of above objects you want to change
1273 brings a suitable reading function sometimes with completion.
1274 Note: If you want to change the argument of section-type command that
1275 contains other La@TeX{} commands, type @kbd{[prefix] c} either of
1276 surrounding braces of the argument in order to make YaTeX ignore the
1277 internal La@TeX{} sequences as an object of changing. Anyway, it is
1278 very difficult to know which argument position the cursor belongs because
1279 the La@TeX{} commands can be nested and braces can freely emerge. So keep
1280 it mind to put the cursor on a brace when you are thinking of changing a
1281 complicated argument.
1283 @node Killing LaTeX commands, , Changing LaTeX commands, Changing and Deleting
1284 @comment node-name, next, previous, up
1285 @section Killing La@TeX{} commands
1286 @cindex Killing La@TeX{} commands
1288 @kbd{[prefix] k} kills the La@TeX{} commands sometimes with their
1289 arguments. Following table illustrates the correspondence of the invoking
1290 position and what is killed.
1292 @example
1293 [Invoking position] [action]
1294 \begin, \end line kill \begin,\end pairs
1295 %#BEGIN, %#END line kill %#BEGIN,%#END pairs
1296 on a Section-type command kill section-type command
1297 on a parenthesis kill parentheses
1298 @end example
1300 Note that when killing @code{\begin, \end} or @code{%#BEGIN, %#END} pair,
1301 the lines @code{\begin, \end} or @code{%#BEGIN, %#END} exist will be
1302 killed entirely. So take care not to create any line that contains more
1303 than one @code{\begin} or so.
1305 While all operations above are to kill `containers' which surround some
1306 text, universal argument (@kbd{C-u}) for these commands kills not only
1307 `containers' but also `contents' of them. See below as a sample.
1309 @example
1310 Original text: [prefix] k C-u [prefix] k
1311 Main \footnote@{note@} here. Main note here. Main here.
1312 ~(cursor)
1313 @end example
1315 @node Filling, Updation of includeonly, Changing and Deleting, Top
1316 @comment node-name, next, previous, up
1317 @chapter Filling
1318 @cindex filling
1320 @section Filling an item
1321 @cindex filling an item
1322 @cindex prefix i
1324 To fill a term (descriptive sentences) of @code{\item}, type
1326 @c @table @kbd
1327 @c @item [prefix] i
1328 @c @dots{} fill item
1329 @c @end table
1330 @table @kbd
1331 @item M-q
1332 @dots{} fill item
1333 @end table
1335 @noindent
1336 on that item.
1338 YaTeX uses the value of the variable @code{YaTeX-item-regexp} as the
1339 regular expression to search item header in itemize environment.
1340 If you make a newcommand to itemize terms(e.g. @code{\underlineitem}), put
1342 @lisp
1343 (setq YaTeX-item-regexp
1344 "\\(\\\\\\(sub\\)*item\\)\\|\\(\\\\underlineitem\\)")
1345 @end lisp
1346 @cindex YaTeX-item-regexp
1348 in your @file{~/.emacs}. If you are not familiar with regular expression
1349 for Emacs-Lisp, name a newcommand for `itemize' beginning with
1350 @code{\item} such as @code{\itembf}, not @code{\bfitem}.
1352 This function reformats the @code{\item} into `hang-indented' style.
1353 For example:
1355 @example
1356 itemize, enumerate environment:
1358 >\item[foo] `foo' is the typical word for describing an
1359 > arbitrarily written....
1360 description environment:
1361 > \item[bar] When the word `for' is used as an arbitrarily
1362 > word, `bar' is bound to follow it.
1363 @end example
1365 Note that the indent depth of an @code{\item} word and its descriptive
1366 paragraph are the same in latter case. If you want to use different
1367 depth, invoke fill-paragraph at the beginning of non-whitespace
1368 character(see below).
1370 @section Filling paragraph
1371 @cindex Filling paragraph
1372 @cindex M-q
1374 Fill-paragraph is little bit adapted for La@TeX{} sources. It retains from
1375 filling in certain environments where formatting leads to a disaster such
1376 as verbatim, tabular, or so. And it protects @code{\verb} expressions
1377 from being folded (The variable @code{YaTeX-verb-regexp} controls this).
1378 Besides, putting cursor on the first occurrence of non-whitespace
1379 character on a line changes the fill-prefix temporarily to the depth of
1380 the line.
1382 @node Updation of includeonly, What column, Filling, Top
1383 @comment node-name, next, previous, up
1384 @chapter Updation of @code{\includeonly}
1385 @cindex includeonly
1387 When you edit splitting source texts, the notation
1389 @example
1390 \includeonly@{CurrentEditingFileName@}
1391 @end example
1393 @noindent
1394 in the main file reduces the time of typesetting. If you want
1395 to hack other file a little however, you have to rewrite it to
1397 @example
1398 \includeonly@{OtherFileNameYouWantToFix@}
1399 @end example
1401 @noindent
1402 in the main file. YaTeX automatically detects that the current
1403 edited text is not in includeonly list and prompts you
1405 @example
1406 A)dd R)eplace %)comment?
1407 @end example
1409 in the minibuffer. Type @kbd{a} if you want to add the current file name
1410 to @code{\includeonly} list, @kbd{r} to replace \@code{includeonly} list
1411 with the current file, and type @kbd{%} to comment out the
1412 @code{\includeonly} line.
1414 @node What column, Intelligent newline, Updation of includeonly, Top
1415 @comment node-name, next, previous, up
1416 @chapter What column?
1417 @cindex what column
1418 @cindex complex tabular
1419 @cindex prefix &
1421 We are often get tired of finding the corresponding column in
1422 large tabulars. For example,
1424 @example
1425 \begin@{tabular@}@{|c|c|c|c|c|c|c|c|@}\hline
1426 Name&Position&Post No.&Addr.&Phone No.&FAX No.&
1427 Home Addr.&Home Phone\\ \hline
1428 Thunder Bird & 6 & 223 & LA & xxx-yyy &
1429 zzz-www & Japan & 9876-54321 \\
1430 & 2 & \multicolumn@{2@}@{c|@}@{Unknown@}
1431 &&&(???)
1432 \\ \hline
1433 \end@{tabular@}
1434 @end example
1436 Suppose you have the cursor located at @code{(???)} mark, can you tell
1437 which column it is belonging at once? Maybe no. In such case,
1438 type
1440 @table @kbd
1441 @item [prefix] &
1442 @dots{} What column
1443 @end table
1445 @noindent
1446 in that position. YaTeX tells you the column header of the
1447 current field. Since YaTeX assumes the first line of tabular
1448 environment as a row of column headers, you can create a row of
1449 virtual column headers by putting them in the first line and
1450 commenting that line with @code{%}.
1452 @node Intelligent newline, Usepackage checker, What column, Top
1453 @comment node-name, next, previous, up
1454 @chapter Intelligent newline
1455 @cindex Intelligent newline
1456 @cindex ESC RET
1457 @cindex M-C-m
1459 At the end of begin-type completion of tabular[*], array, itemize,
1460 enumerate or tabbing environment, or typing
1462 @table @kbd
1463 @item ESC RET
1464 @dots{} Intelligent newline
1465 @end table
1467 @noindent
1468 in these environments inserts the contents corresponding to the current
1469 environment in the next line. (At the begin-type completion, this
1470 contents can be removed by `undo'.) In @code{tabular} environment, for
1471 example, @kbd{ESC RET} inserts the certain number of @code{&} and trailing
1472 @code{\\}, and @code{\hline} if other @code{\hline} is found in backward.
1473 Here are the list of contents vs. environments.
1475 @itemize
1476 @item @code{tabular}, @code{tabular*}, @code{array}
1478 Corresponding number of @code{&} and @code{\\}.
1479 And @code{\hline} if needed.
1481 @item @code{tabbing}
1483 The same number of @code{\>} as @code{\=} in the first line.
1485 @item @code{itemize}, @code{enumerate}, @code{description}, @code{list}
1487 @code{\item} or @code{item[]}.
1488 @end itemize
1490 Note that since this function works seeing the contents of the first
1491 line, please call this after the second line if possible.
1493 If you want to apply these trick to other environments, @code{foo}
1494 environment for example, define the function named
1495 @code{YaTeX-intelligent-newline-foo} to insert corresponding contents.
1496 That function will be called at the beginning of the next line after the
1497 newline is inserted to the current line. Since the function
1498 @code{YaTeX-indent-line} is designed to indent the current line properly,
1499 calling this function before your code to insert certain contents must be
1500 useful. See the definition of the function
1501 @code{YaTeX-intelligent-newline-itemize} as an example.
1503 @node Usepackage checker, Online help, Intelligent newline, Top
1504 @comment node-name, next, previous, up
1505 @chapter Usepackage checker
1506 @cindex usepackage
1508 When you input begint-type, section-type, maketitle-type macros with
1509 completion, and it requires some LaTeX2e package, YaTeX examines
1510 the existence of correct @code{\usepackage}. If not, YaTeX inserts
1511 the @code{\usepackage@{@}} declaration corresponding to input macro.
1513 To activate the package completion for your favarite package,
1514 set the variable @code{YaTeX-package-alist-private} correctly.
1515 Please refere the value of @code{YaTeX-package-alist-default} as an
1516 example.
1518 @node Online help, Browsing file hierarchy, Usepackage checker, Top
1519 @comment node-name, next, previous, up
1520 @chapter Online help
1521 @cindex online help
1522 @cindex prefix ?
1523 @cindex prefix /
1524 @cindex apropos
1525 @cindex keyword search
1527 YaTeX provides you the online help with popular La@TeX{} commands.
1529 Here are the key strokes for the online help.
1531 @table @kbd
1532 @item [prefix] ?
1533 @dots{} Online help
1534 @item [prefix] /
1535 @dots{} Online apropos
1536 @end table
1538 @section Online help
1540 `Online help' shows the documentation for the popular La@TeX{}
1541 commands(defaults to the commands on the cursor) in the next buffer.
1542 There are two help file, `global help' and `private help'. The former
1543 file contains the descriptions on the standard La@TeX{} command and is
1544 specified its name by variable @code{YaTeX-help-file}. Usually, the
1545 global help file should be located in public space (@code{$EMACSEXECPATH}
1546 by default) and should be world writable so that anyone can update it to
1547 enrich its contents. The latter file contains descriptions on
1548 non-standard or personal command definitions and is specified by
1549 @code{YaTeX-help-file-private}. This file should be put into private
1550 directory.
1552 @section Online apropos
1554 `Online apropos' is an equivalent of GNU Emacs's apropos. It
1555 shows all the documentations that contains the keyword entered by
1556 the user.
1558 @section When no descriptions are found...
1560 If there is no description on a command in help files, YaTeX
1561 requires you to write a description on that command. If you are
1562 willing to do, determine which help file to add and write the
1563 description on it referring your manual of (La)TeX. Please send
1564 me your additional descriptions if you describe the help on some
1565 standard commands. I might want to include it in the next
1566 distribution.
1568 @node Browsing file hierarchy, Cooperation with other packages, Online help, Top
1569 @comment node-name, next, previous, up
1570 @chapter Browsing file hierarchy
1571 @cindex hierarchy
1572 @cindex browsing
1574 When you are editing multi-file source, typing
1576 @table @kbd
1577 @item [prefix] d
1578 @dots{} browse file hierarchy
1579 @end table
1581 @noindent
1582 asks you the parent-most file (which may be defaulted) and displays the
1583 documentation hierarchy in the next window. In this buffer, the following
1584 commands are available.
1586 @table @kbd
1587 @item n
1588 @dots{} move to the next line and show its contents
1589 @item p
1590 @dots{} move to the previous line and show its contents
1591 @item N
1592 @dots{} move to the next file in the same inclusion level
1593 @item P
1594 @dots{} move to the previous file in the same inclusion level
1595 @item j
1596 @dots{} move to the next line
1597 @item k
1598 @dots{} move to the previous line
1599 @item u
1600 @dots{} move to the parent file
1601 @item .
1602 @dots{} show the current files contents in the next window
1603 @item SPC
1604 @dots{} scroll up the current file window
1605 @item DEL, b
1606 @dots{} scroll down the current file window
1607 @item <
1608 @dots{} show the beginning of the current file
1609 @item >
1610 @dots{} show the end of the current file
1611 @item >
1612 @dots{} return to the previous postion after @kbd{<} or @kbd{>}
1613 @item RET, g
1614 @dots{} open the current file in the next window
1615 @item mouse-2
1616 @dots{} same as RET(available only with window system)
1617 @item o
1618 @dots{} other window
1619 @item 1
1620 @dots{} delete other windows
1621 @item -
1622 @dots{} shrink hierarchy buffer window
1623 @item +
1624 @dots{} enlarge hierarchy buffer window
1625 @item ?
1626 @dots{} describe mode
1627 @item q
1628 @dots{} quit
1629 @end table
1631 Note that operations on the file contents in the next window do not work
1632 correctly when you close the corresponding file.
1634 @node Cooperation with other packages, Customizations, Browsing file hierarchy, Top
1635 @comment node-name, next, previous, up
1636 @chapter Cooperation with other packages
1638 YaTeX works better with other brilliant packages.
1640 @section gmhist
1641 @cindex gmhist
1642 @cindex command history
1643 @cindex minibuffer history
1645 When you are loading @file{gmhist.el} and @file{gmhist-mh.el}, you can
1646 use independent command history list at the prompt of preview command
1647 (@kbd{[prefix] tp}) and print command (@kbd{[prefix] tl}). On each
1648 prompt, you can enter the previous command line string repeatedly by
1649 typing @kbd{M-p}.
1651 @section min-out
1652 @cindex min-out
1654 @file{min-out}, the outline minor mode, can be used in yatex-mode
1655 buffers. If you want to use it with YaTeX, please refer the
1656 file @file{yatexm-o.el} as an example.
1658 @node Customizations, Etcetera, Cooperation with other packages, Top
1659 @comment node-name, next, previous, up
1660 @chapter Customizations
1661 @cindex customizations
1663 You can customize YaTeX by setting Emacs-Lisp variables and by making
1664 add-in functions.
1666 @menu
1667 * Lisp variables::
1668 * Add-in functions::
1669 * Add-in generator::
1670 @end menu
1672 @node Lisp variables, Add-in functions, Customizations, Customizations
1673 @comment node-name, next, previous, up
1674 @section Lisp variables
1675 @cindex customizable variables
1677 You can change the key assignments or make completion more comfortable
1678 by setting the values of various variables which control the movement of
1679 yatex-mode.
1681 For example, if you want to change the prefix key stroke from @kbd{C-c}
1682 to any other sequence, set YaTeX-prefix to whatever you want to use. If
1683 you don't want to use the key sequence @kbd{C-c letter} which is assumed
1684 to be the user reserved sequence in Emacs world, set
1685 @code{YaTeX-inhibit-prefix-letter} to @code{t}, and all of the default key
1686 bind of @kbd{C-c letter} will turn to the corresponding @kbd{C-c C-letter}
1687 (but the region based completions that is invoked with @kbd{C-c
1688 Capital-letter} remain valid, if you want to disable those bindings, set
1689 that variable to 1 instead of @code{t}).
1691 @menu
1692 * All customizable variables::
1693 * Sample definitions::
1694 * Hook variables::
1695 * Hook file::
1696 @end menu
1698 @node All customizable variables, Sample definitions, Lisp variables, Lisp variables
1699 @comment node-name, next, previous, up
1700 @subsection All customizable variables
1701 @cindex all customizable variables
1703 Here are the customizable variables of yatex-mode. Each value setq-ed
1704 in @file{~/.emacs} is preferred and that of defined in @file{yatex.el} is
1705 neglected. Parenthesized contents stands for the default value. When you
1706 are to change some of these variables, see more detailed documentation of
1707 the variable by @kbd{M-x describe-variable}.
1709 @defvar YaTeX-japan
1710 Set this nil to produce all messages in English
1711 (@code{Depends on Japanese feature of Emacs})
1712 @end defvar
1714 @defvar YaTeX-kanji-code
1715 Default buffer-file-coding-system for YaTeX modes' buffer.
1716 Set this 0 to no language conversion. Nil to preserve original
1717 coding-system. 1=Shift JIS, 2=JIS, 3=EUC, 4=UTF-8 (@code{1 or 2})
1718 @end defvar
1720 @defvar YaTeX-prefix
1721 Prefix key stroke (@kbd{C-c})
1722 @end defvar
1724 @defvar YaTeX-inhibit-prefix-letter
1725 Change key stroke from @kbd{C-c letter} to @kbd{C-c C-letter} (@code{nil})
1726 @end defvar
1728 @defvar YaTeX-fill-prefix
1729 Fill-prefix used in yatex-mode (@code{nil})
1730 @end defvar
1732 @defvar YaTeX-user-completion-table
1733 Name of user dictionary where learned completion table will be stored.
1734 (@code{"~/.yatexrc"})
1735 @end defvar
1737 @defvar tex-command
1738 La@TeX{} typesetter command (@code{"latex"})
1739 @end defvar
1741 @defvar dvi2-command
1742 Preview command (@code{"xdvi -geo +0+0 -s 4"})
1743 @end defvar
1745 @defvar dviprint-command-format
1746 Command format to print dvi file (@code{"dvi2ps %f %t %s | lpr"})
1747 @end defvar
1749 @defvar dviprint-from-format
1750 Start page format of above %f. %b will turn to start page (@code{"-f %b"})
1751 @end defvar
1753 @defvar dviprint-to-format
1754 End page format of above %t. %e will turn to @code{end} page (@code{"-t %e"})
1755 @end defvar
1757 @defvar makeindex-command
1758 Default makeindex command (@code{"makeindex"} (@code{"makeind"} on MS-DOS))
1759 @end defvar
1761 @defvar YaTeX-dvipdf-command
1762 Default command name to convert .dvi to PDF (@code{"dvipdfmx"})
1763 @end defvar
1765 @defvar YaTeX-on-the-fly-preview-interval
1766 Interval time in seconds of idle to trigger on-the-fly preview of
1767 environment by @kbd{[prefix] t e}(0.9).
1768 @code{Nil} disables on-the-fly preview.
1769 @end defvar
1771 @defvar YaTeX-on-the-fly-math-preview-engine
1772 Function symbol to use on-the-fly preview of MATH environment
1773 started by @kbd{[prefix] t e} (@code{'YaTeX-typeset-environment-by-lmp}
1774 which calls latex-math-preview-expression function if latex-math-preview
1775 is available, otherwise @code{'YaTeX-typeset-environment-by-builtin} which
1776 alls built-in function).
1778 @code{Nil} disables on-the-fly preview.
1779 @end defvar
1781 @defvar YaTeX-cmd-gimp
1782 Command name of GIMP (code{"gimp"})
1783 @end defvar
1784 @defvar YaTeX-cmd-tgif
1785 Command name of tgif (code{"tgif"})
1786 @end defvar
1787 @defvar YaTeX-cmd-inkscape
1788 Command name of Inkscape (code{"inkscape"})
1789 @end defvar
1790 @defvar YaTeX-cmd-dia
1791 Command name of Dia (code{"dia"})
1792 @end defvar
1793 @defvar YaTeX-cmd-ooo
1794 Command name of OpenOffice.org/LibreOffice (code{"soffice"})
1795 @end defvar
1796 @defvar YaTeX-cmd-gs
1797 Command name of Ghostscript (code{"gs"})
1798 @end defvar
1799 @defvar YaTeX-cmd-dvips
1800 Command name of dvips (code{"dvips"})
1801 @end defvar
1802 @defvar YaTeX-cmd-displayline
1803 Command name of displayline
1804 (code{"/Applications/Skim.app/Contents/SharedSupport/displayline"})
1805 @end defvar
1806 @defvar YaTeX-cmd-edit-ps
1807 Command name for editing PostScript files(Value of code{"YaTeX-cmd-gimp"})
1808 @end defvar
1809 @defvar YaTeX-cmd-edit-pdf
1810 Command name for editing PDF files(Value of code{"YaTeX-cmd-ooo"})
1811 @end defvar
1812 @defvar YaTeX-cmd-edit-ai
1813 Command name for editing `.ai' files(Value of code{"YaTeX-cmd-inkscape"})
1814 @end defvar
1815 @defvar YaTeX-cmd-edit-svg
1816 Command name for editing SVG files(Value of code{"YaTeX-cmd-inkscape"})
1817 @end defvar
1818 @defvar YaTeX-cmd-edit-images
1819 Command name for editing image files(Value of code{"YaTeX-cmd-gimp"})
1820 @end defvar
1822 @defvar YaTeX-need-nonstop
1823 Put @code{\nonstopmode@{@}} or not (@code{nil})
1824 @end defvar
1826 @defvar latex-warning-regexp
1827 Regular expression of warning message latex command puts out
1828 (@code{"line.* [0-9]*"})
1829 @end defvar
1831 @defvar latex-error-regexp
1832 Regular expression of error message (@code{"l\\.[1-9][0-9]*"})
1833 @end defvar
1835 @defvar latex-dos-emergency-message
1836 Message latex command running on DOS puts at abort (@code{"Emergency stop"})
1837 @end defvar
1839 @defvar YaTeX-item-regexp
1840 Regular expression of item command (@code{"\\\\item"})
1841 @end defvar
1843 @defvar YaTeX-verb-regexp
1844 Regexp of verb family. Omit \\\\. (@code{"verb\\*?\\|path"})
1845 @end defvar
1847 @defvar YaTeX-nervous
1848 T for using local dictionary (@code{t})
1849 @end defvar
1851 @defvar YaTeX-sectioning-regexp
1852 Regexp of La@TeX{} sectioning command
1853 (@code{"\\(part\\|chapter\\*?\\|\\(sub\\)*\\(section\\|paragraph\\)\\*?\\)\\b"})
1854 @end defvar
1856 @defvar YaTeX-fill-inhibit-environments
1857 Inhibit fill in these environments
1858 (@code{'("tabular" "tabular*" "array" "picture" "eqnarray" "eqnarray*" "equation" "math" "displaymath" "verbatim" "verbatim*")})
1859 @end defvar
1861 @defvar YaTeX-uncomment-once
1862 T for deleting all preceding @code{%} (@code{nil})
1863 @end defvar
1865 @defvar YaTeX-close-paren-always
1866 T for always close all parenthesis automatically, @code{nil} for only eol
1867 (@code{t})
1868 @end defvar
1870 @defvar YaTeX-auto-math-mode
1871 Switch math-mode automatically (@code{t})
1872 @end defvar
1874 @defvar YaTeX-math-key-list-private
1875 User defined alist, math-mode-prefix vs completion alist
1876 used in image completion (@code{nil}). See @file{yatexmth.el}
1877 for the information about how to define a completion alist.
1878 @end defvar
1880 @defvar YaTeX-default-pop-window-height
1881 Initial height of typesetting buffer when one-window.
1882 Number for the lines of the buffer, numerical string for
1883 the percentage of the screen-height. @code{nil} for half height (10)
1884 @end defvar
1886 @defvar YaTeX-help-file
1887 Global online help file name (@file{$doc-directory/../../site-lisp/YATEXHLP.eng})
1888 @end defvar
1890 @defvar YaTeX-help-file-private
1891 Private online help file name (@file{"~/YATEXHLP.eng"})
1892 @end defvar
1894 @defvar YaTeX-no-begend-shortcut
1895 Disable [prefix] b ?? shortcut (@code{nil)}
1896 @end defvar
1898 @defvar YaTeX-hilit-pattern-adjustment-private
1899 List of the list that contain the regular expression and the symbol of
1900 logical meaning of the string that matches the pattern. See also the
1901 value from @code{(assq 'yatex-mode hilit-patterns-alist)} and the value of
1902 @code{YaTeX-hilit-pattern-adjustment-default} (and even the document of
1903 hilit19.el).
1904 @end defvar
1906 @defvar YaTeX-sectioning-level
1907 Alist of LaTeX's sectioning command vs its height.
1908 @end defvar
1910 @defvar YaTeX-hierarchy-ignore-heading-regexp
1911 @code{YaTeX-display-hierarchy} searches for sectioning command first, and
1912 comment line secondary as a file headings. In latter case, ignore lines
1913 that match with regular expression of this variable. Default value of
1914 this variable is RCS header expressions and mode specifying line `-*- xxxx
1915 -*'.
1916 @end defvar
1918 @defvar YaTeX-skip-default-reader
1919 Non-nil for this variable skips the default argument reader of
1920 section-type command when add-in function for it is not defined
1921 (@code{nil})
1922 @end defvar
1924 @defvar YaTeX-create-file-prefix-g
1925 When typing @kbd{prefix g} on the @code{\include} line,
1926 open the target file even if the file doesn't exist (@code{nil})
1927 @end defvar
1929 @defvar YaTeX-simple-messages
1930 Simplyfy messages of various completions (@code{nil})
1931 @end defvar
1933 @defvar YaTeX-hilit-sectioning-face
1934 When hilit19 and yatex19 is active, YaTeX colors the sectioning commands.
1935 This variable specifies the foreground and background color of
1936 @code{\part} macro. The default value is @code{'(yellow/dodgerblue
1937 yellow/slateblue)}. The first element of this list is for the screen when
1938 @code{hilit-background-mode} is @code{'light}, and the second element is
1939 for @code{'dark}. You should specify both color as `forecolor/backcolor'.
1940 @end defvar
1942 @defvar YaTeX-hilit-sectioning-attenuation-rate
1943 When color mode, this variable specifies how much attenuate the color
1944 density of @code{\subparagraph} compared with that of @code{\chapter}
1945 (@code{'(15 40)}) See also @code{YaTeX-hilit-sectioning-face}.
1946 @end defvar
1948 @defvar YaTeX-use-AMS-LaTeX
1949 If you use AMS-LaTeX, set to @code{t} (@code{nil})
1950 @end defvar
1952 @defvar YaTeX-use-LaTeX2e
1953 If you use LaTeX2e, set to @code{t} (@code{t})
1954 @end defvar
1956 @defvar YaTeX-template-file
1957 File name which is automatically inserted at creation
1958 (@code{~/work/template.tex})
1959 @end defvar
1961 @defvar YaTeX-search-file-from-top-directory
1962 Non-nil means to search input-files from the directory where main file exists
1963 (@code{t})
1964 @end defvar
1966 @defvar YaTeX-use-font-lock
1967 Use font-lock to fontify buffer or not (@code{(featurep 'font-lock)}
1968 @end defvar
1970 @defvar YaTeX-use-hilit19
1971 Use hilit19 to highlight buffer or not (@code{(featurep 'hilit19)}
1972 @end defvar
1974 @defvar YaTeX-use-italic-bold
1975 YaTeX tries to search italic, bold fontsets or not
1976 (@code{t} if Emacs-20 or later). This variable is effective only when
1977 font-lock is used.
1978 (@code{(featurep 'hilit19)}
1979 @end defvar
1981 @defvar YaTeX-singlecmd-suffix
1982 Suffix which is always inserted after maketitle-type macros.
1983 @code{"@{@}"} is recommended.
1984 @end defvar
1986 @defvar YaTeX-package-alist-private
1987 Alist of LaTeX2e-package name vs. lists of macros in it.
1988 Set this alist properly and YaTeX automatically check the declaratiion of
1989 `usepackage' for corresponding macro, when you input that macro with
1990 completion. If required `usepackage' is not found, YaTeX also
1991 automatically inserts `\usepackage'. Alist is as follows;
1992 @lisp
1993 '((PackageName1
1994 (completionType ListOfMacro)
1995 (completionType ListOfMacro))
1996 (PackageName2
1997 (completionType ListOfMacro)
1998 (completionType ListOfMacro...))....)
1999 @end lisp
2000 completionType is one of @code{env, section, maketitle}.
2001 Consult the value of @code{YaTeX-package-alist-default} as an example.
2002 @end defvar
2004 @defvar YaTeX-tabular-indentation
2005 At indentation by @kbd{C-i} in tabular or array environment,
2006 YaTeX put the additional spaces to the normail indentation depth.
2007 The number of additional spaces is the product of YaTeX-tabular-indentation
2008 and the number of column position in tabular.
2009 @end defvar
2011 @defvar YaTeX-noindent-env-regexp
2012 Regexp of environment names that should begin with no indentation.
2013 All verbatime-like environment name should match with.
2014 @end defvar
2016 @defvar YaTeX-electric-indent-mode
2017 Emacs 24.4 introduces automatic indentation of current and new lines.
2018 This might be annoying for some people. Pass this value to the function
2019 'electric-indent-local-mode. If you prefer to stop electric-indent-mode
2020 in yatex-mode, set `-1' to this variable.
2021 @end defvar
2023 @defvar YaTeX-ref-default-label-string
2024 Default \\ref time string format.
2025 This format is like strftime(3) but allowed conversion char are as follows;
2026 %y -> Last 2 digit of year, %b -> Month name, %m -> Monthe number(1-12),
2027 %d -> Day, %H -> Hour, %M -> Minute, %S -> Second,
2028 %qx -> alphabetical-decimal conversion of yymmdd.
2029 %qX -> alphabetical-decimal conversion of HHMMSS.
2030 Beware defualt label-string should be always unique. So this format string
2031 should have both time part (%H+%M+%S or %qX) and date
2032 part (%y+(%b|%m)+%d or %qx).
2033 @end defvar
2035 @defvar YaTeX-ref-generate-label-function
2036 Function to generate default label string for unnamed \\label@{@}s.
2037 The function pointed to this value should take two arguments.
2038 First argument is LaTeX macro's name, second is macro's argument.
2039 Here is an example for using this value.
2040 @lisp
2041 (setq YaTeX-ref-generate-label-function 'my-yatex-generate-label)
2042 (defun my-yatex-generate-label (command value)
2043 (and (string= command "caption")
2044 (re-search-backward "\\\\begin@{\\(figure\\|table\\)@}" nil t)
2045 (setq command (match-string 1)))
2046 (let ((alist '(("chapter" . "chap")
2047 ("section" . "sec")
2048 ("subsection" . "subsec")
2049 ("figure" . "fig")
2050 ("table" . "tbl"))))
2051 (if (setq command (cdr (assoc command alist)))
2052 (concat command ":" value)
2053 (YaTeX::ref-generate-label nil nil))))
2054 @end lisp
2055 @end defvar
2058 @node Sample definitions, Hook variables, All customizable variables, Lisp variables
2059 @comment node-name, next, previous, up
2060 @subsection Sample definitions
2061 @cindex prefix key stroke
2062 @cindex fill-prefix
2064 For instance, to change the prefix key stroke to @kbd{ESC}, and name of
2065 the user dictionary @file{~/src/emacs/yatexrc}, and set @code{fill-prefix}
2066 to single TAB character, add the following @code{setq} to @file{~/.emacs}.
2068 @lisp
2069 (setq YaTeX-prefix "\e"
2070 YaTeX-user-completion-table "~/src/emacs/yatexrc"
2071 YaTeX-fill-prefix " ")
2072 @end lisp
2074 @node Hook variables, Hook file, Sample definitions, Lisp variables
2075 @comment node-name, next, previous, up
2076 @subsection Hook variables
2077 @cindex hook variables
2079 More customizations will be done by the hook-function defined in
2080 hook-variable @code{yatex-mode-hook}. This is useful to define a shortcut
2081 key sequence to enter some environments other than @code{document} and
2082 @code{enumerate} etc. The following statement defines @code{[prefix] ba}
2083 to enter @code{\begin@{abstract@}} ... @code{=end@{abstract@}}
2084 immediately.
2086 @lisp
2087 (setq yatex-mode-hook
2088 '(lambda() (YaTeX-define-begend-key "ba" "abstract")))
2089 @end lisp
2091 You should use functions @code{YaTeX-define-key}, or
2092 @code{YaTeX-define-begend-key} to define all the key sequences of
2093 yatex-mode.
2095 @node Hook file, , Hook variables, Lisp variables
2096 @comment node-name, next, previous, up
2097 @subsection Hook file
2098 @cindex hook file
2100 You can stuff all of YaTeX related expressions into a file named
2101 @file{yatexhks.el} if you have a lot of codes. YaTeX automatically load
2102 this file at the initialization of itself. Using @file{yatexhks.el}
2103 makes @code{yatex-mode-load-hook} unnecessary.
2105 @node Add-in functions, Add-in generator, Lisp variables, Customizations
2106 @comment node-name, next, previous, up
2107 @section Add-in functions
2108 @cindex add-in functions
2109 @cindex yatexadd.el
2111 You can easily define a function to input detailed arguments
2112 with completion according to La@TeX{} environments or commands.
2114 @c @node What is add-in functions?, , Add-in functions, Add-in functions
2115 @comment node-name, next, previous, up
2116 @subsection What is add-in functions?
2117 @cindex tabular
2119 When you input @code{tabular} environment, don't you think ``I want
2120 YaTeX to complete its argument toward my favorite one such as
2121 @code{@{|c|c|c|@}}...''? Yes, you can define the function to complete
2122 arguments for any environment and any La@TeX{} commands.
2124 @subsection Procedure
2126 Here is the procedure to define add-in functions.
2127 @enumerate
2128 @item
2129 Define the function
2130 @item
2131 Put the function into @file{yatexhks.el}
2132 @end enumerate
2134 @menu
2135 * How the add-in function works::
2136 * How the function is called::
2137 * Useful functions for creating add-in::
2138 * Contribution::
2139 @end menu
2141 @node How the add-in function works, How the function is called, Add-in functions, Add-in functions
2142 @comment node-name, next, previous, up
2143 @subsection How the add-in function works
2145 There are three types of add-in.
2147 @enumerate
2148 @item
2149 Option add-in
2150 @item
2151 argument add-in
2152 @item
2153 enclosing add-in
2154 @end enumerate
2156 @dfn{Option add-in} returns the
2157 La@TeX{}'s optional parameters such as optional strings after
2158 @code{\begin@{ENV@}}, optional strings between a section-type command
2159 and its first argument, and optional strings just after type
2160 maketitle-type command. The following illustrates the name of add-in
2161 functions, where underlined strings are generated by add-in functions.
2163 @display
2164 \begin@{table@}[ht] (Function name: YaTeX:table)
2165 ~~~~
2166 \put(100,200)@{@} (Function name: YaTeX:put)
2167 ~~~~~~~~~
2168 \sum_@{i=0@}^@{n@} (Function name: YaTeX:sum)
2169 ~~~~~~~~~~
2170 @end display
2172 Obviously, the function name is decided by concatenating the prefix
2173 `YaTeX:' and La@TeX{} command's name.
2175 Another add-in type is @dfn{argument add-in}, which completes arguments
2176 for section-type commands.
2178 @display
2179 \newcommand@{\foo@}@{bar@} (Function name: YaTeX::newcommand)
2180 ~~~~ ~~~
2181 @end display
2183 When the section-type command is inputted, the function named by
2184 concatenating `YaTeX::' and section-type command, is called automatically
2185 with an integer argument which indicates which argument of section-type
2186 command is being read. Thus the add-in should determine the
2187 job referring the value of its argument.
2189 @dfn{enclosing add-in} is for modifying and/or checking the region that
2190 will be enclosed by section-type commands via @kbd{[prefix] S}. An
2191 enclosing add-in function will be called with two arguments, beginning of
2192 the enclosed region and end of the region. Suppose you want to enclose
2193 the existing text @code{(a+b)/c} by @code{\frac@{@}}.
2195 @display
2196 a/c
2197 | |
2198 A B
2199 @end display
2201 You do set-mark-command at point A and then move to point B. Typing
2202 @kbd{[prefix] S} and input @code{frac} enclose the region like this;
2204 @display
2205 \frac@{a/c@}
2206 @end display
2208 Normally, the expression @code{a/c} is translated to
2209 @code{\frac@{a@}@{c@}}. An enclosing add-in is useful for modifying
2210 @code{/} to @code{@}@{}.
2212 @menu
2213 * Defining option-add-in::
2214 * Defining argument-add-in::
2215 * Defining enclosing-add-in::
2216 @end menu
2218 @node Defining option-add-in, Defining argument-add-in, How the add-in function works, How the add-in function works
2219 @comment node-name, next, previous, up
2220 @subsubsection Defining `option add-in'
2222 If you want @code{@{|c|c|c|@}} for all @code{tabular} environment,
2224 @lisp
2225 (defun YaTeX:tabular ()
2226 "@{|c|c|c|@}")
2227 @end lisp
2229 @noindent
2230 is enough. If you want more complicated format, define as below.
2232 @lisp
2233 (defun YaTeX:tabular ()
2234 "@{@@@{\\vrule width 1pt\\ @}|||@@@{\\ \\vrule width 1pt@}@}")
2235 @end lisp
2237 @noindent
2238 Note that the character @code{\} must be described as @code{\\} in
2239 Emacs-Lisp. The next example reads the tabular format from keyboard.
2240 @lisp
2241 (defun YaTeX:tabular ()
2242 (concat "@{" (read-string "Rule: ") "@}"))
2243 @end lisp
2245 @node Defining argument-add-in, Defining enclosing-add-in, Defining option-add-in, How the add-in function works
2246 @comment node-name, next, previous, up
2247 @subsubsection Defining `argument add-in'
2249 This section describes how to define the add-in function for
2250 @code{\newcommand}.
2252 The first argument of @code{\newcommand} begins always with @code{\}.
2253 The second argument is usually so complex that we can not edit them in the
2254 minibuffer. Here is the created function considering this.
2256 @lisp
2257 (defun YaTeX::newcommand (n) ;n is argument position
2258 (cond
2259 ((= n 1) ;1st argument is macro name
2260 (read-string "Command: " "\\")) ;initial input `\'
2261 ((= n 2) "") ;do nothing when reading arg#2
2262 (t nil)))
2263 @end lisp
2265 Note that when the `argument add-in' function return `nil', normal
2266 argument reader will be called.
2268 @node Defining enclosing-add-in, , Defining argument-add-in, How the add-in function works
2269 @comment node-name, next, previous, up
2270 @subsubsection Defining `enclosing add-in'
2272 This section describes how to define the add-in function for
2273 text enclosed by @code{\frac@{@}}.
2275 When enclosing the text @code{5/3} by @code{\frac@{@}}, you might want to
2276 replace @code{/} with @code{@}@{}. Enclosing function
2277 @code{YaTeX::frac-region} is called with two arguments, beginning of
2278 enclosed text and end of enclosed text. The function is expected to
2279 replace @code{/} with @code{@}@{}. Here is an example expression.
2281 @lisp
2282 (defun YaTeX::frac-region (beg end)
2283 (catch 'done
2284 (while (search-forward "/" end t)
2285 (goto-char (match-beginning 0))
2286 (if (y-or-n-p "Replace this slash(/) with `@}@{'")
2287 (throw 'done (replace-match "@}@{")))
2288 (goto-char (match-end 0)))))
2289 @end lisp
2291 @node How the function is called, Useful functions for creating add-in, How the add-in function works, Add-in functions
2292 @comment node-name, next, previous, up
2293 @subsection How the function is called
2295 YaTeX calls the add-in functions for specified begin-type, section-type,
2296 and maketitle-type command, if any. `Option add-in' functions for
2297 begin-type are called when @code{\begin@{ENV@}} has been inserted,
2298 functions for section-type are called just before input of the first
2299 argument, and functions for maketitle-type is called after maketitle-type
2300 command has been inserted. `Argument add-in' functions are called at each
2301 entry of arguments for section-type commands.
2303 @node Useful functions for creating add-in, Contribution, How the function is called, Add-in functions
2304 @comment node-name, next, previous, up
2305 @subsection Useful functions for creating add-in
2307 Many add-in functions for typical La@TeX{} commands are defined in
2308 @file{yatexadd.el}. Those are also useful as references. Here are the
2309 short descriptions on useful functions, where [F] means function, [A]
2310 means arguments, [D] means description.
2312 @table @kbd
2313 @item [F]
2314 YaTeX:read-position
2315 @itemx [A]
2316 Character list which can show up in the brackets
2317 @itemx [D]
2318 Return the location specifier such as `[htb]'. When
2319 nothing is entered, omit [] itself. If the possible characters
2320 are "htbp", call this function as
2321 @code{(YaTeX:read-position "htbp")}
2323 @item [F]
2324 YaTeX:read-coordinates
2325 @itemx [A]
2326 Base prompt, X-axis prompt, Y-axis prompt (each optional)
2327 @itemx [D]
2328 Read the coordinates with the prompt ``BasePrompt X-axisPrompt:'' for
2329 X-axis, ``BasePrompt Y-axisPrompt:'' for Y-axis, and return it in the form
2330 of ``(X,Y)''. The default prompts are @code{Dimension}, @code{X},
2331 @code{Y} respectively.
2333 @item [F]
2334 YaTeX:check-completion-type
2335 @itemx [A]
2336 One of the symbols: 'begin, 'section, or 'maketitle
2337 @itemx [D]
2338 Check the current completion type is specified one and cause error if
2339 not. The variable @code{YaTeX-current-completion-type} holds the symbol
2340 according to the current completion type.
2341 @end table
2343 @node Contribution, , Useful functions for creating add-in, Add-in functions
2344 @comment node-name, next, previous, up
2345 @subsection Contribution
2347 If you make your own pretty function and you let it be in public, please
2348 send me the function. I'm going to include it in the next release.
2350 @node Add-in generator, , Add-in functions, Customizations
2351 @comment node-name, next, previous, up
2352 @section Add-in generator
2354 First, don't forget to read the section of add-in functions @ref{Add-in
2355 functions}. If you easily understand how to define them, there's no need
2356 to read this section. But being not familiar with Emacs-Lisp, when you
2357 don't have clear idea what to do, this section describes how to get YaTeX
2358 make add-in function.
2360 There are two methods of generation. One is for fully interactive
2361 generator for beginners and another requires little knowledge of
2362 Emacs-Lisp.
2364 @subsection Generator for beginners
2365 The former generator is called by
2366 @center @kbd{M-x YaTeX-generate}
2368 @noindent
2369 strokes. All you have to do is follow the guidances. Defying them may cases
2370 the disaster (I wonder what is it???). So when you make some mistake, it
2371 is recommendable to type @kbd{C-g} and start afresh.
2373 @subsection Simple generator
2375 The latter generator is invoked by the next sequence.
2376 @center @kbd{M-x YaTeX-generate-simple}
2377 This generator can make both ``option add-in'' and ``argument add-in''
2378 (@emph{refer the section add-in functions}
2379 @ref{How the add-in function works}), whereas @code{YaTeX-generate}
2380 cannot make ``argument addin''.
2382 For example, assume you have the LaTeX command as follows.
2384 @example
2385 \epsinput[t](250,50)@{hoge.eps@}@{plain@}@{Picture of foo@}
2386 (A) (B) (1) (2) (3)
2387 (A)Optional parameter to specify the position
2388 One of t(top), b(bottom), l(left), r(right)
2389 (B)Maximum size of frame
2390 (1)1st argument is filename of EPS file
2391 (2)2nd argument indicates
2392 plain do nothing
2393 frame make frame around image
2394 dframe make double-frame around image
2395 for included EPS file.
2396 (3)Caption for the picture
2397 @end example
2399 Now get start with generation. Typing @kbd{M-x YaTeX-generate-simple}
2400 brings the prompt:
2401 @display
2402 (O)ption? (A)rgument?
2403 @end display
2405 @subsubsection Generating ``option add-in''
2406 @cindex option add-in
2408 Since (A), (B) above are optional argument, all we have to do to
2409 complete them is define the option add-in for them. Let's generate the
2410 function to complete (A).
2412 @display
2413 M-x YaTeX-generate-simple RET
2414 epsinput RET
2416 @end display
2418 @noindent
2419 Typing as above leads the next prompt.
2421 @display
2422 Read type(1): (S)tring (C)omplete (F)ile ([)option (P)osition co(O)rd. (q)uit
2423 @end display
2425 @noindent
2426 This asks that ``Which type is the completion style of 1st argument?''.
2427 Here are the possible completion style.
2429 @table @code
2430 @item String
2431 read plain string
2432 @item Complete
2433 read with completion
2434 @item File
2435 read file name
2436 @item Option
2437 read optional string (if string omitted, omit [] too)
2438 @item Position
2439 read positional option (like [htbp])
2440 @item Coord.
2441 read coordinates
2442 @item Quit
2443 quit from generating
2444 @end table
2446 Since (A) is the optional argument to specify the location of included
2447 EPS file, the completion style is @code{Position}, and the possible
2448 characters are t, b, l, and r. To tell these information to generator,
2449 operate as follows.
2451 @display
2452 Read type(1).... p
2453 Acceptable characters: tblr RET
2454 @end display
2456 (B) is coordinate. So its completion style is coOrd. We want a prompt
2457 meaning ``Maximum size'' when completion.
2459 @display
2460 Read type(2).... o
2461 Prompt for coordinates: Max size RET
2462 @end display
2464 That's all for optional argument. Select quit.
2466 @display
2467 Read type(3).... q
2468 @end display
2470 Then the generated option add-in function for \epsinput will be shown in
2471 the next window.
2473 @subsubsection Generating ``argument add-in''
2474 @cindex argument add-in
2476 Next, create the argument add-in. The arguments for \epsinput are EPS
2477 file name, framing style, and caption string in sequence.
2479 @display
2480 M-x YaTeX-generate-simple RET
2481 epsinput RET
2483 @end display
2485 Above key strokes bring the prompt that asks the number of argument.
2486 Answer it with 3.
2488 @display
2489 How many arguments?: 3 RET
2490 @end display
2492 Then the generator asks the completion style and prompt for completion.
2493 Answer them. @kbd{f} for FileName and prompt string.
2495 @display
2496 Read type(1).... f
2497 Prompt for argument#1 EPS file name RET
2498 @end display
2500 The second argument is one of selected symbol. So the completion type
2501 is @code{Completion}.
2503 @display
2504 Read type(2).... c
2505 Prompt for argument#2 Include style RET
2506 @end display
2508 Then all the candidates ready to be read. Type single RET after
2509 entering all.
2511 @display
2512 Item[1](RET to exit): plain RET
2513 Item[2](RET to exit): frame RET
2514 Item[3](RET to exit): dframe RET
2515 Item[4](RET to exit): RET
2516 @end display
2518 The following prompt asks whether the entered string must belong to
2519 candidates or not. In this case, since the argument must be one of
2520 @code{plain}, @code{frame}, and @code{dframe}, type @code{y}.
2522 @display
2523 Require match? (y or n) y
2524 @end display
2526 The last argument is the caption string for which any completion is
2527 needed.
2529 @display
2530 Read type(3).... s
2531 Prompt for argument#3 Caption RET
2532 default: Figure of RET
2533 @end display
2535 Finally we'll get the argument add-in in the next window.
2537 @subsection Contribution
2539 If you get your own pretty function and you let it be in public, please
2540 steel yourself in the happy atmosphere and do not send me the function.
2541 I do know it is not fine because it is generated by yatexgen:-p.
2543 @node Etcetera, Copying, Customizations, Top
2544 @comment node-name, next, previous, up
2545 @chapter Etcetera
2547 The standard completion tables provided in @file{yatex.el} contain a
2548 few La@TeX{} commands I frequently use. This is to lessen the key
2549 strokes to complete entire word, because too many candidates
2550 rarely used often cause too many hits. Therefore always try to
2551 use completion in order to enrich your dictionary, and you will
2552 also find `Wild Bird' growing suitable for your La@TeX{} style.
2554 The package name `Wild Bird' is the English translation of Japanese
2555 title `Yachou', which is a trick on words of Japanese.
2557 @node Copying, , Etcetera, Top
2558 @comment node-name, next, previous, up
2559 @chapter Copying
2561 This program is distributed as a free software. You can
2562 use/copy/modify/redistribute this software freely but with NO warranty to
2563 anything as a result of using this software. Adopting code from this
2564 program is also free. But I would not do contract act.
2566 This software can be treated with: ``The 2-Clause BSD License''
2567 (since 2017-09-09, yatex 1.80).
2569 Any reports and suggestions are welcome as long as I feel interests in
2570 this software. My possible e-mail address is `yuuji@@yatex.org'. (as of
2571 Sep.2017) And there is mailing list for YaTeX. Although the common
2572 language is Japanese, questions in English will be welcome. To join the
2573 ML, send the mail whose subject is `append' to the address
2574 `yatex@@yatex.org. If you have some question, please ask to
2575 `yatex-admin@@yatex.org'.
2577 The specification of this software will be surely modified
2578 (depending on my feelings) without notice :-p.
2581 @flushright
2582 HIROSE Yuuji
2583 @end flushright
2584 @bye
2586 Local variables:
2587 mode: texinfo
2588 fill-prefix: nil
2589 fill-column: 74
2590 End: