diff options
| author | ru <ru@FreeBSD.org> | 2000-01-17 10:39:58 +0000 |
|---|---|---|
| committer | ru <ru@FreeBSD.org> | 2000-01-17 10:39:58 +0000 |
| commit | b5a89659ea518f3a1817b5aa9569aed569f46835 (patch) | |
| tree | 8bc0265ed289089a4bfc2688eb403478a06653cf /contrib/texinfo | |
| parent | 8bad2738ec49e647fdee28e203379fff23a7e852 (diff) | |
| parent | 05f7b4b96773cc26ff78d5e68babd66861aa07a8 (diff) | |
| download | FreeBSD-src-b5a89659ea518f3a1817b5aa9569aed569f46835.zip FreeBSD-src-b5a89659ea518f3a1817b5aa9569aed569f46835.tar.gz | |
This commit was generated by cvs2svn to compensate for changes in r56160,
which included commits to RCS files with non-trunk default branches.
Diffstat (limited to 'contrib/texinfo')
80 files changed, 20550 insertions, 3762 deletions
diff --git a/contrib/texinfo/AUTHORS b/contrib/texinfo/AUTHORS index 647ea29..ead862a 100644 --- a/contrib/texinfo/AUTHORS +++ b/contrib/texinfo/AUTHORS @@ -1,3 +1,3 @@ Richard Stallman, Brian Fox, Bob Chassell, Noah Friedman, Paul Rubin, -Karl Berry, and no doubt many others. +Karl Berry, Eli Zaretskii, and many others. diff --git a/contrib/texinfo/ChangeLog b/contrib/texinfo/ChangeLog index 8e3fb78..126d1fc 100644 --- a/contrib/texinfo/ChangeLog +++ b/contrib/texinfo/ChangeLog @@ -1,9 +1,3182 @@ +1999-09-28 Karl Berry <karl@gnu.org> + + * doc/texinfo.txi: New isbn. + + * configure.in, + util/texi2dvi: version 4.0. + +1999-09-24 Karl Berry <karl@gnu.org> + + * doc/texinfo.txi: Fixes from Oleg. + +1999-09-20 Karl Berry <karl@gnu.org> + + * makeinfo/node.c: Don't write region at an anchor. + From: Thomas Esken <esken@nmlab.informatik.fh-dortmund.de> + + * info/terminal.c: Only set dumb terminal if tgetent returns < 0, + not 0. + For HP-UP 11. + From jeff.hull@state.co.us. + + * makeinfo/footnote.c: Don't translate the `Footnotes' string + according to LANG, it should be according to + @documentlanguage, which isn't implemented yet. + From: Jan Nieuwenhuizen <janneke@gnu.org> + + * doc/texinfo.txi: @end direntry from kama. + +1999-09-19 Karl Berry <karl@gnu.org> + + * doc/texinfo.txi: \ninett is now \smalltt. + + * doc/texinfo.txi: arnold changes + + 1999-09-03 Akim Demaille <akim@epita.fr> + * texi2dvi (getopt): batch has to be assigned `eval', not `echo'. + (bibtex): Launch BibTeX also when the LOG file complains that + there are no BBL file. + + * doc/texinfo.txi: Document that @anchor ignores spaces. + + * makeinfo/cmds.c (cm_shyph): remove, ­ is not supported in + browsers. + From: Thomas Esken <esken@nmlab.informatik.fh-dortmund.de> + + * makeinfo/makeinfo.c: Don't crash if current_indent = 0. + From: Jan Nieuwenhuizen <janneke@gnu.org> + + * makeinfo/makeinfo.c: Avoid blank lines between @menu entries. + * configure.in: 3.12t + + 1999-08-31 Eli Zaretskii <eliz@is.elta.co.il> + * info/info.c (info_short_help): Document --apropos. + +1999-09-18 Karl Berry <karl@gnu.org> + + * makeinfo/html.c (html_output_head): use text for <title>, not + html markup. From François. + * makeinfo/makeinfo.c (text_expansion): new routine. + * makeinfo/cmds.c (cm_settitle): don't expand the title here, + we'll do it later. + + * makeinfo/makeinfo.h (text_expansion): declare. + + * info/indices.c, + * info/infodoc.c, + * info/session.c, + * info/footnotes.c: translate errors. + * info/info.h: Use `' instead of "" in errors. + +1999-09-06 Karl Berry <karl@gnu.org> + + +1999-08-24 Jan Nieuwenhuizen <janneke@gnu.org> + * makeinfo/node.c:cm_node: don't compare current_node when null. + + 1999-08-23 W. L. Estes <will@fumblers.org> + * makeinfo/node.c (cm_node): write <a name=> tags even + ifusing --no-headers + + * configure.in: ospeedlib -> trylib + From: Andreas Schwab <schwab@suse.de> + + * makeinfo/makeinfo.c (read_command): add explicit 0 to return if + enclosure command. From: Andreas Jaeger <aj@arthur.rhein-neckar.de>. + +1999-08-19 Karl Berry <karl@gnu.org> + + * configure.in: add missing quotes, logic in new termcap library + check. + +1999-08-17 Karl Berry <karl@gnu.org> + + * makeinfo/multi.c, + * makeinfo/sectioning.c, + * makeinfo/node.c, + * makeinfo/macro.c: omit unused vars + * info/session.c (info_goto_invocation_node): omit unused decl. + + * configure.in: Check for extra termlib variable necessary on + HP-UX 9. + From: Olaf Bachmann <obachman@mathematik.uni-kl.de> + + 1999-08-16 Andreas Schwab <schwab@suse.de> + * info/terminal.c (terminal_initialize_terminal): Try tcgetattr + and cfgetospeed in preference to TIOCGETP. + (original_tchars, original_ltchars): Define them only if needed. + +1999-08-16 Karl Berry <karl@gnu.org> + + * info/infodoc.c (create_internal_info_help_node): rename arg. + (info_find_or_create_help_window): avoid deref of null eligible. + + * info/terminal.c (TIOCGETP, TIOCGETC, TIOCGLTC) [alpha && linux]: + #undef. Useless stubs are present. + +1999-08-15 Karl Berry <karl@gnu.org> + + * info/nodes.c: Remove reference to nonexistent RFC for Info + files. + +1999-08-11 Eli Zaretskii <eliz@is.elta.co.il> + + * info/nodes.c (info_find_file_internal): If the file's contents + were gc'ed since last time it was loaded, reload the file. + +Wed Aug 11 06:42:47 1999 Karl Berry <karl@gnu.org> + + * doc/Makefile.am (EXTRA_DIST): add txi-pt.tex from Lalo. + +Mon Aug 9 16:28:18 1999 Karl Berry <karl@gnu.org> + + * util/texi2dvi: Support preloaded texinfo.tex, from Stephen. + + * makeinfo/makeinfo.c (add_char): restore ugly check for first + character being <. + + * makeinfo/cmds.c (cm_kbd): Increment in_fixed_width_font for + html. + + * doc/texinfo.txi: effect not affect + + * makeinfo/makeinfo.c: Rearrange help. + + * makeinfo/toc.c: Cast %* arguments to (int) to placate gcc + -Wformat. + +Fri Aug 6 13:03:14 1999 Karl Berry <karl@gnu.org> + + * util/install-info.c: Hardwire the File: dir, Node: top part of + the skeleton dir file. + Report from: Stanislav Brabec <utx@k332.feld.cvut.cz> + + * info/Makefile.am (BUILT_SOURCES): rm -f $(BUILT_SOURCES), a + kludge. + + 1999-07-28 Karl Eichwalder <ke@gnu.franken.de> + + * makeinfo/makeinfo.c: Fix help string (-o). + + 1999-07-30 Eli Zaretskii <eliz@is.elta.co.il> + + * makeinfo/makeinfo.c (cm_uref, cm_email): Don't collapse -- and + `` in the URL part of the reference. + + 1999-08-03 Eli Zaretskii <eliz@is.elta.co.il> + + * util/install-info.c (main): For entries given on command line, + set entry_sections and entry_sections_tail members to NULL, and + set text_len member to the entry length. After processing the + Info file, update the entry_sections pointers of all entries that + came from the command line. + + * util/texindex.c (sort_offline, sort_in_core): use off_t rather + than long. + Found on FreedBSD 2.2.8 by "Trond Endrestol" <endrestol@hotmail.com>. + +Mon Jul 19 17:16:46 1999 Karl Berry <karl@gnu.org> + + * configure.in: 3.12n + + * makeinfo/makeinfo.c (add_char): Don't insert <p> if we're in + @html. + + * makeinfo/html.c (add_escaped_anchor_name), + * makeinfo/toc.c (toc_add_entry): use URL_SAFE_CHAR. + * makeinfo/makeinfo.h (HTML_SAFE, URL_SAFE_CHAR): new macros. + +Sun Jul 18 14:47:40 1999 Karl Berry <karl@gnu.org> + + * dir-example: Add bzip2. + + * configure.in: 3.12m. + + * doc/texinfo.txi (@afourlatex,@afourwide): add to command list. + +1999-07-17 Eli Zaretskii <eliz@is.elta.co.il> + + * makeinfo/makeinfo.c (cm_xref): Don't collapse `` and -- while + expanding node names. Generate a terminating period for + @pxref, when it has more than a single argument. + + * makeinfo/index.c (cm_printindex): Don't collapse `` and -- while + expanding node names. + +Sat Jul 17 16:33:45 1999 Karl Berry <karl@gnu.org> + + * 3.12l. + + * doc/texinfo.txi: @alias, @definfoenclose, etc. + + * util/texindex.c (indexify): error message instead of abort(2) + when no page number. + +Fri Jul 16 18:00:26 1999 Karl Berry <karl@gnu.org> + + * doc/texinfo.txi: Overfull boxes, help2man, etc. + + * util/Makefile.am (EXTRA_DIST): texi-outline.gawk is really + outline.gawk, add fixref.gawk and prepinfo.awk and + texi-docstring-magic.el. + +Thu Jul 15 18:57:54 1999 Karl Berry <karl@gnu.org> + + * doc/texinfo.txi: .fmt, etc. + * doc/texinfo.txi: More macro docs, etc. + +Wed Jul 14 19:58:47 1999 Karl Berry <karl@gnu.org> + + * doc/texinfo.txi: Give good quote. + + * util/Makefile.am (EXTRA_DIST): add texi-outline.gawk. + + From: kama@hippo.fido.de (Karl Heinz Marbaise) + * makeinfo/toc.c (contents_update_html): go back to start level. + * doc/texinfo.txi: deftypeop + + From: "Kaveh R. Ghazi" <ghazi@caip.rutgers.edu> + * makeinfo/toc.c (toc_add_entry): don't assume sprintf return type + is int. + * makeinfo/sectioning.c (insert_and_underscore): declare more + unsigned char *. + * makeinfo/macro.h (itext_info, itext_size): remove declarations, + they're defined static. + * makeinfo/makeinfo.c: Split up help string even more. + +Tue Jul 13 17:16:18 1999 Karl Berry <karl@gnu.org> + + * doc/texinfo.txi: Document @rmacro. + * makeinfo/macro.c (cm_rmacro): new command to do @allow-recursion + by default. + (define_macro): split off from cm_macro. + + * makeinfo/macro.h (cm_rmacro): declare. + * makeinfo/macro.h (delete_macro): do not need to export. + * makeinfo/cmds.c (rmacro): new command. + + * makeinfo/html.c, + * makeinfo/toc.c, + * makeinfo/lang.c, + * makeinfo/makeinfo.c: Use strchr instead of member. + +Mon Jul 12 08:01:19 1999 Karl Berry <karl@gnu.org> + + * doc/texinfo.txi: document this. + * makeinfo/macro.c (apply): warn if \ in macro body is not + followed by a parameter name or \, instead of silently + accepting it, for compatibility with TeX. + + * makeinfo/macro.c: Doc fix. + +Sun Jul 11 12:49:50 1999 Karl Berry <karl@gnu.org> + + * makeinfo/macro.c (cm_macro): do @quote-arg implicitly if single + argument to macro. + * doc/texinfo.txi: Document this. + + * doc/texinfo.txi (Smallcaps): Document makeinfo warning if arg is + all uppercase. + * makeinfo/cmds.c (cm_sc): warn if arg is all upper (suggested by + Jim Meyering). + + * makeinfo/cmds.c (cm_var): warn if argument contains any of ,[]() + which are unlikely to be allowable in real variable names. + Suggested by rms. + + * makeinfo/makeinfo.h (member): remove weird masking macro. + + * doc/texinfo.txi: Probably ok to indent @example. + + * configure.in: 3.12k. + + * makeinfo/html.c (add_escaped_anchor_name): Cast to unsigned char + for 8-bit chars. From Yoshiki. + + * makeinfo/makeinfo.c: complain -> warn for sake of <80 chars. + +1999-07-09 Eli Zaretskii <eliz@is.elta.co.il> + + * makeinfo/multi.c (multitable_item): Quote the value of align= + property. + + * makeinfo/defun.c (defun_internal): Ditto. + + * makeinfo/cmds.c (cm_center): Ditto. + + * makeinfo/toc.c (toc_add_entry): New argument ANCHOR; all callers + changed. In HTML mode, expand NODE_NAME, or use ANCHOR, if + non-NULL, and save it together with the TOC name in the name + member of the TOC entry. + (toc_add_entry, toc_find_section_of_node): Add a warning in a + comment that the NODE argument must be unexpanded. + (contents_update_html): Terminate the TOC entry with </a>. + + * makeinfo/sectioning.c (sectioning_html): If the sectioning + command is outside any node, generate explicit anchor and pass it + to toc_add_entry. + + * makeinfo/node.c (expand_node_name): Now external instead of + static. + (cm_node): Output expanded node name in the navigation bar. + + * makeinfo/node.h: Declare expand_node_name. + + * makeinfo/index.c (cm_printindex): Produce valid HTML links, even + if index->node is NULL or empty. Fix format of index under + --no-headers. + +Fri Jul 9 18:09:28 1999 Karl Berry <karl@gnu.org> + + * doc/texinfo.txi: Pair @end html properly. From Olaf B. + + * doc/Makefile.am (EXTRA_DIST): add txi-nl.tex from Marcel van der Boom + <marcel@virtualprojects.org>. + + * doc/txi-en.tex: Doc fix. + +Wed Jul 7 16:07:44 1999 Karl Berry <karl@gnu.org> + + * doc/Makefile.am: Doc fix. + + * configure.in (txi_CHECK_DECLS): call this new macro (in + acinclude.m4). + * acinclude.m4: new file. + +Tue Jul 6 19:12:37 1999 Karl Berry <karl@gnu.org> + + * makeinfo/insertion.h, + * makeinfo/insertion.c, + * makeinfo/cmds.c, + * makeinfo/defun.c: new command @deftypeop. + Suggestion from: booth@us.ibm.com. + +1999-07-05 Eli Zaretskii <eliz@is.elta.co.il> + + * makeinfo/makeinfo.c (cm_value): Don't convert quotes and dashes + in the argument of @value, since @set doesn't. + +Mon Jul 5 16:43:23 1999 Karl Berry <karl@gnu.org> + + * makeinfo/insertion.c (get_item_function): return "@ " rather + than "@". (command_needs_braces): new fn. + (cm_item): handle @itemize markers that don't take braces. + Bug reported by Stephen, prototype fix from Yoshiki. + + * doc/texinfo.txi (Contents): @contents ignored at beginning when + outputting to stdout. + Installed this. +>1999-05-02 Eli Zaretskii <eliz@is.elta.co.il> +> * makeinfo/toc.c (cm_contents, cm_shortcontents): If writing to +> stdout, output the contents and short contents immediately, and +> assign NULL to contents_filename and shortcontents_filename, so +> that toc_update won't try to rewrite stdout. + + + * makeinfo/sectioning.c (sectioning_html): declare starting_pos + and ending_pos as unsigned char * since they're based on + output_paragraph. + + * makeinfo/insertion.c: Cast output_paragraph to char * for sake + of strncmp prototype (on IRIX 4). + From: "Kaveh R. Ghazi" <ghazi@caip.rutgers.edu> + + + * info/man.c (get_manpage_contents): restore previous (default) + SIGCHLD handler so the pclose when gunzipping info files + doesn't fail with `No child processes' (because + reap_children reaped it). + From: Josip Rodin <jrodin@public.srce.hr> + njs@uclink4.berkeley.edu, 38063-forwarded@bugs.debian.org + +Fri Jul 2 14:26:22 1999 Karl Berry <karl@gnu.org> + + From gildea: + * info/terminal.c (TIOCGETC) [M_XENIX && TIOCGETC]: #undef. + * info/session.c (strncasecmp) [M_XENIX]: declare. + +Thu Jul 1 19:25:12 1999 Karl Berry <karl@gnu.org> + + * makeinfo/makeinfo.c (cm_value): erroneous capitalization in + error message. + + * makeinfo/insertion.c (end_insertion): @end html should turn html + escaping back on. From esr. + + * makeinfo/makeinfo.c (cm_pxref): No period needed to terminate + cross-reference. + +Sun Jun 13 16:12:41 1999 Karl Berry <karl@gnu.org> + + * doc/texinfo.txi: Remove some more node links. + +Sat May 1 16:01:36 1999 Karl Berry <karl@gnu.org> + + * info/info.c: Single space for option indent to match others. + + * makeinfo/makeinfo.c, + * util/texindex.c, + * util/install-info.c: Must indent option list for help2man. + + * info/infodoc.c [HELP_NODE_GETS_REGENERATED]: set to true. + (info_internal_help_text): put moving cmds first so they know how to go + forward in the help window. + (create_internal_info_help_node): can't always quit help with C-x 0. + (info_find_or_create_help_window): pass !one_window_p. + +1999-04-29 Yoshiki Hayashi <g740685@komaba.ecc.u-tokyo.ac.jp> + + * makeinfo/makeinfo.c (cm_xref): Don't collapse --- to -- etc., + in references. + +Mon Apr 26 16:41:55 1999 Karl Berry <karl@gnu.org> + + * makeinfo/node.c (validate): arrange to translate the reference type. + Report from Sergio. + + * makeinfo/makeinfo.c (validate): should not be declared here. + + * makeinfo/index.c (cm_printindex): <ul compact> is not + translatable. From Yoshiki. + + * doc/Makefile.am (EXTRA_DIST): include new txi-es.tex from Adrian + Perez Jorge <alu1415@csi.ull.es>. And new txi-en.tex. + +Sun Apr 25 16:08:27 1999 Karl Berry <karl@gnu.org> + + * makeinfo/cmds.c (cm_settitle): don't output html head here. + + * makeinfo/makeinfo.c: Move html routines to html.c. + * makeinfo/Makefile.am (makeinfo_SOURCES): add html.[ch]. + * makeinfo/html.[ch]: new files. + + * makeinfo/makeinfo.c: Restore -- in --output line. From Sergio. + +1999-04-23 Yoshiki Hayashi <g740685@komaba.ecc.u-tokyo.ac.jp> + + * makeinfo/cmds.c (cm_center): Recover the previous state when + called with --html. + +1999-04-24 Eli Zaretskii <eliz@is.elta.co.il> + + * makeinfo/cmds.c (cm_bye): Flush the output, in case some command + produced it immediately before @bye. + + * makeinfo/toc.h (TOC_ENTRY_ELT): New member: containing_node. + + * makeinfo/toc.c (lots_of_stars): New variable. + (toc_add_entry): Add a new parameter node_name; all callers + changed. Record the name of the node containing the section. + (toc_find_section_of_node): New function. + (toc_free): Free the new containing_node member. + (contents_update_info, shortcontents_update_info): Underline the + title with stars. Output two empty lines after the TOC. + (contents_update): Fix off-by-one error in writing the rest of the + file after updating the TOC. + + * makeinfo/index.c (cm_printindex): Save and restore line_number + and input_filename. Don't output the "* Menu" header when + --no-headers is in effect. Make the fake node name for index + entries that are outside any node be more explanatory, and emit an + error for such index entries. Under --no-headers, output a + reference to the section name, as returned by a call to + toc_find_section_of_node, instead of a node name. + +1999-04-24 Eli Zaretskii <eliz@is.elta.co.il> + + * makeinfo/index.c (struct index_elt): Add a new member + entry_text. + (free_index, make_index_entries_unique): Free the entry_text + member. + (index_add_arg): Don't HTML-escape the index entry here. + (index_add_arg): Initialize the entry member to NULL. Put the + entry text into the entry_text member. + (sort_index): Expand the index entries as if in non-HTML mode. + Put the expansion into the entry member of struct index_elt. + (cm_printindex): Allocate the line[] array in Info mode only. + In HTML mode, escape and expand the original index entry text, + don't use the results of expansion inside sort_index. + + * makeinfo/cmds.c (cm_r): Undo the effect of @code while printing + one of the "code"-style indices in HTML mode. + +1999-04-23 Eli Zaretskii <eliz@is.elta.co.il> + + * info/infomap.c (initialize_vi_like_keymaps): Bind DEL in echo + area to ea_rubout, except for __MSDOS__. + + * doc/info-stnd.texi (Node Commands): Document that `I' only + produces its effect for programs documented in the current Info + file. Tell them to invoke `I' from DIR if it doesn't work from + current place. + +Thu Apr 22 09:59:02 1999 Karl Berry <karl@gnu.org> + + * makeinfo/makeinfo.c, + * info/info.c: Rewrite help string a little more. + + * doc/info-stnd.texi: Change chapter name to match node name, + * other changes. + + * makeinfo/cmds.c (cm_bye): call discard_braces. + + * makeinfo/cmds.c (cm_settitle): output more meta and link tags. + + * configure.in (ALL_LINGUAS): add eo. + + * util/install-info.c [STRIP_DOT_EXE]: #if not #ifdef + +Wed Apr 21 19:40:51 1999 Karl Berry <karl@gnu.org> + + * makeinfo/makeinfo.c: Doc fix. + + * makeinfo/sectioning.c (insert_and_underscore): do not output + html anchor here. + * makeinfo/node.c (cm_node): do anchor at node name not sectioning + title. + + * makeinfo/node.c: Newlines on node lines. + +Tue Apr 20 13:02:46 1999 Karl Berry <karl@gnu.org> + + * info/man.c (get_manpage_contents): freopen stdin and stderr to + /dev/null rather than closing them. http://bugs.debian.org/14787 + +Mon Apr 19 14:12:09 1999 Karl Berry <karl@gnu.org> + + * doc/texinfo.txi: Document possibility of `titlepage' stuff for + plain text output using @ifinfo. + Report from: Kurt Hornik <Kurt.Hornik@ci.tuwien.ac.at>. + + * makeinfo/cmds.c: Screw that. + * doc/texinfo.txi: Fix up frontmatter a bit. + + * dir-example: Spaces not tabs. + * dir-example (R FAQ): add. + + * makeinfo/makeinfo.c: Lowercase makeinfo in first line. + + * doc/info.texi (The node reached...): is a @subsection not a + @subsub. + + * doc/texinfo.txi: Document option rename. + * makeinfo/makeinfo.c: Rename option to commands-in-node-names. + + * makeinfo/index.h (index_compare_fn): declare. + * makeinfo/index.c (index_element_compare): call through new + variable index_compare_fn, and set it to strcoll if + @documentlanguage was used and LANG != en. + #include lang.h. + +Sat Apr 17 14:46:47 1999 Karl Berry <karl@gnu.org> + + * makeinfo/insertion.c (current_item_function, cm_item): rewrite + to skip all conditionals. + (cm_item): use current_item_function rather than current_insertion_type + to check what to use for @item, so @ifset etc. can be used around + @items. + Report from: "W. L. Estes" <wlestes@br20920.uncg.edu>. + + * makeinfo/makeinfo.c (current_insertion_type): no need to + declare. + + * makeinfo/makeinfo.c: Add examples to help message. + + * util/texindex.c (usage): Rearrange --help, avoid extra newline. + + * info/info.c: Sort --help in the usual place. + + * makeinfo/makeinfo.c: Reindent help message, rename + --expensive-validation to --commands-in-nodes. + +Fri Apr 16 17:53:48 1999 Karl Berry <karl@gnu.org> + + * makeinfo/cmds.c (cm_ignore_arg): new routine. + (cm_ignore_line_no_op): remove, can use cm_ignore_line. + +Tue Apr 13 16:45:39 1999 Karl Berry <karl@gnu.org> + + * doc/info-stnd.texi: Frontmatter changes. + + * doc/info.texi: Remove advanced remark in first node. + + * doc/texinfo.txi: Texinfo.tex does macros now. From Eli. + + * doc/texinfo.txi: Document @w{ } to produce an unbreakable space. + + * util/texi2dvi: Update from Akim, avoid Solaris ucb echo weirdness. + + * info/infodoc.c: Parenthesize function calls, don't depend on + gettext being there. Report from: Doug Semler + <doug@seaspace.com>. + +1999-04-12 Eli Zaretskii <eliz@is.elta.co.il> + + * info/infomap.c (initialize_vi_like_keymaps): Initialize the echo + are keymap *before* it is filled up with keys. + +1999-04-10 Eli Zaretskii <eliz@is.elta.co.il> + + * makeinfo/macro.c (execute_macro): Reset the line number to where + the macro argumenst begin, before executing its expansion. + + * makeinfo/makeinfo.c (cm_xref): Expand the name of arguments + before writing them in HTML mode. + (handle_menu_entry): Expand the name of the gleaned node before + writing it in HTML mode. + + * makeinfo/sectioning.c (sectioning_html): Expand the name of the + current node when producing the <a name=... anchor. + + * makeinfo/node.c (cm_node): Expand the name of node and its links + before outputting them in HTML mode. + + * makeinfo/index.c (cm_printindex): Expand node names to which the + index points. + + * makeinfo/footnote.c (cm_footnote): Call execute_string instead + of add_word_args, since current_node needs to be expanded. Expand + the name of the Footnotes node before calling + remember_node_reference. + + * makeinfo/tests/node-expand.txi: New test, for testing how node + names are expanded in @node, @menu, cross-references, and + indices. + + * makeinfo/makeinfo.c (add_char): If we output <p>, adjust the + affected brace positions by 3, so cm_xxx functions get what they + expect in START and END. + (insert_html_tag): Likewise. + + * makeinfo/cmds.c (cm_sc): Remove the kludge that looks for the + beginning of <small>, it is no longer needed. + + * makeinfo/macro.c (cm_definfoenclose): Don't stop at the first + blank after the second comma: the blank may belong to the second + delimiter. + + * makeinfo/tests/htmlpara.txi: New test, for the commands affected + by the <p> output at paragraph beginning. + + * makeinfo/makeinfo.h (expensive_validation): New option. + + * makeinfo/makeinfo.c (long_options): Add expensive_validation. + (usage): Likewise. + + * makeinfo/node.c (find_node): If NAME isn't found verbatim, try + expanding it and every node name in tag table, before comparing + them, but only if expensive_validation is non-zero. + (find_node_reference): Likewise. + (cm_node): Don't expand node name and its links here. + (validate_file): If direct comparisons fail, try expanding the + comparees before giving up, unless expensive_validation is zero. + Switch the order of NODE and UP in error message about a lacking + menu item. + +1999-04-07 Eli Zaretskii <eliz@is.elta.co.il> + + * makeinfo/index.c (cm_printindex): Don't output "Menu" header. + + * makeinfo/node.c (get_node_token): Collapse whitespace in node + names. + (glean_node_from_menu, expand_node_name): Likewise. + + * info/infomap.c (initialize_vi_like_keymaps): Bind all the 256 + keys to ea_insert, like the Emacs-like case does. + + * doc/info-stnd.texi (Invoking Info): Document support for files + compessed with bzip2, and the --vi-keys option. + (Many places): Document key bindings under --vi-keys. + +1999-04-06 Eli Zaretskii <eliz@is.elta.co.il> + + * info/session.c (info_last_node, info_first_node): With a numeric + argument, go to ARGth node counting from the beginning. Skip + anchor tags when looking for the target node--the last tag can be + an anchor, for example. + (last_search_direction, last_search_case_sensitive): New + variables. + (last_search_for_string): Remove variable. + (info_search_internal): Always move point by one notch before + beginning the search, to avoid complications in repeated search + commands. When looking for the next node tag, skip any anchor + tags. + (info_search_1): Accept a 5th argument ASK_FOR_STRING, and only + prompt for search string if it's non-zero. All callers changed. + Look for the COUNTth occurence of the string. + (info_search, info_search_backward, info_search_case_sensitively): + Set last_search_direction and last_search_case_sensitive. + (info_search_next, info_search_previous): New commands, repeat + last search in the same or reverse direction without prompting the + user for the string. + + * info/infomap.c (initialize_emacs_like_keymaps): Bind `C-x n' to + info_search_next and `C-x N' to info_search_previous. + (initialize_vi_like_keymaps): Bind `n' to info_search_next and `N' + to info_search_previous. + +1999-04-04 Eli Zaretskii <eliz@is.elta.co.il> + + * makeinfo/makeinfo.c (get_rest_of_line): Don't expand non-macros, + so that macro-expanded output will still have them. + +1999-04-03 Eli Zaretskii <eliz@is.elta.co.il> + + * makeinfo/node.c (cm_node): Expand the node name and its links + completely before using them, so that they could use e.g. @value{} + etc. + + * makeinfo/makeinfo.c (replace_with_expansion): Don't + remember_itext if we are executing_string. + + * makeinfo/sectioning.c (sectioning_html): Remove #ifdef + HAVE_MACROS. Don't call me_execute_string if already + executing_string. + + * makeinfo/toc.c (toc_add_entry): Expand macros in TOCNAME right + here, since the macro can be later redefined. + (contents_update_html, contents_update_info, + shortcontents_update_html, shortcontents_update_info): Use stdio + functions for output instead of add_word etc. + (rewrite_top, contents_update, shortcontents_update, toc_update): + New functions, replace the TOC placebo with the actual TOC. + (cm_contents): Output a placebo instead of writing the TOC. + (cm_shortcontents): Output a placebo instead of writing the short + TOC. + + * makeinfo/makeinfo.c (convert_from_loaded_file): Call toc_update + if appropriate. + + * makeinfo/sectioning.c (cm_top): Don't output the HTML header + here, since the Top node might be preceeded by other commands, + like @contents. + + * makeinfo/cmds.c (cm_settitle): Output the HTML header here. + + * makeinfo/node.c (set_current_output_filename): New function, + saves the name of the actual file we are now writing, including in + the case of split-HTML output. + (cm_node): Call it to record the name of output file. + + * makeinfo/footnote.c (free_pending_notes): Re-initialize + current_footnote_number to 1. + + * makeinfo/index.c (index_add_arg): Remove redundant xstrdup. + (cm_printindex): Don't free index->entry: it is freed in + free_index, if, e.g., there's more than one file to convert. + + * makeinfo/makeinfo.c (init_internals): Call toc_free. + +Mon Apr 5 16:53:33 1999 Karl Berry <karl@gnu.org> + + * doc/Makefile.am: Texmf_{texinfo,dvips}: dirs not files. From + Kurt Hornik. + +Wed Mar 31 13:50:09 1999 Karl Berry <karl@gnu.org> + + * Pretest 3.12h. + + * makeinfo/node.c (last_node_p): new fn. + (split_file): call it, instead of assuming no more entries means + no more nodes. (Loses with anchors.) + Report from: "Oleg S. Tihonov" <ost@benetnash.ffke-campus.mipt.ru>. + + * makeinfo/index.c (sort_index): whether an entry is @code or not + depends on the element, not the index, because of synindex. + + * doc/Makefile.am (install-tex): Must use $(TEXMF), do + $(mkinstalldirs) on tex dirs. + From: Nathan Sidwell <nathan@acm.org>. + + * doc/texinfo.txi: Document need for blank line before @image if + you want space. + + * Install changes from Eli: + + 1999-03-09 Eli Zaretskii <eliz@is.elta.co.il> + + * info/infodoc.c (info_internal_help_text): Remove hard-wired key + names, use %-10s instead. + (info_help_keys_text): New variable, holds two variants of keys + that invoke basic commands, indexed by vi_keys_p. + (create_internal_info_help_node): Use info_help_keys_text[]. + + * info/window.c (build_message_buffer): Support more general + format strings, like %-10.15s, %+4d etc. + + * info/infomap.c (initialize_vi_like_keymaps): Bind ESC-h, ESC-t, + C-x LFD and C-x RET. + + 1999-03-08 Eli Zaretskii <eliz@is.elta.co.il> + + * util/install-info.c (output_dirfile): Sort the entries and + output them in alphabetic order. Output each entry only in those + sections where it belongs. + (parse_input): New function, code moved from main. Process + sections and entries in a single loop, and record with each entry + the list of sections where that entry belongs. Record each entry + separately, not all of them together as a single block. + (parse_dir_file): New function, code moved from main. + (main): Move code to parse_input and parse_dir_file. Put the new + entries only into sections where they belong. + (compare_entries_text): New function, called when sorting new + entries. + + * info/infomap.c (initialize_vi_like_keymaps): New function. Bind + keys a-la Less, including new functions from session.c below. + (initialize_emacs_like_keymaps): New function, with the guts of + initialize_info_keymaps. + + * info/session.c (info_scroll_forward, info_scroll_backward): If + default_window_size is non-negative, use it as the default number + of lines to scroll. + (info_scroll_forward_set_window, info_scroll_backward_set_window, + info_down_line, info_up_line, info_scroll_half_screen_down, + info_scroll_half_screen_up, info_search_backward): New functions, + for Less-like look and feel. + +Tue Mar 30 16:44:53 UTC 1999 Karl Heinz Marbaise <kama@hippo.fido.de> + + * doc/txi-de.tex: + - added additional putwordin + * doc/texinfo.txi: + - changed defivar into deftypeivar + * makeinfo/sectioning.c: + - changed output of anchors based on problems with ie. + * makeinfo/defun.c: + - output in HTML mode changed to be on previous state. + * makeinfo/insertion.c: + - fixed up HTML output for deftypeivar. + +1999-03-30 Akim Demaille <demaille@inf.enst.fr> + + * texi2dvi ($tmpdir): Avoid security holes. + +Fri Mar 26 17:06:55 1999 Karl Berry <karl@gnu.org> + + * makeinfo/cmds.c (cm_exdent): rewrite to preserve blank lines. + Bug from: "Oleg S. Tihonov" <ost@benetnash.ffke-campus.mipt.ru>. + + * makeinfo/cmds.c (cm_exdent): arg is in `roman'. + +Thu Mar 25 16:21:27 1999 Karl Berry <karl@gnu.org> + + * makeinfo/insertion.c, + * makeinfo/defun.c, + * makeinfo/insertion.h (insertion_type): add deftypeivar. + * makeinfo/defun.h (cm_defun): declare here. + * makeinfo/cmds.c (defun.h): include. + * doc/texinfo.txi (deftypeivar[x]): new commands. + * makeinfo/cmds.c (deftypeivar[x]): new commands. + + * makeinfo/cmds.c (cm_exdent): save, set and restore + in_fixed_width_font. + + * doc/texinfo.txi (uref): rewrite. + + * info/info.c (info_short_help): more spaces for new help2man. + + * makeinfo/node.c (cm_node): output node name in html, change + navbar punctuation. + + * doc/texinfo.5: Fix URL. + + * Finally installed this: + 1998-05-01 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de> + * makeinfo/makeinfo.c (convert_from_loaded_file): When the file + contains no @setfilename then always look for \input (not + \include) in the first line and skip that. Don't skip the first + line if no \input was found. + +1999-03-24 Akim Demaille <demaille@inf.enst.fr> + + * configure.in (AC_HEADER_STAT): Added. + * util/texindex.c (main): Check infiles are not directories. + +1999-03-24 Akim Demaille <demaille@inf.enst.fr> + + * texi2dvi (index_files): Don't use `!' to run sed -e "s!foo$!!" + since the shell will interpret `$!'. + +Tue Mar 23 16:41:08 1999 Karl Berry <karl@gnu.org> + + * doc/texinfo.txi (uref): rewrite to make HTML output read more + nicely. From Tim S. + + * info/info.c (info_short_help): include examples. + + * makeinfo/makeinfo.c (close_paragraph_with_lines): move earlier + so can be static. + + * makeinfo/sectioning.c, + * makeinfo/node.c, + * makeinfo/makeinfo.h, + * makeinfo/makeinfo.c, + * makeinfo/macro.c, + * makeinfo/insertion.c, + * makeinfo/cmds.c, + * makeinfo/files.c, + * makeinfo/footnote.c (size_of_input_text): rename to + input_text_length. + + * makeinfo/makeinfo.c (cm_xref): make wrong-char-following a warning. + (replace_with_expansion): remove bogus conditional that was duplicated + unconditionally. + From: Hans-Bernhard Broeker <broeker@physik.rwth-aachen.de> + +Mon Mar 22 14:39:59 1999 Karl Berry <karl@gnu.org> + + * doc/Makefile.am (install-tex): parenthesize. + + * Makefile.am (dist-hook): remove, it uses hard links so we chmod + all our sources. + + * makeinfo/toc.c, + * makeinfo/defun.c, + * makeinfo/sectioning.c: Use _, not N_. + + * info/Makefile.am (ginfo_SOURCES): include $(BUILT_SOURCES) + explicitly. + + * makeinfo/lang.c, + * makeinfo/lang.h: ISO-639 updates. + + * makeinfo/cmds.c: exampleindent changes. + + * info/info.c (info_short_help): reformat somewhat, and don't say + info info options any more. + + * doc/info-stnd.texi (Invoking): make description format somewhat + more standard. + + * info/infomap.c (Initialize_info_keymaps): do ea_insert bindings + first so subsequent bindings (e.g., for ESC) override. + +Sun Mar 21 17:31:00 1999 Karl Berry <karl@gnu.org> + + * makeinfo/multi.c (output_multitable_row): remove unnecessary + trailing whitespace from output, output blank row for blank @item. + + * doc/texinfo.txi: Remove extra @item in language multitable. + +Sat Mar 20 12:30:25 1999 Karl Berry <karl@gnu.org> + + * doc/texinfo.txi: Update language table from ISO 639: + http://www.iro.umontreal.ca/contrib/po/iso-639. From kama. + + * doc/texinfo.txi (exampleindent): document. + + * doc/texinfo.txi (Creating an Info File): use this for the node name. + + * doc/info.texi: Make Texinfo references consistent, etc. + +1999-03-18 Yoshiki Hayashi <g740685@komaba.ecc.u-tokyo.ac.jp> + + * makeinfo/makeinfo.c (set_default_indentation_increment): new + routine. + * makeinfo/insertion.c (cm_exampleindent): new routine. + Call set_default_indentation_increment. + +Mon Mar 15 17:06:15 1999 Karl Berry <karl@gnu.org> + + * info/Makefile.am (ginfo_SOURCES): Remove doc.c and funs.h in + hopes they then won't be distributed. Report from Andreas. + + * makeinfo/cmds.c (cm_sp): close paragraph and disable filling to + produce blank lines in info. + Report from: Michael Vanier <mvanier@bbb.caltech.edu>. + + * doc/texinfo.txi: Attempt to get Edition info on one line. + + * makeinfo/makeinfo.h (cr_or_whitespace): use whitespace and check + for \r. (skip_whitespace_and_newlines, command_char): use it. + Report from bonzini@gnu.org. + + * makeinfo/cmds.c (cm_center): save and restore filling_enabled, + so @center can be used inside an @example. Bug from kama. + +1999-03-13 Eli Zaretskii <eliz@is.elta.co.il> + + * makeinfo/footnote.c (cm_footnote): In separate footnote style, + generate a reference to "foo-Footnote-NN" for each footnote. + (output_pending_notes): In separate footnote style, generate an + anchor "foo-Footnote-NN" for each footnote, so that the link in + the parent node would lead directly to the footnote. + + * info/footnotes.c (make_footnotes_node): Recognize the new + "foo-Footnote-NN" style of footnote references. + +1999-03-09 Andreas Schwab <schwab@issan.cs.uni-dortmund.de> + + * configure.in (AC_OUTPUT): Remove command to create po/Makefile, + already done by AM_GNU_GETTEXT. + +Tue Mar 9 17:48:46 1999 Karl Berry <karl@gnu.org> + + * Makefile.am (dist-hook): make distribution directory writable. + + * Installed these changes: + + 1999-03-04 Akim Demaille <demaille@inf.enst.fr> + + * texi2dvi (bibtex): Allow several runs of bibtex, this can be + used if bibentries reference other bibentries. Moreover, looking + for `Citation' in the LOG should be enough to avoid uneless runs. + + Sun Mar 7 15:15:00 1999 UTC Karl Heinz Marbaise <kama@hippo.fido.de> + + * makeinfo/sectioning.{c,h}: + - using defines instead of literals. + - cleaned up some stylistic matters like Karl Berry + suggested. Handling of things like: + @unnumbered .. + @section ... + now it works correct. + + * makeinfo/toc.{c,h} + - addTocEntry, freeToc changed into toc_add_entry + toc_free. stylistics changed. + + * makeinfo/iso2cht.pl,iso-639: script, table from the web. + - perl script converting the iso-639 table from the web + into the appropiate files (isoenum.h, isotab.c and + iso.texi) which can be inserted directly into + lang.c, lang.h and texinfo.txi. + +Tue Mar 9 17:47:59 1999 Karl Berry <karl@gnu.org> + + * configure.in: Bump to 3.12g. + +Sun Mar 7 07:01:19 1999 Karl Berry <karl@gnu.org> + + * info/infomap.c: Don't do isprint, just bind everything. + +Fri Mar 5 14:31:42 1999 Karl Berry <karl@gnu.org> + + * doc/texinfo.txi, + * makeinfo/makeinfo.c: Document that --no-headers writes to stdout + by default. + + * doc/texinfo.txi: @setchapternewpage doesn't change + \bindingoffset, just headers. Recommend not including it in the + manual source at all. + + * makeinfo/node.c (write_tag_table_internal): set + in_fixed_width_font while constructing this so --- doesn't + collapse to --, etc. Bug report from Sergio. + + * dir-example: Add a2ps stuff. + + * info/session.c: Allow any character in search string. + + * info/infodoc.c (describe_key): don't assume non-latin1 + characters are undefined. + + * info/infomap.c (initialize_info_keymaps): make all characters + insertable by default in echo area. From Eli. + + * Installed these changes: + + Wed Feb 23 22:00:00 1999 Karl Heinz Marbaise <kama@hippo.fido.de> + + * makeinfo/sectioning.{c,h}: + - added to hold complete handling of sectioning + a little step towards modularization ;-) + + * makeinfo/cmds.c: + - sectioning_alist moved to sectioning.c and + added information about enumerated chapter, + section ..., appendix or not. Everything + which has any relationship with sectioning + moved to sectioning.{c,h} I hope I have found + all. + + * makeinfo/toc.{c,h}: + - added for complete handling of "table of contents" + "short contents". Better ASCII only support + (--no-headers) so no Text "Menu" is printed. + May be we can do more. + + * makeinfo/makeinfo.{c,h}: + - added new command line switch --number to enumerate + chapter, sections etc. + + * doc/texinfo.txi: + - --number option documented. + + 1999-02-28 Yoshiki Hayashi <g740685@komaba.ecc.u-tokyo.ac.jp> + + * makeinfo/insertion.c (in_paragraph): New variable. + (cm_item): Add </p> only if <p> is open. + * makeinfo/makeinfo.c (handle_menu_entry): Ditto. + + * makeinfo/insertion.c (begin_insertion), + * makeinfo/makeinfo.c (handle_menu_entry): If commentary + precedes first menu item, put them outside of <ul>. + Put <p> and </p> correctly. + + 1999-02-27 Eli Zaretskii <eliz@is.elta.co.il> + + * info/info.c (info_short_help): Document --show-options and + --usage. + + 1999-02-26 Eli Zaretskii <eliz@is.elta.co.il> + + * info/makedoc.c (main) [STRIP_DOT_EXE]: Strip the .exe suffix, so + that doc.c says "./makedoc.c", not "./makedoc.exe.c". + + * info/info.c (goto_invocation_p): New variable. + (long_options): New options --show-options and its alias --usage. + (main): Don't update the display until we find the first node to + be displayed, to avoid flushing incorrect display. If user wants + to see the command-line options node right away, display whatever + info_intuit_options_node finds. + + * info/session.c (info_intuit_options_node): New function, uses + heuristics to find the node which describes program's invocation. + (info_goto_invocation_node): New command, asks for a program's + name and displays the invocation node of that program. + (entry_in_menu): New function, fuzzily looks for a menu entry in a + node's menu. + (program_name_from_file_name): New function, suggests a program + name given a name of its Info file. + (info_search_in_node): Accept an additional argument: a flag to + search case-sensitively; all callers changed. If case-sensitive + search is required, don't turn on the case-fold flag in the search + binding. + (info_search_internal): Accept an additional argument: a flag to + search case-sensitively; all callers changed. Share the last + search string between normal and case-sensitive search commands. + (info_search_1): New function, with the guts that previously + belonged to info_search. If the search is case-sensitive, + mentions that in the prompt for the search string. If the search + string includes upper-case characters, searches case-sensitively. + (info_search): Calls info_search_1 with zero case-sensitivity + flag. + (info_search_case_sensitively): New command, calls info_search_1 + with non-zero case-sensitivity flag. + (incremental_search): If the search + string includes upper-case characters, searches case-sensitively. + + * info/search.c (search_backward): Fix bug in case-sensitive + search. + + * info/infomap.c (initialize_info_keymaps): `-' in info window map + produces negative arguments. `S' invokes case-sensitive search. + `O' and `I' invoke goto-invocation. + + * doc/info-stnd.texi (Invoking Info): Document --show-options. + (Node Commands): Document `O', goto-invocation. + (Searching Commands): Document `S' and the case-sensitive search + when the search string includes upper-case letters. Document `/' + as a synonym for `s'. + (Miscellaneous Commands): Document `M--' and `-'. + + 1999-02-25 Eli Zaretskii <eliz@is.elta.co.il> + + * info/info.c (main): Under --index-search, search indices *after* + following menus, so that we don't look for an index in DIR. + + +Wed Mar 3 17:20:07 1999 Karl Berry <karl@gnu.org> + + * makeinfo/cmds.c: Do not output <small> in info mode. + From: Eli Zaretskii <eliz@is.elta.co.il>. + + * makeinfo/insertion.c (enum_html): Remove unused var temp. + From: Yoshiki Hayashi <g740685@komaba.ecc.u-tokyo.ac.jp> + + * info/infodoc.c: Avoid translation of blank lines. + + * info/tilde.c, + * info/man.c, + * makeinfo/index.c (index_add_arg): avoid use of alloca. + + * info/echo-area.c: Don't pause for an additional 75 microseconds. + Noted by Eli. + + * configure.in: Bump to 3.12f. + + * doc/texinfo.txi: findex enddots. From Eli. + +1999-03-01 Yoshiki Hayashi <g740685@komaba.ecc.u-tokyo.ac.jp> + + * makeinfo/makeinfo.c (insert_html_tag): Add <p> when + paragraph is not opened. + (sectioning_html): Call close_paragraph so that paragraph + will be started. + +1999-02-26 Akim Demaille <demaille@inf.enst.fr> + + * texi2dvi (get_xref_files): Take $filename_noext as $1. + (get_xref_files): Look for $1.idx only, not *.idx. + (get_xref_files): Look for $1.cb files (\usepackage{changebar}). + * texi2dvi: Look for rerun requests in LOG files in addition to + xref files comparison. + (bibtex): Remove useless `./' (already added in + command_line_filename). + (filename_dir): Smarter sed expression that handles file names + with no directory part. + (txiversion): Removed useless () (`` already guarantee a subshell). + +1999-02-25 Andreas Schwab <schwab@issan.cs.uni-dortmund.de> + + * makeinfo/multi.c (find_template_width): Fix operator precedence. + +Tue Feb 23 10:35:53 1999 Karl Berry <karl@gnu.org> + + * dir-example: ccmode not cc-mode. From hds. + +Mon Feb 22 07:34:00 1999 Karl Berry <karl@gnu.org> + + * makeinfo/lang.c, + * doc/texinfo.txi: Fix kazakhkh typo. + +1999-02-21 Eli Zaretskii <eliz@is.elta.co.il> + + * djgpp/config.sed: Add pcterm.c to terminal.o dependencies. + +1999-02-21 Andreas Schwab <schwab@issan.cs.uni-dortmund.de> + + * makeinfo/lang.c (cm_accent_generic): Emit the accent character + only once, after the argument. + +Sun Feb 21 16:36:14 1999 Karl Berry <karl@gnu.org> + + * makeinfo/makeinfo.c (handle_menu_entry): new routine. + (reader_loop): call it, allowing for comments in menus. + + * makeinfo/node.c: Rearrange functions to make static, etc. + + * doc/Makefile.am (EXTRA_DIST, install-tex): Add txi-cs and txi-no. + +1999-02-20 Eli Zaretskii <eliz@is.elta.co.il> + + * util/install-info.c (open_possibly_compressed_file): Output + explicit message about empty input files. + (insert_entry_here): Insert multiple entries in alphabetical order. + +Fri Feb 19 09:13:28 1999 Karl Berry <karl@gnu.org> + + * makeinfo/insertion.c (enum_html): new routine. + (begin_insertion): call it. + Based on code from: Yoshiki Hayashi <g740685@komaba.ecc.u-tokyo.ac.jp>. + + * lib/xexit.c (EXIT_FAILURE) [!defined EXIT_SUCCESS && VMS]: weird + long value. + From: Lars Hecking <lhecking@nmrc.ucc.ie> + +Thu Feb 18 16:42:10 1999 Karl Berry <karl@gnu.org> + + * makeinfo/node.h (remember_node_reference): decl. + * makeinfo/makeinfo.c (find_unused_reference): dump unused decl. + +1999-02-18 Eli Zaretskii <eliz@is.elta.co.il> + + * makeinfo/cmds.c (cm_dots, cm_enddots): Don't produce … for + HTML, as too many browsers don't support it; use "..." in a + smaller font. + (cm_top): Output the lang= attribute inside <html>. + + * makeinfo/node.c (cm_node): Output the lang= attribute inside + <html>. + + * makeinfo/footnote.c (output_pending_notes): Generate <ol> + instead of <dl compact>. Make the text of each footnote start a + new paragraph. + +1999-02-17 Eli Zaretskii <eliz@is.elta.co.il> + + * makeinfo/insertion.c (cm_item): Remove <dd> when immediately + followed by a <dt>. Add a <br> before every <dt>, except if we + are converting @itemx, or in the first item after <dl>. + (begin_insertion): Use <dl> for tables, to make it look closer to + the Info output. Don't output a newline after a <pre>. + +1999-02-17 Eli Zaretskii <eliz@is.elta.co.il> + + * makeinfo/makeinfo.c (handle_variable): Don't backup input + pointer if we hit the end of text (usually, inside + execute_string). + * makeinfo/insertion.c (get_item_function): Likewise. + +Wed Feb 17 15:09:06 1999 Karl Berry <karl@gnu.org> + + * doc/texinfo.txi: Better indexing of space entries. + + * makeinfo/multi.c (find_template_width): new routine to really + parse @multitable {...} templates. + (setup_multitable_parameters): call it. + Bug report from: Sergio Pokrovskij <pok@nbsp.nsk.su>. + + * lib/system.h (substring): declare. + + * lib/Makefile.am (libtxi_a_SOURCES): add substring.c. + + * makeinfo/defun.c: Move substring to lib. + + * util/texindex.c (tempcopy): no longer used. + (maketempname): make static. + + * Installed these changes: + +1999-02-13 Eli Zaretskii <eliz@is.elta.co.il> + + * makeinfo/cmds.c (cm_acronym): New function, makes @acronym + produce a smaller font size in HTML mode. + (cm_sc): Produce smaller font size in HTML mode. + + * makeinfo/footnote.c (cm_footnote): In HTML output, make the + footnote number be a superscript; remove [] around the link. + + * makeinfo/cmds.c (cm_var_sc): Separated into two functions: + cm_var and cm_sc, since @var and @sc have different effects in + HTML output. + + * makeinfo/makeinfo.c (cm_xref, cm_inforef): Don't put "[]" around + HTML links. + + * info/pcterm.c (DJGPP_keytab): Add translation for Alt-PgUp and + Alt-PgDn, to support the new M-prior key. + +Wed Feb 17 11:50:46 1999 Karl Berry <karl@gnu.org> + + * doc/texinfo.txi: Don't mention texi2roff so prominently. + + * makeinfo/makeinfo.c: Pass enclose_expand to remember_brace + rather than enclose_command. From Eli. + + * makeinfo/macro.c (cm_alias, cm_definfoenclose): Expand macros in + first call to get_until_in_line. From Eli. + + * info/makedoc.c, + * info/session.c, + * info/man.c, + * info/tilde.c, + * info/info.c, + * makeinfo/files.c, + * makeinfo/multi.c, + * makeinfo/node.c, + * makeinfo/makeinfo.c: Use xexit. + * makeinfo/makeinfo.h (NO_ERROR, FATAL, SYNTAX): remove. + + * info/terminal.c: Avoid sleep unless on sun-cmd terminal. + + * lib/xexit.c (EXIT_FAILURE) [!EXIT_FAILURE]: #define to 1 to fix + Sony NEWS-OS 4.0C lossage. From Akim. + + * info/infodoc.c: Translate where is doc string, underline lines + in help. + From: Trond Endrestol <trond@agamemnon.gtf.ol.no> + + * makeinfo/cmds.c (cm_dots, cm_enddots): go back to ... and ...., + … apparently doesn't work widely enough. + +Tue Feb 16 07:37:54 1999 Karl Berry <karl@gnu.org> + + * configure.in (ALL_LINGUAS): add de_AT. + + * util/texi2dvi: Redirect cd output to /dev/null when determining + txiversion. + +Mon Feb 15 13:43:37 1999 Karl Berry <karl@gnu.org> + + * util/install-info.c, + * util/texindex.c: Call xexit instead of exit. + + * lib/system.h (xexit): Declare. + + * lib/Makefile.am (libtxi_a_SOURCES): Add xexit.c. + + * doc/texinfo.txi: Document that @documentencoding is used in the + HTML output. + + * makeinfo/cmds.c (cm_top): use document_encoding if set. + (command_table): call cm_documentencoding instead of no-op. + * makeinfo/lang.c (document_encoding, cm_documentencoding): define. + * makeinfo/lang.h (document_encoding, cm_documentencoding): declare. + + * makeinfo/insertion.c: Restore </p> before <li>. + + * util/texi2dvi: If texinfo.tex version is too low for macros, use + makeinfo. + + * makeinfo/cmds.c (cm_center): save and restore value of + indented_fill, otherwise @center within an @enumerate (say) + also closes the indentation. + Bug from: Sergio Pokrovskij <pok@nbsp.nsk.su>. + +Sun Feb 14 15:25:02 1999 Karl Berry <karl@gnu.org> + + * makeinfo/makeinfo.c: Doc fix. + + * doc/texinfo.txi: Be enthusiastic if people want to implement + more output formats, but use makeinfo to do the job. + + * makeinfo/index.c (index_element_compare): Use strcoll if it's + available. + * configure.in: Call AC_FUNC_STRCOLL. + * makeinfo/makeinfo.c (main): Use LC_CTYPE and LC_COLLATE + categories. Suggestion from Oleg. + + * lib/system.h (setlocale) [!HAVE_SETLOCALE]: #define away. + Suggestion from Akim. + + * doc/texinfo.txi: Document @paragraphindent working in TeX now. + + * doc/texinfo.txi, + * makeinfo/lang.c, + * makeinfo/lang.h (language_code_type): abbrev changes from Oleg. + + * makeinfo/cmds.c, + * makeinfo/node.c: Only translate `Next:', `Previous:', and `Up:', + not the whole href. From Eli. + + * doc/texinfo.txi: Document that only unsplit html output is + supported in this release. + +Sat Feb 13 17:55:30 1999 Karl Berry <karl@gnu.org> + + * configure.in: Check for termlib before termcap for sake of + Solaris (judging from less-332 configure.in) and maybe + HP-UX 11. + + * doc/texinfo.txi (Footnote commands): incoherency reported by Aharon. + Language vs country fixes from Oleg. + +1999-02-13 Karl Eichwalder <ke@gnu.franken.de> + + * makeinfo/node.c (cm_node): Tag navigation links as translatable. + * makeinfo/cmds.c (cm_top): Ditto. + +Wed Feb 10 22:00:00 1999 Karl Heinz Marbaise <kama@hippo.fido.de> + + * makeinfo/defun.h: + - new because we need get_base_type-function + accessible in insertion.c + + * makeinfo/defun.c: + - complete HTML handling of the @def... things. + + * makeinfo/Makefile.am: + - defun.h added as part of makeinfo. + + * makeinfo/makeinfo.c: + - define looking_at moved into header-file, because + we need it in defun.c + + * makeinfo/insertion.c: + - some minor changes made to support the @def... + things in HTML. + + * makeinfo/lang.c: (cm_accent_generic) + - bug fixed. Using umlaut (accent ...) + would produce &A only if an umlaut follows + an empty line. + - bug fixed. Because things like ˜ ` + and ˆ do not exist as standalone characters + in HTML. + - cm_special_char now produce correct HTML for + @O{} and @o{}. + - warning using _("Text") instead "Text" (gettext). + + * makeinfo/cmds.c: + - @url fixed. Display the given Text. + + * doc/texinfo.txi: + - corrected the references for @uref, because + they were given as "url" instead of "uref". + @uref has three arguments, so show them in + command list. + +Wed Feb 10 17:27:58 1999 Karl Berry <karl@gnu.org> + + * doc/texinfo.txi: Rewrite for overfull box. + +Tue Feb 9 19:03:16 1999 Karl Berry <karl@gnu.org> + + * doc/texinfo.txi: Document more HTML output stuff. Based on esr + changes. + * makeinfo/macro.c, + * makeinfo/macro.h, + * makeinfo/makeinfo.c: Do alias and definfoenclose expansion. + From esr. + +Mon Feb 8 14:41:07 1999 Karl Berry <karl@gnu.org> + + * makeinfo/cmds.c: New commands @alias and @definfoenclose. + From: "Eric S. Raymond" <esr@snark.thyrsus.com>. + + * doc/texinfo.txi: Document @documentlanguage and + @documentencoding. + + * makeinfo/cmds.c: Move accent support to lang.c. + + * makeinfo/makeinfo.c (add_char): add rather than an 8-bit + char for html. + + * makeinfo/Makefile.am (makeinfo_SOURCES): add lang.[ch]. + + * doc/texinfo.txi: Be even more emphatic that @url is not + typically what you want. + * doc/texinfo.txi: Document that macro calls must use empty + braces. + + * info/session.c: Do not translate node pointers. From Karl E. + + * makeinfo/cmds.c (cm_dfn): Use <dfn>. Suggestion from Eli. + +Sun Feb 7 07:00:08 1999 Karl Berry <karl@gnu.org> + + * makeinfo/makeinfo.c: Make --html imply --no-split. + + * makeinfo/cmds.c (cm_top): don't core dump if the top node has no + next. + + * makeinfo/makeinfo.c (replace_with_expansion): compare length + after expansion with length of full input text before + expansion, not just the length of the expanded text. + Bug (contents2) reported by kama. + + * info/infodoc.c (create_internal_info_help_node): gettext calls + to help msg strings. From Ulrich. + +Fri Feb 5 17:35:13 1999 Karl Berry <karl@gnu.org> + + * util/texi2dvi: set makeinfo= for latex case. + + * doc/texinfo.txi (@deftp summary): ref Data Types node that + actually describes it. From kama. + +Thu Feb 4 07:39:10 1999 Karl Berry <karl@gnu.org> + + * makeinfo/makeinfo.c: Take it back. Emacs info needs that text + before the CTRL-_. + * makeinfo/makeinfo.c: Don't bother to output the header (This is + -, produced ...) to stdout. + + * doc/texinfo.txi (Other Info Directories): Mention that dir files + must be named dir. + + * makeinfo/makeinfo.c (cm_uref): implement optional third + argument. + * doc/texinfo.txi (uref): document it. + Suggestion from: Charles Karney <karney@pppl.gov> + + * doc/Makefile.am (info_TEXINFOS): put texinfo.txi first so + UPDATED reflects its modtime, rather than info-stnd's. + + * makeinfo/files.c (full_pathname) [!WIN32]: #endif in wrong place. + From: Yoshiki Hayashi <g740685@komaba.ecc.u-tokyo.ac.jp> + + * makeinfo/cmds.c (cm_url): Remove URL: from output. It's ugly. + +Wed Feb 3 16:05:03 1999 Karl Berry <karl@gnu.org> + + * info/infodoc.c: Doc fix, zero not oh. + + * makeinfo/makeinfo.c (add_char): don't ignore if + only_macro_expansion, even in no_headers case. + Otherwise menu items don't get remembered and defaulting + doesn't work. Macros suck! + + * util/texi2dvi (common): include orig_pwd. + (language): reguess for each file if not explicitly set. + +Tue Feb 2 16:22:32 1999 Karl Berry <karl@gnu.org> + + * configure.in: Bump to 3.12d now. + +Mon Feb 1 14:46:45 1999 Karl Berry <karl@gnu.org> + + * makeinfo/insertion.c (cm_item): For itemize and enumerate, do + </p> before the <li> for html. Bug from Eli. + + * makeinfo/index.c: Installed change in index.c: + Mon Dec 28 12:50:14 1998 Matthew Fredette <fredette@mit.edu> + * makeinfo.c (index_add_arg): Use xstrdup on input_filename + when saving it in the new index entry. + + * util/texi2dvi: cd / before cd $orig_pwd in case of DOS drive + change. + +Sun Jan 31 16:39:01 1999 Karl Berry <karl@gnu.org> + + * util/texi2dvi: Used sed to expand only the @{if,}tex parts of + the source since makeinfo's conditional options aren't ready yet + (from Akim). + Also use ${1+"$@"} for Digital Unix "$@" expansion bug (from Noah). + + * util/install-info.c: Doc fix from Eli. + + * doc/texinfo.txi: Oops, said we looked for .png twice. + +Sat Jan 30 17:18:14 1999 Karl Berry <karl@gnu.org> + + * info/session.c (forward_move_node_structure): remove tangled + code to merely print words instead of numbers; too hard to translate. + + * info/session.c: Missing _'s for more i18n. From Trond. + + * doc/Makefile.am (EXTRA_DIST): Include txi-no.tex from Trond. + +Sun Jan 24 09:28:12 1999 Karl Berry <karl@gnu.org> + + * Makefile.am (EXTRA_DIST): Use djgpp by itself instead of listing + each file separately (new feature in automake 1.4). + + * makeinfo/insertion.c (begin_insertion): for quotation, always + increment current_indent even if html output, why not. + (Otherwise must not decrement current_indent in end_insertion.) + + * doc/texinfo.txi: More overfull box fixes. + + * makeinfo/insertion.c: Add some assertions and the beginnings of + handling @tex. + + * doc/texinfo.txi: Fix overfull boxes, but tables of contents at + the front. + + * util/texi2dvi: Can't pass --no-ifinfo --iftex to makeinfo yet, + it's not ready. + +Sat Jan 23 10:22:16 1999 Karl Berry <karl@gnu.org> + + * util/texi2dvi: Pass --no-ifinfo --iftex to makeinfo. + +Fri Jan 22 19:09:49 1999 Karl Berry <karl@gnu.org> + + * doc/texinfo.txi: Include version.texi before @settitle so + @value{VERSION} gets expanded in the html title. From kama. + + * These patches from Tim Singletary <talon@clark.net>. + * makeinfo/makeinfo.c: Simplify and improve html menus. + * makeinfo/insertion.c (begin_insertion): simplify html menu case + and set had_menu_commentary. + * makeinfo/insertion.h (had_menu_commentary): declare new global. + * makeinfo/node.h (glean_node_from_menu): declare. + * makeinfo/node.c (glean_node_from_menu): new arg to specify what + type of reference to remember as. + + Date: Sun, 29 Nov 1998 09:21:01 -0500 (EST) + From: Tim Singletary <tsingle@talon.clark.net> + To: texinfo-pretest@tug.org + Subject: explanation of previous patches + + > These diffs introduce some non-trivial changes into very + > sensitive parts of makeinfo, and it is hard to judge them without + > knowing what exactly do they solve. + + At a high level, these patches fix (or at least significantly improve) + the html conversion of menus. Specifically, they fix bugs in the + conversion of menu commentary and detailmenu entries. + + The menu commentary fixes require some justification: The unpatched + makeinfo attempts, with many bugs, to place menu commentary outside + the <menu> by adding </ul> and <ul> tags. While I understand the + motivation for this, that there might be browsers that don't support + <p> within <menu>, I'm not aware of any such browser and don't see any + compelling reason to continue the </ul> kludge. + + Certainly + <menu> + <li>First paragraph. + <p>Second paragraph. + <li>Second item. + </menu> + is valid html! + + Anyway, here's what my patches do: + + 1) Deleted the `<h4>Menu</h4>' at the beginning of each menu. Using + `<h4>' is wrong since menus don't usually come after an `h3' + header. `<b>' looks the same on most browsers, but my opinion is + that there's no need for any header at all! + + 2) Deleted the `<li>' kludge at the begining of each menu. It's no + longer needed since I'm deleting the </ul> kludge. + + 3) Replace `in_menu_para', declared static in makeinfo.c:add_char() + with `had_menu_commentary', declared globally. Modified + insertion.c:begin_insertion() to initialize had_menu_commentary to + 1 when beginning a menu. Now there's enough state information for + menu commentary to be processed within <menu> ... </menu>; the + commentary can be seperated from the rest of the menu by bracketing + it between <p>'s. + + Note that the first patch had a bug initializing + had_menu_commentary; the second patch fixes this bug. + + 4) Changed the semantics of the argument to + node.c:glean_node_from_menu(). Previously, glean_node_from_menu() + only called remember_node_reference() when the argument was + non-zero. But add_char() didn't call `glean_node_from_menu(1)' + when processing detailmenu entries. In other words, detailmenu + entries didn't get registered as references, which lead to the html + conversion of detailmenu entries not producing proper hrefs! + + The new semantics are that glean_node_from_menu always calls + remember_node_reference(), but calls it with `menu_reference' when + the first arg to glean_node_from_menu() is 1 and with + `followed_reference' otherwise. Now, detailmenu entries get + registered as `followed_reference' (normal menu entries still get + registered as `menu_reference') and the html conversion produces + proper hrefs. + + 5) The above changes made it possible to streamline the section of + add_char() that deals with html menu text. + + 6) In an otherwise unrelated change, rewrote a section of + glean_node_from_menu to no longer use `goto save_node;'. + + +Thu Jan 21 12:55:42 1999 Karl Berry <karl@gnu.org> + + * doc/info-stnd.texi: OK, let's try restoring the @include + version.texi with the new automake. + + * makeinfo/cmds.c: Improve HTML @pounds, @bullet, etc. + + * doc/Makefile.am (install-tex): new target. + (EXTRA_DIST): Include txi-??.tex. + txi-de.tex: new file from kama. + + * Makefile.am (AUTOMAKE_OPTIONS): Bump to 1.4. + (install-tex): new target. + + * util/texi2dvi: Restore "$@" for explicitness in main loop. + + * doc/Makefile.am (*.1) [TEXINFO_MAINT]: Conditionalize. + + * configure.in (AC_PREREQ): Bump to 2.13. + (TEXINFO_MAINT): Define this AM_CONDITIONAL. + + * doc/texinfo.txi: Document that the HTML output name is derived + from @setfilename. + + * makeinfo/makeinfo.c (convert_from_loaded_file): Use @setfilename + for basename of html output. + + * doc/texinfo.txi (url): Use example.org for the example. + + * makeinfo/cmds.c (cm_url): @url should not produce a link, sorry + to say. + +Wed Jan 20 16:31:55 1999 Karl Berry <karl@gnu.org> + + * util/texindex.c, + * util/install-info.c, + * makeinfo/makeinfo.c, + * info/info.c: It's 1999. + + * doc/info.texi (Advanced info commands): Fix typos from Gildea. + + * makeinfo/makeinfo.c (end_of_sentence_p): don't check negative + array offset. + From: Enrico Scholz <enrico.scholz@wirtschaft.tu-chemnitz.de> + +Sun Jan 17 16:42:16 1999 Karl Berry <karl@gnu.org> + + * util/texi2dvi: Restore --batch, handle changing escape character + more cleanly. From Akim (as always). + +Thu Jan 14 16:47:41 1999 Karl Berry <karl@gnu.org> + + * configure.in (ALL_LINGUAS): Add no. + From: Trond Endrestol <trond@agamemnon.gtf.ol.no> + + * util/texi2dvi: Doc fix from Akim and do not always exit 1 from trap. + And it's 1999. + + * doc/texinfo.txi (image): Document imagename.pdf. + + * Apply this change from Eli: + + 1998-11-20 Eli Zaretskii <eliz@is.elta.co.il> + + * makeinfo/makeinfo.h (meta_char_pos): New variable. + * makeinfo/makeinfo.c (init_paragraph): Initialize it. + (add_char): Use META to create a non-breakable space character. + (add_meta_char): New function. + (end_of_sentence_p): Don't handle characters at meta_char_pos as + normal sentence enders. + (flush_output): Only unMETA the non-breaking space character. + Reset meta_char_pos to zero. + (do_flush_right_indentation): Call adjust_braces_following. + (indent): Likewise. + (cm_value): Save and restore the value of meta_char_pos. + (expansion): Likewise. + * makeinfo/macro.c (me_execute_string_keep_state): Save and + restore the value of meta_char_pos. + * makeinfo/node.c (cm_node): Save and restore the value of + meta_char_pos. + * makeinfo/cmds.c (cm_accent): Make the dot we add due to + @dotaccent be a meta-character. + (cm_code, cm_dfn): Call add_meta_char to insert the closing + quote. + (cm_cite): Call add_char instead of add_word. + +Thu Jan 7 18:04:26 1999 Karl Berry <karl@gnu.org> + + * util/texi2dvi: Handle pdf files more cleanly. From Akim. + +Wed Jan 6 17:49:11 1999 Karl Berry <karl@gnu.org> + + * makeinfo/makeinfo.c (cm_image): Check for .png also. + +Sun Dec 20 07:54:47 1998 Karl Berry <karl@gnu.org> + + * util/texi2dvi: Add --pdf. + + * util/texi2dvi: New option -@ to use @input and @nonstopmode, in + case texinfo is preloaded. + From: Khimenko Victor <khim@sch57.msk.ru> + Date: Sun, 20 Dec 1998 02:04:12 +0300 (EET) + +Sat Dec 19 17:37:37 1998 Karl Berry <karl@gnu.org> + + * doc/texinfo.txi (Multitable Column Widths): leading zero ok for + @columnfractions. + + * util/texi2dvi: New version from Akim, plus --quiet is like + --batch, etc. + +Fri Dec 18 17:22:44 1998 Karl Berry <karl@gnu.org> + + * doc/texinfo.txi: Document that the Texinfo source can't be + arbitrarily ordered (for print) even if all pointers are supplied. + + * makeinfo/insertion.c (end_insertion): In itemize case, + close_insertion_paragraph so @end itemize cause a line break. + Report from: Sergei Pokrovsky <pok@nbsp.nsk.su> + Date: Sun, 22 Nov 1998 19:45:21 +0700 (GMT) + +Tue Dec 15 16:21:51 1998 Karl Berry <karl@gnu.org> + + * doc/texinfo.txi: More fixes from Oleg. + + * configure.in: Bump version to 3.12c for next pretest. + + * util/install-info.c (open_possibly_compressed_file) + [STRIP_DOT_EXE]: logic for compression_program assignment + was reversed. + From: wlestes@wlestes.uncg.edu + +Sat Dec 12 18:02:48 1998 Karl Berry <karl@gnu.org> + + * Merged these changes from Andreas: + +1998-12-06 Andreas Schwab <schwab@issan.cs.uni-dortmund.de> + + * makeinfo/node.c (cm_node): When searching for @menu don't + require a space after it. + +1998-12-06 Andreas Schwab <schwab@issan.cs.uni-dortmund.de> + + * makeinfo/cmds.c (cm_top): free top_name only after done using it. + +Sat Dec 12 15:40:13 1998 Karl Berry <karl@gnu.org> + + * doc/texinfo.txi: Various typos and fixes from Oleg. + + * doc/texinfo.txi: Move @node's outside of @ifinfo for the sake of + HTML processing. + + * doc/texinfo.txi (titlepage): @pxref was not in parens. From Oleg. + +Sun Dec 6 16:49:09 1998 Karl Berry <karl@gnu.org> + + * dir-example: Amd is now am-utils. + + * doc/Makefile.am: Reinstate help2man invocations for development. + + * doc/texinfo.txi: Document @set...contentsaftertitlepage (from kama). + Fix incorrect sense for @image and Hungariam typo (from Oleg). + + * lib/system.h: #include libintl.h here instead of acconfig.h, so + the system include files have a chance to #define NULL + before it does. + * acconfig.h: Remove libintl.h and #defines from here. + From: "Philippe De Muyter" <phdm@macqel.be> + Date: Fri, 4 Dec 1998 00:56:25 +0100 (CET) + + * info/signals.c: Start #ifdef's in column one for cc on sysv68 + (m68k-motorola-sysv). + From: "Philippe De Muyter" <phdm@macqel.be> + Date: Fri, 4 Dec 1998 00:56:25 +0100 (CET) + + * info/filesys.c (is_dir_name): use strcpy instead of automatic + array initialization. + From: "Philippe De Muyter" <phdm@macqel.be> + Date: Fri, 4 Dec 1998 00:56:25 +0100 (CET) + + * configure.in (ALL_LINGUAS): add ru. + +Fri Dec 4 08:12:11 1998 Karl Berry <karl@gnu.org> + + * info/infodoc.c: Gettextize the help buffer string. + +Sun Nov 29 17:12:35 1998 Karl Berry <karl@gnu.org> + + * doc/texinfo.txi: Use @ifnottex rather than @ifinfo for @top. + (makeinfo top): document this. + + * doc/info-stnd.texi, + * doc/info.texi: Use @ifnottex rather than @ifinfo for @top. + + * makeinfo/insertion.c (cm_menu): Implicitly insert @top command + so we can construct the node tree as usual when we see @menu + before @node. Probably this is when the input uses + @ifinfo instead of @ifnottex, as virtually all existing + manuals do. + + * makeinfo/insertion.c (discard_insertions): Let any conditional + cross node boundary. (So the @top node can be wrapped + in @ifnottex, for example.) + + * Installed these: + +1998-11-21 Eli Zaretskii <eliz@is.elta.co.il> + + * makeinfo/makeinfo.c (expansion): Save and restore + last_inserted_character and last_char_was_newline. + + * makeinfo/cmds.c (cm_dircategory): Kill any indentation before + INFO-DIR-SECTION. install-info relies on this. + +1998-11-20 Eli Zaretskii <eliz@is.elta.co.il> + + * makeinfo/multi.c (struct env): Add meta_char_pos member. + (select_output_environment): Save and restore meta_char_pos. + (out_char): Output characters by switching environment to #0 and + calling insert. Call flush_output when a newline is output. + (output_multitable_row): Update the current environment's + output_paragraph_offset as well, after removing trailing + whitespace. Fix typo in loop index. + (do_multitable): Call close_single_paragraph. + (end_multitable): Call close_insertion_paragraph. Don't output + an extra newline. + +1998-11-20 Eli Zaretskii <eliz@is.elta.co.il> + + * makeinfo/makeinfo.h (meta_char_pos): New variable. + * makeinfo/makeinfo.c (init_paragraph): Initialize it. + (add_char): Use META to create a non-breakable space character. + (add_meta_char): New function. + (end_of_sentence_p): Don't handle characters at meta_char_pos as + normal sentence enders. + (flush_output): Only unMETA the non-breaking space character. + Reset meta_char_pos to zero. + (do_flush_right_indentation): Call adjust_braces_following. + (indent): Likewise. + (cm_value): Save and restore the value of meta_char_pos. + (expansion): Likewise. + * makeinfo/macro.c (me_execute_string_keep_state): Save and + restore the value of meta_char_pos. + * makeinfo/node.c (cm_node): Save and restore the value of + meta_char_pos. + * makeinfo/cmds.c (cm_accent): Make the dot we add due to + @dotaccent be a meta-character. + (cm_code, cm_dfn): Call add_meta_char to insert the closing + quote. + (cm_cite): Call add_char instead of add_word. + +Sun Nov 29 16:30:06 1998 Karl Berry <karl@gnu.org> + + * info/info.h, + * info/footnotes.h (FOOTNOTE_LABEL), + * info/indices.c (APROPOS_NONE): Use N_ rather than _. + + * info/infodoc.c (create_internal_info_help_node, + function_documentation): Do not translate the empty string. + Date: Fri, 25 Sep 1998 15:09:42 +0400 + From: "Oleg S. Tihonov" <tihonov@ffke-campus.mipt.ru> + + * doc/info-stnd.texi: Mention PRIOR as another alias for + PREVIOUS/PageUp. + + * doc/texinfo.txi: @emph produces _emph_ not *emph*. Spurious + junk before makeinfo bison example. + From: tihonov@ffke-campus.mipt.ru. + +1998-11-16 Eli Zaretskii <eliz@is.elta.co.il> + + * makeinfo/defun.c (defun_internal): Don't expand the arguments to + @defun and its ilk. + + * makeinfo/makeinfo.c (expansion): Copy the name of the currently- + executing command and restore it after expansion. + +Sun Nov 15 17:40:51 1998 Karl Berry <karl@gnu.org> + + * makeinfo/makeinfo.c: Rearrange usage, allow -v for verbose, only + output `Making' line when verbose. + * makeinfo/makeinfo.h (process_html, process_info, process_tex): + declare. + * makeinfo/cmds.c: Use conditional commands. + * makeinfo/insertion.c (find_type_from_name): Handle rawhtml and + rawtex. + (conditional commands): Allow individual switching on and off. + + * makeinfo/insertion.h: Declare conditionals. + +1998-11-14 Eli Zaretskii <eliz@is.elta.co.il> + + * makeinfo/insertion.c (begin_insertion, end_insertion): Use <pre> + to convert @display and @smalldisplay into HTML. + + * makeinfo/cmds.c (cm_asterisk): Don't insert an extra newline in + HTML mode, since input includes a newline right after the @*. + (cm_sp): Output "<br><p>\n" as many times as the argument says. + (cm_url): Don't include "<a href=" in the anchor text in HTML + output. + + * makeinfo/makeinfo.c (cm_pxref): Don't add a period after @pxref + if in HTML mode. + (get_rest_of_line): Accept an additional argument EXPAND, and + expand the rest of line if it's non-zero. All callers changed. + (close_paragraph): When in HTML mode, honor the formatting of the + source paragraphs by generating "<p>" for every closed paragraph; + follow it by as many "<p>"'s as paragraph_spacing specifies. + +Sat Nov 14 17:38:27 1998 Karl Berry <karl@gnu.org> + + * makeinfo/insertion.c: Use <ul compact> instead of deprecated <menu>. + Omit extra <li> after the menu beginning. + + * makeinfo/index.c: Use <ul compact> instead of deprecated <menu>. + +Thu Nov 12 16:33:09 1998 Karl Berry <karl@gnu.org> + + * Makefile.am (EXTRA_DIST): add djgpp/config.sed. + + * info/terminal.c: #include <sys/ioctl.h> to define TIOCGWINSZ + under LynxOS. From: Marius Groeger <mag@sysgo.de>. + +1998-11-06 Andreas Schwab <schwab@issan.cs.uni-dortmund.de> + + * makeinfo/insertion.c (begin_insertion): Correctly handle + ifnottex and ifnothtml. + (end_insertion): Likewise. + +Sun Nov 8 17:30:23 1998 Karl Berry <karl@gnu.org> + + * makeinfo/index.c, + * makeinfo/insertion.c: Menu is special to Info. + * makeinfo/node.c: Top is a special name, don't translate it. + * info/session.c (info_top_node): Top is a special name, don't + translate it. + From: "Oleg S. Tihonov" <tihonov@ffke-campus.mipt.ru>. + +Fri Nov 6 17:18:43 1998 Karl Berry <karl@gnu.org> + + * configure.in: Version 3.12b. + + * util/texi2dvi: Fixes from Eli and Christoph Martin. + + Mon Oct 5 13:58:53 1998 Dave Glowacki <dglo@ssec.wisc.edu> + * util/install-info.c: Fix off-by-one error in findlines() + + * util/texindex.c (usage): avoid trigraph until Ulrich fixes + po2tbl.sed.in. From Paul Eggert. + +1998-11-03 Eli Zaretskii <eliz@is.elta.co.il> + + * makeinfo/makeinfo.c (cm_xref): Don't bypass the test that an + xref ends with a period or a comma if the reference has a single + argument. + +1998-10-31 Eli Zaretskii <eliz@is.elta.co.il> + + * makeinfo/insertion.c (end_insertion): Don't decrement + in_fixed_width_font when leaving a menu, the previous value is + restored by pop_insertion. + + * makeinfo/makeinfo.c (add_char): Don't increment output_column + twice when a newline is inserted into the output. + + * doc/texinfo.txi (emph & strong): Document the use of underscores + for @emph in the Info output. + +1998-10-30 Eli Zaretskii <eliz@is.elta.co.il> + + * djgpp/config.bat: Make sure intl/po2tblsed.in exists before we + begin the configure boogie. + * djgpp/config.sed: Sed script, to be run by config.bat. + + * doc/info-stnd.texi (Node Commands): Document the new G command. + + * info/session.c (info_follow_menus): Step over a possible leading + space in a menu entry in menus[]. + (split_list_of_nodenames): Renamed from split_words. Split the + string on commas, not on spaces, since a menu entry can have + embedded whitespace. Get past the null byte after inserting it. + (info_menu_sequence): Don't crash if there's no DIR node; try + using Top of the current Info file, and if that doesn't work + either, throw an error. + + * util/texi2dvi: Use $path_sep in TEXINPUTS. Don't include any + dots in $tmpdir, 8+3 filesystems won't like that. + + * makeinfo/makeinfo.c (reader_loop): Expand any macros in a menu + entry when creating a <menu> item for HTML. Fix an off-by-one + error in counting input lines. + + * makeinfo/files.c (expand_filename): Don't treat .foo/bar as + absolute file name. + + * makeinfo/makeinfo.c (add_char): Use strncpy instead of memcpy, + since the buffers overlap. If the line being refilled includes + nothing but the indentation and the word being added, do NOT add + an extra newline. + + * util/install-info.c (strip_info_suffix, menu_item_equal, + open_possibly_compressed_file) [__MSDOS__]: Allow .inz and .igz as + suffuxes for compressed files. + (open_possibly_compressed_file): Return an indication whether we + opened a file or a pipe. Use FOPEN_RBIN from system.h. + [STRIP_DOT_EXE]: Use gzip.exe with an explicit .exe extension. + [O_BINARY]: If the file is not compressed, switch its stream to + text mode. + (readfile): Close the file or the pipe. + (output_dirfile): Call pclose to actually run the compressor. + +Thu Nov 5 08:33:06 1998 Karl Berry <karl@gnu.org> + + * doc/texinfo.txi: effect -> affect + From: Eric Hanchrow <offby1@blarg.net> + +Tue Nov 3 14:26:59 1998 Karl Berry <karl@gnu.org> + + * makeinfo/makeinfo.c (cm_image): Allocate enough space for the + zero byte. + + * doc/texinfo.txi: Document epsf.tex standard location. + +Tue Oct 27 10:45:47 1998 Karl Berry <karl@gnu.org> + + * Makefile.am (TEXINFO_TEX): add definition. + + * doc/info-stnd.texi: Avoid unnecessary overfull boxes from + examples. + + * doc/Makefile.am (install-data-local): missing ". + + * doc/Makefile.am: Don't try to run help2man in distribution. + +Mon Oct 26 13:43:53 1998 Karl Berry <karl@gnu.org> + + * configure.in (TEXMF): lose this whole block. It is too painful + to maintain with the different tex installations out there. + + * util/Makefile.am (EXTRA_DIST): update-info renamed to + fix-info-dir. + + * makeinfo/footnote.h: Doc fix. + + * makeinfo/multi.c: #include "insertion.h" + * makeinfo/cmds.c: #include "node.h" + * makeinfo/makeinfo.h, + * makeinfo/makeinfo.c: Move globals, functions for insertions and + nodes. + * makeinfo/defun.c: #include "insertion.h" + * makeinfo/Makefile.am: Add insertion.[ch], node.[ch]. + * node.[ch], insertion.[ch]: New files. + + * makeinfo/makeinfo.c, + * makeinfo/makeinfo.h: Move globals for cmds.h. + * makeinfo/index.h: Include cmds.h. + * makeinfo/Makefile.am (makeinfo_SOURCES): Add cmds.h, cmds.c. + * cmds.c, cmds.h: New files. + +Sat Oct 24 17:28:14 1998 Karl Berry <karl@gnu.org> + + * makeinfo/makeinfo.c, + * makeinfo/makeinfo.h: Globals for files.c. + * makeinfo/Makefile.am (makeinfo_SOURCES): add files.[ch]. + +Tue Oct 20 17:03:10 1998 Karl Berry <karl@gnu.org> + + * makeinfo/Makefile.am (makeinfo_SOURCES): add macro.c and + macro.h. + * makeinfo/makeinfo.c: Move macro code to macro.h and macro.c. + * makeinfo/makeinfo.h: Move macro stuff to macro.h, expose global + last_char_was_newline for macro.c. + * makeinfo/index.c, + * makeinfo/footnote.c: #include macro.h. + +Wed Oct 7 16:24:07 1998 Karl Berry <karl@gnu.org> + + * doc/info-stnd.texi: For now don't include version.texi due to + automake error. + + * makeinfo/index.h: #include makeinfo.h for sake of COMMAND type. + * makeinfo/index.c: No need to include makeinfo.h, index.h does + now. + + * makeinfo/makeinfo.c: Move footnote code to footnote.c. + * makeinfo/makeinfo.h: Globals for footnote.c. + * makeinfo/Makefile.am (makeinfo_SOURCES): add footnote.[ch]. + + * makeinfo/makeinfo.c: Move defun code to defun.c, necessary + global to makeinfo.h. + * makeinfo/makeinfo.h (default_indentation_increment): move here + for defun.c. + * makeinfo/Makefile.am (makeinfo_SOURCES): add defun.c. + + * Makefile.am: Doc fix. + + * configure.in (AC_OUTPUT): generate makeinfo/tests/Makefile. + + * makeinfo/makeinfo.c, + * makeinfo/makeinfo.h, + * makeinfo/Makefile.am (makeinfo_SOURCES): add index.[ch]. + +Fri Oct 2 17:42:26 1998 Karl Berry <karl@gnu.org> + + * lib/system.h (STREQ): new macro. + +Thu Oct 1 09:26:57 1998 Karl Berry <karl@gnu.org> + + * doc/texinfo.txi: Delete spare copy since out of date, + add makeinfo html to menu, + detailmenu doesn't take braces in summary. + +Wed Sep 30 14:38:21 1998 Karl Berry <karl@gnu.org> + + * makeinfo/makeinfo.c: Remove != NULL comparisons, + xmalloc/xrealloc casts, assignments in if statements. + +Wed Sep 30 14:16:01 1998 Karl Berry <karl@cs.umb.edu> + + * makeinfo/makeinfo.c: Remove NULL casts and parentheses in return + statements. + + * makeinfo/makeinfo.c (add_link): Don't add a link if the node is null. + (reader_loop): don't glean_node_from_menu if detailmenu, even if html. + Various formatting changes. + + * doc/help2man: Always exit successfully. + + * makeinfo/Makefile.am (SUBDIRS): add. + (makeinfo_SOURCES): no more html.h. + +Fri Sep 11 18:47:15 1998 Karl Berry <karl@cs.umb.edu> + + * makeinfo/makeinfo.c: Fiddle with html output. + +1998-09-07 Eli Zaretskii <eliz@is.elta.co.il> + + * makeinfo/makeinfo.c (maybe_update_execution_strings): Only + reallocate TEXT if the existing storage is too small, otherwise + leave TEXT alone. + (replace_with_expansion): Call maybe_update_execution_strings to + reallocate input_text if we are executing_string, since storage + for execution_string is assumed to be large enough to hold every + possible string. + (me_execute_string): xstrdup the argument, so callees could freely + relocate it as needed. + +1998-09-06 Eli Zaretskii <eliz@is.elta.co.il> + + * makeinfo/makeinfo.c (replace_with_expansion): Don't remember + macro-expansion pointers if we are executing_string. + +1998-09-05 Eli Zaretskii <eliz@is.elta.co.il> + + * info/filesys.c (info_suffixes): Put the empty suffix last in the + list, so that `foo.info' is found before `foo', if both exist. + +1998-09-05 Eli Zaretskii <eliz@is.elta.co.il> + + * makeinfo/makeinfo.c (maybe_update_execution_strings): New + function, updates an entry in execution_strings[] array after + input_text is relocated by replace_with_expansion. + (replace_with_expansion): Call it. + +1998-09-04 Eli Zaretskii <eliz@is.elta.co.il> + + * makeinfo/makeinfo.c (expand_macro): If a macro is called with + too many arguments, return NULL and print the line number where + the call begins. + (execute_macro): If expand_macro returns NULL, return + immediately. + +Sun Sep 6 19:11:28 1998 Karl Berry <karl@cs.umb.edu> + + * makeinfo/makeinfo.c, + * makeinfo/makeinfo.h, + * makeinfo/multi.c: Html output. Specifically, these changes: + + Fri Jul 4 22:58:29 1997 Dave Love <d.love@dl.ac.uk> + + * doc/makeinfo.texi: Document HTML output. + + * makeinfo/makeinfo.c: Wrap strings in _() in bits changed for + HTML. + (cm_image): Generate <img> for HTML. + + Sun Jun 22 22:50:07 1997 Dave Love <d.love@dl.ac.uk> + + * makeinfo/makeinfo.c (NAMED_NODE_ANCHORS): New define. + (title, outstanding_node, node_number, node_node_references, + escape_html, ifinfo_as_html): New variables. + (tentry.number, node_ref.number, fn.number): New fields. + (CommandTable): Various additions and alterations for HTML. + (long_options): Add html and no-info-as-html. + (main): Extra code for HTML. + (usage): Add HTML stuff. + (expand_filename): Deal with .html. + (escape_string): New procedure. + (convert_from_loaded_file): Extra code for HTML. + (init_internals): Call free_node_references, initialize + node_number. + (reader_loop): Process menu items for HTML hyperlinks. Escape + HTML special characters. + (add_char): Code for line breaks and paragraph insertions in + HTML. + (flush_output): Don't UNMETA for HTML. + (indent): Do nothing for HTML. + (current_item_function): Case for ifhtml. + (begin_insertion): Deal with HTML in various cases. + (insert_html_tag): new procedure. + (cm_asterisk, cm_copyright, cm_accent, cm_code, cm_kbd, + cm_angle_brackets, cm_var, cm_defn, cm_var, cm_emph, cm_string, + cm_cite, cm_top, cm_xref, cm_inforef, cm_uref, cm_direntry, + cm_ifinfo, cm_item, process_defun_args, defun_internal, cm_sp, + cm_dircategory, cm_center, cm_result, cm_expansion, cm_error, + cm_exdent, index_add_arg, make_index_entries_unique, + cm_printindex, cm_footnote, output_pending_notes, + me_execute_string): Code for HTML. + (cm_shyph): New procedure. + (cm_special_char): Add start, end args. Code for HTML. + (cm_email, cm_url, cm_i, cm_b, cm_r): New procedures. + (sectioning_html): New procedure. + (sectioning_underscore): Use it. + (add_link): New procedure. + (remember_node): Add number field and update node_number. Note + next, etc. nodes for HTML. + (add_escaped_anchor_name, add_anchor_name): New procedures. + (cm_node): New code for HTML. Move some other code to more + useful place. + (remember_node_reference): Add number field and update + node_number. + (remember_node_node_reference, free_node_node_references, + number_of_node): New procedures. + (cm_ifhtml, cm_html): New procedures. + (expansion): Take care of HTML escaping. + (cm_settitle): New procedure. + (remember_note): Set number field. + + Declare various procedures in advance. + + * doc/texinfo.txi: Makeinfo --html documentation from Dave Love. + Typo fixes from: Paul DuBois <dubois@primate.wisc.edu>. + +Thu Sep 3 11:11:01 1998 Karl Berry <karl@cs.umb.edu> + + * makeinfo/Makefile.am (makeinfo_SOURCES): add html.[ch]. + +1998-08-28 Eli Zaretskii <eliz@is.elta.co.il> + + * makeinfo/makeinfo.c (cm_uref, cm_email): Use get_xref_token to + gather arguments. + (get_xref_token): Keep track of input line number when expanding + xref arguments. + +Tue Aug 25 14:36:44 1998 Karl Berry <karl@cs.umb.edu> + + * util/texi2dvi: Exit the script if TeX exits with bad status. + +1998-08-16 Eli Zaretskii <eliz@is.elta.co.il> + + * info/indices.c (info_index_apropos): In the *Apropos* + menu, print the label first, then the Info file name and + the node name. Make the Info file name part of the menu + entry, so that all entries are distinct. + (apropos_in_all_indices): Scan each Info file only once, thus + avoiding multiple identical entries in the *Apropos* menu. + Free xstrdup'ed buffer, to avoid leaking memory. + +Thu Aug 13 12:54:58 1998 Karl Berry <karl@cs.umb.edu> + + * configure.in: Set version to 3.12a. + + * Makefile.am (AUTOMAKE_OPTIONS): bump required version to 1.3, + add readme-alpha option. + + * util/texindex.c (program_name), + * util/install-info.c (progname), + * info/info.c (program_name), + * makeinfo/makeinfo.c (progname): hardwire per coding standards. + * doc/help2man: Remove ginfo special case. + +Tue Aug 11 17:41:15 1998 Karl Berry <karl@cs.umb.edu> + + * util/gen-dir-node: New version from drk@sgi.com. + +Mon Aug 10 13:55:37 1998 Karl Berry <karl@cs.umb.edu> + + * dir-example: Add entries from Linux. + + * info/info-utils.c (get_window_of_node): New fn. + * info/info-utils.h (get_window_of_node): New fn. + * (strchr,...) [!HAVE_STRCHR]: remove these #defines. + * info/infodoc.c (info_find_or_create_help_window): Call + get_window_of_node instead of get_internal_info_window. + This is so pressing ? repeatedly will always get to the same Help + window instead of popping up new ones. + From: "Brian J. Fox" <bfox@prospero.datawave.net> + + * info/signals.c: Ignore SIGWINCH if we're in the midst of it. + We might get a whole lot of them. Noticed on Afterstep. + From: "Brian J. Fox" <bfox@prospero.datawave.net> + +1998-07-25 Bruno Haible <bruno@linuix.math.u-bordeaux.fr> + + * install-info.c (findlines): Allocate room for one more line, + to avoid crash if dir file has exactly 512 lines. + +Tue Aug 4 07:14:35 1998 Karl Berry <karl@cs.umb.edu> + + * info/info.c: Improve help message. + + * dir-example: Add mtools. + +Fri Jul 31 13:29:52 1998 Karl Berry <karl@cs.umb.edu> + + * doc/help2man: Various hacks for texinfo. + + * doc/texinfo.txi: Make dir entries more consistent. + + * doc/Makefile.am: Generate man pages with help2man. + + * util/texi2dvi, + * util/install-info.c, + * makeinfo/makeinfo.c, + * util/texindex.c: Improve help message. + + * doc/info.5: Initial. + * doc/texinfo.5: Section 5. + +Thu Jul 30 17:31:42 1998 Karl Berry <karl@cs.umb.edu> + + * doc/info-stnd.texi, + * doc/texinfo.txi: Use Automake-standard VERSION and UPDATED. + +Wed Jul 29 17:34:41 1998 Karl Berry <karl@cs.umb.edu> + + * doc/texinfo.txi: Describe macro limitations a bit more. + + * dir-example: Correct makeinfo link. + +Tue Jul 28 16:44:06 1998 Karl Berry <karl@cs.umb.edu> + + * makeinfo/makeinfo.c (remember_brace_1): xstrdup command, since + we free it later. + +Mon Jul 27 16:27:30 1998 Karl Berry <karl@cs.umb.edu> + + * info/session.c (node_printed_rep): New fn. + Change calls. + + * info/session.c (info_set_node_of_window): Simplify by taking new + argument to say whether to call + set_remembered_pagetop_and_point. Change calls. + * info/indices.c: Change call. + + * info/info.c: Rewrite initial menu-sequence following stuff as a + function in session.c, and call it. + + * info/infomap.c: Define `G' as info_menu_sequence. + * info/session.h (info_menu_sequence, info_follow_menus): declare + new fns. + * info/session.c (info_follow_menus, split_words, + * info_menu_sequence): New functions for new command. + +Thu Jul 23 16:44:42 1998 Karl Berry <karl@cs.umb.edu> + + * info/session.c (info_scroll_other_window_backward): new command. + * info/infomap.c (initialize_info_keymaps): bind M-DEL and M-prior to + scroll-other-window-backward. + Report from: Vladimir Alexiev <vladimir@cs.ualberta.ca> + Date: Tue, 2 Dec 1997 14:54:30 -0700 + + * info/info-utils.c (printed_representation): If ISO_Latin_p, show + characters as-is. Don't assume iscntrl(x) returns false + for meta characters. + Report from: Francois Pinard <pinard@iro.umontreal.ca> + Date: 15 Jan 1998 17:48:51 -0500 + + * info/pcterm.c (pc_initialize_terminal): now no need to set it + here. + * info/info-utils.c (ISO_Latin_p): set to 1 by default. + + * doc/info-stnd.texi: Document SPC, add goto-node anchor. + +Wed Jul 22 18:58:38 1998 Karl Berry <karl@cs.umb.edu> + + * info/window.c (message_buffer_to_node), + * info/session.c (kill_node), + * info/nodes.c (info_get_node_of_file_buffer, + info_node_of_file_buffer_tags), + * info/man.c (manpage_node_of_file_buffer), + * info/footnotes.c (make_footnotes_node): set display_pos member + in new node. + +Tue Jul 21 14:04:52 1998 Karl Berry <karl@cs.umb.edu> + + (all of this is to make SPC/DEL not move outside the current + document, i.e., not up through dir) + * info/info-utils.h (info_label_was_found): Move from here. + * (info_prev_label_of_node): Don't use it any more. + * info/session.c (INFO_LABEL_WAS_FOUND): Move to here, add test + for filename not dir. + (forward_move_node_structure): Change calls, notice if no more nodes. + (backward_move_node_structure): Check for moving outside current + document to dir. + * info/filesys.c (compression_suffixes): Add bz2 for bunzip2. + (is_dir_name): New fn. + * info/filesys.h: Declare it. + * info/nodes.c (info_get_node, info_find_file_internal): Use it. + + * makeinfo/makeinfo.c: Set in_fixed_width_font to avoid munging + node names. + +Sat Jul 18 17:14:10 1998 Karl Berry <karl@cs.umb.edu> + + * info/man.c (reap_children): Call wait (NULL), since we don't + actually use the return status for anything. NEXTSTEP 3.3 + doesn't like an int * even though that is the POSIX + specification. + Date: Fri, 22 Aug 1997 13:55:42 +0200 + From: "Felix H. Gatzemeier" <fxg@imib.rwth-aachen.de> + Via: Thomas Esser <te@informatik.uni-hannover.de> + + * info/session.c (kill_node): Restore point when we go back. + +Thu Jul 16 18:54:04 1998 Karl Berry <karl@cs.umb.edu> + + * makeinfo/makeinfo.c (BRACE_ELEMENT): Add `command' to the save + stack. + (MAYBE_BRACE_ARGS): New possibility, somewhat like TeX's + next-token-as-argument. + (command_table): Use cm_accent and MAYBE_BRACE_ARGS for all accents. + (read_command): Implement MAYBE_BRACE_ARGS. + (init_brace_stack): save current command. + (pop_and_call_brace): restore current command. + (cm_accent): move almost all accent characters to after the argument. + Suggested by Fran,cois. + + * info/info.c (version_string): Remove defn. + Change call for --version option. + * info/session.c (display_startup_message_and_start): Just use + VERSION. + * info/info.h (version_string): Remove decl. + +Tue Jul 14 16:46:58 1998 Karl Berry <karl@cs.umb.edu> + + * makeinfo/makeinfo.h: Doc fix. + + * makeinfo/makeinfo.c (validate_file): Don't complain about + unreferenced anchors. + + * doc/texinfo.txi: Document @anchor. + +Sun Jul 12 14:14:50 1998 Karl Berry <karl@cs.umb.edu> + + * makeinfo/makeinfo.c (remember_node): Only set `current_node' if + this is not an anchor. + + * info/nodes.c (get_tags_of_indirect_tags_table): Don't set + nodelen to -1 when fixing up the subfile entries, it might be 0 + from an anchor. + + * info/nodes.c (find_node_of_anchor): Offset display_pos for + anchor tags by the amount that node references are off by (- 1). + +Sat Jul 11 17:37:18 1998 Karl Berry <karl@cs.umb.edu> + + * makeinfo/makeinfo.c (cm_anchor): Add output_column for anchors + embedded in a line. + +Fri Jul 10 16:28:21 1998 Karl Berry <karl@cs.umb.edu> + + * info/session.c (info_menu_or_ref_item): Don't search for the + xref text if it's an anchor. + * info/nodes.h (N_FromAnchor): New NODE flag. + * info/nodes.c (find_node_of_anchor): New fn. + (info_node_of_file_buffer_tags): Handle anchor case. + +Wed Jul 8 17:48:59 1998 Karl Berry <karl@cs.umb.edu> + + * info/window.c (window_set_node_of_window): Set window->point to + node->display_pos. + Remove unneeded casts. + +Tue Jul 7 08:06:14 1998 Karl Berry <karl@cs.umb.edu> + + * makeinfo/makeinfo.c (add_word_args) [!VA_SPRINTF]: Use buffer, + not the undeclared temp_string. + From: Tobias Naehring <naehring@eeetw3.et.tu-dresden.de> + To: egcs-bugs@cygnus.com + Date: Mon, 6 Jul 98 13:51:55 +0200 + +Mon Jul 6 17:43:25 1998 Karl Berry <karl@cs.umb.edu> + + * info/nodes.h (NODE): Add display_pos member. + +Sun Jul 5 08:17:43 1998 Karl Berry <karl@cs.umb.edu> + + * info/nodes.h (INFO_REF_LABEL): Define. + + * util/texi2dvi: Rationalize use of `index' vs. more general + `xref'. + +Thu Jul 2 18:53:43 1998 Karl Berry <karl@cs.umb.edu> + + * makeinfo/makeinfo.c: Don't translate -Footnotes, it's a magic + cookie. From Eli. + +Wed Jul 1 08:42:41 1998 Karl Berry <karl@cs.umb.edu> + + * doc/texinfo.txi (url): Missing word `command'. + +Tue Jun 30 10:35:48 1998 Karl Berry <karl@cs.umb.edu> + + * info/info.c: Missing \n in try --help msg. + + * makeinfo/makeinfo.c (cm_anchor): New fn for new cmd. + (TAG_FLAG_ANCHOR): New flag for tag entries. + (write_tag_table_internal): Handle anchor case. + (TAG_FLAG_{{PREV,NEXT,UP}_ERROR,NO_WARN,IS_TOP}): Add TAG_FLAG_ prefix + for clarity, change uses. + + * doc/texinfo.txi: Remove warning about footnotes with @item, that + works now. + +Mon Jun 29 10:17:50 1998 Karl Berry <karl@cs.umb.edu> + + * configure.in (AM_CONFIG_HEADER): Use second argument to be 8.3 + compliant. + * config.h.in: Rename to config.in. + + * info/Makefile.am (EXTRA_DIST), + * info/terminal.c [__MSDOS__]: Change #include to pcterm.c and + rename file. + +Sun Jun 28 14:29:27 1998 Karl Berry <karl@cs.umb.edu> + + * info/Makefile.am (EXTRA_DIST): Add pc_term.c. + + * makeinfo/makeinfo.c (HAVE_MACROS): Remove this conditional, we + always want macros now. + + * info/indices.c: Copyright. + +1998-06-26 Eli Zaretskii <eliz@is.elta.co.il> + + * makeinfo/makeinfo.c: (only_macro_expansion): New variable, + suppresses all expansions except macros. + (replace_with_expansion): New function, replaces a portion of + input text with its expansion. Avoids moving the text around if + we are positive it will expand into itself. If the length of the + expanded text is the same as the length of the original text, just + replaces the original text without moving the rest. Resyncs the + remembered text pointers with the realloc'ed input_text, when it + is realloc'ed. + (reader_loop): When only_macro_expansion is non-zero, only handle + macros, but leave the rest of input intact. + (read_command): Now returns an int, zero means no known command or + macro is found after the prefix character; all callers changed. + Support operation under non-zero only_macro_expansion. + (cm_node): Expand only the macros in the @node line. Allocate and + generate the macro-expanded @node line in one swell whoop. + (glean_node_from_menu): Expand macros in menu entries. + (get_xref_token): A new argument EXPAND, when non-zero, means + expand macros in the entire brace-delimited argument before + looking for the next comma; all callers changed. + (expansion): Save and restore additional state variables important + for output generation machinery. Disable indentation and filling + during the recursive expansion, so that the output buffer offset + is not invalidated by filling. + (me_execute_string_keep_state): New function, calls + me_execute_string, but saves and restores state variables + important for output generation, so that -E doesn't change the + generated Info output. + (index_add_arg, cm_footnote): Call me_execute_string_keep_state. + (expand_macro): New function, returns the macro expansion as a + malloc'ed string. + (execute_macro): Call expand_macro. + (me_execute_string): Avoid memory leak by freeing input_filename. + (get_until_in_braces, replace_with_expansion, add_char, + cm_footnote, cm_macro, cm_unmacro, get_brace_args, + extract_colon_unit): Use the faster memcpy/memmove instead of + strncpy. + +Sat Jun 27 14:18:54 1998 Karl Berry <karl@cs.umb.edu> + + * doc/info.texi: Use @subsubsection instead of + @unnumberedsubsubsection, since it's in a numbered chapter. + + * Started installation of following DOS patches from Eli. +>1998-05-16 Eli Zaretskii <eliz@is.elta.co.il> +> +> * info/session.c (info_goto_node): Don't show the nodes of the +> current Info file twice in *Completions*. +> * info/echo-area.c (ea_possible_completions): Actually pass the +> number of completions to printf_to_message_buffer. +> +> * info/man.c (manpage_node_of_file_buffer): xstrdup the nodename +> member of manpage nodes, since the tags are freed and recomputed +> when a new man page is added to *manpages* file_buffer. +> (get_manpage_node): Recompute info_windows[]->nodes[] for all +> windows showing the man pages after nodes[]->contents are +> invalidated by reallocation of file_buffer->contents. +> +>1998-05-15 Eli Zaretskii <eliz@is.elta.co.il> +> +> * lib/system.h (DEFAULT_INFO_PRINT_COMMAND) [__MSDOS__]: Define to +> ">PRN". +> * info/session.c (print_node): Support ">printer" in +> INFO_PRINT_COMMAND, to mean write to the named file/device insead +> of piping to it as a program. +> (kill_node): Compare window in addition to the nodename, when +> looking for the node to kill. +> +>1998-05-09 Eli Zaretskii <eliz@is.elta.co.il> +> +> * lib/system.h (SET_SCREEN_SIZE_HELPER) [__MSDOS__]: Define a new +> macro. +> * info/m-x.c (set_screen_height): Use SET_SCREEN_SIZE_HELPER, if +> defined. If the screen size did'n change, redisplay the previous +> screen contents. +> +> * info/infomap.c (initialize_info_keymaps) [__MSDOS__]: Bind DEL +> to ea_delete in the echo-area keymap. +> * info/session.c (incremental_search): If the key is +> isearch_terminate_search_key, but buffered input is pending, don't +> gobble the ESC key. +> +> * info/info.c (main): Switch the order thet terminal_prep_terminal +> and terminal_clear_screen are called, to make it consistent with +> what initialize_info_session does when called with non-zero second +> argument. Call terminal_unprep_terminal last, after moving the +> cursor to the bottom of the screen. If user_filename is of the +> form "d:foo", add "d:." to the INFOPATH, not "d:". +> +> * info/signals.c (initialize_info_signal_handler): Save old +> SIGUSR1 handler. +> (info_signal_handler): Handle SIGUSR1. +> +> * info/indices.c (info_apropos): Print the results to stdout. +> +>1998-05-02 Eli Zaretskii <eliz@is.elta.co.il> +> +> * makeinfo/makeinfo.c (ALSO_NULL_DEVICE): New macro, for alternate +> null device name. +> +> * info/man.c (get_manpage_contents): Redirect stderr of the man +> page formatter to the null device. +> (executable_file_in_path): Use IS_SLASH. +> +> * info/session.c (info_gather_typeahead) [__DJGPP__]: Call +> pc_term_chars_avail to get the number of pending characters. +> +> * info/filesys.c (convert_eols): New function, converts DOS-style +> EOLs to a single Newline. +> (filesys_read_info_file, filesys_read_compressed): Call it. +> (filesys_read_compressed) [STRIP_DOT_EXE]: Use explicit .exe +> suffix. +> (filesys_read_compressed): Check return status of `pclose'. +> +>1998-05-01 Eli Zaretskii <eliz@is.elta.co.il> +> +> * info/filesys.c (filesys_read_info_file): Add additional +> parameter: is_compressed. All callers changed. +> +> * makeinfo/makeinfo.c (convert_from_loaded_file): Compare file +> names with FILENAME_CMP. Use NULL_DEVICE. +> (cm_node): Compare file names with FILENAME_CMP. +> * info/tilde.c (tilde_find_suffix, tilde_expand_word): Use +> IS_SLASH. +> +> * info/pc_term.c: New file, handles the PC terminal on MS-DOS and +> MS-Windows. +> * info/terminal.c [__MSDOS__]: Include pc_term.c. +> * info/Makefile.in (ginfo_SOURCES): Add pc_term.c +> Add pc_term.c to dependencies of terminal.o. +> +> * info/session.c (info_get_input_char): Reassign tty after EOF +> from a non-stdin input stream. +> +>1998-04-30 Eli Zaretskii <eliz@is.elta.co.il> +> +> * info/session.c (info_set_input_from_file): Use binary input. +> (info_gc_file_buffers): Compare file names with FILENAME_CMP. +> * info/search.c (skip_whitespace_and_newlines): Use +> whitespace_or_newline macro instead of reinventing the wheel. +> * info/nodes.c (info_find_file_internal): Use IS_ABSOLUTE and +> FILENAME_CMP. +> (info_load_file_internal): Call filename_non_directory to find out +> where the basename begins. +> (get_tags_of_indirect_tags_table): Call filename_non_directory. +> containing_dir of "d:foo" is "d:.", not "d:". +> (forget_info_file): Compare file names with FILENAME_CMP. +> * info/nodemenu.c (get_visited_nodes): Use FILENAME_CMP to find +> duplicate lines. +> +> * lib/system.h (PIPE_USE_FORK): New macro. +> * info/man.c (get_manpage_contents): Use it to determine whether +> to call pipe/fork/exec or popen/pclose to run the man page +> formatter. +> (executable_file_in_path): Search for the file with several known +> extensions such as .exe, where appropriate. +> +> * lib/system.h (NULL_DEVICE): A new macro. +> * info/makedoc.c (main): Use it. +> (maybe_dump_tags): Switch output strem to binary mode when +> appropriate. +> (process_one_file): Update file_size after reading the file. +> +> * info/infodoc.c: Add TAB, RET, and `i' to the list of important +> commands in info_internal_help_text. +> +> * info/info.c (main): Support the --speech-friendly option. Use +> PATH_SEP to separate directories. +> (info_short_help) [__MSDOS__]: Mention the --speech-friendly +> option. +> +> * info/info-utils.c (filename_non_directory): Use HAVE_DRIVE and +> IS_SLASH. +> * info/indices.c (do_info_index_search, index_entry_exists): Use +> FILENAME_CMP to compare file names. +> * info/filesys.c: Add ".inf" to the list of known extensions. +> Look for .z before .Z, for the sake of case-insensitive +> filesystems. Add DOS-specific extensions to work around 8+3 +> namespace restrictions. +> (info_absolute_file): New function. +> (info_find_fullpath): Call it for candidates which are absolute +> file names. Use IS_SLASH and IS_ABSOLUTE. +> (info_file_in_path): Use IS_SLASH. +> (extract_colon_unit, info_add_path): Use PATH_SEP instead of ":". +> (lookup_info_filename): Compare file names with FILENAME_CMP. +> (filesys_read_info_file): Read Info files in binary mode. +> (filesys_decompressor_for_file): Read Info files in binary mode. +> Compare file names with FILENAME_CMP. On MS-DOS, allow files +> whose names end with a `z' be decompressed with gunzip. +> * info/dribble.c (open_dribble_file): Open dribble file in +> FOPEN_WBIN mode. +> * info/dir.c (maybe_build_dir_node): Use IS_SLASH. +> * util/texindex.c (maketempname): Put the numeric suffix after the +> dot, to salvage 3 more characters on 8+3 filesystems. +> +>1998-04-29 Eli Zaretskii <eliz@is.elta.co.il> +> +> * util/texindex.c (main): Use IS_SLASH to find the basename of +> argv[0]. Lose the .exe suffix, if any. +> (decode_command): Look at $TEMP and $TMP in addition to $TMPDIR. +> Use DEFAULT_TMPDIR. +> * util/texi2dvi: Use either `:' or `;' as directory separator in +> TEXINPUTS, computed at run time. Save previous versions of index +> files in a separate backup directory. +> * util/install-info.c (main): Support backslashes in file names by +> using IS_SLASH. Avoid recomputing length of infile_basename +> unnecessarily. Use FILENAME_CMP for comparing file names +> case-insensitively, where appropriate. Allow foo.inf as well as +> foo.info to be an Info file name. +> * lib/system.h (PATH_SEP, STRIP_DOT_EXE, FILENAME_CMPN, +> DEFAULT_TMPDIR): New macros. +> +>1998-04-25 Eli Zaretskii <eliz@is.elta.co.il> +> +> * lib/system.h (O_BINARY, SET_BINARY, FOPEN_RBIN, FOPEN_WBIN, +> IS_SLASH, HAVE_DRIVE, IS_ABSOLUTE, FILENAME_CMP, PATH_SEP, +> HAVE_LONG_FILENAMES): New macros. +> * makeinfo/makeinfo.c (find_and_load): Use O_BINARY to decide when +> read returning a value different from what st_size says is not an +> error. Realloc the buffer after we've read the file. +> (skip_directory_part): New function, skips leading directory in a +> way that works on DOSISH systems. +> (filename_non_directory, pathname_part): Call it. +> (filename_part): Call filename_non_directory. +> (expand_filename, full_pathname): Use IS_ABSOLUTE and IS_SLASH. +> (convert_from_file): Check .txi extension first. +> (split_file): Support splitting output files on 8+3 filesystems. +> (main, extract_colon_unit): Use PATH_SEP instead of ':'. +> (get_file_info_in_path): Use IS_ABSOLUTE and IS_SLASH. + + + * doc/texinfo.txi: Changes from Eli for MS-DOS stuff. + * doc/info-stnd.texi: Fixes from Eli: he documented all the + missing keys and command-line options, corrected + inaccuracies (probably left-overs from previous versions), + and added some clarifications where I thought the manual + was not clear enough. + * Makefile.am (EXTRA_DIST): Add djgpp files. + + * makeinfo/makeinfo.c: New no-op commands @setcontentsaftertitlepage + and @setshortcontentsaftertitlepage. + * doc/texinfo.txi: Document the new @set{,short}contentsaftertitlepage + commands and the possibility of putting @contents and + @shortcontents after @end titlepage. + + * util/texi2dvi: Check that the toc file has not changed (as well + as .aux and .??). + +Thu Jun 25 16:58:46 1998 Karl Berry <karl@cs.umb.edu> + + * doc/texinfo.txi: Document new commands @env, @command, @option. + + * makeinfo/makeinfo.c (option, command, env): New markup commands, same + as @code in info. + +Wed Jun 24 15:39:38 1998 Karl Berry <karl@cs.umb.edu> + + * makeinfo/makeinfo.c: New no-op command @acronym. + + * doc/texinfo.txi: Document new command @acronym. + + * util/install-info.c (strip_info_suffix, menu_item_equal): New fns. + (main): Call them instead of doing the filename test inline; all the + .info variations are too confusing to write out twice. + +Tue Jun 23 18:01:40 1998 Karl Berry <karl@cs.umb.edu> + + * doc/texinfo.txi: Fix some overfull boxes. + +Mon Jun 22 19:22:17 1998 Karl Berry <karl@north> + + * configure.in: Remove AC_LINK_FILES call, that was an old gettext + thing, no longer necessary, and causes problems with Autoconf. + +Sun Jun 14 07:00:15 1998 Karl Berry <karl@cs.umb.edu> + + * util/texi2dvi: Indent options so help2man will work. From Akim. + +Sat Jun 13 10:45:25 1998 Karl Berry <karl@cs.umb.edu> + + * configure.in (ALL_LINGUAS): Add nl. + + * util/texi2dvi: Avoid tabs. + +Wed Jun 10 17:38:21 1998 Karl Berry <karl@cs.umb.edu> + + * makeinfo/makeinfo.c (gen_defindex): Use xmalloc instead of alloca. + This was our only use of alloca, so also remove all the #if junk + at the beginning to define it. + + * makeinfo/makeinfo.c: Fix grammar in multiply-defined-node error + message. + +Tue Jun 9 17:53:54 1998 Karl Berry <karl@cs.umb.edu> + + * doc/texinfo.txi: Document new commands @smallformat, + @smalldisplay. + + * makeinfo/makeinfo.c: New commands @smalldisplay and @smallformat. + Suggestion from: Eli Zaretskii <eliz@is.elta.co.il>. + + * makeinfo/makeinfo.h (insertion_type, insertion_type_names): + Declare smalldisplay and smallformat. + +Mon Jun 8 07:57:52 1998 Karl Berry <karl@cs.umb.edu> + + * doc/texinfo.txi: Document possibility of combining @titlefont + and @title. From Eli. + + * util/texi2dvi: Set verbose to : instead of false by default. + + * util/texi2dvi: Missing \\ for sed with -t text. From Akim. + +Sun Jun 7 13:02:13 1998 Karl Berry <karl@cs.umb.edu> + + * doc/texinfo.txi: Document @pagesizes and texidvi -t. + + * makeinfo/makeinfo.c: Define no-op @pagesizes and @afourpaper. + (major_version, minor_version): Remove these globals, just use the + Texinfo package version. + (print_version_info): Ditto. + +Fri Jun 5 17:54:16 1998 Karl Berry <karl@cs.umb.edu> + + * doc/texinfo.txi: Change texi2dvi documentation a bit. + + * util/texi2dvi: Handle --option=argument style of specifying + arguments. + +Sat May 30 14:01:37 1998 Karl Berry <karl@cs.umb.edu> + + * doc/texinfo.txi: More. + + * util/install-info.c (open_possibly_compressed_file): Finish + implementation. + + * doc/texinfo.txi: Document install-info compression support. + +Fri May 29 08:01:43 1998 Karl Berry <karl@cs.umb.edu> + + * util/install-info.c (open_possibly_compressed_file): Initial + implementation. + + * util/install-info.c (output_dirfile): Attempt to write dir.gz if + that's what we read. + (readfile): Pass back the actual opened filename, too. + + * info/indices.c: Check in Eli's patch. + +Thu May 28 17:09:45 1998 Karl Berry <karl@cs.umb.edu> + + * util/install-info.c (readfile): Set up to handle compressed + input (and output) files. Change callers. + Rearrange function order to avoid forward declarations. + + * configure.in: Remove check for libz, we'll fork gzip instead. + +Tue May 26 18:01:13 1998 Karl Berry <karl@cs.umb.edu> + + * util/install-info.c (print_help): Missing \n\ in help string. + + * makeinfo/makeinfo.c (POST_SENTENCE): Rename from post_sentence. + Change calls. + (flush_output): Strip 8th bit if post_sentence char as well as space. + (cm_code, etc.): Change add_char calls for post_sentence chars to set + 8th bit. + +1998-05-23 Eli Zaretskii <eliz@is.elta.co.il> + + * info/indices.c (info_next_index_match): Call + info_set_node_of_window to display the node, so that footnotes are + displayed as well. + +Thu May 21 11:05:50 1998 Karl Berry <karl@cs.umb.edu> + + * util/install-info.c (output_dirfile): New function, extracted + from the end of main. + + * makeinfo/makeinfo.c (begin_insertion): Ignore @group in all the + example-like environments, not just @example. Otherwise the first + line in the environment is not indented correctly. Reported by rms. + +Wed May 20 17:44:38 1998 Karl Berry <karl@cs.umb.edu> + + * util/install-info.c: Doc fixes. + + * util/install-info.c: Handle XEmacs-style dir entries: + * FILENAME::PROGRAM DESCRIPTION. + Date: Wed, 13 May 1998 13:58:28 +0900 + From: KIRIYAMA Kazuhiko <kiri@kiri.toba-cmt.ac.jp> + + Also, do not set something_deleted on continuation lines; they are only + deleted if the entry was deleted. + +Tue May 19 17:22:50 1998 Karl Berry <karl@cs.umb.edu> + + * util/install-info.c: Do not read the dir file if we are only + deleting -- it might not exist, and we don't actually need it. + From: David Kaelbling <drk@sgi.com> + Date: Tue, 12 May 1998 11:05:26 -0400 + + * util/gen-dir-node: + From: David Kaelbling <drk@sgi.com> + Date: Tue, 12 May 1998 16:05:16 -0400 - + - The "dir" moobler header is slightly different from the default + dir file. + - If all files in ${infofiles} appear in the skeleton the last one + is processed twice. + - INFO-DIR-SECTION data is ignored. + - Don't generate entries for directories. + +Sat May 16 17:16:56 1998 Karl Berry <karl@cs.umb.edu> + + * makeinfo/makeinfo.c (cm_novalidate): New fn for new command + @novalidate, like --no-validate. + +Thu May 14 18:02:31 1998 Karl Berry <karl@cs.umb.edu> + + * doc/texinfo.txi: Document the @novalidate command. + +Wed May 13 17:47:20 1998 Karl Berry <karl@cs.umb.edu> + + * doc/texinfo.txi: Document limitation on @set/@value names in + index commands. + +Fri May 1 14:12:15 1998 Karl Berry <karl@cs.umb.edu> + + * doc/texinfo.txi (Command List): @deftypevar out of order. + + * configure.in (ALL_LINGUAS): Add cs. + +Tue Apr 28 09:33:41 1998 Karl Berry <karl@cs.umb.edu> + + * makeinfo/makeinfo.c (strcasecmp): This is in lib now. + +1998-04-26 Richard Stallman <rms@psilocin.gnu.org> + + * util/install-info.c (print_help): Doc clarifications. + +Sun Apr 19 15:55:10 1998 Karl Berry <karl@cs.umb.edu> + + * lib/system.h (strcasecmp, strncasecmp) [!HAVE_STR[N]CASECMP]: + Declare these. + + * info/search.h (str[n]casecmp): Remove decl from here. + + * configure.in (AC_REPLACE_FUNCS): Check for strcasecmp and + strncasecmp here. + (AC_CHECK_FUNCS): Instead of just strcasecmp here. + + * configure.in (texconfig): Use TEXMFMAIN in preference to TEXMF + for post-0.4 teTeX. + +Wed Apr 15 17:20:31 1998 Karl Berry <karl@cs.umb.edu> + + * doc/texinfo.txi (Reporting Bugs): New section. + Suggestion from: Andrew Shapira <shapiraa@cs.rpi.edu> + Date: Mon, 4 Aug 1997 19:06:06 -0400 (EDT) + + * info/infomap.c: Define / to be info_search. + Suggestion from: Egil Kvaleberg <egil@kvaleberg.no> + Date: Fri, 1 Aug 1997 08:16:45 +0200 (MET DST) + + * doc/texinfo.txi (uref): Document reason for not using <URL: format. + Also use ftp.gnu.org instead of ftp.gnu.ai.mit.edu throughout. + +Tue Apr 14 10:43:39 1998 Karl Berry <karl@cs.umb.edu> + + 1998-04-05 Karl Eichwalder <ke@suse.de> + * makeinfo/makeinfo.c (begin_insertion): No need to + gettext; it's a keyword. From carl-friedriech.spilcke-liss@ensae.fr. + (cm_printindex): ditto. + + * util/texi2dvi: Always remove the $tmp_dir's. + From: Dean Gaudet <dgaudet@arctic.org> + Date: Tue, 14 Apr 1998 00:55:36 -0700 (PDT) + +Mon Apr 13 18:02:57 1998 Karl Berry <karl@cs.umb.edu> + + * configure.in: Include + AM_SYS_POSIX_TERMIOS + AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL + to avoid window resizing being ignored under glibc2 systems, + e.g., Red Hat Linux 5.0. Actually any system where the ioctls are not + defined in <termios.h>. + See also http://www-gnats.gnu.org:8080/cgi-bin/wwwgnats.pl/full/206. + * acconfig.h (GWINSZ_IN_SYS_IOCTL): New #undef for autoheader. + * info/termdep.h [GWINSZ_IN_SYSIOCTL]: #include <sys/ioctl> if + this is defined. + From: Mark Jefferys <mjeffery@cse.ogi.edu> + Date: Thu, 9 Apr 1998 12:38:27 -0700 (PDT) + +Fri Apr 3 01:18:22 1998 Philippe De Muyter <phdm@macqel.be> + + * info/info.c (main): Use 0, not NULL, as ? : alternative. + Tue Mar 3 13:29:17 1998 Karl Berry <karl@cs.umb.edu> * configure.in: Version 3.12. * po/de.po: New version. - + * po/POTFILES.in: Do not include doc.c; that gets built at runtime, thus causing texinfo.pot to try to get rebuilt. Besides, it doesn't have any translatable strings. @@ -34,7 +3207,7 @@ Fri Feb 27 16:06:23 1998 Karl Berry <karl@cs.umb.edu> * info/info.c: Make help messages consistent with others. * util/install-info.c (print_help): Format consistently. - + (readfile): Support gzipped files via libz. From: Elliot Lee <sopwith@redhat.com> Date: Mon, 1 Sep 1997 23:37:14 -0400 (EDT) @@ -152,7 +3325,7 @@ Sat Feb 21 17:41:26 1998 Karl Berry <karl@cs.umb.edu> * util/texindex.c (--version), * makeinfo/makeinfo.c (cm_today), * makeinfo/makeinfo.c (print_version_info): Version strings etc. do not - need translation. + need translation. From: Karl Eichwalder <ke@suse.de> Date: 13 Sep 1997 16:20:02 +0200 @@ -219,7 +3392,7 @@ Fri Aug 1 14:05:10 1997 Karl Berry <karl@cs.umb.edu> * Makefile.am (EXTRA_DIST): Remove README-alpha. From: "ir. Mark M._Kettenis" <kettenis@phys.uva.nl>. -1997-07-31 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de> +1997-07-31 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de> * configure.in: Use AC_CHECK_HEADERS, not AC_CHECK_HEADER. @@ -476,14 +3649,14 @@ Fri Jul 18 10:02:18 1997 Karl Berry <karl@cs.umb.edu> Thu Jul 17 17:19:34 1997 Karl Berry <karl@cs.umb.edu> - + * emacs/Makefile.am (*clean-lisp): Define, as Automake didn't. From: Kenneth Stailey <kstailey@disclosure.com>. * doc/Makefile.am: Do not distribute info.1. * makeinfo/macros: Do not distribute this directory, it's merged into the main documentation. - * doc/makeinfo.texi: Don't distribute this either, it's in the + * doc/makeinfo.texi: Don't distribute this either, it's in the main manual. * util/install-info.c: Use \n\ for multiline string constant. @@ -602,7 +3775,7 @@ Sat Jul 5 17:17:14 1997 Karl Berry <karl@cs.umb.edu> * makeinfo/makeinfo.c (kbdinputstyle): New command. (cm_no_op_line_arg): New function. - * info/termdep.h (HAVE_TERMIOS_H) [NeXT]: #undef. + * info/termdep.h (HAVE_TERMIOS_H) [NeXT]: #undef. From: Gregor Hoffleit <flight@mathi.uni-heidelberg.de> et al. Fri Jul 4 14:18:08 1997 Karl Berry <karl@cs.umb.edu> @@ -755,12 +3928,12 @@ Thu Jun 12 08:37:52 1997 Karl Eichwalder <ke@ke.Central.DE> * info/Makefile.am: * makeinfo/Makefile.am: * util/Makefile.am: - (localedir): Set. + (localedir): Set. (INCLUDES): Add intl/ and LOCALEDIR. (LDADD): Add @INTLLIBS@. * makeinfo/makeinfo.c (main): - * util/texindex.c (main): + * util/texindex.c (main): * util/install-info.c (main): setlocale, bindtextdomain, and textdomain. @@ -804,7 +3977,7 @@ Sun Jun 1 16:34:12 1997 Karl Berry <karl@cs.umb.edu> Tue May 27 17:20:44 1997 Karl Berry <karl@cs.umb.edu> - * doc/texinfo.texi (various): Document @deftypemethod. + * doc/texinfo.texi (various): Document @deftypemethod. (email): @ should have been @@ in the example. From: Mate Wierdl <mw@wierdlmpc.msci.memphis.edu> @@ -917,7 +4090,7 @@ Sun Apr 27 16:12:44 1997 Karl Berry <karl@cs.umb.edu> * info/terminal.c (term_kP, term_kN): New variables to hold PageUp, PageDown key sequences. (terminal_initialize_terminal): Set them. - + * util/texindex.c (main), * util/install-info.c (main), * makeinfo/makeinfo.c (print_version_info), @@ -1083,10 +4256,10 @@ Thu Mar 13 13:59:45 1997 Karl Berry <karl@cs.umb.edu> * configure.in (AC_CONFIG_HEADER): Use this, to avoid hugely long compile line with all the -D's. * info/general.h: Include <config.h>. - + * emacs/Makefile.am (install, install-data): Do @echo to tell the user to compile/install the elisp manually. - + * configure.in (AC_REPLACE_FUNCS): Move strerror check to here. (AC_CHECK_FUNCS): From here. @@ -1230,7 +4403,7 @@ Mon Sep 30 10:07:21 1996 Karl Berry <karl@cs.umb.edu> better page breaks. (\tex): Reset \, to its plain TeX meaning, and do not reset \l. - + * COPYING: Update for new FSF address (from gcc dist). * libtxi/Makefile.in: Various simplifications. @@ -1336,10 +4509,10 @@ Thu Sep 26 10:46:34 1996 Karl Berry <karl@cs.umb.edu> * emacs/texnfo-upd.el, * emacs/texinfo.el, * emacs/texinfmt.el: Update from bob for new Texinfo commands, etc. - + * emacs/info.el, emacs/informat.el, emacs/makeinfo.el, emacs/texnfo-tex.el: Update from Emacs 19.34 dist. - + * emacs/elisp-comp: Use TMPDIR if set. * util/Makefile.in (libdir): Remove. @@ -1591,8 +4764,8 @@ Mon Jul 29 14:44:33 1996 Karl Berry <karl@cs.umb.edu> Sun Jul 28 13:37:05 1996 Karl Berry <karl@cs.umb.edu> * texinfo.tex (paragraphindent): Move to more reasonable place in - the source file. - (chapfonts, secfonts, subsecfonts, indexfonts): Call \setleading. + the source file. + (chapfonts, secfonts, subsecfonts, indexfonts): Call \setleading. (\chfplain, \secheading, \plainsecheading, \subsecheading, \subsubheading): Rewrite to properly \hangindent the title. (\sectionheading): New generic macro to print section titles. @@ -1724,7 +4897,7 @@ Fri Feb 23 19:50:18 1996 Richard Stallman <rms@whiz-bang.gnu.ai.mit.edu> Wed Jan 3 10:01:45 1996 Brian J. Fox <bfox@nirvana.datawave.net> * makeinfo/makeinfo.c (make_index_entries_unique): Be a little bit - stricter about what makes two index entries identical. + stricter about what makes two index entries identical. Fri Dec 29 13:00:24 1995 Brian J. Fox <bfox@wizard.datawave.net> diff --git a/contrib/texinfo/INTRODUCTION b/contrib/texinfo/INTRODUCTION index 1355e6f..13e24f7 100644 --- a/contrib/texinfo/INTRODUCTION +++ b/contrib/texinfo/INTRODUCTION @@ -48,18 +48,6 @@ read this file, type $ info -f info-stnd -If you are using GNU Emacs, you may want to install the Emacs Lisp files -permanently. Move them them to a directory in the load-path for Emacs; -otherwise Emacs will not be able to load the autoloaded support files, such -as `texinfmt.el'. - -The `texinfo.el' file contains the autoload commands; it is the only -file that needs to be loaded initially. If your Emacs does not -automatically load `texinfo.el', you can tell it to do so by placing -the following in `default.el' or in your `.emacs' file: - - (load "texinfo") - To create a printed manual ========================== @@ -90,13 +78,10 @@ program is not part of this distribution, but is available separately. After following those instructions, type the following to make the .dvi files: - $ make texinfo.dvi - $ (cd info; make info.dvi info-stnd.dvi) - $ (cd makeinfo; make makeinfo.dvi) + $ (cd doc; make dvi) -You can then print the resulting .dvi files with the `lpr' command (on BSD -systems. On SysV systems the command is `lp'. Consult your man pages for -more information). +You can then print the resulting .dvi files with the `lpr' or `lp' +commands, or maybe `dvips'. For example, the command to print the texinfo.dvi file might be: diff --git a/contrib/texinfo/NEWS b/contrib/texinfo/NEWS index a9d80d8..18423d5 100644 --- a/contrib/texinfo/NEWS +++ b/contrib/texinfo/NEWS @@ -1,11 +1,113 @@ This file records noteworthy changes. +4.0 (28 September 1999) +* Language: + . New command @anchor for cross references to arbitrary points. + . New commands @documentlanguage sets the main document language, + and @documentencoding sets the document input encoding (although not + much is done yet with either). + . New command @pagesizes allows limited control of text area for typesetting. + . New command @acronym for abbreviations in all caps, such as `NASA'. + . New command @alias for simple command aliases. + . New command @definfoenclose for better control of info output. + . New commands @deftypeivar for typed instance variables of a class + and @deftypeop for typed operations of a class. + . New command @novalidate suppresses cross-reference checking and (in + TeX) auxiliary file creation. + . New commands @setcontentsaftertitlepage and + @setshortcontentsaftertitlepage to force printing the table of + contents after @end titlepage. Also, @contents and @shortcontents + themselves can now appear at the beginning of the document as + well as the end. + . New markup commands: @env (for environment variables), @command (for + command names), @option (for command-line options). + . New commands @smallformat and @smalldisplay, a la @smallexample. + . New command @exampleindent to set indentation of example-like + environments a la @paragraphindent. + . @uref takes an optional third argument of text to show instead of + (rather than in addition to) the url for info and dvi output. + . @footnote works in an @item for a @table. +* texinfo.tex: + . latest version always at ftp://ftp.gnu.org/gnu/texinfo.tex (and mirrors). + . implements @macro. + . implements @paragraphindent (except asis). + . @emph and @i use true italic type (cmti) instead of slanted (cmsl). + . implements pdf output when run with pdftex. + . better support for internationalization via txi-??.tex files. +* makeinfo: + . supports HTML output with the --html option. + . implication of --html: @top nodes should be wrapped in @ifnottex + rather than @ifinfo. @ifinfo conditionals are not expanded with --html. + . new option --number-sections to output chapter/section numbers. + . dashes and quotes are not treated specially in node names. + . new option --commands-in-node-names to allow @-commands in node names. + (Not implemented in TeX, and most likely never will be.) + . @emph output uses _underscores_. + . @image looks for .png files before .jpg. + . only output `Making ... file' line when verbose. + . allow -v as synonym for --verbose. + . new command line options to specify which conditionals to process + (but --iftex is not fully implemented). + . warns if @var contains any of ,[](). + . @quote-arg implicitly done for all one-argument macros, so commas in + the argument text are allowed. + . \\ required in macro body to get single \, no other `escapes' defined. +* info: + . ISO Latin 1 characters are displayed and input as-is by default. + . new option --vi-keys to enable vi-like and less-like key bindings. + . new command S does case-sensitive searching. + . new commands C-x n and C-x N repeat last search, respectively, in the + same and in reverse direction, without prompting for the string. These + commands are bound to n and N under --vi-keys, like in Less. + . new command G menu1 menu2 ... searches for menu items from (dir), + as allowed on the command line. + . new command O (capital o, not zero) goes directly to the node that + describes command-line options. + . new command-line option --show-options causes the node which + describes command-line options to be the first node displayed. + . M-prior and M-DEL do new command info-scroll-other-window-backward. + . / searches like s does. + . If the search string includes upper-case letters, in both incremental + and non-incremental search, the search is case-sensitive. + . S searches case-sensitively even if the search string is all + lower-case. + . - makes the argument negative (so e.g. `- /' searches backward). + . l restores point in the window returned to. + . SPC/DEL do not move outside the current document. + . foo.info is found before foo. + . `info foo --index-search=bar' now searches for bar in foo's index. + . support for files compressed with bzip2. +* install-info: + . handles gzipped dir files. + . sort entries into alphabetical order. + . install direntries only in preceding dircategory, not in all. + . --delete does not require the info file to exist. + . --delete can handle XEmacs-style dir entries. +* texi2dvi: + . bug fixed: now uses only the @iftex and @tex parts of the source. + . process LaTeX source as well as Texinfo source. + . output PDF (using pdftex) with new option --pdf. + . handles --OPTION=ARG style of command line arguments. + . new option --batch for progress reports but no interaction. + . new option --clean to remove all auxiliary files. + . new option --quiet for silence (unless there are errors). + . new option -I for specifying directories for @include to search. + . handles LaTeX files (running BibTeX etc.). +* Fixes to util/gen-dir-node and util/fix-info-dir (formerly util/update-info). +* Distribution: + . Man pages included. + . Czech and Norwegian message translations. + . Various translations for texinfo.tex fixed words included. + . DJGPP support. + + 3.12 (3 March 1998) * Elisp files removed, since they are only usefully distributed with Emacs. * Restore inclusion of compile-time $(infodir) to INFOPATH. * install-info creates a proper dir file. * Various portability fixes. + 3.11 (31 July 1997) * New commands: - @uref to make a reference to a url; @url now only indicates such. @@ -40,6 +142,7 @@ This file records noteworthy changes. 3.10 (nonexistent) + 3.9 (4 October 1996) * makeinfo: - Give a suppressible (with --no-validate) error for references @@ -52,6 +155,7 @@ This file records noteworthy changes. * configure: Include replacements for memcpy and memmove functions in the distribution, in case they are missing. + 3.8 (30 September 1996) * Define and/or document new and/or previously existing commands: Accents: @" @' @, @" @= @^ @` @~ @H @d @dotaccent @dotless @ringaccent @@ -93,46 +197,55 @@ This file records noteworthy changes. @infoinclude @iappendix @iappendixsection @iappendixsec @iappendixsubsec @iappendixsubsubsec - @ichapter @isection @isubsection @isubsubsection + @ichapter @isection @isubsection @isubsubsection @iunnumbered @iunnumberedsec @iunnumberedsubsec @iunnumberedsubsubsec @setchapterstyle @titlespec + 3.7 (24 December 1995) * Have --version print texinfo release number as well as the individual program version. * Better man page cleaning. * Update Elisp files from current Emacs release. + 3.6 (21 June 1995) * Unmatched brace error reporting improved. * Missing comment terminator prevented compilation. + 3.5 (20 June 1995) * Autoconf update. * Support for parallel makes. * make install does not install Elisp files. + 3.4 (19 June 1995) * Handle @ifhtml in Elisp. * Update FSF address. + 3.3 (15 June 1995) * Portability changes. * Compile Elisp files. * Don't distribute .info* files. + 3.2 (9 June 1995) * Standalone Info can read Unix man pages. * New commands: @! @? @^ @" @enddots. * makeinfo -E does macro expansion (and nothing else). + 3.1 (23 May 1993) -Just bug fixes, see ChangeLog for full details. +Just bug fixes, see ChangeLog for full details. -texinfo-3.0: first release of Texinfo version 2, with many new commands. + +3.0: first release of Texinfo version 2, with many new commands. + Here is the separate NEWS for old releases of Info: Version 2.11, Sat Apr 1 09:15:21 1995 @@ -332,4 +445,3 @@ Changes since 2.0: * Scrolling in redisplay is implemented. * Recursive uses of the echo area made more robust. * Garbage collection of unreferenced nodes. - diff --git a/contrib/texinfo/README b/contrib/texinfo/README index 15f8323..0b865ef 100644 --- a/contrib/texinfo/README +++ b/contrib/texinfo/README @@ -1,48 +1,82 @@ This is the README file for the GNU Texinfo distribution. -The primary distribution point is ftp://ftp.gnu.org/pub/gnu. +The primary distribution point is ftp://ftp.gnu.org/gnu/texinfo/. + +Mailing lists: +- bug-texinfo@gnu.org for bug reports or enhancement suggestions, + archived at ftp://ftp-mailing-list-archives.gnu.org/. +- help-texinfo@gnu.org for authoring questions and general discussion. + archived at the same place. +- texinfo-pretest@tug.org for pretests of new releases, + archived at http://tug.org/archives/texinfo-pretest/. +There are as yet no corresponding newsgroups. + +For bug reports, please include enough information for the maintainers +to reproduce the problem. Generally speaking, that means: +- the version number of Texinfo and the program(s) involved (use --version). +- hardware, operating system, and compiler versions (uname -a). +- any unusual options you gave to configure (see config.status). +- the contents of any input files necessary to reproduce the bug (crucial!). +- a description of the problem and any samples of the erroneous output. +- anything else that you think would be helpful. + +Patches are most welcome; if possible, please make them with diff -c and +include ChangeLog entries. + +When sending email, please do not encode or split the messages in any +way if at all possible; it's much easier to deal with one large message +than many small ones. GNU shar is a convenient way of packaging +multiple and/or binary files for email. -Please email bugs or suggestions to bug-texinfo@gnu.org. (If you wish, -you can join this list by sending a subscribe message to -bug-texinfo-request@gnu.org.) Patches are welcome; if possible, please -make them with diff -c and include ChangeLog entries. - -Programs within this distribution have their own version numbers. When -you refer to a file, please mention its own version, as well as the -version number of the Texinfo distribution. For generic installation instructions on compiling and installing this Automake-based distribution, please read the file `INSTALL'. Installation notes specific to Texinfo: - * The Info tree uses a file `dir' as its root node; the `dir-example' - file in this distribution is included for informative purposes. - Use it, modify it, or ignore it just as you like. +* The Info tree uses a file `dir' as its root node; the `dir-example' + file in this distribution is included as a possible starting point. + Use it, modify it, or ignore it just as you like. + +* You can create a file texinfo.cnf to be read by TeX when + processing Texinfo manuals. For example, you might like to use + @afourpaper by default. See the `Preparing for TeX' node in + texinfo.txi for more details. You don't have to create the file if + you have nothing to put in it. + +* If your info files are not in $prefix/info, you may wish to add a line +#define DEFAULT_INFOPATH "/mydir1:/mydir2:..." + to config.h after running configure. - * You can create a file texinfo.cnf to be read by TeX when - processing Texinfo manuals. For example, it might contain the - command @afourpaper. See the `Preparing for TeX' node in - texinfo.texi for more details. +* For instructions on compiling this distribution with DJGPP tools + for MS-DOS and MS-Windows, please see the file djgpp/README. - * If your info files are not in $prefix/info, you may wish to add a line -#define DEFAULT_INFOPATH "/mydir1:/mydir2:/etc" - to config.h after running configure. +If you would like to contribute to the GNU project by implementing +additional documentation output formats for Texinfo, that would be +great. But please do not write a separate translator texi2foo for your +favorite format foo! That is the hard way to do the job, and makes +extra work in subsequent maintenance, since the Texinfo language is +continually being enhanced and updated. Instead, the best approach is +modify Makeinfo to generate the new format, as it does now for Info and HTML. -This distribution includes (but is not limited to) the following files: + +This distribution includes the following files, among others: README This file. + + NEWS Summary of new features by release. + INTRODUCTION Brief introduction to the system, and how to create readable files from the Texinfo source files in this distribution. Texinfo source files (in ./doc): - texinfo.texi This manual describes the Texinfo language - and many of the associated tools. It - tells how to use Texinfo to write - documentation, how to use Texinfo mode - in GNU Emacs, TeX, makeinfo, and the - Emacs Lisp Texinfo formatting commands. + texinfo.txi Describes the Texinfo language and many + of the associated tools. It tells how + to use Texinfo to write documentation, + how to use Texinfo mode in GNU Emacs, + TeX, makeinfo, and the Emacs Lisp + Texinfo formatting commands. info.texi This manual tells you how to use Info. This document comes as part of @@ -72,26 +106,20 @@ Printing related files: util/texi2dvi This is a shell script for producing an indexed DVI file using - TeX and texindex. Must be used if the - source document uses Texinfo @macros. + TeX and texindex. Source files for standalone C programs (./lib, ./makeinfo, ./info): - makeinfo.c This file contains the source for + makeinfo/makeinfo.c This file contains the source for the `makeinfo' program that you can use to create an Info file from a Texinfo file. - info.c This file contains the source for + info/info.c This file contains the source for the `info' program that you can use to view Info files on an ASCII terminal. - getopt.c Various support files - getopt1.c - getopt.h - - Installation files: configure This file creates creates a Makefile @@ -110,11 +138,7 @@ Installation files: to use to make a Makefile.in. -Other files (util): - - NEWS This contains a summary of new - features since the first edition - of Texinfo. +Other files: fixfonts This is a shell script to install the `lcircle10' TeX fonts as an alias for diff --git a/contrib/texinfo/TODO b/contrib/texinfo/TODO index 6df65a8..a06b40c 100644 --- a/contrib/texinfo/TODO +++ b/contrib/texinfo/TODO @@ -1,8 +1,8 @@ If you are interested in working on any of these, email bug-texinfo@gnu.org. * Makeinfo: - - HTML output is being actively worked on, and with luck will be in - the next release. + - Support output of Docbook format and SGML-Tools format. + - Support output of true 8-bit characters from accent commands, etc. - A detexinfo program, like detex or delatex. This command would strip all the texinfo commands out, and would be used as a filter on the way to a speller. An option would be to NOT strip comments out. @@ -13,23 +13,27 @@ If you are interested in working on any of these, email bug-texinfo@gnu.org. chapter/section references. See: ftp://ftp.simtel.net/pub/simtelnet/gnu/djgpp/v2/faq201s.zip - Call Ghostscript to get ASCII output for the @image command. + - Better HTML output: allow settable background color, table colors + and spacing, <head> meta tags, back link from footnote marker, etc. + - Could warn if @sc{TEXT} for all-caps TEXT, since it's a no-op. * TeX: - Use @ as the escape character, and Texinfo syntax generally, in the table of contents, aux, and index files. Eliminate all the crazy multiple redefinitions of every Texinfo command in different contexts. - Handle @hsep and @vsep in @multitables. + - Introduce new command to change \bindingoffset. + - How about using latex2html to produce HTML? * General: - Better i18n support, including support for 8-bit input characters, and 8-bit output in info. Perhaps have to use the ec fonts. - Support compressed image files, automatic generation of .txt or .jpg from .eps by Ghostscript. - - Repeat TeX run until cross-references stabilize, not just twice. - (Document this in manual and fix texi2dvi.) - Handle reference card creation, perhaps by only paying attention to sectioning and @def... commands. - Allow : in node names for info files, for names like `class::method'. + - Allow @end (and other?) commands to be indented in the source. - Get Info declared as a MIME Content-Type. * Language: @@ -41,15 +45,18 @@ If you are interested in working on any of these, email bug-texinfo@gnu.org. @caption ... @end caption <arbitrary Texinfo commands> @end figure + - support bibliographies with BibTeX (see web2c/doc for kludge prototype). - @flushboth to combine @flushleft and @flushright, for RFC's. - @part sectioning command. - - Anchors a la HTML? - Allow subitems and `see' and `see also' in indices. + - @verbatim ... @end verbatim. - @exercise/@answer command for, e.g., gawk. - Allow @hsep/@vsep at @item, instead of just in template. - The dark corner symbol for the gawk manual. + - Support automatic line numbering of examples. - Change bars. This is difficult or impossible in TeX, unfortunately. To do it right requires device driver support. + wdiff or ediff may be better in some cases, anyway. * Doc: - Include a complete functional summary, as in a reference card, in @@ -59,20 +66,29 @@ If you are interested in working on any of these, email bug-texinfo@gnu.org. for an example of doing it in both the tex and info versions. * Info: + - Regular expression search. + - Allow key rebinding, perhaps through the readline library. + - Full-text search across all info files installed on the system. + - Support character sets other than ISO Latin 1. + - Perhaps comply with LANGUAGE setting on a per-node basis, to allow + incremental translation of Texinfo files. - Search all nodes of dir file at startup, then can have INFO-DIR-SEPARATE-GROUPS and other such. - Better dir file merging. - Steal interface ideas from Lynx: TAB for navigating to next link - within a page, number links, etc. + within a page, number links, use color, etc. Perhaps code from the pinfo + viewer can be reused: http://zeus.polsl.gliwice.pl/~pborys/. - q within help should quit help like C-x 0. - - Full-text search on all available info files. - - Incorporate an X-based viewer, perhaps tkinfo: - http://www.math.ucsb.edu/~boldt/tkinfo/. + - Incorporate an X-based viewer, perhaps tkinfo + http://www.math.ucsb.edu/~boldt/tkinfo/ + or saxinfo. - Perhaps process Texinfo files directly instead of converting to Info: ftp://ftp.cs.berkeley.edu/ucb/people/phelps/tcltk/tkman.tar.Z + ftp://ftp.cs.berkeley.edu/ucb/people/phelps/tcltk/rman.tar.Z + Tcl/Tk 8.0 from ftp.smli.com in the /pub/tcl directory. From: phelps@ecstasy.CS.Berkeley.EDU (Tom Phelps) + (But this has the disadvantage of needing to be updated when the + Texinfo language changes, so don't.) * Install-info: - be able to copy the info file to compile-time $(infodir), to diff --git a/contrib/texinfo/config.h.in b/contrib/texinfo/config.h.in index f814b65..7434895 100644 --- a/contrib/texinfo/config.h.in +++ b/contrib/texinfo/config.h.in @@ -1,6 +1,7 @@ -/* config.h.in. Generated automatically from configure.in by autoheader. */ +/* config.in. Generated automatically from configure.in by autoheader. */ /* acconfig.h This file is in the public domain. + $Id: acconfig.h,v 1.3 1998/12/06 22:04:03 karl Exp $ Descriptive text for the C preprocessor macros that the distributed Autoconf macros can define. @@ -38,6 +39,9 @@ /* Define if you have a working `mmap' system call. */ #undef HAVE_MMAP +/* Define if you have the strcoll function and it is properly defined. */ +#undef HAVE_STRCOLL + /* Define if you have the vprintf function. */ #undef HAVE_VPRINTF @@ -77,6 +81,9 @@ */ #undef STACK_DIRECTION +/* Define if the `S_IS*' macros in <sys/stat.h> do not work properly. */ +#undef STAT_MACROS_BROKEN + /* Define if you have the ANSI C header files. */ #undef STDC_HEADERS @@ -98,12 +105,6 @@ /* Define as 1 if you have the stpcpy function. */ #undef HAVE_STPCPY -/* Define to the name of the distribution. */ -#undef PACKAGE - -/* Define to the version of the distribution. */ -#undef VERSION - /* Define if you have the __argz_count function. */ #undef HAVE___ARGZ_COUNT @@ -170,6 +171,9 @@ /* Define if you have the strerror function. */ #undef HAVE_STRERROR +/* Define if you have the strncasecmp function. */ +#undef HAVE_STRNCASECMP + /* Define if you have the <argz.h> header file. */ #undef HAVE_ARGZ_H @@ -185,6 +189,9 @@ /* Define if you have the <malloc.h> header file. */ #undef HAVE_MALLOC_H +/* Define if you have the <memory.h> header file. */ +#undef HAVE_MEMORY_H + /* Define if you have the <ncurses/termcap.h> header file. */ #undef HAVE_NCURSES_TERMCAP_H @@ -194,6 +201,9 @@ /* Define if you have the <pwd.h> header file. */ #undef HAVE_PWD_H +/* Define if you have the <stdlib.h> header file. */ +#undef HAVE_STDLIB_H + /* Define if you have the <string.h> header file. */ #undef HAVE_STRING_H @@ -233,22 +243,33 @@ /* Define if you have the <unistd.h> header file. */ #undef HAVE_UNISTD_H -/* Define if you have the <values.h> header file. */ -#undef HAVE_VALUES_H - /* Define if you have the bsd library (-lbsd). */ #undef HAVE_LIBBSD /* Define if you have the i library (-li). */ #undef HAVE_LIBI -/* Define if you have the z library (-lz). */ -#undef HAVE_LIBZ +/* Name of package */ +#undef PACKAGE + +/* Version number of package */ +#undef VERSION + +/* Define if TIOCGWINSZ requires sys/ioctl.h */ +#undef GWINSZ_IN_SYS_IOCTL + +/* Define if this function is declared. */ +#undef HAVE_DECL_STRERROR + +/* Define if this function is declared. */ +#undef HAVE_DECL_STRCASECMP + +/* Define if this function is declared. */ +#undef HAVE_DECL_STRNCASECMP + +/* Define if this function is declared. */ +#undef HAVE_DECL_STRCOLL -/* For gettext (NLS) */ -#include <libintl.h> -#define _(String) gettext (String) -#define N_(String) (String) /* Leave that blank line there!! Autoheader needs it. diff --git a/contrib/texinfo/doc/README b/contrib/texinfo/doc/README index fe8e654..c10fad9 100644 --- a/contrib/texinfo/doc/README +++ b/contrib/texinfo/doc/README @@ -1,22 +1,30 @@ This directory contains documentation on the Texinfo system and the TeX -sources needed to process Texinfo sources. (Use texi2dvi to run a -Texinfo manual through TeX to produce a DVI file.) +sources needed to process Texinfo sources. We recommend using the +texi2dvi included in the distribution to run a Texinfo manual through +TeX to produce a DVI file. The .tex files are not installed automatically because TeX installations vary so widely. Installing them in the wrong place would give a false sense of security. So, you should simply cp *.tex to the appropriate place. If your installation follows the TeX Directory Structure -standard (http://www.tug.org/tds/), this will be the directory +standard (http://tug.org/tds/), this will be the directory <texmf>/tex/texinfo/ for texinfo.tex and <texmf>/tex/plain/dvips/ for epsf.tex. If you use the default installation paths, <texmf> will be -/usr/local/share/texmf. If you have teTeX, you can find <texmf> by -running: - texconfig confall | grep \^TEXMF= -(The configure script tries to do this for you.) +/usr/local/share/texmf. On systems with TeX preinstalled, as most +GNU/Linux distributions offer, <texmf> will often be something like +/usr/share/texmf. + +It is also possible to put these .tex files in a `local' place instead +of overwriting existing ones, but it is more complicated. See your TeX +documentation in general and the texmf.cnf file in particular for information. + +If you add files to your TeX installations, not just replace existing +ones, you very likely have to update your ls-R file; do this with the +mktexlsr command. In older versions, this was named MakeTeXls-R. You can get the latest texinfo.tex from -ftp://ftp.tug.org/tex/texinfo.tex -ftp://ftp.cs.umb.edu/pub/tex/texinfo.tex +ftp://ftp.gnu.org/gnu/texinfo.tex (and all GNU mirrors) +ftp://tug.org/tex/texinfo.tex (and all CTAN mirrors) or on the FSF machines in /home/gd/gnu/doc/texinfo.tex. If you have problems with the version in this distribution, please check for a newer version. diff --git a/contrib/texinfo/doc/help2man b/contrib/texinfo/doc/help2man new file mode 100755 index 0000000..d33f7cd --- /dev/null +++ b/contrib/texinfo/doc/help2man @@ -0,0 +1,401 @@ +#!/usr/local/bin/perl -w + +# Generate a short man page from --help and --version output. +# Copyright İ 1997, 98, 99 Free Software Foundation, Inc. + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. + +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software Foundation, +# Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + +# Written by Brendan O'Dea <bod@compusol.com.au> + +use 5.004; +use strict; +use Getopt::Long; +use Text::Tabs qw(expand); +use POSIX qw(strftime setlocale LC_TIME); + +my $this_program = 'help2man'; +my $this_version = '1.013'; +my $version_info = <<EOT; +$this_program $this_version + +Copyright (C) 1997, 98, 99 Free Software Foundation, Inc. +This is free software; see the source for copying conditions. There is NO +warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + +Written by Brendan O'Dea <bod\@compusol.com.au> +EOT + +my $help_info = <<EOT; +`$this_program' generates a man page out of `--help' and `--version' output. + +Usage: $this_program [OPTION]... EXECUTABLE + + -n, --name=STRING use `STRING' as the description for the NAME paragraph + -s, --section=SECTION use `SECTION' as the section for the man page + -i, --include=FILE include material from `FILE' + -I, --opt-include=FILE include material from `FILE' if it exists + -o, --output=FILE send output to `FILE' + -N, --no-info suppress pointer to Texinfo manual + --help print this help, then exit + --version print $this_program program version number, then exit + +EXECUTABLE should accept `--help' and `--version' options. +EOT + +my $section = 1; +my ($include, $opt_name, $opt_include, $opt_output, $opt_no_info); + +# Parse options. +Getopt::Long::config('bundling'); +GetOptions ( + 'n|name=s' => \$opt_name, + 's|section=s' => \$section, + 'i|include=s' => \$include, + 'I|opt-include=s' => \$opt_include, + 'o|output=s' => \$opt_output, + 'N|no-info' => \$opt_no_info, + help => sub { print $help_info; exit }, + version => sub { print $version_info; exit }, +) or die $help_info; + +die $help_info unless @ARGV == 1; + +my %include = (); +my @include = (); # to retain order + +# Process include file (if given). Format is: +# +# [section name] +# verbatim text + +if ($include or $opt_include) +{ + if (open INC, $include || $opt_include) + { + my $sect; + + while (<INC>) + { + if (/^\[([^]]+)\]/) + { + $sect = uc $1; + $sect =~ s/^\s+//; + $sect =~ s/\s+$//; + next; + } + + # Silently ignore anything before the first + # section--allows for comments and revision info. + next unless $sect; + + push @include, $sect unless $include{$sect}; + $include{$sect} ||= ''; + $include{$sect} .= $_; + } + + close INC; + + die "$this_program: no valid information found in `$include'\n" + unless %include; + + # Compress trailing blank lines. + for (keys %include) + { + $include{$_} =~ s/\n+$//; + $include{$_} .= "\n" unless /^NAME$/; + } + } + else + { + die "$this_program: can't open `$include' ($!)\n" if $include; + } +} + +# Turn off localisation of executable's ouput. +@ENV{qw(LANGUAGE LANG LC_ALL)} = ('C') x 3; + +# Turn off localisation of date (for strftime) +setlocale LC_TIME, 'C'; + +# Expand tabs, strip trailing spaces and break into paragraphs +sub paragraphs { split /\n\n+/, join '', expand @_ } + +# Grab help and version paragraphs from executable +my @help = paragraphs `$ARGV[0] --help 2>/dev/null` + or die "$this_program: can't get `--help' info from $ARGV[0]\n"; + +my @version = paragraphs `$ARGV[0] --version 2>/dev/null` + or die "$this_program: can't get `--version' info from $ARGV[0]\n"; + +my $date = strftime "%B %Y", localtime; +(my $program = $ARGV[0]) =~ s!.*/!!; +my $package = $program; +my $version; + +if ($opt_output) +{ + unlink $opt_output + or die "$this_program: can't unlink $opt_output ($!)\n" + if -e $opt_output; + + open STDOUT, ">$opt_output" + or die "$this_program: can't create $opt_output ($!)\n"; +} + +# The first line of the --version information is assumed to be in one +# of the following formats: +# +# <version> +# <program> <version> +# {GNU,Free} <program> <version> +# <program> ({GNU,Free} <package>) <version> +# <program> - {GNU,Free} <package> <version> +# +# and seperated from any copyright/author details by a blank line. + +$_ = shift @version; + +if (/^(\S+) +\(((?:GNU|Free) +[^)]+)\) +(.*)/ or + /^(\S+) +- *((?:GNU|Free) +\S+) +(.*)/) +{ + $program = $1; + $package = $2; + $version = $3; +} +elsif (/^((?:GNU|Free) +)?(\S+) +(.*)/) +{ + $program = $2; + $package = $1 ? "$1$2" : $2; + $version = $3; +} +else +{ + $version = $_; +} + +$program =~ s!.*/!!; + +# no info for `info' itself +$opt_no_info = 1 if $program eq 'info'; + +# --name overrides --include contents +$include{NAME} = "$program \\- $opt_name" if $opt_name; + +# Default (useless) NAME paragraph +$include{NAME} ||= "$program \\- manual page for $program $version"; + +# Man pages traditionally have the page title in caps. +my $PROGRAM = uc $program; + +# Header. +print <<EOT; +.\\" DO NOT MODIFY THIS FILE! It was generated by $this_program $this_version. +.TH $PROGRAM "$section" "$date" "$package $version" FSF +.SH NAME +$include{NAME} +EOT + +my $break; +my $accumulate = 1; +my @description = (); + +sub convert_option; + +# Output converted --help information. +for (@help) +{ + chomp; + + if (s/^Usage: +\S+ +(.*)\n?//) + { + # Turn the usage clause into a synopsis. + my $synopsis = ''; + + do { + my $syn = $1; + $syn =~ s/(([][]|\.\.+)+)/\\fR$1\\fI/g; + $syn =~ s/^/\\fI/ unless $syn =~ s/^\\fR//; + $syn .= '\fR'; + $syn =~ s/\\fI( *)\\fR/$1/g; + + $synopsis .= ".br\n" unless $accumulate; + $synopsis .= ".B $program\n"; + $synopsis .= "$syn\n"; + $accumulate = 0; + } while s/^(?:Usage| *or): +\S+ +(.*)\n?//; + + # Include file overrides SYNOPSIS. + print ".SH SYNOPSIS\n", $include{SYNOPSIS} || $synopsis; + + # Dump any accumulated description text. + print ".SH DESCRIPTION\n"; + print @description; + + # Add additional description text from include file. + if ($include{DESCRIPTION}) + { + print ".PP\n" unless $include{DESCRIPTION} =~ /^\..P/; + print $include{DESCRIPTION}; + } + + $break = 1; + next unless $_; + } + + # Accumulate text if the synopsis has not been produced yet. + if ($accumulate) + { + push @description, ".PP\n" if @description; + push @description, "$_\n"; + next; + } + + # Convert some standard paragraph names + if (s/^(Options|Examples): *\n//) + { + print qq(.SH \U$1\n); + $break = ''; + next unless length; + } + + # Catch bug report text. + if (/^Report bugs |^Email bug reports to /) + { + print qq(.SH "REPORTING BUGS"\n$_\n); + $break = ''; + next; + } + + # Option subsections have second line indented. + if (s/^(\S.*)\n / /) + { + print qq(.SS "$1"\n); + $break = ''; + } + + my $output = ''; + while (length) + { + my $indent = 0; + + # Tagged paragraph + if (s/^( +(\S.*?) +)(\S.*)\n?//) + { + $indent = length $1; + $output .= ".TP\n$2\n$3\n"; + $break = 1; + } + + # Indented paragraph + elsif (s/^( +)(\S.*)\n?//) + { + $indent = length $1; + $output .= ".IP\n$2\n"; + $break = 1; + } + + # Left justified paragraph + else + { + s/(.*)\n?//; + $output .= ".PP\n" if $break; + $output .= "$1\n"; + $break = 1; + } + + # Continuations + $output .= "$1\n" while s/^ {$indent}(\S.*)\n?//; + } + + $_ = $output; + + # Escape backslashes. + s/\\/\\e/g; + + # Convert options. + s/(^| )(-[][\w=-]+)/$1 . convert_option $2/mge; + print; +} + +# Print any include items other than the ones we have already dealt +# with. +for (@include) +{ + print qq(.SH "$_"\n$include{$_}) + unless /^(NAME|SYNOPSIS|DESCRIPTION|SEE ALSO)$/; +} + +# Refer to the real documentation. +if ($include{'SEE ALSO'} or !$opt_no_info) +{ + print qq(.SH "SEE ALSO"\n); + print $include{'SEE ALSO'}, ".PP\n" if $include{'SEE ALSO'}; + + print <<EOT unless $opt_no_info; +The full documentation for +.B $program +is maintained as a Texinfo manual. If the +.B info +and +.B $program +programs are properly installed at your site, the command +.IP +.B info $program +.PP +should give you access to the complete manual. +EOT +} + +# Output converted --version information. +for (@version) +{ + chomp; + + # Join hyphenated lines. + s/([A-Za-z])-\n */$1/g; + + # Convert copyright symbol or (c) to nroff character. + s/Copyright +(?:\xa9|\([Cc]\))/Copyright \\(co/g; + + # Insert appropriate headings for copyright and author. + if (/^Copyright \\/) { print ".SH COPYRIGHT\n" } + elsif (/^Written +by/) { print ".SH AUTHOR\n" } + else { print ".PP\n"; } + + # Insert line breaks before additional copyright messages and the + # disclaimer. + s/(.)\n(Copyright |This is free software)/$1\n.br\n$2/g; + + print "$_\n"; +} + +exit; + +# Convert option dashes to \- to stop nroff from hyphenating 'em, and +# embolden. Option arguments get italicised. +sub convert_option +{ + my $option = '\fB' . shift; + + $option =~ s/-/\\-/g; + unless ($option =~ s/\[=(.*)\]$/\\fR[=\\fI$1\\fR]/) + { + $option =~ s/=(.)/\\fR=\\fI$1/; + $option =~ s/ (.)/ \\fI$1/; + $option .= '\fR'; + } + + $option; +} diff --git a/contrib/texinfo/doc/info-stnd.texi b/contrib/texinfo/doc/info-stnd.texi index 9eb6836d..c08a8a5 100644 --- a/contrib/texinfo/doc/info-stnd.texi +++ b/contrib/texinfo/doc/info-stnd.texi @@ -2,18 +2,17 @@ @comment %**start of header @setfilename info-stnd.info @settitle GNU Info -@set InfoProgVer 2.11 -@paragraphindent none -@footnotestyle end @synindex vr cp @synindex fn cp @synindex ky cp @comment %**end of header -@comment $Id: info-stnd.texi,v 1.3 1997/07/06 21:49:30 karl Exp $ +@comment $Id: info-stnd.texi,v 1.23 1999/06/25 21:57:04 karl Exp $ + +@include version.texi @dircategory Texinfo documentation system @direntry -* info program: (info-stnd). Standalone Info-reading program. +* Standalone info program: (info-stnd). Standalone Info-reading program. @end direntry @ifinfo @@ -23,7 +22,7 @@ documentation for the Info reader that is part of GNU Emacs. If you do not know how to use Info, but have a working Info reader, you should read that documentation first. -Copyright @copyright{} 1992, 93, 96, 97 Free Software Foundation, Inc. +Copyright @copyright{} 1992, 93, 96, 97, 98, 99 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are @@ -50,12 +49,14 @@ approved by the Free Software Foundation. @end ifinfo @titlepage -@title GNU Info User's Guide -@subtitle For GNU Info version @value{InfoProgVer} -@author Brian J. Fox (bfox@@ai.mit.edu) +@title GNU Info +@subtitle for version @value{VERSION}, @value{UPDATED} +@author Brian J. Fox (bfox@@gnu.org) @page @vskip 0pt plus 1filll -Copyright @copyright{} 1992, 1993, 1997 Free Software Foundation +Copyright @copyright{} 1992, 93, 97, 98, 99 Free Software Foundation + +This manual is for GNU Info version @value{VERSION}, @value{UPDATED}. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are @@ -74,21 +75,23 @@ except that this permission notice may be stated in a translation approved by the Free Software Foundation. @end titlepage -@ifinfo -@node Top, What is Info, , (dir) -@top The GNU Info Program +@ifnottex +@node Top +@top GNU Info This file documents GNU Info, a program for viewing the on-line -formatted versions of Texinfo files, version @value{InfoProgVer}. This +formatted versions of Texinfo files, version @value{VERSION}. This documentation is different from the documentation for the Info reader that is part of GNU Emacs. -@end ifinfo + +This manual is for Info version @value{VERSION}, updated @value{UPDATED}. +@end ifnottex @menu -* What is Info:: -* Options:: Options you can pass on the command line. +* What is Info:: What is Info? +* Invoking Info:: Options you can pass on the command line. * Cursor Commands:: Commands which move the cursor within a node. -* Scrolling Commands:: Commands for moving the node around +* Scrolling Commands:: Commands for moving the node around in a window. * Node Commands:: Commands for selecting a new node. * Searching Commands:: Commands for searching an Info file. @@ -97,30 +100,29 @@ that is part of GNU Emacs. * Printing Nodes:: How to print out the contents of a node. * Miscellaneous Commands:: A few commands that defy categories. * Variables:: How to change the default behavior of Info. -* GNU Info Global Index:: Global index containing keystrokes, - command names, variable names, +* GNU Info Global Index:: Global index containing keystrokes, + command names, variable names, and general concepts. @end menu -@node What is Info, Options, Top, Top -@chapter What is Info? -@iftex -This file documents GNU Info, a program for viewing the on-line formatted -versions of Texinfo files, version @value{InfoProgVer}. -@end iftex +@node What is Info +@chapter What is Info? @dfn{Info} is a program which is used to view Info files on an ASCII terminal. @dfn{Info files} are the result of processing Texinfo files with the program @code{makeinfo} or with one of the Emacs commands, such as @code{M-x texinfo-format-buffer}. Texinfo itself is a documentation system that uses a single source file to produce both on-line -information and printed output. You can typeset and print the -files that you read in Info.@refill +information and printed output. You can typeset and print the files +that you read in Info. -@node Options, Cursor Commands, What is Info, Top -@chapter Command Line Options + +@node Invoking Info +@chapter Invoking Info +@cindex invoking info @cindex command line options +@cindex options, command line @cindex arguments, command line GNU Info accepts several options to control the initial node being @@ -128,24 +130,46 @@ viewed, and to specify which directories to search for Info files. Here is a template showing an invocation of GNU Info from the shell: @example -info [--@var{option-name} @var{option-value}] @var{menu-item}@dots{} +info [@var{option}]@dots{} [@var{menu-item}@dots{}] @end example -The following @var{option-names} are available when invoking Info from -the shell: +The program accepts the following options: @table @code +@item --apropos=@var{string} +@cindex Searching all indices +@cindex Info files@r{, searching all indices} +@cindex Apropos@r{, in Info files} +Specify a string to search in every index of every Info file installed +on your system. Info looks up the named @var{string} in all the indices +it can find, prints the results to standard output, and then exits. If +you are not sure which Info file explains certain issues, this option is +your friend. Note that if your system has a lot of Info files +installed, searching all of them might take some time. + @cindex directory path @item --directory @var{directory-path} @itemx -d @var{directory-path} -Add @var{directory-path} to the list of directory paths searched when -Info needs to find a file. You may issue @code{--directory} multiple -times; once for each directory which contains Info files. -Alternatively, you may specify a value for the environment variable -@code{INFOPATH}; if @code{--directory} is not given, the value of -@code{INFOPATH} is used. The value of @code{INFOPATH} is a colon -separated list of directory names. If you do not supply @code{INFOPATH} -or @code{--directory-path}, Info uses a default path. +Prepend @var{directory-path} to the list of directory paths searched +when Info needs to find a file. You may issue @code{--directory} +multiple times; once for each directory which contains Info files. The +list of directories searched by Info is constructed from the value of +the environment variable @code{INFOPATH}; @code{--directory} causes the +named @var{directory-path} to be prepended to that list. The value of +@code{INFOPATH} is a list of directories usually separated by a colon; +on MS-DOS/MS-Windows systems, the semicolon is used. If you do not +define @code{INFOPATH}, Info uses a default path defined when Info was +built as the initial list of directories. If the value of +@code{INFOPATH} ends with a colon (or semicolon on MS-DOS/MS-Windows), +the initial list of directories is constructed by appending the +build-time default to the value of @code{INFOPATH}. + +@cindex keystrokes, recording +@cindex remembering user keystrokes +@item --dribble=@var{dribble-file} +Specify a file where all user keystrokes will be recorded. This file +can be used later to replay the same sequence of commands, see the +@samp{--restore} option below. @item --file @var{filename} @itemx -f @var{filename} @@ -154,23 +178,66 @@ Specify a particular Info file to visit. By default, Info visits the file @code{dir}; if you use this option, Info will start with @code{(@var{filename})Top} as the first file and node. +@cindex relative Info file names +@cindex file names, relative +@cindex Info files, relative +If @var{filename} is an absolute file name, or begins with @file{./} or +@file{../}, Info looks for @var{filename} only in the directory of the +specified @var{filename}, and adds the directory of @var{filename} to +the value of @code{INFOPATH}. In contrast, if @var{filename} is in the +form of a relative file name, but without the @file{./} or @file{../} +prefix, Info will only look for it in the directories specified in +@code{INFOPATH}. In other words, Info does @emph{not} treat file names +which lack @file{./} and @file{../} prefix as relative to the current +directory. + +@cindex compressed Info files +@cindex files, compressed +@cindex Info files, compressed +In every directory Info tries, if @var{filename} is not found, Info +looks for it with a number of known extensions of Info files@footnote{ +@file{.info}, @file{-info}, @file{/index}, and @file{.inf}.}. For every +known extension, Info looks for a compressed file, if a regular file +isn't found. Info supports files compressed with @code{gzip}, +@code{bzip2}, @code{compress} and @code{yabba} programs; it calls +@code{gunzip}, @code{bunzip2}, @code{uncompress} and @code{unyabba}, +accordingly, to decompress such files. Compressed Info files are +assumed to have @file{.z}, @file{.gz}, @file{.bz2}, @file{.Z}, or +@file{.Y} extensions, possibly in addition to one of the known Info +files extensions@footnote{The MS-DOS version allows for the Info +extension, such as @code{.inf}, and the short compressed file +extensions, such as @file{.z} and @file{.gz}, to be merged into a single +extension, since DOS doesn't allow more than a single dot in the +basename of a file. Thus, on MS-DOS, if Info looks for @file{bison}, +file names like @file{bison.igz} and @file{bison.inz} will be found and +decompressed by @code{gunzip}.}. + +@item --help +@itemx -h +Produces a relatively brief description of the available Info options. + @item --index-search @var{string} -@cindex index search, selecting +@cindex index search, selecting from the command line @cindex online help, using Info as -Go to the index entry @var{string} in the Info file specified with -@samp{--file}. If no such entry, print @samp{no entries found} and exit -with nonzero status. This can used from another program as a way to -provide online help. +After processing all command-line arguments, go to the index in the Info +file and search for index entries which matche @var{string}. If such an +entry is found, the Info session begins with displaying the node pointed +to by the first matching index entry; press @kbd{,} to step through the +rest of the matching entries. If no such entry exists, print @samp{no +entries found} and exit with nonzero status. This can be used from +another program as a way to provide online help, or as a quick way of +starting to read an Info file at a certain node when you don't know the +exact name of that node. @item --node @var{nodename} @itemx -n @var{nodename} -@cindex node, selecting +@cindex node, selecting from the command line Specify a particular node to visit in the initial file that Info loads. This is especially useful in conjunction with @code{--file}@footnote{Of course, you can specify both the file and node in a @code{--node} command; but don't forget to escape the open and -close parentheses from the shell as in: @code{info --node -"(emacs)Buffers"}}. You may specify @code{--node} multiple times; for +close parentheses and whitespace from the shell as in: @code{info --node +"(emacs)Buffers"}.}. You may specify @code{--node} multiple times; for an interactive Info, each @var{nodename} is visited in its own window, for a non-interactive Info (such as when @code{--output} is given) each @var{nodename} is processed sequentially. @@ -184,6 +251,36 @@ Each node that Info visits will be output to @var{filename} instead of interactively viewed. A value of @code{-} for @var{filename} specifies the standard output. +@cindex replaying recorded keystrokes +@item --restore=@var{dribble-file} +Read keystrokes from @var{dribble-file}, presumably recorded during +previous Info session (see the description of the @samp{--dribble} +option above). When the keystrokes in the files are all read, Info +reverts its input to the usual interactive operation. + +@anchor{--show-options} +@cindex command-line options, how to find +@cindex invocation description, how to find +@item --show-options +@itemx --usage +@itemx -O +This option causes Info to look for the node that describes how to +invoke the program and its command-line options, and begin the session +by displaying that node. It is provided to make it easier to find the +most important usage information in a manual without the need to wade +through complex menu hierarchies. The effect is similar to the +@code{M-x goto-invocation} command (@pxref{goto-invocation}) from inside +Info. + +@cindex speech synthesizers +@item --speech-friendly +@itemx -b +On MS-DOS/MS-Windows only, this option causes Info to use standard file +I/O functions for screen writes. (By default, Info uses direct writes +to the video memory on these systems, for faster operation and colored +display support.) This allows the speech synthesizers used by blind +persons to catch the output and convert it to audible speech. + @item --subnodes @cindex @code{--subnodes}, command line option This option only has meaning when given in conjunction with @@ -192,21 +289,26 @@ the menus of each node being output. Menu items which resolve to external Info files are not output, and neither are menu items which are members of an index. Each node is only output once. -@item --help -@itemx -h -Produces a relatively brief description of the available Info options. - @item --version @cindex version information Prints the version information of Info and exits. +@anchor{--vi-keys} +@cindex vi-like key bindings +@cindex Less-like key bindings +@item --vi-keys +This option binds functions to keys differently, to emulate the key +bindings of @code{vi} and Less. The default key bindings are generally +modeled after Emacs. + @item @var{menu-item} @cindex menu, following +@anchor{command-line menu items} Info treats its remaining arguments as the names of menu items. The -first argument is a menu item in the initial node visited, while -the second argument is a menu item in the first argument's node. -You can easily move to the node of your choice by specifying the menu -names which describe the path to that node. For example, +first argument is a menu item in the initial node visited (generally +@code{dir}), the second argument is a menu item in the first argument's +node, etc. You can easily move to the node of your choice by specifying +the menu names which describe the path to that node. For example, @example info emacs buffers @@ -218,9 +320,23 @@ and then selects the menu item @samp{Buffers} in the node @samp{(emacs)Top}. @end table -@node Cursor Commands, Scrolling Commands, Options, Top +To avoid searching the @file{dir} files and just show some arbitrary +file, use @samp{-f} and the filename, as in @samp{info -f ./foo.info}. + +The index search and the search for the node which describes program +invocation and command-line options begins @emph{after} processing all +the command-line menu items. Therefore, the Info file searched for the +index or the invocation node is the file where Info finds itself after +following all the menu items given on the command line. This is so +@samp{info emacs --show-options} does what you'd expect. + +@c FIXME: the feature with lowercasing the file name isn't documented + + +@node Cursor Commands @chapter Moving the Cursor @cindex cursor, moving +@cindex moving the cursor Many people find that reading screens of text page by page is made easier when one is able to indicate particular pieces of text with some @@ -230,7 +346,12 @@ move the cursor about the screen. The notation used in this manual to describe keystrokes is identical to the notation used within the Emacs manual, and the GNU Readline manual. @xref{Characters, , Character Conventions, emacs, the GNU Emacs Manual}, if you are unfamiliar with the -notation. +notation@footnote{ +Here's a short summary. @kbd{C-@var{x}} means press the @kbd{CTRL} key +and the key @var{x}. @kbd{M-@var{x}} means press the @kbd{META} key and +the key @var{x}. On many terminals th @kbd{META} key is known as the +@kbd{ALT} key. @kbd{SPC} is the space bar. The other keys are usually +called by the names imprinted on them.}. The following table lists the basic cursor movement commands in Info. Each entry consists of the key sequence you should type to execute the @@ -239,8 +360,8 @@ invokes @code{execute-extended-command}. @xref{M-x, , Executing an extended command, emacs, the GNU Emacs Manual}, for more detailed information.} command name (displayed in parentheses), and a short description of what the command does. All of the cursor motion commands -can take an @dfn{numeric} argument (@pxref{Miscellaneous Commands, -@code{universal-argument}}), to find out how to supply them. With a +can take a @dfn{numeric} argument (see @ref{Miscellaneous Commands, +@code{universal-argument}, to find out how to supply them}. With a numeric argument, the motion commands are simply executed that many times; for example, a numeric argument of 4 given to @code{next-line} causes the cursor to move down 4 lines. With a @@ -249,59 +370,83 @@ given to the @code{next-line} command would cause the cursor to move @emph{up} 4 lines. @table @asis -@item @code{C-n} (@code{next-line}) +@item @key{C-n} (@code{next-line}) +@itemx @key{DOWN} (an arrow key) @kindex C-n +@kindex DOWN (an arrow key) @findex next-line Move the cursor down to the next line. -@item @code{C-p} (@code{prev-line}) +@item @key{C-p} (@code{prev-line}) +@itemx @key{UP} (an arrow key) @kindex C-p +@kindex UP (an arrow key) @findex prev-line Move the cursor up to the previous line. -@item @code{C-a} (@code{beginning-of-line}) +@item @key{C-a} (@code{beginning-of-line}) +@itemx @key{Home} (on DOS/Windows only) @kindex C-a, in Info windows +@kindex Home @findex beginning-of-line Move the cursor to the start of the current line. -@item @code{C-e} (@code{end-of-line}) +@item @key{C-e} (@code{end-of-line}) +@itemx @key{End} (on DOS/Windows only) @kindex C-e, in Info windows +@kindex End @findex end-of-line Move the cursor to the end of the current line. -@item @code{C-f} (@code{forward-char}) +@item @key{C-f} (@code{forward-char}) +@itemx @key{RIGHT} (an arrow key) @kindex C-f, in Info windows +@kindex RIGHT (an arrow key) @findex forward-char Move the cursor forward a character. -@item @code{C-b} (@code{backward-char}) +@item @key{C-b} (@code{backward-char}) +@itemx @key{LEFT} (an arrow key) @kindex C-b, in Info windows +@kindex LEFT (an arrow key) @findex backward-char Move the cursor backward a character. -@item @code{M-f} (@code{forward-word}) +@item @key{M-f} (@code{forward-word}) +@itemx @kbd{C-@key{RIGHT}} (on DOS/Windows only) @kindex M-f, in Info windows +@kindex C-RIGHT @findex forward-word Move the cursor forward a word. -@item @code{M-b} (@code{backward-word}) +@item @key{M-b} (@code{backward-word}) +@itemx @kbd{C-@key{LEFT}} (on DOS/Windows only) @kindex M-b, in Info windows +@kindex C-LEFT @findex backward-word Move the cursor backward a word. -@item @code{M-<} (@code{beginning-of-node}) -@itemx @code{b} +@item @key{M-<} (@code{beginning-of-node}) +@itemx @key{C-@key{Home}} (on DOS/Windows only) +@itemx @key{b} +@itemx @key{M-b}, vi-like operation @kindex b, in Info windows @kindex M-< +@kindex C-Home +@kindex M-b, vi-like operation @findex beginning-of-node Move the cursor to the start of the current node. -@item @code{M->} (@code{end-of-node}) +@item @key{M->} (@code{end-of-node}) +@itemx @key{C-@key{End}} (on DOS/Windows only) +@itemx @key{e} @kindex M-> +@kindex e, in Info windows +@kindex C-End @findex end-of-node Move the cursor to the end of the current node. -@item @code{M-r} (@code{move-to-window-line}) +@item @key{M-r} (@code{move-to-window-line}) @kindex M-r @findex move-to-window-line Move the cursor to a specific line of the window. Without a numeric @@ -319,11 +464,23 @@ current paragraph you are reading is visible on the screen. The commands detailed in this section are used to shift which part of the current node is visible on the screen. +Scrolling commands are bound differently when @samp{--vi-keys} operation +(@pxref{--vi-keys}) is in effect. These key bindings are designated +with ``vi-like operation''. + @table @asis -@item @code{SPC} (@code{scroll-forward}) -@itemx @code{C-v} +@item @key{SPC} (@code{scroll-forward}) +@itemx @key{NEXT} (an arrow key) +@itemx @key{C-v} +@itemx @key{C-f}, vi-like operation +@itemx @key{f}, vi-like operation +@itemx @key{M-SPC}, vi-like operation @kindex SPC, in Info windows +@kindex NEXT @kindex C-v +@kindex C-f, vi-like operation +@kindex f, vi-like operation +@kindex M-SPC, vi-like operation @findex scroll-forward Shift the text in this window up. That is, show more of the node which is currently below the bottom of the window. With a numeric argument, @@ -332,15 +489,99 @@ argument of 4 would shift all of the text in the window up 4 lines (discarding the top 4 lines), and show you four new lines at the bottom of the window. Without a numeric argument, @key{SPC} takes the bottom two lines of the window and places them at the top of the window, -redisplaying almost a completely new screenful of lines. - -@item @code{DEL} (@code{scroll-backward}) -@itemx @code{M-v} +redisplaying almost a completely new screenful of lines. If you are at +the end of a node, SPC takes you to the ``next'' node, so that you can +read an entire manual from start to finish by repeating SPC. + +The default scroll size is one screen-full, but it can be changed by +invoking the (@code{scroll-forward-set-window}) command, @samp{z} under +@samp{--vi-keys}, with a numeric argument. + +@kindex PageDown +The @key{NEXT} key is known as the @key{PageDown} key on some +keyboards. When you use @key{NEXT} or @key{PageDown} to scroll, Info +never scrolls beyond the end of the current node. + +@item @key{z} (@code{scroll-forward-set-window}, vi-like operation) +@kindex z, vi-like operation +@findex scroll-forward-set-window +Scroll forward, like with @key{SPC}, but if a numeric argument is +specified, it becomes the default scroll size for subsequent +@code{scroll-forward} and @code{scroll-backward} commands. + +@item @key{DEL} (@code{scroll-backward}) +@itemx @key{PREVIOUS} (arrow key) +@itemx @key{PRIOR} (arrow key) +@itemx @key{M-v} +@itemx @key{b}, vi-like operation +@itemx @key{C-b}, vi-like operation @kindex DEL, in Info windows +@kindex PREVIOUS @kindex M-v +@kindex b, vi-like operation +@kindex C-b, vi-like operation @findex scroll-backward Shift the text in this window down. The inverse of -@code{scroll-forward}. +@code{scroll-forward}. The default scroll size can be changed by +invoking the(@code{scroll-backward-set-window}) command, @samp{w} under +@samp{--vi-keys}, with a numeric argument. + +@item @key{w} (@code{scroll-backward-set-window}, vi-like operation) +@kindex w, vi-like operation +@findex scroll-backward-set-window +Scroll backward, like with @key{DEL}, but if a numeric argument is +specified, it becomes the default scroll size for subsequent +@code{scroll-forward} and @code{scroll-backward} commands. + +@item @key{C-n} (@code{down-line}, vi-like operation) +@itemx @key{C-e}, vi-like operation +@itemx @key{RET}, vi-like operation +@itemx @key{LFD}, vi-like operation +@itemx @key{DOWN}, vi-like operation +@kindex C-n, vi-like operation +@kindex C-e, vi-like operation +@kindex RET, vi-like operation +@kindex LFD, vi-like operation +@kindex DOWN, vi-like operation +@findex down-line +Scroll forward by one line. With a numeric argument, scroll forward +that many lines. + +@item @key{C-p} (@code{up-line}, vi-like operation) +@itemx @key{UP}, vi-like operation +@itemx @key{y}, vi-like operation +@itemx @key{k}, vi-like operation +@itemx @key{C-k}, vi-like operation +@itemx @key{C-y}, vi-like operation +@kindex C-p, vi-like operation +@kindex UP, vi-like operation +@kindex y, vi-like operation +@kindex k, vi-like operation +@kindex C-k, vi-like operation +@kindex C-y, vi-like operation +@findex up-line +Scroll backward one line. With a numeric argument, scroll backward that +many lines. + +@item @key{d} (@code{scroll-half-screen-down}, vi-like operation) +@itemx @key{C-d}, vi-like operation +@kindex d, vi-like operation +@kindex C-d, vi-like operation +@findex scroll-half-screen-down +Scroll forward by half of the screen size. With a numeric argument, +scroll that many lines. If an argument is specified, it becomes the new +default number of lines to scroll for subsequent @samp{d} and @samp{u} +commands. + +@item @key{u} (@code{scroll-half-screen-up}, vi-like operation) +@itemx @key{C-u}, vi-like operation +@kindex u, vi-like operation +@kindex C-u, vi-like operation +@findex scroll-half-screen-up +Scroll back by half of the screen size. With a numeric argument, +scroll that many lines. If an argument is specified, it becomes the new +default number of lines to scroll for subsequent @samp{u} and @samp{d} +commands. @end table @cindex scrolling through node structure @@ -351,8 +592,19 @@ viewing the beginning of a node, what happens is controlled by the variable @code{scroll-behavior}. @xref{Variables, @code{scroll-behavior}}, for more information. +@kindex PageUp +The @key{PREVIOUS} key is the @key{PageUp} key on many keyboards. Emacs +refers to it by the name @key{PRIOR}. When you use @key{PRIOR} or +@key{PageUp} to scroll, Info never scrolls beyond the beginning of the +current node. + +@kindex BS (backspace) +If your keyboard lacks the @key{DEL} key, look for a key called +@key{BS}, or @samp{BackSpace}, sometimes designated with an arrow which +points to the left, which should perform the same function. + @table @asis -@item @code{C-l} (@code{redraw-display}) +@item @key{C-l} (@code{redraw-display}) @kindex C-l @findex redraw-display Redraw the display from scratch, or shift the line containing the cursor @@ -361,7 +613,7 @@ the screen, and then redraws its entire contents. Given a numeric argument of @var{n}, the line containing the cursor is shifted so that it is on the @var{n}th line of the window. -@item @code{C-x w} (@code{toggle-wrap}) +@item @kbd{C-x @key{w}} (@code{toggle-wrap}) @kindex C-w @findex toggle-wrap Toggles the state of line wrapping in the current window. Normally, @@ -372,7 +624,8 @@ terminated at the rightmost column by changing the state of line wrapping in the window with @code{C-x w}. When a line which needs more space than one screen width to display is displayed, a @samp{$} appears in the rightmost column of the screen, and the remainder of the line is -invisible. +invisible. When long lines are truncated, the modeline displays the +@samp{$} character near its left edge. @end table @node Node Commands, Searching Commands, Scrolling Commands, Top @@ -383,7 +636,9 @@ This section details the numerous Info commands which select a new node to view in the current window. The most basic node commands are @samp{n}, @samp{p}, @samp{u}, and -@samp{l}. +@samp{l}. Note that the commands to select nodes are mapped differently +when @samp{--vi-keys} is in effect; these keybindings are designated +below as ``vi-like operation''. When you are viewing a node, the top line of the node contains some Info @dfn{pointers} which describe where the next, previous, and up nodes @@ -391,47 +646,78 @@ are. Info uses this line to move about the node structure of the file when you use the following commands: @table @asis -@item @code{n} (@code{next-node}) +@item @key{n} (@code{next-node}) +@itemx @kbd{C-@key{NEXT}} (on DOS/Windows only) +@itemx @kbd{C-x @key{n}}, vi-like operation @kindex n +@kindex C-NEXT +@kindex C-x n, vi-like operation @findex next-node -Select the `Next' node. +Select the `Next' node. -@item @code{p} (@code{prev-node}) +@kindex C-PgDn +The @key{NEXT} key is known as the @key{PgDn} key on some +keyboards. + +@item @key{p} (@code{prev-node}) +@itemx @kbd{C-@key{PREVIOUS}} (on DOS/Windows only) @kindex p +@kindex C-PREVIOUS @findex prev-node Select the `Prev' node. -@item @code{u} (@code{up-node}) +@kindex C-PgUp +The @key{PREVIOUS} key is known as the @key{PgUp} key on some +keyboards. + +@item @key{u} (@code{up-node}) +@itemx @kbd{C-@key{UP}} (an arrow key on DOS/Windows only) +@itemx @kbd{C-x @key{u}}, vi-like operation @kindex u +@kindex C-UP +@kindex C-x u, vi-like operation @findex up-node Select the `Up' node. @end table You can easily select a node that you have already viewed in this window by using the @samp{l} command -- this name stands for "last", and -actually moves through the list of already visited nodes for this -window. @samp{l} with a negative numeric argument moves forward through -the history of nodes for this window, so you can quickly step between -two adjacent (in viewing history) nodes. +actually moves backwards through the history of visited nodes for this +window. This is handy when you followed a reference to another node, +possibly to read about a related issue, and would like then to resume +reading at the same place where you started the excursion. + +Each node where you press @samp{l} is discarded from the history. Thus, +by the time you get to the first node you visited in a window, the +entire history of that window is discarded. @table @asis -@item @code{l} (@code{history-node}) +@item @key{l} (@code{history-node}) +@itemx @key{C-@key{CENTER}} (on DOS/Windows only) +@itemx @key{'}, vi-like operation @kindex l +@kindex C-CENTER +@kindex ', vi-like operation @findex history-node -Select the most recently selected node in this window. +Pop the most recently selected node in this window from the node +history. @end table Two additional commands make it easy to select the most commonly selected nodes; they are @samp{t} and @samp{d}. @table @asis -@item @code{t} (@code{top-node}) +@item @key{t} (@code{top-node}) +@itemx @key{M-t}, vi-like operation @kindex t +@kindex M-t, vi-like operation @findex top-node Select the node @samp{Top} in the current Info file. -@item @code{d} (@code{dir-node}) +@item @key{d} (@code{dir-node}) +@itemx @key{M-d}, vi-like operation @kindex d +@kindex M-d, vi-like operation @findex dir-node Select the directory node (i.e., the node @samp{(dir)}). @end table @@ -440,18 +726,27 @@ Here are some other commands which immediately result in the selection of a different node in the current window: @table @asis -@item @code{<} (@code{first-node}) +@item @key{<} (@code{first-node}) +@itemx @key{g}, vi-like operation @kindex < +@kindex g, vi-like operation @findex first-node Selects the first node which appears in this file. This node is most -often @samp{Top}, but it does not have to be. +often @samp{Top}, but it does not have to be. With a numeric argument +@var{N}, select the @var{N}th node (the first node is node 1). An +argument of zero is the same as the argument of 1. -@item @code{>} (@code{last-node}) +@item @key{>} (@code{last-node}) +@itemx @key{G}, vi-like operation @kindex > +@kindex G, vi-like operation @findex last-node -Select the last node which appears in this file. +Select the last node which appears in this file. With a numeric argument +@var{N}, select the @var{N}th node (the first node is node 1). An +argument of zero is the same as no argument, i.e., it selects the last +node. -@item @code{]} (@code{global-next-node}) +@item @key{]} (@code{global-next-node}) @kindex ] @findex global-next-node Move forward or down through node structure. If the node that you are @@ -460,7 +755,7 @@ Otherwise, if this node has a menu, the first menu item is selected. If there is no @samp{Next} and no menu, the same process is tried with the @samp{Up} node of this node. -@item @code{[} (@code{global-prev-node}) +@item @key{[} (@code{global-prev-node}) @kindex [ @findex global-prev-node Move backward or up through node structure. If the node that you are @@ -475,13 +770,18 @@ You can get the same behavior as @code{global-next-node} and more information. @table @asis -@item @code{g} (@code{goto-node}) +@anchor{goto-node} +@item @key{g} (@code{goto-node}) +@itemx @kbd{C-x @key{g}}, vi-like operation @kindex g +@kindex C-x g, vi-like operation @findex goto-node -Read the name of a node and select it. No completion is done while -reading the node name, since the desired node may reside in a separate -file. The node must be typed exactly as it appears in the Info file. A -file name may be included as with any node specification, for example +Read the name of a node and select it. While reading the node name, +completion (@pxref{The Echo Area, completion}) is only done for the +nodes which reside in one of the Info files that were loaded in the +current Info session; if the desired node resides in some other file, +you must type the node exactly as it appears in that Info file, and you +must include the Info file of the other file. For example, @example @code{g(emacs)Buffers} @@ -489,7 +789,61 @@ file name may be included as with any node specification, for example finds the node @samp{Buffers} in the Info file @file{emacs}. -@item @code{C-x k} (@code{kill-node}) +@anchor{goto-invocation} +@item @key{O} (@code{goto-invocation} +@itemx @key{I} +@kindex O +@kindex I +@findex goto-invocation +@cindex finding the Invocation node +Read the name of a program and look for a node in the current Info file +which describes the invocation and the command-line options for that +program. The default program name is derived from the name of the +current Info file. This command does the same as the +@samp{--show-options} command-line option (@pxref{--show-options}), but +it also allows to specify the program name; this is important for those +manuals which describe several programs. + +If you need to find the Invocation node of a program that is documented +in another Info file, you need to visit that file before invoking +@samp{I}. For example, if you are reading the Emacs manual and want to +see the command-line options of the @code{makeinfo} program, type @kbd{g +(texinfo) @key{RET}} and then @kbd{I makeinfo @key{RET}}. If you don't +know what Info file documents the command, or if invoking @samp{I} +doesn't display the right node, go to the @samp{(dir)} node (using the +@samp{d} command) and invoke @samp{I} from there. + +@item @key{G} (@code{menu-sequence}) +@kindex G +@findex menu-sequence +@cindex menu, following, from inside Info +Read a sequence of menu entries and follow it. Info prompts for a +sequence of menu items separated by commas. (Since commas are not +allowed in a node name, they are a natural choice for a delimiter in a +list of menu items.) Info then looks up the first item in the menu of +the node @samp{(dir)} (if the @samp{(dir)} node cannot be found, Info +uses @samp{Top}). If such an entry is found, Info goes to the node it +points to and looks up the second item in the menu of that node, etc. +In other words, you can specify a complete path which descends through +the menu hierarchy of a particular Info file starting at the +@samp{(dir)} node. This has the same effect as if you typed the menu +item sequence on Info's command line, see @ref{command-line menu items,, +Info command-line arguments processing}. For example, + +@example + @kbd{G Texinfo,Overview,Reporting Bugs @key{RET}} +@end example + +@noindent +displays the node @samp{Reporting Bugs} in the Texinfo manual. (You +don't actually need to type the menu items in their full length, or in +their exact letter-case. However, if you do type the menu items +exactly, Info will find it faster.) + +If any of the menu items you type are not found, Info stops at the last +entry it did find and reports an error. + +@item @kbd{C-x @key{k}} (@code{kill-node}) @kindex C-x k @findex kill-node Kill a node. The node name is prompted for in the echo area, with a @@ -498,7 +852,7 @@ hard to forget about it, removing it from the list of history nodes kept for the window where that node is found. Another node is selected in the window which contained the killed node. -@item @code{C-x C-f} (@code{view-file}) +@item @kbd{C-x C-f} (@code{view-file}) @kindex C-x C-f @findex view-file Read the name of a file and selects the entire file. The command @@ -510,14 +864,14 @@ is equivalent to typing @code{g(@var{filename})*} @end example -@item @code{C-x C-b} (@code{list-visited-nodes}) +@item @kbd{C-x C-b} (@code{list-visited-nodes}) @kindex C-x C-b @findex list-visited-nodes Make a window containing a menu of all of the currently visited nodes. This window becomes the selected window, and you may use the standard Info commands within it. -@item @code{C-x b} (@code{select-visited-node}) +@item @kbd{C-x @key{b}} (@code{select-visited-node}) @kindex C-x b @findex select-visited-node Select a node which has been previously visited in a visible window. @@ -534,49 +888,111 @@ entire Info file, search through the indices of an Info file, or find areas within an Info file which discuss a particular topic. @table @asis -@item @code{s} (@code{search}) +@item @key{s} (@code{search}) +@itemx @key{/} @kindex s +@kindex / @findex search -Read a string in the echo area and search for it. - -@item @code{C-s} (@code{isearch-forward}) +Read a string in the echo area and search for it. If the string +includes upper-case characters, the Info file is searched +case-sensitively; otherwise Info ignores the letter case. With a +numeric argument of @var{N}, search for @var{N}th occurrence of the +string. Negative arguments search backwards. + +@item @key{?} (@code{search-backward}, vi-like operation) +@kindex ?, vi-like operation +@findex search-backward +Read a string in the echo area and search backward through the Info file +for that string. If the string includes upper-case characters, the Info +file is searched case-sensitively; otherwise Info ignores the letter +case. With a numeric argument of @var{N}, search for @var{N}th +occurrence of the string. Negative arguments search forward. + +@item @key{S} (@code{search-case-sensitively} +@kindex S +@findex search-case-sensitively +@cindex search, case-sensitive +@cindex case-sensitive search +Read a string in the echo area and search for it case-sensitively, even +if the string includes only lower-case letters. With a numeric argument +of @var{N}, search for @var{N}th occurrence of the string. Negative +arguments search backwards. + +@item @kbd{C-x @key{n}} (@code{search-next}) +@itemx @key{n}, vi-like operation +@kindex C-x n +@kindex n, vi-like operation +@findex search-next +@cindex repeated search +Search for the same string used in the last search command, in the same +direction, and with the same case-sensitivity option. With a numeric +argument of @var{N}, search for @var{N}th next occurrence. + +@item @kbd{C-x @key{N}} (@code{search-previous}) +@itemx @key{N}, vi-like operation +@kindex C-x N +@kindex n, vi-like operation +@findex search-previous +Search for the same string used in the last search command, and with the +same case-sensitivity option, but in the reverse direction. With a +numeric argument of @var{N}, search for @var{N}th previous occurrence. + +@item @key{C-s} (@code{isearch-forward}) @kindex C-s @findex isearch-forward +@cindex incremental search Interactively search forward through the Info file for a string as you -type it. +type it. If the string includes upper-case characters, the search is +case-sensitive; otherwise Info ignores the letter case. -@item @code{C-r} (@code{isearch-backward}) +@item @key{C-r} (@code{isearch-backward}) @kindex C-r @findex isearch-backward Interactively search backward through the Info file for a string as -you type it. +you type it. If the string includes upper-case characters, the search +is case-sensitive; otherwise Info ignores the letter case. -@item @code{i} (@code{index-search}) +@item @key{i} (@code{index-search}) @kindex i @findex index-search +@cindex index, searching +@cindex searching, in the indices Look up a string in the indices for this Info file, and select a node where the found index entry points to. -@item @code{,} (@code{next-index-match}) +@item @key{,} (@code{next-index-match}) @kindex , @findex next-index-match Move to the node containing the next matching index item from the last @samp{i} command. @end table -The most basic searching command is @samp{s} (@code{search}). The -@samp{s} command prompts you for a string in the echo area, and then -searches the remainder of the Info file for an occurrence of that string. -If the string is found, the node containing it is selected, and the -cursor is left positioned at the start of the found string. Subsequent -@samp{s} commands show you the default search string within @samp{[} and -@samp{]}; pressing @key{RET} instead of typing a new string will use the -default search string. +The most basic searching command is @samp{s} or @samp{/} +(@code{search}). The @samp{s} command prompts you for a string in the +echo area, and then searches the remainder of the Info file for an +occurrence of that string. If the string is found, the node containing +it is selected, and the cursor is left positioned at the start of the +found string. Subsequent @samp{s} commands show you the default search +string within @samp{[} and @samp{]}; pressing @key{RET} instead of +typing a new string will use the default search string. Under +@samp{--vi-keys} (@pxref{--vi-keys}), using the @samp{n} or @samp{N} +commands is a faster way of searching for the same string. @dfn{Incremental searching} is similar to basic searching, but the string is looked up while you are typing it, instead of waiting until the entire search string has been specified. +@cindex search, and case-sensitivity +@cindex case-sensitivity, and search +Both incremental and non-incremental search by default ignore the case +of letters when comparing the Info file text with the search string. +However, an uppercase letter in the search string makes the search +case-sensitive. You can force a case-sensitive non-incremental search, +even for a string that includes only lower-case letters, by using the +@samp{S} command (@code{search-case-sensitively}). The @samp{n} and +@samp{N} commands operate case-sensitively if the last search command +was @samp{S}. + @node Xref Commands, Window Commands, Searching Commands, Top @chapter Selecting Cross References @@ -645,63 +1061,85 @@ references. The following table lists the Info commands which operate on menu items. @table @asis -@item @code{1} (@code{menu-digit}) -@itemx @code{2} @dots{} @code{9} +@item @key{1} (@code{menu-digit}) +@itemx @key{2} @dots{} @key{9} +@itemx @key{M-1}, vi-like operation +@itemx @key{M-2} @dots{} @key{M-9}, vi-like operation @cindex 1 @dots{} 9, in Info windows +@cindex M-1 @dots{} M-9, vi-like operation @kindex 1 @dots{} 9, in Info windows +@kindex M-1 @dots{} M-9, vi-like operation @findex menu-digit Within an Info window, pressing a single digit, (such as @samp{1}), selects that menu item, and places its node in the current window. For convenience, there is one exception; pressing @samp{0} selects the -@emph{last} item in the node's menu. +@emph{last} item in the node's menu. When @samp{--vi-keys} is in +effect, digits set the numeric argument, so these commands are remapped +to their @samp{M-} varieties. For example, to select the last menu +item, press @key{M-0}. -@item @code{0} (@code{last-menu-item}) +@item @key{0} (@code{last-menu-item}) +@itemx @key{M-0}, vi-like operation @kindex 0, in Info windows +@kindex M-0, vi-like operation @findex last-menu-item Select the last item in the current node's menu. -@item @code{m} (@code{menu-item}) +@item @key{m} (@code{menu-item}) @kindex m @findex menu-item Reads the name of a menu item in the echo area and selects its node. -Completion is available while reading the menu label. +Completion is available while reading the menu label. @xref{The Echo +Area, completion}. -@item @code{M-x find-menu} +@item @kbd{M-x find-menu} @findex find-menu Move the cursor to the start of this node's menu. @end table -This table lists the Info commands which operate on note cross references. +This table lists the Info commands which operate on cross references. @table @asis -@item @code{f} (@code{xref-item}) -@itemx @code{r} +@item @key{f} (@code{xref-item}) +@itemx @key{r} +@item @key{M-f}, vi-like operation +@itemx @kbd{C-x @key{r}}, vi-like operation @kindex f @kindex r +@kindex M-f, vi-like operation +@kindex C-x r, vi-like operation @findex xref-item Reads the name of a note cross reference in the echo area and selects its node. Completion is available while reading the cross reference -label. +label. @xref{The Echo Area, completion}. @end table Finally, the next few commands operate on menu or note references alike: @table @asis -@item @code{TAB} (@code{move-to-next-xref}) +@item @key{TAB} (@code{move-to-next-xref}) @kindex TAB, in Info windows @findex move-to-next-xref Move the cursor to the start of the next nearest menu item or note reference in this node. You can then use @key{RET} (@code{select-reference-this-line}) to select the menu or note reference. -@item @code{M-TAB} (@code{move-to-prev-xref}) +@item @key{M-TAB} (@code{move-to-prev-xref}) +@itemx @key{Shift-@key{TAB}} (on DOS/Windows only) @kindex M-TAB, in Info windows @findex move-to-prev-xref Move the cursor the start of the nearest previous menu item or note reference in this node. -@item @code{RET} (@code{select-reference-this-line}) +@kindex Shift-TAB, in Info windows +@kindex BackTab, in Info windows +On DOS/Windows only, the @kbd{Shift-@key{TAB}} key is an alias for +@kbd{M-@key{TAB}}. This key is sometimes called @samp{BackTab}. + +@item @key{RET} (@code{select-reference-this-line}) +@itemx @key{M-g}, vi-like operation @kindex RET, in Info windows +@kindex M-g, vi-like operation @findex select-reference-this-line Select the menu item or note reference appearing on this line. @end table @@ -744,7 +1182,7 @@ named @file{dir}, showing the node @samp{Top}. @example @group ------Info: (dir)Top, 40 lines --Top--------------------------------------- +-----Info: (dir)Top, 40 lines --Top------------------------------------- ^^ ^ ^^^ ^^ (file)Node #lines where @end group @@ -756,8 +1194,16 @@ the Info file containing the node has been split into subfiles, the name of the subfile containing the node appears in the modeline as well: @example ---zz-Info: (emacs)Top, 291 lines --Top-- Subfile: emacs-1.Z--------------- -@end example +--zz-Info: (emacs)Top, 291 lines --Top-- Subfile: emacs-1.Z------------- +@end example + +Truncation of long lines (as opposed to wrapping them to the next +display line, @pxref{Scrolling Commands, toggle-wrap}) is indicated by a +@samp{$} at the left edge of the mode line: + +@example +--$--Info: (texinfo)Top, 480 lines --Top-- Subfile: texinfo-1----------- +@end example When Info makes a node internally, such that there is no corresponding info file on disk, the name of the node is surrounded by asterisks @@ -766,7 +1212,7 @@ are; the sample mode line below shows an internally constructed node showing possible completions: @example ------Info: *Completions*, 7 lines --All----------------------------------- +-----Info: *Completions*, 7 lines --All--------------------------------- @end example @node Basic Windows, The Echo Area, The Mode Line, Window Commands @@ -778,7 +1224,7 @@ own mode line (@pxref{The Mode Line}) and history of nodes viewed in that window (@pxref{Node Commands, , @code{history-node}}). @table @asis -@item @code{C-x o} (@code{next-window}) +@item @kbd{C-x @key{o}} (@code{next-window}) @cindex windows, selecting @kindex C-x o @findex next-window @@ -790,12 +1236,12 @@ window on the screen. Given a numeric argument, @samp{C-x o} moves over that many windows. A negative argument causes @samp{C-x o} to select the previous window on the screen. -@item @code{M-x prev-window} +@item @kbd{M-x prev-window} @findex prev-window Select the previous window on the screen. This is identical to @samp{C-x o} with a negative argument. -@item @code{C-x 2} (@code{split-window}) +@item @kbd{C-x @key{2}} (@code{split-window}) @cindex windows, creating @kindex C-x 2 @findex split-window @@ -806,7 +1252,7 @@ can cause all of the windows on the screen to be resized for you automatically, please @pxref{Variables, , automatic-tiling} for more information. -@item @code{C-x 0} (@code{delete-window}) +@item @kbd{C-x @key{0}} (@code{delete-window}) @cindex windows, deleting @kindex C-x 0 @findex delete-window @@ -814,26 +1260,26 @@ Delete the current window from the screen. If you have made too many windows and your screen appears cluttered, this is the way to get rid of some of them. -@item @code{C-x 1} (@code{keep-one-window}) +@item @kbd{C-x @key{1}} (@code{keep-one-window}) @kindex C-x 1 @findex keep-one-window Delete all of the windows excepting the current one. -@item @code{ESC C-v} (@code{scroll-other-window}) +@item @kbd{ESC @key{C-v}} (@code{scroll-other-window}) @kindex ESC C-v, in Info windows @findex scroll-other-window Scroll the other window, in the same fashion that @samp{C-v} might scroll the current window. Given a negative argument, scroll the "other" window backward. -@item @code{C-x ^} (@code{grow-window}) +@item @kbd{C-x @key{^}} (@code{grow-window}) @kindex C-x ^ @findex grow-window Grow (or shrink) the current window. Given a numeric argument, grow the current window that many lines; with a negative numeric argument, shrink the window instead. -@item @code{C-x t} (@code{tile-windows}) +@item @kbd{C-x @key{t}} (@code{tile-windows}) @cindex tiling @kindex C-x t @findex tile-windows @@ -858,117 +1304,170 @@ table briefly lists the commands that are available while input is being read in the echo area: @table @asis -@item @code{C-f} (@code{echo-area-forward}) +@item @key{C-f} (@code{echo-area-forward}) +@itemx @key{RIGHT} (an arrow key) +@itemx @key{M-h}, vi-like operation @kindex C-f, in the echo area +@kindex RIGHT, in the echo area +@kindex M-h, in the echo area, vi-like operation @findex echo-area-forward Move forward a character. -@item @code{C-b} (@code{echo-area-backward}) +@item @key{C-b} (@code{echo-area-backward}) +@itemx @key{LEFT} (an arrow key) +@itemx @key{M-l}, vi-like operation +@kindex LEFT, in the echo area @kindex C-b, in the echo area +@kindex M-l, in the echo area, vi-like operation @findex echo-area-backward Move backward a character. -@item @code{C-a} (@code{echo-area-beg-of-line}) +@item @key{C-a} (@code{echo-area-beg-of-line}) +@itemx @key{M-0}, vi-like operation @kindex C-a, in the echo area +@kindex M-0, in the echo area, vi-like operation @findex echo-area-beg-of-line Move to the start of the input line. -@item @code{C-e} (@code{echo-area-end-of-line}) +@item @key{C-e} (@code{echo-area-end-of-line}) +@itemx @key{M-$}, vi-like operation @kindex C-e, in the echo area +@kindex M-$, vi-like operation @findex echo-area-end-of-line Move to the end of the input line. -@item @code{M-f} (@code{echo-area-forward-word}) +@item @key{M-f} (@code{echo-area-forward-word}) +@itemx @key{C-@key{RIGHT}} (DOS/Windows only) +@itemx @key{M-w}, vi-like operation @kindex M-f, in the echo area +@kindex M-w, in the echo area, vi-like operation @findex echo-area-forward-word Move forward a word. -@item @code{M-b} (@code{echo-area-backward-word}) +@kindex C-RIGHT, in the echo area +On DOS/Windows, @kbd{C-@key{RIGHT}} moves forward by words. + +@item @key{M-b} (@code{echo-area-backward-word}) +@itemx @key{C-@key{LEFT}} (DOS/Windows only) @kindex M-b, in the echo area @findex echo-area-backward-word Move backward a word. -@item @code{C-d} (@code{echo-area-delete}) +@kindex C-LEFT, in the echo area +On DOS/Windows, @kbd{C-@key{LEFT}} moves backward by words. + +@item @key{C-d} (@code{echo-area-delete}) +@itemx @key{M-x}, vi-like operation @kindex C-d, in the echo area +@kindex M-x, in the echo area, vi-like operation @findex echo-area-delete Delete the character under the cursor. -@item @code{DEL} (@code{echo-area-rubout}) +@item @key{DEL} (@code{echo-area-rubout}) @kindex DEL, in the echo area @findex echo-area-rubout Delete the character behind the cursor. -@item @code{C-g} (@code{echo-area-abort}) +On some keyboards, this key is designated @key{BS}, for +@samp{BackSpace}. Those keyboards will usually bind @key{DEL} in the +echo area to @code{echo-area-delete}. + +@item @key{C-g} (@code{echo-area-abort}) +@itemx @key{C-u}, vi-like operation @kindex C-g, in the echo area +@kindex C-u, in the echo area, vi-like operation @findex echo-area-abort -Cancel or quit the current operation. If completion is being read, -@samp{C-g} discards the text of the input line which does not match any -completion. If the input line is empty, @samp{C-g} aborts the calling -function. +Cancel or quit the current operation. If completion is being read, this +command discards the text of the input line which does not match any +completion. If the input line is empty, it aborts the calling function. -@item @code{RET} (@code{echo-area-newline}) +@item @key{RET} (@code{echo-area-newline}) @kindex RET, in the echo area @findex echo-area-newline Accept (or forces completion of) the current input line. -@item @code{C-q} (@code{echo-area-quoted-insert}) +@item @key{C-q} (@code{echo-area-quoted-insert}) +@itemx @key{C-v}, vi-like operation @kindex C-q, in the echo area +@kindex C-v, in the echo area, vi-like operation @findex echo-area-quoted-insert Insert the next character verbatim. This is how you can insert control -characters into a search string, for example. +characters into a search string, for example, or the @samp{?} character +when Info prompts with completion. @item @var{printing character} (@code{echo-area-insert}) @kindex printing characters, in the echo area @findex echo-area-insert -Insert the character. +Insert the character. Characters that have their 8th bit set, and not +bound to @samp{M-} commands, are also inserted verbatim; this is useful +for terminals which support Latin scripts. -@item @code{M-TAB} (@code{echo-area-tab-insert}) +@item @key{M-TAB} (@code{echo-area-tab-insert}) +@itemx @key{Shift-@key{TAB}} (on DOS/Windows only) @kindex M-TAB, in the echo area +@kindex Shift-TAB, in the echo area @findex echo-area-tab-insert Insert a TAB character. -@item @code{C-t} (@code{echo-area-transpose-chars}) +@kindex Shift-TAB, in the echo area +@kindex BackTab, in the echo area +On DOS/Windows only, the @kbd{Shift-@key{TAB}} key is an alias for +@kbd{M-@key{TAB}}. This key is sometimes called @samp{BackTab}. + +@item @key{C-t} (@code{echo-area-transpose-chars}) @kindex C-t, in the echo area @findex echo-area-transpose-chars Transpose the characters at the cursor. @end table The next group of commands deal with @dfn{killing}, and @dfn{yanking} -text. For an in depth discussion of killing and yanking, -@pxref{Killing, , Killing and Deleting, emacs, the GNU Emacs Manual} +text@footnote{ +Some people are used to calling these operations @dfn{cut} and +@dfn{paste}, respectively.}. For an in depth discussion of killing and +yanking, @pxref{Killing, , Killing and Deleting, emacs, the GNU Emacs +Manual} @table @asis -@item @code{M-d} (@code{echo-area-kill-word}) +@item @key{M-d} (@code{echo-area-kill-word}) +@itemx @key{M-X}, vi-like operation @kindex M-d, in the echo area +@kindex M-X, in the echo area, vi-like operation @findex echo-area-kill-word Kill the word following the cursor. -@item @code{M-DEL} (@code{echo-area-backward-kill-word}) +@item @key{M-DEL} (@code{echo-area-backward-kill-word}) +@itemx @key{M-@key{BS}} @kindex M-DEL, in the echo area @findex echo-area-backward-kill-word Kill the word preceding the cursor. -@item @code{C-k} (@code{echo-area-kill-line}) +@kindex M-BS, in the echo area +On some keyboards, the @code{Backspace} key is used instead of +@code{DEL}, so @code{M-@key{Backspace}} has the same effect as +@code{M-@key{DEL}}. + +@item @key{C-k} (@code{echo-area-kill-line}) @kindex C-k, in the echo area @findex echo-area-kill-line Kill the text from the cursor to the end of the line. -@item @code{C-x DEL} (@code{echo-area-backward-kill-line}) +@item @kbd{C-x @key{DEL}} (@code{echo-area-backward-kill-line}) @kindex C-x DEL, in the echo area @findex echo-area-backward-kill-line Kill the text from the cursor to the beginning of the line. -@item @code{C-y} (@code{echo-area-yank}) +@item @key{C-y} (@code{echo-area-yank}) @kindex C-y, in the echo area @findex echo-area-yank Yank back the contents of the last kill. -@item @code{M-y} (@code{echo-area-yank-pop}) +@item @key{M-y} (@code{echo-area-yank-pop}) @kindex M-y, in the echo area @findex echo-area-yank-pop Yank back a previous kill, removing the last yanked text first. @end table +@cindex completion Sometimes when reading input in the echo area, the command that needed input will only accept one of a list of several choices. The choices represent the @dfn{possible completions}, and you must respond with one @@ -981,14 +1480,14 @@ is called @dfn{completion}. The following commands are available when completing in the echo area: @table @asis -@item @code{TAB} (@code{echo-area-complete}) -@itemx @code{SPC} +@item @key{TAB} (@code{echo-area-complete}) +@itemx @key{SPC} @kindex TAB, in the echo area @kindex SPC, in the echo area @findex echo-area-complete Insert as much of a completion as is possible. -@item @code{?} (@code{echo-area-possible-completions}) +@item @key{?} (@code{echo-area-possible-completions}) @kindex ?, in the echo area @findex echo-area-possible-completions Display a window containing a list of the possible completions of what @@ -1004,13 +1503,14 @@ forget @end example @noindent -and you have typed an @samp{f}, followed by @samp{?}, the possible -completions would contain: +and you have typed an @samp{f}, followed by @samp{?}, Info will pop up a +window showing a node called @samp{*Completions*} which lists the +possible completions like this: @example @group -foliate -food +3 completions: +foliate food forget @end group @end example @@ -1023,7 +1523,7 @@ Now, typing @samp{l} followed by @samp{TAB} results in @samp{foliate} appearing in the echo area, since that is the only choice which begins with @samp{fol}. -@item @code{ESC C-v} (@code{echo-area-scroll-completions-window}) +@item @key{ESC C-v} (@code{echo-area-scroll-completions-window}) @kindex ESC C-v, in the echo area @findex echo-area-scroll-completions-window Scroll the completions window, if that is visible, or the "other" @@ -1034,19 +1534,29 @@ window if not. @chapter Printing Out Nodes @cindex printing -You may wish to print out the contents of a node as a quick reference -document for later use. Info provides you with a command for doing -this. In general, we recommend that you use @TeX{} to format the -document and print sections of it, by running @code{tex} on the Texinfo -source file. +In general, we recommend that you use @TeX{} to format the document and +print sections of it, by running @code{tex} on the Texinfo source file. +However, you may wish to print out the contents of a node as a quick +reference document for later use, or if you don't have @TeX{} installed. +Info provides you with a command for doing this. @table @asis -@item @code{M-x print-node} +@item @kbd{M-x print-node} @findex print-node @cindex INFO_PRINT_COMMAND, environment variable Pipe the contents of the current node through the command in the environment variable @code{INFO_PRINT_COMMAND}. If the variable does not -exist, the node is simply piped to @code{lpr}. +exist, the node is simply piped to @code{lpr} (on DOS/Windows, the +default is to print the node to the local printer device, @file{PRN}). + +@cindex printing nodes to the local printer +@cindex local printer device +The value of @code{INFO_PRINT_COMMAND} may begin with the @samp{>} +character, as in @samp{>/dev/printer}, in which case Info treats the +rest as the name of a file or a device. Instead of piping to a command, +Info opens the file, writes the node contents, and closes the file, +under the assumption that text written to that file will be printed by +the underlying OS. @end table @node Miscellaneous Commands, Variables, Printing Nodes, Top @@ -1055,39 +1565,45 @@ exist, the node is simply piped to @code{lpr}. GNU Info contains several commands which self-document GNU Info: @table @asis -@item @code{M-x describe-command} +@item @kbd{M-x describe-command} @cindex functions, describing @cindex commands, describing @findex describe-command Read the name of an Info command in the echo area and then display a brief description of what that command does. -@item @code{M-x describe-key} +@item @kbd{M-x describe-key} @cindex keys, describing @findex describe-key Read a key sequence in the echo area, and then display the name and documentation of the Info command that the key sequence invokes. -@item @code{M-x describe-variable} +@item @kbd{M-x describe-variable} Read the name of a variable in the echo area and then display a brief description of what the variable affects. -@item @code{M-x where-is} +@item @kbd{M-x where-is} @findex where-is Read the name of an Info command in the echo area, and then display a key sequence which can be typed in order to invoke that command. -@item @code{C-h} (@code{get-help-window}) -@itemx @code{?} +@item @key{C-h} (@code{get-help-window}) +@itemx @key{?} +@itemx @key{F1} (on DOS/Windows only) +@itemx h, vi-like operation @kindex C-h @kindex ?, in Info windows +@kindex F1 +@kindex h, vi-like operation @findex get-help-window Create (or Move into) the window displaying @code{*Help*}, and place a node containing a quick reference card into it. This window displays the most concise information about GNU Info available. -@item @code{h} (@code{get-info-help-node}) +@item @key{h} (@code{get-info-help-node}) +@itemx @key{M-h}, vi-like operation @kindex h +@kindex M-h, vi-like operation @findex get-info-help-node Try hard to visit the node @code{(info)Help}. The Info file @file{info.texi} distributed with GNU Info contains this node. Of @@ -1098,18 +1614,25 @@ placed into the location of your Info directory. Here are the commands for creating a numeric argument: @table @asis -@item @code{C-u} (@code{universal-argument}) +@item @key{C-u} (@code{universal-argument}) @cindex numeric arguments @kindex C-u @findex universal-argument Start (or multiply by 4) the current numeric argument. @samp{C-u} is a good way to give a small numeric argument to cursor movement or scrolling commands; @samp{C-u C-v} scrolls the screen 4 lines, while -@samp{C-u C-u C-n} moves the cursor down 16 lines. - -@item @code{M-1} (@code{add-digit-to-numeric-arg}) -@itemx @code{M-2} @dots{} @code{M-9} -@kindex M-1 @dots{} M-9 +@samp{C-u C-u C-n} moves the cursor down 16 lines. @samp{C-u} followed +by digit keys sets the numeric argument to the number thus typed: +@kbd{C-u 1 2 0} sets the argument to 120. + +@item @key{M-1} (@code{add-digit-to-numeric-arg}) +@itemx @key{1}, vi-like operation +@itemx @key{M-2} @dots{} @key{M-9} +@itemx @key{2} @dots{} @key{9}, vi-like operation +@itemx @key{M-0} +@itemx @key{0}, vi-like operation +@kindex M-0 @dots{} M-9 +@kindex 0 @dots{} 9, vi-like operation @findex add-digit-to-numeric-arg Add the digit value of the invoking key to the current numeric argument. Once Info is reading a numeric argument, you may just type @@ -1126,6 +1649,22 @@ or @example @kbd{M-3 2 C-l} @end example + +@item @key{M--} (@code{add-digit-to-numeric-arg} +@itemx @key{-} +@kindex M-- +@kindex - +@cindex negative arguments +@cindex arguments, negative +@cindex numeric arguments, negative +To make a negative argument, type @kbd{-}. Typing @kbd{-} alone makes a +negative argument with a value of -1. If you continue to type digit or +Meta-digit keys after @kbd{-}, the result is a negative number produced +by those digits. + +@kbd{-} doesn't work when you type in the echo area, because you need to +be able to insert the @samp{-} character itself; use @kbd{M--} instead, +if you need to specify negative arguments in the echo area. @end table @samp{C-g} is used to abort the reading of a multi-character key @@ -1133,20 +1672,29 @@ sequence, to cancel lengthy operations (such as multi-file searches) and to cancel reading input in the echo area. @table @asis -@item @code{C-g} (@code{abort-key}) +@item @key{C-g} (@code{abort-key}) +@itemx @key{C-u}, vi-like operation @cindex cancelling typeahead @cindex cancelling the current operation @kindex C-g, in Info windows +@kindex C-u cancels typeahead, vi-like operation @findex abort-key Cancel current operation. @end table -The @samp{q} command of Info simply quits running Info. +The @samp{q} command of Info simply quits running Info. Under +@samp{--vi-keys} (@pxref{--vi-keys}), you can also exit with @samp{:q} +or @samp{ZZ}. @table @asis -@item @code{q} (@code{quit}) +@item @key{q} (@code{quit}) +@itemx @kbd{C-x C-c} +@itemx @kbd{:q}, vi-like operation +@itemx @kbd{ZZ}, vi-like operation @cindex quitting @kindex q +@kindex C-x C-c +@kindex ZZ, vi-like operation @findex quit Exit GNU Info. @end table @@ -1156,18 +1704,22 @@ and it is actually only 40 lines tall, here is a way to tell Info that the operating system is correct. @table @asis -@item @code{M-x set-screen-height} +@item @kbd{M-x set-screen-height} @findex set-screen-height @cindex screen, changing the height of Read a height value in the echo area and set the height of the displayed screen to that value. @end table +On MS-DOS/MS-Windows, this command actually tries to change the +dimensions of the visible screen to the value you type in the echo +area. + Finally, Info provides a convenient way to display footnotes which might be associated with the current node that you are viewing: @table @asis -@item @code{ESC C-f} (@code{show-footnotes}) +@item @key{ESC C-f} (@code{show-footnotes}) @kindex ESC C-f @findex show-footnotes @cindex footnotes, displaying @@ -1186,17 +1738,17 @@ and thus change the behavior of Info to more closely match your environment and Info file reading manner. @table @asis -@item @code{M-x set-variable} +@item @kbd{M-x set-variable} @cindex variables, setting @findex set-variable Read the name of a variable, and the value for it, in the echo area and then set the variable to that value. Completion is available when -reading the variable name; often, completion is available when reading -the value to give to the variable, but that depends on the variable -itself. If a variable does @emph{not} supply multiple choices to -complete over, it expects a numeric value. +reading the variable name (@pxref{The Echo Area, completion}); often, +completion is available when reading the value to give to the variable, +but that depends on the variable itself. If a variable does @emph{not} +supply multiple choices to complete over, it expects a numeric value. -@item @code{M-x describe-variable} +@item @kbd{M-x describe-variable} @cindex variables, describing @findex describe-variable Read the name of a variable in the echo area and then display a brief diff --git a/contrib/texinfo/doc/info.1 b/contrib/texinfo/doc/info.1 new file mode 100644 index 0000000..f572a4f --- /dev/null +++ b/contrib/texinfo/doc/info.1 @@ -0,0 +1,80 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.013. +.TH INFO "1" "September 1999" "GNU texinfo 4.0" FSF +.SH NAME +info \- read Info documents +.SH SYNOPSIS +.B info +[\fIOPTION\fR]... [\fIMENU-ITEM\fR...] +.SH DESCRIPTION +.PP +Read documentation in Info format. +.SH OPTIONS +.TP +\fB\-\-apropos\fR=\fISUBJECT\fR +look up SUBJECT in all indices of all manuals. +.TP +\fB\-\-directory\fR=\fIDIR\fR +add DIR to INFOPATH. +.TP +\fB\-\-dribble\fR=\fIFILENAME\fR +remember user keystrokes in FILENAME. +.TP +\fB\-\-file\fR=\fIFILENAME\fR +specify Info file to visit. +.TP +\fB\-\-help\fR +display this help and exit. +.TP +\fB\-\-index\-search\fR=\fISTRING\fR +go to node pointed by index entry STRING. +.TP +\fB\-\-node\fR=\fINODENAME\fR +specify nodes in first visited Info file. +.TP +\fB\-\-output\fR=\fIFILENAME\fR +output selected nodes to FILENAME. +.TP +\fB\-\-restore\fR=\fIFILENAME\fR +read initial keystrokes from FILENAME. +.TP +\fB\-\-show\-options\fR, \fB\-\-usage\fR +go to command-line options node. +.TP +\fB\-\-subnodes\fR +recursively output menu items. +.TP +\fB\-\-vi\-keys\fR +use vi-like and less-like key bindings. +.TP +\fB\-\-version\fR +display version information and exit. +.PP +The first non-option argument, if present, is the menu entry to start from; +it is searched for in all `dir' files along INFOPATH. +If it is not present, info merges all `dir' files and shows the result. +Any remaining arguments are treated as the names of menu +items relative to the initial node visited. +.SH EXAMPLES +.TP +info +show top-level dir menu +.TP +info emacs +start at emacs node from top-level dir +.TP +info emacs buffers +start at buffers node within emacs manual +.TP +info \fB\-\-show\-options\fR emacs +start at node with emacs' command line options +.TP +info \fB\-f\fR ./foo.info +show file ./foo.info, not searching dir +.SH "REPORTING BUGS" +Email bug reports to bug-texinfo@gnu.org, +general questions and discussion to help-texinfo@gnu.org. +.SH COPYRIGHT +Copyright \(co 1999 Free Software Foundation, Inc. +There is NO warranty. You may redistribute this software +under the terms of the GNU General Public License. +For more information about these matters, see the files named COPYING. diff --git a/contrib/texinfo/doc/info.5 b/contrib/texinfo/doc/info.5 new file mode 100644 index 0000000..0e7ed48 --- /dev/null +++ b/contrib/texinfo/doc/info.5 @@ -0,0 +1,62 @@ +.\" info(5) +.\" $Id: info.5,v 1.2 1998/07/31 17:39:31 karl Exp $ +.\" +.\" Copyright (C) 1998 Free Software Foundation, Inc. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Permission is granted to copy and distribute translations of this +.\" manual into another language, under the above conditions for modified +.\" versions, except that this permission notice may be stated in a +.\" translation approved by the Foundation. +.\" +.TH INFO 5 "GNU Info" "FSF" +.SH NAME +info \- readable online documentation +.SH DESCRIPTION +The Info file format is an easily-parsable representation for online +documents. It can be read by +.I emacs(1) +and +.I info(1) +among other programs. +.PP +Info files are usually created from +.I texinfo(5) +sources by +.IR makeinfo(1) , +but can be created from scratch if so desired. +.PP +For a full description of the Texinfo language and associated tools, +please see the Texinfo manual (written in Texinfo itself). Most likely, +running this command from your shell: +.RS +.I info texinfo +.RE +or this key sequence from inside Emacs: +.RS +.I M-x info RET m texinfo RET +.RE +will get you there. +.SH AVAILABILITY +ftp://ftp.gnu.org/pub/gnu/texinfo-<version>.tar.gz +.br +or any GNU mirror site. +.SH "REPORTING BUGS" +Please send bug reports to bug-texinfo@gnu.org, +general questions and discussion to help-texinfo@gnu.org. +.SH "SEE ALSO" +info(1), install-info(1), makeinfo(1), texi2dvi(1), +.br +texindex(1). +.br +emacs(1), tex(1). +.br +texinfo(5). diff --git a/contrib/texinfo/doc/info.texi b/contrib/texinfo/doc/info.texi index f7cb1cd..c81bfd2 100644 --- a/contrib/texinfo/doc/info.texi +++ b/contrib/texinfo/doc/info.texi @@ -1,9 +1,9 @@ \input texinfo @c -*-texinfo-*- -@comment %**start of header +@comment %**start of header @setfilename info.info -@settitle Info 1.0 -@comment %**end of header -@comment $Id: info.texi,v 1.4 1997/07/10 21:58:11 karl Exp $ +@settitle Info +@comment %**end of header +@comment $Id: info.texi,v 1.11 1999/04/19 21:37:23 karl Exp $ @dircategory Texinfo documentation system @direntry @@ -11,10 +11,10 @@ @end direntry @ifinfo -This file describes how to use Info, -the on-line, menu-driven GNU documentation system. +This file describes how to use Info, the on-line, menu-driven GNU +documentation system. -Copyright (C) 1989, 92, 96, 97 Free Software Foundation, Inc. +Copyright (C) 1989, 92, 96, 97, 98, 99 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -44,10 +44,9 @@ by the Free Software Foundation. @author Brian Fox @page @vskip 0pt plus 1filll -Copyright @copyright{} 1989, 1992, 1993, 1996, 1997 Free Software +Copyright @copyright{} 1989, 92, 93, 96, 97, 98, 99 Free Software Foundation, Inc. @sp 2 - Published by the Free Software Foundation @* 59 Temple Place - Suite 330 @* Boston, MA 02111-1307, USA. @@ -67,31 +66,20 @@ except that this permission notice may be stated in a translation approved by the Free Software Foundation. @end titlepage -@ifinfo -@node Top, Getting Started, , (dir) +@ifnottex +@node Top @top Info: An Introduction Info is a program for reading documentation, which you are using now. To learn how to use Info, type the command @kbd{h}. It brings you to a programmed instruction sequence. - -@c Need to make sure that `Info-help' goes to the right node, -@c which is the first node of the first chapter. (It should.) -@c (Info-find-node "info" -@c (if (< (window-height) 23) -@c "Help-Small-Screen" -@c "Help"))) - -To learn advanced Info commands, type @kbd{n} twice. This brings you to -@cite{Info for Experts}, skipping over the `Getting Started' chapter. -@end ifinfo +@end ifnottex @menu * Getting Started:: Getting started using an Info reader. * Advanced Info:: Advanced commands within Info. -* Create an Info File:: How to make your own Info file. -* The Standalone Info Program: (info-stnd.info). +* Creating an Info File:: How to make your own Info file. @end menu @node Getting Started, Advanced Info, Top, Top @@ -101,7 +89,7 @@ To learn advanced Info commands, type @kbd{n} twice. This brings you to This first part of the Info manual describes how to get around inside of Info. The second part of the manual describes various advanced Info commands, and how to write an Info as distinct from a Texinfo -file. The third part is about how to generate Info files from +file. The third part is about how to generate Info files from Texinfo files. @iftex @@ -110,7 +98,7 @@ try Info commands while reading about them. Reading it on paper is less effective, since you must take it on faith that the commands described really do what the manual says. By all means go through this manual now that you have it; but please try going through the on-line version as -well. +well. There are two ways of looking at the online version of this manual: @@ -340,7 +328,7 @@ Info can interpret it. The beginning of a menu is always identified by a line which starts with @samp{* Menu:}. A node contains a menu if and only if it has a line in it which starts that way. The only menu you can use at any moment is the one in the node you are in. To use a -menu in any other node, you must move to that node first. +menu in any other node, you must move to that node first. After the start of the menu, each line that starts with a @samp{*} identifies one subtopic. The line usually contains a brief name @@ -427,16 +415,14 @@ what you have entered. not need to type the argument: you just type a Return, and it stands for the subtopic of the line you are on. -Here is a menu to give you a chance to practice. - -* Menu: The menu starts here. - -This menu gives you three ways of going to one place, Help-FOO. - -* Foo: Help-FOO. A node you can visit for fun.@* -* Bar: Help-FOO. Strange! two ways to get to the same place.@* -* Help-FOO:: And yet another!@* +Here is a menu to give you a chance to practice. This menu gives you +three ways of going to one place, Help-FOO: +@menu +* Foo: Help-FOO. A node you can visit for fun. +* Bar: Help-FOO. Strange! two ways to get to the same place. +* Help-FOO:: And yet another! +@end menu >> Now type just an @kbd{m} and see what happens: @@ -559,17 +545,16 @@ to cancel the @samp{f}. @c It is an accident of the menu updating command. @node Help-Cross, , , Help-Adv -@comment node-name, next, previous, up -@unnumberedsubsec The node reached by the cross reference in Info +@subsection The node reached by the cross reference in Info This is the node reached by the cross reference named @samp{Cross}. While this node is specifically intended to be reached by a cross -reference, most cross references lead to nodes that ``belong'' -someplace else far away in the structure of Info. So you cannot expect -the footnote to have a @samp{Next}, @samp{Previous} or @samp{Up} pointing back to -where you came from. In general, the @kbd{l} (el) command is the only -way to get back there. +reference, most cross references lead to nodes that ``belong'' someplace +else far away in the structure of Info. So you cannot expect the +footnote to have a @samp{Next}, @samp{Previous} or @samp{Up} pointing +back to where you came from. In general, the @kbd{l} (el) command is +the only way to get back there. >> Type @kbd{l} to return to the node where the cross reference was. @@ -590,15 +575,15 @@ manner. @samp{mInfo} and Return, to get to the node about Info and see what other help is available. -@node Advanced Info, Create an Info File, Getting Started, Top -@comment node-name, next, previous, up + +@node Advanced Info @chapter Info for Experts This chapter describes various advanced Info commands, and how to write an Info as distinct from a Texinfo file. (However, in most cases, writing a Texinfo file is better, since you can use it @emph{both} to generate an Info file and to make a printed manual. @xref{Top,, Overview of -Texinfo, texinfo, Texinfo: The GNU Documentation Format}.) +Texinfo, texinfo, Texinfo}.) @menu * Expert:: Advanced Info commands: g, s, e, and 1 - 5. @@ -639,12 +624,12 @@ type @kbd{s} followed by the string to search for, terminated by @key{RET}. To search for the same string again, just @kbd{s} followed by @key{RET} will do. The file's nodes are scanned in the order they are in in the file, which has no necessary relationship to the -order that they may be in in the tree structure of menus and @samp{next} pointers. -But normally the two orders are not very different. In any case, -you can always do a @kbd{b} to find out what node you have reached, if -the header is not visible (this can happen, because @kbd{s} puts your -cursor at the occurrence of the string, not at the beginning of the -node). +order that they may be in in the tree structure of menus and @samp{next} +pointers. But normally the two orders are not very different. In any +case, you can always do a @kbd{b} to find out what node you have +reached, if the header is not visible (this can happen, because @kbd{s} +puts your cursor at the occurrence of the string, not at the beginning +of the node). If you grudge the system each character of type-in it requires, you might like to use the commands @kbd{1}, @kbd{2}, @kbd{3}, @kbd{4}, ... @@ -652,9 +637,9 @@ might like to use the commands @kbd{1}, @kbd{2}, @kbd{3}, @kbd{4}, ... argument. @kbd{1} goes through the first item in the current node's menu; @kbd{2} goes through the second item, etc. -If you display supports multiple fonts, and you are using Emacs' Info +If your display supports multiple fonts, and you are using Emacs' Info mode to read Info files, the @samp{*} for the fifth menu item is -underlines, and so is the @samp{*} for the ninth item; these underlines +underlined, and so is the @samp{*} for the ninth item; these underlines make it easy to see at a glance which number to use for an item. On ordinary terminals, you won't have underlining. If you need to @@ -678,12 +663,12 @@ Create some nodes, in some file, to document that topic. Put that topic in the menu in the directory. @xref{Menus, Menu}. @end enumerate -Usually, the way to create the nodes is with Texinfo @pxref{Top,, Overview of -Texinfo, texinfo, Texinfo: The GNU Documentation Format}); this has the -advantage that you can also make a printed manual from them. However, -if hyou want to edit an Info file, here is how. +Usually, the way to create the nodes is with Texinfo (@pxref{Top,, +Overview of Texinfo, texinfo, Texinfo}); this has the advantage that you +can also make a printed manual from them. However, if you want to edit +an Info file, here is how. - The new node can live in an existing documentation file, or in a new +The new node can live in an existing documentation file, or in a new one. It must have a @key{^_} character before it (invisible to the user; this node has one but you cannot see it), and it ends with either a @key{^_}, a @key{^L}, or the end of file. Note: If you put in a @@ -693,12 +678,12 @@ Also, a nicer way to make a node boundary be a page boundary as well is to put a @key{^L} @emph{right after} the @key{^_}. The @key{^_} starting a node must be followed by a newline or a -@key{^L} newline, after which comes the node's header line. The -header line must give the node's name (by which Info finds it), -and state the names of the @samp{Next}, @samp{Previous}, and @samp{Up} nodes (if -there are any). As you can see, this node's @samp{Up} node is the node -@samp{Top}, which points at all the documentation for Info. The @samp{Next} -node is @samp{Menus}. +@key{^L} newline, after which comes the node's header line. The header +line must give the node's name (by which Info finds it), and state the +names of the @samp{Next}, @samp{Previous}, and @samp{Up} nodes (if there +are any). As you can see, this node's @samp{Up} node is the node +@samp{Top}, which points at all the documentation for Info. The +@samp{Next} node is @samp{Menus}. The keywords @dfn{Node}, @dfn{Previous}, @dfn{Up}, and @dfn{Next}, may appear in any order, anywhere in the header line, but the @@ -728,10 +713,10 @@ node @kbd{*} is to make it possible to make old-fashioned, unstructured files into nodes of the tree. The @samp{Node:} name, in which a node states its own name, must not -contain a filename, since Info when searching for a node does not -expect one to be there. The @samp{Next}, @samp{Previous} and @samp{Up} names may -contain them. In this node, since the @samp{Up} node is in the same file, -it was not necessary to use one. +contain a filename, since Info when searching for a node does not expect +one to be there. The @samp{Next}, @samp{Previous} and @samp{Up} names +may contain them. In this node, since the @samp{Up} node is in the same +file, it was not necessary to use one. Note that the nodes in this file have a file name in the header line. The file names are ignored by Info, but they serve as comments @@ -741,7 +726,7 @@ to help identify the node for the user. @comment node-name, next, previous, up @section How to Create Menus - Any node in the Info hierarchy may have a @dfn{menu}---a list of subnodes. + Any node in the Info hierarchy may have a @dfn{menu}---a list of subnodes. The @kbd{m} command searches the current node's menu for the topic which it reads from the terminal. @@ -766,11 +751,11 @@ short abbreviations. In a long menu, it is a good idea to capitalize the beginning of each item name which is the minimum acceptable abbreviation for it (a long menu is more than 5 or so entries). - The nodes listed in a node's menu are called its ``subnodes'', and -it is their ``superior''. They should each have an @samp{Up:} pointing at -the superior. It is often useful to arrange all or most of the -subnodes in a sequence of @samp{Next} and @samp{Previous} pointers so that someone who -wants to see them all need not keep revisiting the Menu. + The nodes listed in a node's menu are called its ``subnodes'', and it +is their ``superior''. They should each have an @samp{Up:} pointing at +the superior. It is often useful to arrange all or most of the subnodes +in a sequence of @samp{Next} and @samp{Previous} pointers so that +someone who wants to see them all need not keep revisiting the Menu. The Info Directory is simply the menu of the node @samp{(dir)Top}---that is, node @samp{Top} in file @file{.../info/dir}. You can put new entries @@ -816,7 +801,7 @@ They are just examples. The places they ``lead to'' do not really exist! You can speed up the access to nodes of a large Info file by giving it a tag table. Unlike the tag table for a program, the tag table for -an Info file lives inside the file itself and is used +an Info file lives inside the file itself and is used automatically whenever Info reads in the file. To make a tag table, go to a node in the file using Emacs Info mode and type @@ -847,24 +832,24 @@ the beginning of the node's header (ending just after the node name), a Delete character, and the character position in the file of the beginning of the node. + @node Checking, Emacs Info Variables, Tags, Advanced Info -@comment node-name, next, previous, up @section Checking an Info File - When creating an Info file, it is easy to forget the name of a node -when you are making a pointer to it from another node. If you put in -the wrong name for a node, this is not detected until someone -tries to go through the pointer using Info. Verification of the Info -file is an automatic process which checks all pointers to nodes and -reports any pointers which are invalid. Every @samp{Next}, @samp{Previous}, and +When creating an Info file, it is easy to forget the name of a node when +you are making a pointer to it from another node. If you put in the +wrong name for a node, this is not detected until someone tries to go +through the pointer using Info. Verification of the Info file is an +automatic process which checks all pointers to nodes and reports any +pointers which are invalid. Every @samp{Next}, @samp{Previous}, and @samp{Up} is checked, as is every menu item and every cross reference. In -addition, any @samp{Next} which does not have a @samp{Previous} pointing back is -reported. Only pointers within the file are checked, because checking -pointers to other files would be terribly slow. But those are usually -few. +addition, any @samp{Next} which does not have a @samp{Previous} pointing +back is reported. Only pointers within the file are checked, because +checking pointers to other files would be terribly slow. But those are +usually few. - To check an Info file, do @kbd{M-x Info-validate} while looking at -any node of the file with Emacs Info mode. +To check an Info file, do @kbd{M-x Info-validate} while looking at any +node of the file with Emacs Info mode. @node Emacs Info Variables, , Checking, Advanced Info @section Emacs Info-mode Variables @@ -894,18 +879,17 @@ The standard directory for Info documentation files. Only used when the function @code{Info-directory} is called. @end vtable -@node Create an Info File, , Advanced Info, Top -@comment node-name, next, previous, up -@chapter Creating an Info File from a Makeinfo file -@code{makeinfo} is a utility that converts a Texinfo file into an Info -file; @code{texinfo-format-region} and @code{texinfo-format-buffer} are -GNU Emacs functions that do the same. +@node Creating an Info File +@chapter Creating an Info File + +@xref{Top,, Overview of Texinfo, texinfo, Texinfo}, to learn how to +write a Texinfo file. -@xref{Create an Info File, , Creating an Info File, texinfo, the Texinfo -Manual}, to learn how to create an Info file from a Texinfo file. +@xref{Creating an Info File,,, texinfo, Texinfo}, to learn how to create +an Info file from a Texinfo file. -@xref{Top,, Overview of Texinfo, texinfo, Texinfo: The GNU Documentation -Format}, to learn how to write a Texinfo file. +@xref{Installing an Info File,,, texinfo, Texinfo}, to learn how to +install an Info file after you have created one. @bye diff --git a/contrib/texinfo/doc/install-info.1 b/contrib/texinfo/doc/install-info.1 new file mode 100644 index 0000000..f2b8c2a --- /dev/null +++ b/contrib/texinfo/doc/install-info.1 @@ -0,0 +1,84 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.013. +.TH INSTALL-INFO "1" "September 1999" "GNU texinfo 4.0" FSF +.SH NAME +install-info \- update info/dir entries +.SH SYNOPSIS +.B install-info +[\fIOPTION\fR]... [\fIINFO-FILE \fR[\fIDIR-FILE\fR]] +.SH DESCRIPTION +.PP +Install or delete dir entries from INFO-FILE in the Info directory file +DIR-FILE. +.SH OPTIONS +.TP +\fB\-\-delete\fR +delete existing entries for INFO-FILE from DIR-FILE; +.IP +don't insert any new entries. +.TP +\fB\-\-dir\-file\fR=\fINAME\fR +specify file name of Info directory file. +.IP +This is equivalent to using the DIR-FILE argument. +.TP +\fB\-\-entry\fR=\fITEXT\fR +insert TEXT as an Info directory entry. +.IP +TEXT should have the form of an Info menu item line +plus zero or more extra lines starting with whitespace. +If you specify more than one entry, they are all added. +If you don't specify any entries, they are determined +from information in the Info file itself. +.TP +\fB\-\-help\fR +display this help and exit. +.TP +\fB\-\-info\-file\fR=\fIFILE\fR +specify Info file to install in the directory. +.IP +This is equivalent to using the INFO-FILE argument. +.TP +\fB\-\-info\-dir\fR=\fIDIR\fR +same as \fB\-\-dir\-file\fR=\fIDIR\fR/dir. +.TP +\fB\-\-item\fR=\fITEXT\fR +same as \fB\-\-entry\fR TEXT. +.IP +An Info directory entry is actually a menu item. +.TP +\fB\-\-quiet\fR +suppress warnings. +.TP +\fB\-\-remove\fR +same as \fB\-\-delete\fR. +.TP +\fB\-\-section\fR=\fISEC\fR +put this file's entries in section SEC of the directory. +.IP +If you specify more than one section, all the entries +are added in each of the sections. +If you don't specify any sections, they are determined +from information in the Info file itself. +.TP +\fB\-\-version\fR +display version information and exit. +.SH "REPORTING BUGS" +Email bug reports to bug-texinfo@gnu.org, +general questions and discussion to help-texinfo@gnu.org. +.SH "SEE ALSO" +The full documentation for +.B install-info +is maintained as a Texinfo manual. If the +.B info +and +.B install-info +programs are properly installed at your site, the command +.IP +.B info install-info +.PP +should give you access to the complete manual. +.SH COPYRIGHT +Copyright \(co 1999 Free Software Foundation, Inc. +There is NO warranty. You may redistribute this software +under the terms of the GNU General Public License. +For more information about these matters, see the files named COPYING. diff --git a/contrib/texinfo/doc/makeinfo.1 b/contrib/texinfo/doc/makeinfo.1 new file mode 100644 index 0000000..62d22b8 --- /dev/null +++ b/contrib/texinfo/doc/makeinfo.1 @@ -0,0 +1,152 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.013. +.TH MAKEINFO "1" "September 1999" "GNU texinfo 4.0" FSF +.SH NAME +makeinfo \- translate Texinfo documents +.SH SYNOPSIS +.B makeinfo +[\fIOPTION\fR]...\fI TEXINFO-FILE\fR... +.SH DESCRIPTION +.PP +Translate Texinfo source documentation to various other formats: +Info files suitable for reading online with Emacs or standalone GNU Info +(by default); plain text (with \fB\-\-no\-headers\fR); or HTML (with \fB\-\-html\fR). +.SH OPTIONS +.TP +\fB\-\-commands\-in\-node\-names\fR +allow @ commands in node names. +.TP +\fB\-D\fR VAR +define a variable, as with @set. +.TP +\fB\-E\fR, \fB\-\-macro\-expand\fR FILE +output macro-expanded source to FILE. +.TP +\fB\-\-error\-limit\fR=\fINUM\fR +quit after NUM errors (default 100). +.TP +\fB\-\-fill\-column\fR=\fINUM\fR +break Info lines at NUM characters (default 72). +.TP +\fB\-\-footnote\-style\fR=\fISTYLE\fR +output footnotes according to STYLE: +.IP +`separate' to place footnotes in their own node, +`end' to place the footnotes at the end of the +.IP +node in which they are defined (the default). +.TP +\fB\-\-force\fR +preserve output even if errors. +.TP +\fB\-\-help\fR +display this help and exit. +.TP +\fB\-\-html\fR +output HTML rather than Info format; +.TP +\fB\-I\fR DIR +append DIR to the @include search path. +.TP +\fB\-\-ifhtml\fR +process @ifhtml and @html text even when not +.IP +generating HTML. +.TP +\fB\-\-ifinfo\fR +process @ifinfo text even when generating HTML. +.TP +\fB\-\-iftex\fR +process @iftex and @tex text. +.IP +implies \fB\-\-no\-split\fR. +.TP +\fB\-\-no\-headers\fR +suppress Info node separators and Node: lines and +.IP +write to standard output without \fB\-\-output\fR. +.TP +\fB\-\-no\-ifhtml\fR +do not process @ifhtml and @html text. +.TP +\fB\-\-no\-ifinfo\fR +do not process @ifinfo text. +.TP +\fB\-\-no\-iftex\fR +do not process @iftex and @tex text. +.TP +\fB\-\-no\-split\fR +suppress splitting of large Info output files or +generation of one HTML file per node. +.TP +\fB\-\-no\-validate\fR +suppress node cross-reference validation. +.TP +\fB\-\-no\-warn\fR +suppress warnings (but not errors). +.TP +\fB\-\-number\-sections\fR +include chapter, section, etc. numbers in output. +.TP +\fB\-o\fR, \fB\-\-output\fR=\fIFILE\fR +output to FILE, ignoring any @setfilename. +.TP +\fB\-P\fR DIR +prepend DIR to the @include search path. +.TP +\fB\-\-paragraph\-indent\fR=\fIVAL\fR +indent Info paragraphs by VAL spaces (default 3). +.IP +if VAL is `none', do not indent; +if VAL is `asis', preserve existing indentation. +.TP +\fB\-\-reference\-limit\fR=\fINUM\fR +warn about at most NUM references (default 1000). +.TP +\fB\-U\fR VAR +undefine a variable, as with @clear. +.TP +\fB\-v\fR, \fB\-\-verbose\fR +explain what is being done. +.TP +\fB\-\-version\fR +display version information and exit. +.PP +The defaults for the @if... conditionals depend on the output format: +if generating HTML, \fB\-\-ifhtml\fR is on and the others are off; +if generating Info or plain text, \fB\-\-ifinfo\fR is on and the others are off. +.SH EXAMPLES +.TP +makeinfo foo.texi +write Info to foo's @setfilename +.TP +makeinfo \fB\-\-html\fR foo.texi +write HTML to foo's @setfilename +.TP +makeinfo \fB\-\-no\-headers\fR \fB\-o\fR - foo.texi +write plain text to standard output +.TP +makeinfo \fB\-\-number\-sections\fR foo.texi +write Info with numbered sections +.TP +makeinfo \fB\-\-no\-split\fR foo.texi +write one Info file however big +.SH "REPORTING BUGS" +Email bug reports to bug-texinfo@gnu.org, +general questions and discussion to help-texinfo@gnu.org. +.SH "SEE ALSO" +The full documentation for +.B makeinfo +is maintained as a Texinfo manual. If the +.B info +and +.B makeinfo +programs are properly installed at your site, the command +.IP +.B info makeinfo +.PP +should give you access to the complete manual. +.SH COPYRIGHT +Copyright \(co 1999 Free Software Foundation, Inc. +There is NO warranty. You may redistribute this software +under the terms of the GNU General Public License. +For more information about these matters, see the files named COPYING. diff --git a/contrib/texinfo/doc/texindex.1 b/contrib/texinfo/doc/texindex.1 new file mode 100644 index 0000000..6708829 --- /dev/null +++ b/contrib/texinfo/doc/texindex.1 @@ -0,0 +1,47 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.013. +.TH TEXINDEX "1" "September 1999" "GNU texinfo 4.0" FSF +.SH NAME +texindex \- sort Texinfo index files +.SH SYNOPSIS +.B texindex +[\fIOPTION\fR]...\fI FILE\fR... +.SH DESCRIPTION +.PP +Generate a sorted index for each TeX output FILE. +Usually FILE... is specified as `foo.??' for a document `foo.texi'. +.SH OPTIONS +.TP +\fB\-h\fR, \fB\-\-help\fR +display this help and exit +.TP +\fB\-k\fR, \fB\-\-keep\fR +keep temporary files around after processing +.TP +\fB\-\-no\-keep\fR +do not keep temporary files around after processing (default) +.TP +\fB\-o\fR, \fB\-\-output\fR FILE +send output to FILE +.TP +\fB\-\-version\fR +display version information and exit +.SH "REPORTING BUGS" +Email bug reports to bug-texinfo@gnu.org, +general questions and discussion to help-texinfo@gnu.org. +.SH "SEE ALSO" +The full documentation for +.B texindex +is maintained as a Texinfo manual. If the +.B info +and +.B texindex +programs are properly installed at your site, the command +.IP +.B info texindex +.PP +should give you access to the complete manual. +.SH COPYRIGHT +Copyright \(co 1999 Free Software Foundation, Inc. +There is NO warranty. You may redistribute this software +under the terms of the GNU General Public License. +For more information about these matters, see the files named COPYING. diff --git a/contrib/texinfo/doc/texinfo.5 b/contrib/texinfo/doc/texinfo.5 new file mode 100644 index 0000000..cd29c1b --- /dev/null +++ b/contrib/texinfo/doc/texinfo.5 @@ -0,0 +1,51 @@ +.\" texinfo(5) +.\" $Id: texinfo.5,v 1.3 1999/03/25 21:28:25 karl Exp $ +.\" +.\" Copyright (C) 1998, 99 Free Software Foundation, Inc. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Permission is granted to copy and distribute translations of this +.\" manual into another language, under the above conditions for modified +.\" versions, except that this permission notice may be stated in a +.\" translation approved by the Foundation. +.\" +.TH TEXINFO 5 "GNU Texinfo" "FSF" +.SH NAME +Texinfo \- software documentation system +.SH DESCRIPTION +Texinfo is a documentation system that uses a single source file to +produce both online information and printed output. It is primarily +designed for writing software manuals. +.PP +For a full description of the Texinfo language and associated tools, +please see the Texinfo manual (written in Texinfo itself). Most likely, +running this command from your shell: +.RS +.I info texinfo +.RE +or this key sequence from inside Emacs: +.RS +.I M-x info RET m texinfo RET +.RE +will get you there. +.SH AVAILABILITY +ftp://ftp.gnu.org/gnu/texinfo/ +.br +or any GNU mirror site. +.SH "REPORTING BUGS" +Please send bug reports to bug-texinfo@gnu.org, +general questions and discussion to help-texinfo@gnu.org. +.SH "SEE ALSO" +info(1), install-info(1), makeinfo(1), texi2dvi(1), texindex(1). +.br +emacs(1), tex(1). +.br +info(5). diff --git a/contrib/texinfo/doc/texinfo.txi b/contrib/texinfo/doc/texinfo.txi index c0b7a20..7e0bbd0 100644 --- a/contrib/texinfo/doc/texinfo.txi +++ b/contrib/texinfo/doc/texinfo.txi @@ -1,15 +1,12 @@ \input texinfo.tex @c -*-texinfo-*- -@c $Id: texinfo.txi,v 1.50 1998/02/27 21:21:34 karl Exp $ +@c $Id: texinfo.txi,v 1.162 1999/09/28 19:38:01 karl Exp $ @c %**start of header @c All text is ignored before the setfilename. @setfilename texinfo -@settitle Texinfo @value{edition} -@c Edition number is now the same as the Texinfo distribution version number. -@set edition 3.12 -@set update-month February 1998 -@set update-date 27 @value{update-month} +@include version.texi +@settitle Texinfo @value{VERSION} @c Define a new index for options. @defcodeindex op @@ -22,20 +19,21 @@ @footnotestyle separate @paragraphindent 2 @finalout -@comment %**end of header -@c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a -@c prefix arg). This updates the node pointers, which texinfmt.el needs. +@comment %**end of header @dircategory Texinfo documentation system @direntry * Texinfo: (texinfo). The GNU documentation format. -* install-info: (texinfo)Invoking install-info. Updating info/dir entries. -* texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation. -* texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files. +* install-info: (texinfo)Invoking install-info. Update info/dir entries. +* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents. +* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files. * makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source. @end direntry +@c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a +@c prefix arg). This updates the node pointers, which texinfmt.el needs. + @c Set smallbook if printing in smallbook format so the example of the @c smallbook font is actually written using smallbook; in bigbook, a kludge @c is used for TeX output. Do this through the -t option to texi2dvi, @@ -44,17 +42,20 @@ @c set smallbook @c @@clear smallbook +@c If you like blank pages. Can add through texi2dvi -t. +@c setchapternewpage odd + @c Currently undocumented command, 5 December 1993: @c nwnode (Same as node, but no warnings; for `makeinfo'.) @ifinfo This file documents Texinfo, a documentation system that can produce -both on-line information and a printed manual from a single source file. +both online information and a printed manual from a single source file. -Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 +Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99 Free Software Foundation, Inc. -This edition is for Texinfo version @value{edition}. +This edition is for Texinfo version @value{VERSION}, @value{UPDATED}. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -78,7 +79,6 @@ except that this permission notice may be stated in a translation approved by the Free Software Foundation. @end ifinfo -@setchapternewpage odd @shorttitlepage Texinfo @@ -86,25 +86,27 @@ by the Free Software Foundation. @c use the new format for titles @title Texinfo @subtitle The GNU Documentation Format -@subtitle for Texinfo version @value{edition} -@subtitle @value{update-month} +@subtitle for Texinfo version @value{VERSION}, @value{UPDATED} -@author Robert J.@: Chassell -@author Richard M.@: Stallman +@author Robert J. Chassell +@author Richard M. Stallman @c Include the Distribution inside the titlepage so @c that headings are turned off. @page @vskip 0pt plus 1filll -Copyright @copyright{} 1988, 90, 91, 92, 93, 95, 96, 97, 98 +Copyright @copyright{} 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99 Free Software Foundation, Inc. +This manual is for Texinfo version @value{VERSION}, @value{UPDATED}. + Published by the Free Software Foundation @* 59 Temple Place Suite 330 @* Boston, MA 02111-1307 @* USA @* -ISBN 1-882114-65-5 +ISBN 1-882114-67-1 @c for version 4.0, September 1999. +@c ISBN 1-882114-65-5 @c for version 3.12, March 1998. @c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995 @c ISBN 1-882114-64-7 is for edition 2.24 of November 1996. @@ -125,65 +127,22 @@ by the Free Software Foundation. Cover art by Etienne Suvasa. @end titlepage -@ifinfo -@node Top, Copying, (dir), (dir) +@summarycontents +@contents + +@ifnottex +@node Top @top Texinfo Texinfo is a documentation system that uses a single source file to -produce both on-line information and printed output.@refill +produce both online information and printed output. The first part of this master menu lists the major nodes in this Info document, including the @@-command and concept indices. The rest of -the menu lists all the lower level nodes in the document.@refill - -This is Edition @value{edition} of the Texinfo documentation, -@w{@value{update-date}}. -@end ifinfo +the menu lists all the lower level nodes in the document. -@c Here is a spare copy of the chapter menu entry descriptions, -@c in case they are accidently deleted -@ignore -Your rights. -Texinfo in brief. -How to use Texinfo mode. -What is at the beginning of a Texinfo file? -What is at the end of a Texinfo file? -How to create chapters, sections, subsections, - appendices, and other parts. -How to provide structure for a document. -How to write nodes. -How to write menus. -How to write cross references. -How to mark words and phrases as code, - keyboard input, meta-syntactic - variables, and the like. -How to write quotations, examples, etc. -How to write lists and tables. -How to create indices. -How to insert @@-signs, braces, etc. -How to indicate results of evaluation, - expansion of macros, errors, etc. -How to force and prevent line and page breaks. -How to describe functions and the like in a uniform manner. -How to write footnotes. -How to specify text for either @TeX{} or Info. -How to print hardcopy. -How to create an Info file. -How to install an Info file -A list of all the Texinfo @@-commands. -Hints on how to write a Texinfo document. -A sample Texinfo file to look at. -Tell readers they have the right to copy - and distribute. -How to incorporate other Texinfo files. -How to write page headings and footings. -How to find formatting mistakes. -All about paragraph refilling. -A description of @@-Command syntax. -Texinfo second edition features. -A menu containing commands and variables. -A menu covering many topics. -@end ignore +This is Edition @value{VERSION} of the Texinfo manual, updated @value{UPDATED}. +@end ifnottex @menu * Copying:: Your rights. @@ -206,13 +165,12 @@ A menu covering many topics. * Breaks:: How to force and prevent line and page breaks. * Definition Commands:: How to describe functions and the like in a uniform manner. -* Footnotes:: How to write footnotes. * Conditionals:: How to specify text for either @TeX{} or Info. -* Macros:: Defining new Texinfo commands. -* Format/Print Hardcopy:: How to convert a Texinfo file to a file +* Internationalization:: +* Defining New Texinfo Commands:: +* Hardcopy:: How to convert a Texinfo file to a file for printing and how to print that file. -* Create an Info File:: Convert a Texinfo file into an Info file. -* Install an Info File:: Make an Info file accessible to users. +* Creating and Installing Info Files:: * Command List:: All the Texinfo @@-commands. * Tips:: Hints on how to write a Texinfo document. * Sample Texinfo File:: A sample Texinfo file to look at. @@ -233,18 +191,17 @@ A menu covering many topics. Overview of Texinfo -* Using Texinfo:: Create a conventional printed book - or an Info file. +* Reporting Bugs:: Submitting effective bug reports. +* Using Texinfo:: Create printed or online output. * Info Files:: What is an Info file? * Printed Books:: Characteristics of a printed book or manual. * Formatting Commands:: @@-commands are used for formatting. * Conventions:: General rules for writing a Texinfo file. -* Comments:: How to write comments and mark regions that - the formatting commands will ignore. +* Comments:: Writing comments and ignored text in general. * Minimum:: What a Texinfo file must have. * Six Parts:: Usually, a Texinfo file has six parts. * Short Sample:: A short sample Texinfo file. -* Acknowledgements:: +* Acknowledgements and History:: Contributors and genesis. Using Texinfo Mode @@ -285,7 +242,8 @@ The Texinfo File Header * setfilename:: Tell Info the name of the Info file. * settitle:: Create a title for the printed work. * setchapternewpage:: Start chapters on right-hand pages. -* paragraphindent:: An option to specify paragraph indentation. +* paragraphindent:: Specify paragraph indentation. +* exampleindent:: Specify environment indentation. * End of Header:: Formatting a region requires this. The Title and Copyright Pages @@ -334,8 +292,9 @@ Nodes * Two Paths:: Different commands to structure Info output and printed output. * Node Menu Illustration:: A diagram, and sample nodes and menus. -* node:: How to write a node, in detail. -* makeinfo Pointer Creation:: How to create node pointers with @code{makeinfo}. +* node:: Creating nodes, in detail. +* makeinfo Pointer Creation:: Letting makeinfo determine node pointers. +* anchor:: Defining arbitrary cross-reference targets. The @code{@@node} Command @@ -384,23 +343,26 @@ Marking Words and Phrases Indicating Definitions, Commands, etc. * Useful Highlighting:: Highlighting provides useful information. -* code:: How to indicate code. -* kbd:: How to show keyboard input. -* key:: How to specify keys. -* samp:: How to show a literal sequence of characters. -* var:: How to indicate a metasyntactic variable. -* file:: How to indicate the name of a file. -* dfn:: How to specify a definition. -* cite:: How to refer to a book that is not in Info. -* url:: How to indicate a world wide web reference. -* email:: How to indicate an electronic mail address. +* code:: Indicating program code. +* kbd:: Showing keyboard input. +* key:: Specifying keys. +* samp:: Showing a literal sequence of characters. +* var:: Indicating metasyntactic variables. +* env:: Indicating environment variables. +* file:: Indicating file names. +* command:: Indicating command names. +* option:: Indicating option names. +* dfn:: Specifying definitions. +* cite:: Referring to books not in the Info system. +* acronym:: Indicating acronyms. +* url:: Indicating a World Wide Web reference. +* email:: Indicating an electronic mail address. Emphasizing Text * emph & strong:: How to emphasize text in Texinfo. * Smallcaps:: How to use the small caps font. * Fonts:: Various font commands for printed output. -* Customized Highlighting:: How to define highlighting commands. Quotations and Examples @@ -409,8 +371,8 @@ Quotations and Examples * quotation:: How to write a quotation. * example:: How to write an example in a fixed-width font. * noindent:: How to prevent paragraph indentation. -* Lisp Example:: How to illustrate Lisp code. -* smallexample & smalllisp:: Forms for the @code{@@smallbook} option. +* lisp:: How to illustrate Lisp code. +* small:: Forms for @code{@@smallbook}. * display:: How to write an example in the current font. * format:: How to write an example that does not narrow the margins. @@ -437,7 +399,7 @@ Multi-column Tables * Multitable Column Widths:: Defining multitable column widths. * Multitable Rows:: Defining multitable rows, with examples. -Creating Indices +Indices * Index Entries:: Choose different words for index entries. * Predefined Indices:: Use different indices for different kinds @@ -467,6 +429,7 @@ Special Insertions * math:: How to format a mathematical expression. * Glyphs:: How to indicate results of evaluation, expansion of macros, errors, etc. +* Footnotes:: How to include footnotes. * Images:: How to include graphics. Inserting @@ and Braces @@ -503,12 +466,17 @@ Glyphs for Examples Glyphs Summary -* result:: -* expansion:: -* Print Glyph:: -* Error Glyph:: -* Equivalence:: -* Point Glyph:: +* result:: +* expansion:: +* Print Glyph:: +* Error Glyph:: +* Equivalence:: +* Point Glyph:: + +Footnotes + +* Footnote Commands:: How to write a footnote in Texinfo. +* Footnote Styles:: Controlling how footnotes appear in Info. Making and Preventing Breaks @@ -540,11 +508,6 @@ The Definition Commands * Abstract Objects:: Commands for object-oriented programming. * Data Types:: The definition command for data types. -Footnotes - -* Footnote Commands:: How to write a footnote in Texinfo. -* Footnote Styles:: Controlling how footnotes appear in Info. - Conditionally Visible Text * Conditional Commands:: Specifying text for HTML, Info, or @TeX{}. @@ -557,30 +520,45 @@ Conditionally Visible Text @code{@@set}, @code{@@clear}, and @code{@@value} * ifset ifclear:: Format a region if a flag is set. -* value:: Replace a flag with a string. +* set value:: Expand a flag variable to a string. * value Example:: An easy way to update edition information. -Macros: Defining New Texinfo Commands +Internationalization + +* documentlanguage:: Declaring the current language. +* documentencoding:: Declaring the input encoding. -* Defining Macros:: Both defining and undefining new commands. +Defining New Texinfo Commands + +* Defining Macros:: Defining and undefining new commands. * Invoking Macros:: Using a macro, once you've defined it. +* Macro Details:: Beyond basic macro usage. +* alias:: Command aliases. +* definfoenclose:: Customized highlighting. -Format and Print Hardcopy +Formatting and Printing Hardcopy * Use TeX:: Use @TeX{} to format for hardcopy. -* Format with tex/texindex:: How to format in a shell. -* Format with texi2dvi:: A simpler way to use the shell. +* Format with tex/texindex:: How to format with explicit shell commands. +* Format with texi2dvi:: A simpler way to format. * Print with lpr:: How to print. * Within Emacs:: How to format and print from an Emacs shell. * Texinfo Mode Printing:: How to format and print in Texinfo mode. * Compile-Command:: How to print using Emacs's compile command. * Requirements Summary:: @TeX{} formatting requirements summary. -* Preparing for TeX:: What you need to do to use @TeX{}. +* Preparing for TeX:: What to do before you use @TeX{}. * Overfull hboxes:: What are and what to do with overfull hboxes. * smallbook:: How to print small format books and manuals. * A4 Paper:: How to print on European A4 paper. +* pagesizes:: How to print with customized page sizes. * Cropmarks and Magnification:: How to print marks to indicate the size of pages and how to print scaled up output. +* PDF Output:: Portable Document Format output. + +Creating and Installing Info Files + +* Creating an Info File:: +* Install an Info File:: Creating an Info File @@ -595,10 +573,11 @@ Creating an Info File * Batch Formatting:: How to format for Info in Emacs Batch mode. * Tag and Split Files:: How tagged and split files help Info to run better. +* makeinfo html:: Generating HTML output. Installing an Info File -* Directory file:: The top level menu for all Info files. +* Directory File:: The top level menu for all Info files. * New Info File:: Listing a new info file. * Other Info Directories:: How to specify Info files that are located in other directories. @@ -645,16 +624,19 @@ Finding Badly Referenced Nodes * Unsplit:: How to create an unsplit file. * Tagifying:: How to tagify a file. * Splitting:: How to split a file manually. - -How to Obtain @TeX{} - -* New Texinfo Mode Commands:: The updating commands are especially useful. -* New Commands:: Many newly described @@-commands. @end detailmenu @end menu -@node Copying, Overview, Top, Top -@comment node-name, next, previous, up +@c Reward readers for getting to the end of the menu :). +@c Contributed by Arnold Robbins. +@quotation +Documentation is like sex: when it is good, it is very, very good; and +when it is bad, it is better than nothing. +---Dick Brandon +@end quotation + + +@node Copying @unnumbered Texinfo Copying Conditions @cindex Copying conditions @cindex Conditions for copying Texinfo @@ -690,100 +672,171 @@ their recipients to know that what they have is not what we distributed, so that any problems introduced by others will not reflect on our reputation.@refill - The precise conditions of the licenses for the programs currently +The precise conditions of the licenses for the programs currently being distributed that relate to Texinfo are found in the General Public -Licenses that accompany them.@refill +Licenses that accompany them. -@node Overview, Texinfo Mode, Copying, Top -@comment node-name, next, previous, up + +@node Overview @chapter Overview of Texinfo @cindex Overview of Texinfo @cindex Texinfo overview -@dfn{Texinfo}@footnote{Note that the first syllable of ``Texinfo'' is -pronounced like ``speck'', not ``hex''. This odd pronunciation is -derived from, but is not the same as, the pronunciation of @TeX{}. In -the word @TeX{}, the @samp{X} is actually the Greek letter ``chi'' -rather than the English letter ``ex''. Pronounce @TeX{} as if the -@samp{X} were the last sound in the name `Bach'; but pronounce Texinfo -as if the @samp{x} were a `k'. Spell ``Texinfo'' with a capital ``T'' -and write the other letters in lower case.} -is a documentation system that uses a single source file to produce both -on-line information and printed output. This means that instead of -writing two different documents, one for the on-line help or other on-line -information and the other for a typeset manual or other printed work, you -need write only one document. When the work is revised, you need revise -only one document. (You can read the on-line information, known as an -@dfn{Info file}, with an Info documentation-reading program.)@refill +@dfn{Texinfo}@footnote{The first syllable of ``Texinfo'' is pronounced +like ``speck'', not ``hex''. This odd pronunciation is derived from, +but is not the same as, the pronunciation of @TeX{}. In the word +@TeX{}, the @samp{X} is actually the Greek letter ``chi'' rather than +the English letter ``ex''. Pronounce @TeX{} as if the @samp{X} were the +last sound in the name `Bach'; but pronounce Texinfo as if the @samp{x} +were a `k'. Spell ``Texinfo'' with a capital ``T'' and the other +letters in lower case.} is a documentation system that uses a single +source file to produce both online information and printed output. This +means that instead of writing two different documents, one for the +online information and the other for a printed work, you need write only +one document. Therefore, when the work is revised, you need revise only +that one document. @menu -* Using Texinfo:: Create a conventional printed book - or an Info file. +* Reporting Bugs:: Submitting effective bug reports. +* Using Texinfo:: Create printed or online output. * Info Files:: What is an Info file? * Printed Books:: Characteristics of a printed book or manual. * Formatting Commands:: @@-commands are used for formatting. * Conventions:: General rules for writing a Texinfo file. -* Comments:: How to write comments and mark regions that - the formatting commands will ignore. +* Comments:: Writing comments and ignored text in general. * Minimum:: What a Texinfo file must have. * Six Parts:: Usually, a Texinfo file has six parts. * Short Sample:: A short sample Texinfo file. -* Acknowledgements:: +* Acknowledgements and History:: Contributors and genesis. @end menu -@node Using Texinfo, Info Files, Overview, Overview -@ifinfo -@heading Using Texinfo -@end ifinfo + +@node Reporting Bugs +@section Reporting Bugs + +@cindex Bugs, reporting +@cindex Suggestions for Texinfo, making +@cindex Reporting bugs +We welcome bug reports or suggestions for the Texinfo system, both +programs and documentation. Please email them to +@email{bug-texinfo@@gnu.org}. You can get the latest version of Texinfo +from @uref{ftp://ftp.gnu.org/gnu/texinfo/} and its mirrors worldwide. + +@cindex Checklist for bug reports +For bug reports, please include enough information for the maintainers +to reproduce the problem. Generally speaking, that means: + +@itemize @bullet +@item the version number of Texinfo and the program(s) or manual(s) involved. +@item hardware, operating system, and compiler versions. +@item any unusual options you gave to @command{configure}. +@item the contents of any input files necessary to reproduce the bug. +@item a description of the problem and samples of any erroneous output. +@item anything else that you think would be helpful. +@end itemize + +When in doubt whether something is needed or not, include it. It's +better to include too much than to leave out something important. + +Patches are most welcome; if possible, please make them with +@samp{@w{diff -c}} (@pxref{Top,, Overview, diffutils, Comparing and +Merging Files}) and include @file{ChangeLog} entries (@pxref{Change +Log,,, emacs, The GNU Emacs Manual}). + +When sending email, please do not encode or split the messages in any +way if possible; it's much easier to deal with one plain text message, +however large, than many small ones. +@uref{ftp://ftp.gnu.org/gnu/sharutils/, GNU shar} is a convenient way of +packaging multiple and/or binary files for email. + + +@node Using Texinfo +@section Using Texinfo + +@cindex Using Texinfo in general +@cindex Texinfo, introduction to +@cindex Introduction to Texinfo Using Texinfo, you can create a printed document with the normal -features of a book, including chapters, sections, cross references, -and indices. From the same Texinfo source file, you can create a -menu-driven, on-line Info file with nodes, menus, cross references, -and indices. You can, if you wish, make the chapters and sections of -the printed document correspond to the nodes of the on-line -information; and you use the same cross references and indices for -both the Info file and the printed work. @cite{The GNU -Emacs Manual} is a good example of a Texinfo file, as is this manual.@refill +features of a book, including chapters, sections, cross references, and +indices. From the same Texinfo source file, you can create a +menu-driven, online Info file with nodes, menus, cross references, and +indices. You can also create from that same source file an HTML output +file suitable for use with a web browser. @cite{The GNU Emacs Manual} +is a good example of a Texinfo file, as is this manual. To make a printed document, you process a Texinfo source file with the -@TeX{} typesetting program. This creates a DVI file that you can -typeset and print as a book or report. (Note that the Texinfo language -is completely different from @TeX{}'s usual language, plain @TeX{}.) If -you do not have @TeX{}, but do have @code{troff} or @code{nroff}, you -can use the @code{texi2roff} program instead.@refill - -To make an Info file, you process a Texinfo source file with the -@code{makeinfo} utility or Emacs's @code{texinfo-format-buffer} command; -this creates an Info file that you can install on-line.@refill - -@TeX{} and @code{texi2roff} work with many types of printers; similarly, -Info works with almost every type of computer terminal. This power -makes Texinfo a general purpose system, but brings with it a constraint, -which is that a Texinfo file may contain only the customary -``typewriter'' characters (letters, numbers, spaces, and punctuation -marks) but no special graphics.@refill - -A Texinfo file is a plain @sc{ascii} file containing text and +@TeX{} typesetting program (but the Texinfo language is very different +from @TeX{}'s usual language, plain @TeX{}). This creates a DVI file +that you can typeset and print as a book or report (@pxref{Hardcopy}). + +@pindex makeinfo +To output an Info file, process your Texinfo source with the +@code{makeinfo} utility or Emacs's @code{texinfo-format-buffer} command. +You can install the result in your Info tree (@pxref{Install an Info +File}). + +To output an HTML file, process your Texinfo source with @code{makeinfo} +using the @samp{--html} option. You can (for example) install the +result on your web site. + +@cindex Output formats, supporting more +@cindex Docbook output format +@cindex SGML-tools output format +If you are a programmer and would like to contribute to the GNU project +by implementing additional output formats for Texinfo, that would be +excellent. But please do not write a separate translator texi2foo for +your favorite format foo! That is the hard way to do the job, and makes +extra work in subsequent maintenance, since the Texinfo language is +continually being enhanced and updated. Instead, the best approach is +modify @code{makeinfo} to generate the new format, as it does now for +Info and HTML. + +@TeX{} works with virtually all printers; Info works with virtually all +computer terminals; the HTML output works with virtually all web +browsers. Thus Texinfo can be used by almost any computer user. + +@cindex Source file +A Texinfo source file is a plain @sc{ascii} file containing text and @dfn{@@-commands} (words preceded by an @samp{@@}) that tell the -typesetting and formatting programs what to do. You may edit a -Texinfo file with any text editor; but it is especially convenient to -use GNU Emacs since that editor has a special mode, called Texinfo -mode, that provides various Texinfo-related features. (@xref{Texinfo -Mode}.)@refill - -Before writing a Texinfo source file, you should become familiar with -the Info documentation reading program and learn about nodes, -menus, cross references, and the rest. (@inforef{Top, info, info}, -for more information.)@refill +typesetting and formatting programs what to do. You may edit a Texinfo +file with any text editor; but it is especially convenient to use GNU +Emacs since that editor has a special mode, called Texinfo mode, that +provides various Texinfo-related features. (@xref{Texinfo Mode}.) -You can use Texinfo to create both on-line help and printed manuals; -moreover, Texinfo is freely redistributable. For these reasons, Texinfo -is the format in which documentation for GNU utilities and libraries is -written.@refill +Before writing a Texinfo source file, you should learn about nodes, +menus, cross references, and the rest, for example by reading this +manual. -@node Info Files, Printed Books, Using Texinfo, Overview -@comment node-name, next, previous, up +You can use Texinfo to create both online help and printed manuals; +moreover, Texinfo is freely redistributable. For these reasons, Texinfo +is the official documentation format of the GNU project. More +information is available at the @uref{http://www.gnu.org/doc/, GNU +documentation web page}. + +@cindex Man page output, not supported +From time to time, proposals are made to generate traditional Unix man +pages from Texinfo source. This is not likely to ever be supported, +because man pages have a very strict conventional format. Merely +enhancing @command{makeinfo} to output troff format would be +insufficient. Generating a good man page therefore requires a +completely different source than the typical Texinfo applications of +generating a good user manual or a good reference manual. This makes +generating man pages incompatible with the Texinfo design goal of not +having to document the same information in different ways for different +output formats. You might as well just write the man page directly. + +@pindex help2man +@cindex O'Dea, Brendan +If you wish to support man pages, the program @command{help2man} may be +useful; it generates a traditional man page from the @samp{--help} +output of a program. In fact, this is currently used to generate man +pages for the Texinfo programs themselves. It is free software written +by Brendan O'Dea, available from +@uref{http://www.ozemail.com.au/~bod/help2man.tar.gz}. + + +@node Info Files @section Info files @cindex Info files @@ -870,8 +923,20 @@ The @file{dir} file in the @file{info} directory serves as the departure point for the whole Info system. From it, you can reach the `Top' nodes of each of the documents in a complete Info system.@refill -@node Printed Books, Formatting Commands, Info Files, Overview -@comment node-name, next, previous, up +@cindex URI syntax for Info +If you wish to refer to an Info file in a URI, you can use the +(unofficial) syntax exemplified in the following. This works with +Emacs/W3, for example: +@example +info:///usr/info/emacs#Dissociated%20Press +info:emacs#Dissociated%20Press +info://localhost/usr/info/emacs#Dissociated%20Press +@end example + +The @command{info} program itself does not follow URI's of any kind. + + +@node Printed Books @section Printed Books @cindex Printed book and manual characteristics @cindex Manual characteristics, printed @@ -883,9 +948,12 @@ departure point for the whole Info system. From it, you can reach the A Texinfo file can be formatted and typeset as a printed book or manual. To do this, you need @TeX{}, a powerful, sophisticated typesetting program written by Donald Knuth.@footnote{You can also use the -@code{texi2roff} program if you do not have @TeX{}; since Texinfo is -designed for use with @TeX{}, @code{texi2roff} is not described here. -@code{texi2roff} is not part of the standard GNU distribution.} +@pindex texi2roff@r{, unsupported software} +@uref{ftp://tug.org/texi2roff.tar.gz, @code{texi2roff}} program if you +do not have @TeX{}; since Texinfo is designed for use with @TeX{}, +@code{texi2roff} is not described here. @code{texi2roff} is not part of +the standard GNU distribution and is not maintained or up-to-date with +all the Texinfo features described in this manual.} A Texinfo-based book is similar to any other typeset, printed work: it can have a title page, copyright page, table of contents, and preface, @@ -893,18 +961,19 @@ as well as chapters, numbered or unnumbered sections and subsections, page headers, cross references, footnotes, and indices.@refill You can use Texinfo to write a book without ever having the intention -of converting it into on-line information. You can use Texinfo for +of converting it into online information. You can use Texinfo for writing a printed novel, and even to write a printed memo, although this latter application is not recommended since electronic mail is so much easier.@refill @TeX{} is a general purpose typesetting program. Texinfo provides a -file called @file{texinfo.tex} that contains information (definitions or +file @file{texinfo.tex} that contains information (definitions or @dfn{macros}) that @TeX{} uses when it typesets a Texinfo file. (@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands to @TeX{} commands, which @TeX{} can then process to create the typeset document.) @file{texinfo.tex} contains the specifications for printing -a document.@refill +a document. You can get the latest version of @file{texinfo.tex} from +@uref{ftp://ftp.gnu.org/gnu/texinfo.tex}. Most often, documents are printed on 8.5 inch by 11 inch pages (216@dmn{mm} by 280@dmn{mm}; this is the default size), but you @@ -933,7 +1002,8 @@ character-only terminal in Info form and in a typeset book, the formatting commands that Texinfo supports are necessarily limited.@refill -@xref{Obtaining TeX, , How to Obtain @TeX{}}. +To get a copy of @TeX{}, see +@ref{Obtaining TeX, , How to Obtain @TeX{}}. @node Formatting Commands, Conventions, Printed Books, Overview @@ -963,17 +1033,17 @@ numeric characters. Similarly, you can print the output generated by @TeX{} on a wide variety of printers.@refill Depending on what they do or what arguments@footnote{The word -@dfn{argument} comes from the way it is used in mathematics and does -not refer to a disputation between two people; it refers to the -information presented to the command. According to the @cite{Oxford -English Dictionary}, the word derives from the Latin for @dfn{to make -clear, prove}; thus it came to mean `the evidence offered as proof', -which is to say, `the information offered', which led to its -mathematical meaning. In its other thread of derivation, the word -came to mean `to assert in a manner against which others may make -counter assertions', which led to the meaning of `argument' as a -disputation.} they take, you need to write @@-commands on lines of -their own or as part of sentences:@refill +@dfn{argument} comes from the way it is used in mathematics and does not +refer to a dispute between two people; it refers to the information +presented to the command. According to the @cite{Oxford English +Dictionary}, the word derives from the Latin for @dfn{to make clear, +prove}; thus it came to mean `the evidence offered as proof', which is +to say, `the information offered', which led to its mathematical +meaning. In its other thread of derivation, the word came to mean `to +assert in a manner against which others may make counter assertions', +which led to the meaning of `argument' as a dispute.} they take, you +need to write @@-commands on lines of their own or as part of +sentences: @itemize @bullet @item @@ -998,12 +1068,14 @@ wish (but usually within a sentence) with its argument, marks text as being code.)@refill @item -Write a command such as @code{@@example} at the beginning of a line of -its own; write the body-text on following lines; and write the matching -@code{@@end} command, @code{@@end example} in this case, at the -beginning of a line of its own after the body-text. (@code{@@example} -@dots{} @code{@@end example} indents and typesets body-text as an -example.)@refill +Write a command such as @code{@@example} on a line of its own; write the +body-text on following lines; and write the matching @code{@@end} +command, @code{@@end example} in this case, at the on a line of its own +after the body-text. (@code{@@example} @dots{} @code{@@end example} +indents and typesets body-text as an example.) It's usually ok to +indent environment commands like this, but in complicated and +hard-to-define circumstances the extra spaces cause extra space to +appear in the output, so beware. @end itemize @noindent @@ -1026,6 +1098,10 @@ syntax, see @ref{Command Syntax, , @@-Command Syntax}.)@refill @cindex Syntactic conventions @cindex Conventions, syntactic +This section describes the general conventions used in all Texinfo documents. + +@itemize @bullet +@item All printable @sc{ascii} characters except @samp{@@}, @samp{@{} and @samp{@}} can appear in a Texinfo file and stand for themselves. @samp{@@} is the escape character which introduces commands. @@ -1034,6 +1110,7 @@ certain commands. To put one of these special characters into the document, put an @samp{@@} character in front of it, like this: @samp{@@@@}, @samp{@@@{}, and @samp{@@@}}.@refill +@item @ifinfo It is customary in @TeX{} to use doubled single-quote characters to begin and end quotations: ` ` and ' ' (but without a space between the @@ -1044,23 +1121,26 @@ single-quote characters to @sc{ascii} double-quotes: ` ` and ' ' to " .@refill @end ifinfo @iftex It is customary in @TeX{} to use doubled single-quote characters to -begin and end quotations: @w{@tt{ `` }} and @w{@tt{ '' }}. This +begin and end quotations: @w{@t{ `` }} and @w{@t{ '' }}. This convention should be followed in Texinfo files. @TeX{} converts doubled single-quote characters to left- and right-hand doubled quotation marks, ``like this'', and Info converts doubled single-quote -characters to @sc{ascii} double-quotes: @w{@tt{ `` }} and -@w{@tt{ '' }} to @w{@tt{ " }}.@refill +characters to @sc{ascii} double-quotes: @w{@t{ `` }} and +@w{@t{ '' }} to @w{@t{ " }}.@refill @end iftex +@item Use three hyphens in a row, @samp{---}, for a dash---like this. In @TeX{}, a single or double hyphen produces a printed dash that is shorter than the usual typeset dash. Info reduces three hyphens to two for display on the screen. +@item To prevent a paragraph from being indented in the printed manual, put the command @code{@@noindent} on a line by itself before the paragraph.@refill +@item If you mark off a region of the Texinfo file with the @code{@@iftex} and @w{@code{@@end iftex}} commands, that region will appear only in the printed copy; in that region, you can use certain commands @@ -1071,8 +1151,9 @@ region, you can use Info commands that you cannot use in @TeX{}. Similarly for @code{@@ifhtml @dots{} @@end ifhtml}, @code{@@ifnothtml @dots{} @@end ifnothtml}, @code{@@ifnotinfo @dots{} @@end ifnotinfo}, -@code{@@ifnottex @dots{} @@end ifnottex}, +@code{@@ifnottex @dots{} @@end ifnottex}. @xref{Conditionals}. +@end itemize @cindex Tabs; don't use! @quotation @@ -1090,9 +1171,6 @@ spaces when you press the @key{TAB} key.@refill @noindent Also, you can run @code{untabify} in Emacs to convert tabs in a region to multiple spaces.@refill - -@noindent -Don't use tabs. @end quotation @node Comments, Minimum, Conventions, Overview @@ -1102,7 +1180,7 @@ Don't use tabs. You can write comments in a Texinfo file that will not appear in either the Info file or the printed manual by using the @code{@@comment} command (which may be abbreviated to @code{@@c}). -Such comments are for the person who reads the Texinfo file. All the +Such comments are for the person who revises the Texinfo file. All the text on a line that follows either @code{@@comment} or @code{@@c} is a comment; the rest of the line does not appear in either the Info file or the printed manual. (Often, you can write the @code{@@comment} or @@ -1148,9 +1226,9 @@ within ignored text. @cindex Texinfo file minimum By convention, the names of Texinfo files end with one of the -extensions @file{.texinfo}, @file{.texi}, or @file{.tex}. The longer -extension is preferred since it describes more clearly to a human -reader the nature of the file. The shorter extensions are for +extensions @file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.tex}. +The longer extension is preferred since it describes more clearly to a +human reader the nature of the file. The shorter extensions are for operating systems that cannot handle long file names.@refill In order to be made into a printed manual and an Info file, a Texinfo @@ -1252,8 +1330,7 @@ the table of contents, and the @code{@@bye} command on a line of its own.@refill @end table -@node Short Sample, Acknowledgements, Six Parts, Overview -@comment node-name, next, previous, up +@node Short Sample @section A Short Sample Texinfo File @cindex Sample Texinfo file @@ -1264,7 +1341,6 @@ the material is standard boilerplate; when you write a manual, simply insert the names for your own manual in this segment. (@xref{Beginning a File}.)@refill -@noindent In the following, the sample text is @emph{indented}; comments on it are not. The complete file, without any comments, is shown in @ref{Sample Texinfo File}. @@ -1282,9 +1358,8 @@ name of the Info file and the title used in the header. @@c %**start of header @@setfilename sample.info @@settitle Sample Document -@@c %**end of header - @@setchapternewpage odd +@@c %**end of header @end group @end example @@ -1393,15 +1468,14 @@ manual. @subheading Part 6: The End of the Document @noindent -The end segment contains commands both for generating an index in a node -and unnumbered chapter of its own and for generating the table of -contents; and it contains the @code{@@bye} command that marks the end of -the document.@refill +The end segment contains commands for generating an index in a node and +unnumbered chapter of its own, (usually) for generating the table of +contents, and the @code{@@bye} command that marks the end of the +document.@refill @example @group @@node Concept Index, , First Chapter, Top -@@comment node-name, next, previous, up @@unnumbered Concept Index @end group @@ -1438,41 +1512,61 @@ an Info file; and @TeX{} typesets it for a printed manual. @end quotation -@node Acknowledgements, , Short Sample, Overview -@comment node-name, next, previous, up -@section Acknowledgements + +@node Acknowledgements and History +@section Acknowledgements and History @cindex Stallman, Richard M. @cindex Chassell, Robert J. @cindex Berry, Karl -Richard M.@: Stallman wrote Edition 1.0 of this manual. @w{Robert J.@: -Chassell} revised and extended it, starting with Edition 1.1. Karl -Berry made updates for the Texinfo 3.8 and subsequent releases, starting -with Edition 2.22. +Richard M.@: Stallman invented the Texinfo format, wrote the initial +processors, and created Edition 1.0 of this manual. @w{Robert J.@: +Chassell} greatly revised and extended the manual, starting with Edition +1.1. Brian Fox was responsible for the standalone Texinfo distribution +until version 3.8, and wrote the standalone @command{makeinfo} and +@command{info}. Karl Berry has made the updates since Texinfo 3.8 and +subsequent releases, starting with Edition 2.22 of the manual. @cindex Pinard, Fran@,{c}ois @cindex Zuhn, David D. @cindex Weisshaus, Melissa +@cindex Zaretskii, Eli +@cindex Schwab, Andreas +@cindex Weinberg, Zack Our thanks go out to all who helped improve this work, particularly to Fran@,{c}ois Pinard and @w{David D.@: Zuhn}, who tirelessly recorded and reported mistakes and obscurities; our special thanks go to Melissa Weisshaus for her frequent and often tedious reviews of nearly similar -editions. Our mistakes are our own. - -Please send suggestions and corrections to: - -@example -@group -@r{Internet address:} - bug-texinfo@@gnu.org -@end group -@end example - -@noindent -Please include the manual's edition number and update date in your messages. - -@node Texinfo Mode, Beginning a File, Overview, Top -@comment node-name, next, previous, up +editions. The indefatigable Eli Zaretskii and Andreas Schwab have +provided patches beyond counting. Zack Weinberg did the impossible by +implementing the macro syntax in @file{texinfo.tex}. Dozens of others +have contributed patches and suggestions, they are gratefully +acknowledged in the @file{ChangeLog} file. Our mistakes are our own. + +@cindex Scribe +@cindex Reid, Brian +@cindex History of Texinfo +A bit of history: in the 1970's at CMU, Brian Reid developed a program +and format named Scribe to mark up documents for printing. It used the +@code{@@} character to introduce commands as Texinfo does and strived to +describe document contents rather than formatting. + +@cindex Bolio +@cindex Bo@TeX{} +Meanwhile, people at MIT developed another, not too dissimilar format +called Bolio. This then was converted to using @TeX{} as its typesetting +language: Bo@TeX{}. + +Bo@TeX{} could only be used as a markup language for documents to be +printed, not for online documents. Richard Stallman (RMS) worked on +both Bolio and Bo@TeX{}. He also developed a nifty on-line help format +called Info, and then combined Bo@TeX{} and Info to create Texinfo, a +mark up language for text that is intended to be read both on line and +as printed hard copy. + + + +@node Texinfo Mode @chapter Using Texinfo Mode @cindex Texinfo mode @cindex Mode, using Texinfo @@ -1509,7 +1603,8 @@ detail.@refill @end ifinfo Texinfo mode provides special features for working with Texinfo -files:@refill +files. +You can:@refill @itemize @bullet @item @@ -1565,12 +1660,12 @@ delimiter, you can jump from chapter title to chapter title with the The GNU Emacs Manual}, for details about the page commands.)@refill You may name a Texinfo file however you wish, but the convention is to -end a Texinfo file name with one of the three extensions -@file{.texinfo}, @file{.texi}, or @file{.tex}. A longer extension is -preferred, since it is explicit, but a shorter extension may be -necessary for operating systems that limit the length of file names. -GNU Emacs automatically enters Texinfo mode when you visit a file with -a @file{.texinfo} or @file{.texi} +end a Texinfo file name with one of the extensions +@file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.tex}. A longer +extension is preferred, since it is explicit, but a shorter extension +may be necessary for operating systems that limit the length of file +names. GNU Emacs automatically enters Texinfo mode when you visit a +file with a @file{.texinfo}, @file{.texi} or @file{.txi} extension. Also, Emacs switches to Texinfo mode when you visit a file that has @samp{-*-texinfo-*-} in its first line. If ever you are @@ -1762,14 +1857,10 @@ cursor in the @file{*Occur*} buffer.@refill If you call @code{texinfo-show-structure} with a prefix argument by typing @w{@kbd{C-u C-c C-s}}, it will list not only those lines with the -@@-commands for @code{@@chapter}, @code{@@section}, and the like, -but also the @code{@@node} lines. (This is how the -@code{texinfo-show-structure} command worked without an argument in -the first version of Texinfo. It was changed because @code{@@node} -lines clutter up the @samp{*Occur*} buffer and are usually not -needed.) You can use @code{texinfo-show-structure} with a prefix -argument to check whether the `Next', `Previous', and `Up' pointers of -an @code{@@node} line are correct.@refill +@@-commands for @code{@@chapter}, @code{@@section}, and the like, but +also the @code{@@node} lines. You can use @code{texinfo-show-structure} +with a prefix argument to check whether the `Next', `Previous', and `Up' +pointers of an @code{@@node} line are correct. Often, when you are working on a manual, you will be interested only in the structure of the current chapter. In this case, you can mark @@ -1823,18 +1914,18 @@ node pointers by hand, which is a tedious task.@refill @subheading The Updating Commands @end ifinfo -You can use the updating commands@refill +You can use the updating commands to:@refill @itemize @bullet @item -to insert or update the `Next', `Previous', and `Up' pointers of a +insert or update the `Next', `Previous', and `Up' pointers of a node,@refill @item -to insert or update the menu for a section, and@refill +insert or update the menu for a section, and@refill @item -to create a master menu for a Texinfo source file.@refill +create a master menu for a Texinfo source file.@refill @end itemize You can also use the commands to update all the nodes and menus in a @@ -1856,11 +1947,11 @@ interpose only an @code{@@comment} line or an @code{@@ifinfo} line. Commands which work on a whole buffer require that the `Top' node be followed by a node with an @code{@@chapter} or equivalent-level command. -Note that the menu updating commands will not create a main or master -menu for a Texinfo file that has only @code{@@chapter}-level nodes! The -menu updating commands only create menus @emph{within} nodes for lower level +The menu updating commands will not create a main or master menu for a +Texinfo file that has only @code{@@chapter}-level nodes! The menu +updating commands only create menus @emph{within} nodes for lower level nodes. To create a menu of chapters, you must provide a `Top' -node.@refill +node. The menu updating commands remove menu entries that refer to other Info files since they do not refer to nodes within the current buffer. This @@ -1906,7 +1997,7 @@ This updates all the nodes and menus completely and all at once.@refill @end table The other major updating commands do smaller jobs and are designed for -the person who updates nodes and menus as he or she writes a Texinfo +the person who updates nodes and menus as he or she writes a Texinfo file.@refill @need 1000 @@ -2031,7 +2122,7 @@ In this example, `Comments' is the name of both the node and the section. The next node is called `Minimum' and the previous node is called `Conventions'. The `Comments' section is within the `Overview' node, which is specified by the `Up' pointer. (Instead of an -@code{@@comment} line, you can write an @code{@@ifinfo} line.)@refill +@code{@@comment} line, you may also write an @code{@@ifinfo} line.)@refill If a file has a `Top' node, it must be called @samp{top} or @samp{Top} and be the first node in the file.@refill @@ -2040,14 +2131,14 @@ The menu updating commands create a menu of sections within a chapter, a menu of subsections within a section, and so on. This means that you must have a `Top' node if you want a menu of chapters.@refill -Incidentally, the @code{makeinfo} command will create an Info file for -a hierarchically organized Texinfo file that lacks `Next', `Previous' -and `Up' pointers. Thus, if you can be sure that your Texinfo file -will be formatted with @code{makeinfo}, you have no need for the -`update node' commands. (@xref{Create an Info File, , Creating an -Info File}, for more information about @code{makeinfo}.) However, -both @code{makeinfo} and the @code{texinfo-format-@dots{}} commands -require that you insert menus in the file.@refill +Incidentally, the @code{makeinfo} command will create an Info file for a +hierarchically organized Texinfo file that lacks `Next', `Previous' and +`Up' pointers. Thus, if you can be sure that your Texinfo file will be +formatted with @code{makeinfo}, you have no need for the update node +commands. (@xref{Creating an Info File}, for more information about +@code{makeinfo}.) However, both @code{makeinfo} and the +@code{texinfo-format-@dots{}} commands require that you insert menus in +the file. @node Other Updating Commands, , Updating Requirements, Updating Nodes and Menus @comment node-name, next, previous, up @@ -2078,11 +2169,11 @@ For example, the following marks a whole buffer as a region and inserts C-x h C-u M-x texinfo-insert-node-lines @end example -(Note that this command inserts titles as node names in @code{@@node} -lines; the @code{texinfo-start-menu-description} command -(@pxref{Inserting, Inserting Frequently Used Commands}) inserts titles -as descriptions in menu entries, a different action. However, in both -cases, you need to edit the inserted text.)@refill +This command inserts titles as node names in @code{@@node} lines; the +@code{texinfo-start-menu-description} command (@pxref{Inserting, +Inserting Frequently Used Commands}) inserts titles as descriptions in +menu entries, a different action. However, in both cases, you need to +edit the inserted text. @item M-x texinfo-multiple-files-update @findex texinfo-multiple-files-update @r{(in brief)} @@ -2182,7 +2273,7 @@ M-x makeinfo-buffer For @TeX{} or the Info formatting commands to work, the file @emph{must} include a line that has @code{@@setfilename} in its header.@refill -@xref{Create an Info File}, for details about Info formatting.@refill +@xref{Creating an Info File}, for details about Info formatting.@refill @node Printing, Texinfo Mode Summary, Info Formatting, Texinfo Mode @comment node-name, next, previous, up @@ -2245,7 +2336,7 @@ on a line by itself. (When you use @code{texinfo-tex-region}, you must surround the @code{@@settitle} line with start-of-header and end-of-header lines.)@refill -@xref{Format/Print Hardcopy}, for a description of the other @TeX{} related +@xref{Hardcopy}, for a description of the other @TeX{} related commands, such as @code{tex-show-print-queue}.@refill @node Texinfo Mode Summary, , Printing, Texinfo Mode @@ -2297,6 +2388,7 @@ C-c C-s @r{List all the headings.} The @code{texinfo-master-menu} command creates a master menu; and can be used to update every node and menu in a file as well.@refill +@c Probably should use @tables in this section. @example @group C-c C-u m @@ -2398,7 +2490,7 @@ C-c C-t C-l @r{Recenter the output buffer.} @subheading Other Updating Commands -The `other updating commands' do not have standard keybindings because +The remaining updating commands do not have standard keybindings because they are rarely used. @example @@ -2609,12 +2701,13 @@ or else like this: * setfilename:: Tell Info the name of the Info file. * settitle:: Create a title for the printed work. * setchapternewpage:: Start chapters on right-hand pages. -* paragraphindent:: An option to specify paragraph indentation. +* paragraphindent:: Specify paragraph indentation. +* exampleindent:: Specify environment indentation. * End of Header:: Formatting a region requires this. @end menu -@node First Line, Start of Header, Header, Header -@comment node-name, next, previous, up + +@node First Line @subsection The First Line of a Texinfo File @cindex First line of a Texinfo file @cindex Beginning line of a Texinfo file @@ -2669,8 +2762,7 @@ A start-of-header line looks like this:@refill The odd string of characters, @samp{%**}, is to ensure that no other comment is accidentally taken for a start-of-header line.@refill -@node setfilename, settitle, Start of Header, Header -@comment node-name, next, previous, up +@node setfilename @subsection @code{@@setfilename} @cindex Info file requires @code{@@setfilename} @findex setfilename @@ -2688,11 +2780,13 @@ else on the line; anything on the line after the command is considered part of the file name, including what would otherwise be a comment. -The @code{@@setfilename} line specifies the name of the Info file to be -generated. This name should be different from the name of the Texinfo -file. There are two conventions for choosing the name: you can either -remove the @samp{.texi} extension from the input file name, or replace -it with the @samp{.info} extension. +The @code{@@setfilename} line specifies the name of the output file to +be generated. This name should be different from the name of the +Texinfo file. There are two conventions for choosing the name: you can +either remove the extension (such as @samp{.texi}) from the input file +name, or replace it with the @samp{.info} extension. When producing +HTML output, @code{makeinfo} will replace any extension with +@samp{html}, or add @samp{.html} if the given name has no extension. Some operating systems cannot handle long file names. You can run into a problem even when the file name you specify is itself short enough. @@ -2702,19 +2796,24 @@ short indirect subfiles, and name them by appending @samp{-1}, file name. (@xref{Tag and Split Files, , Tag Files and Split Files}.) The subfile name @file{texinfo.info-10}, for example, is too long for some systems; so the Info file name for this document is @file{texinfo} -rather than @file{texinfo.info}. +rather than @file{texinfo.info}. When @code{makeinfo} is running on +operating systems such as MS-DOS which impose grave limits on file +names, it will sometimes remove some characters from the original file +name to leave enough space for the subfile suffix, thus producing files +named @file{texin-10}, @file{gcc.i12}, etc. @cindex Ignored before @code{@@setfilename} +@cindex @samp{\input} source line ignored The Info formatting commands ignore everything written before the @code{@@setfilename} line, which is why the very first line of the file (the @code{\input} line) does not show up in the output. @pindex texinfo.cnf The @code{@@setfilename} line produces no output when you typeset a -manual with @TeX{}, but it nevertheless is essential: it opens the +manual with @TeX{}, but it is nevertheless essential: it opens the index, cross-reference, and other auxiliary files used by Texinfo, and also reads @file{texinfo.cnf} if that file is present on your system -(@pxref{Preparing for TeX,, Preparing to Use @TeX{}}). +(@pxref{Preparing for TeX,, Preparing for @TeX{}}). @node settitle, setchapternewpage, setfilename, Header @@ -2766,15 +2865,15 @@ You may, if you wish, create your own, customized headings and footings. @xref{Headings, , Page Headings}, for a detailed discussion of this process.@refill -@node setchapternewpage, paragraphindent, settitle, Header -@comment node-name, next, previous, up + +@node setchapternewpage @subsection @code{@@setchapternewpage} @cindex Starting chapters @cindex Pages, starting odd @findex setchapternewpage -In a book or a manual, text is usually printed on both sides of the -paper, chapters start on right-hand pages, and right-hand pages have +In an officially bound book, text is usually printed on both sides of +the paper, chapters start on right-hand pages, and right-hand pages have odd numbers. But in short reports, text often is printed only on one side of the paper. Also in short reports, chapters sometimes do not start on new pages, but are printed on the same page as the end of the @@ -2782,7 +2881,7 @@ preceding chapter, after a small amount of vertical whitespace.@refill You can use the @code{@@setchapternewpage} command with various arguments to specify how @TeX{} should start chapters and whether it -should typeset pages for printing on one or both sides of the paper +should format headers for printing on one or both sides of the paper (single-sided or double-sided printing).@refill Write the @code{@@setchapternewpage} command at the beginning of a @@ -2799,17 +2898,7 @@ You can specify one of three alternatives with the @code{@@setchapternewpage} command:@refill @table @asis -@ignore -@item No @code{@@setchapternewpage} command -If the Texinfo file does not contain an @code{@@setchapternewpage} -command before the @code{@@titlepage} command, @TeX{} automatically -begins chapters on new pages and prints headings in the standard -format for single-sided printing. This is the conventional format for -single-sided printing.@refill -The result is exactly the same as when you write -@code{@@setchapternewpage on}.@refill -@end ignore @item @code{@@setchapternewpage off} Cause @TeX{} to typeset a new chapter on the same page as the last chapter, after skipping some vertical whitespace. Also, cause @TeX{} to @@ -2818,9 +2907,9 @@ headers format with the @code{@@headings double} command; see @ref{headings on off, , The @code{@@headings} Command}.)@refill @item @code{@@setchapternewpage on} -Cause @TeX{} to start new chapters on new pages and to typeset page +Cause @TeX{} to start new chapters on new pages and to format page headers for single-sided printing. This is the form most often -used for short reports.@refill +used for short reports or personal printing. This alternative is the default.@refill @@ -2830,13 +2919,11 @@ Cause @TeX{} to start new chapters on new, odd-numbered pages the form most often used for books and manuals.@refill @end table -@noindent Texinfo does not have an @code{@@setchapternewpage even} command.@refill -@noindent -(You can countermand or modify an @code{@@setchapternewpage} command -with an @code{@@headings} command. @xref{headings on off, , The -@code{@@headings} Command}.)@refill +You can countermand or modify the effect on headers of an +@code{@@setchapternewpage} command with an @code{@@headings} command. +@xref{headings on off, , The @code{@@headings} Command}.@refill At the beginning of a manual or book, pages are not numbered---for example, the title and copyright pages of a book are not numbered. @@ -2846,62 +2933,100 @@ numerals and not in sequence with the rest of the document.@refill Since an Info file does not have pages, the @code{@@setchapternewpage} command has no effect on it.@refill -Usually, you do not write an @code{@@setchapternewpage} command for -single-sided printing, but accept the default which is to typeset for -single-sided printing and to start new chapters on new pages. Usually, -you write an @code{@@setchapternewpage odd} command for double-sided -printing.@refill +We recommend not including any @code{@@setchapternewpage} command in +your manual sources at all, since the desired output is not intrinsic to +the document. Instead, if you don't want the default option (no blank +pages, same headers on all pages) use the @option{--texinfo} option to +@command{texi2dvi} to specify the output you want. -@node paragraphindent, End of Header, setchapternewpage, Header -@comment node-name, next, previous, up + + +@node paragraphindent @subsection Paragraph Indenting @cindex Indenting paragraphs @cindex Paragraph indentation @findex paragraphindent -The Info formatting commands may insert spaces at the beginning of the -first line of each paragraph, thereby indenting that paragraph. You -can use the @code{@@paragraphindent} command to specify the -indentation. Write an @code{@@paragraphindent} command at the -beginning of a line followed by either @samp{asis} or a number. The -template is:@refill +The Texinfo processors may insert whitespace at the beginning of the +first line of each paragraph, thereby indenting that paragraph. You can +use the @code{@@paragraphindent} command to specify this indentation. +Write an @code{@@paragraphindent} command at the beginning of a line +followed by either @samp{asis} or a number: @example @@paragraphindent @var{indent} @end example -The Info formatting commands indent according to the value of -@var{indent}:@refill +The indentation is according to the value of @var{indent}: -@itemize @bullet -@item -If the value of @var{indent} is @samp{asis}, the Info formatting -commands do not change the existing indentation.@refill +@table @asis +@item @code{asis} +Do not change the existing indentation (not implemented in @TeX{}). -@item -If the value of @var{indent} is zero, the Info formatting commands delete -existing indentation.@refill +@item 0 +Omit all indentation. -@item -If the value of @var{indent} is greater than zero, the Info formatting -commands indent the paragraph by that number of spaces.@refill -@end itemize +@item @var{n} +Indent by @var{n} space characters in Info output, by @var{n} ems in +@TeX{}. + +@end table -The default value of @var{indent} is @samp{asis}.@refill +The default value of @var{indent} is @samp{asis}. +@code{@@paragraphindent} is ignored for HTML output. Write the @code{@@paragraphindent} command before or shortly after the end-of-header line at the beginning of a Texinfo file. (If you write the command between the start-of-header and end-of-header lines, the -region formatting commands indent paragraphs as specified.)@refill +region formatting commands indent paragraphs as specified.) A peculiarity of the @code{texinfo-format-buffer} and @code{texinfo-format-region} commands is that they do not indent (nor fill) paragraphs that contain @code{@@w} or @code{@@*} commands. -@xref{Refilling Paragraphs}, for a detailed description of what goes -on.@refill +@xref{Refilling Paragraphs}, for further information. -@node End of Header, , paragraphindent, Header -@comment node-name, next, previous, up + +@node exampleindent +@subsection @code{@@exampleindent}: Environment Indenting +@cindex Indenting environments +@cindex Environment indentation +@cindex Example indentation +@findex exampleindent + +The Texinfo processors indent each line of @code{@@example} and similar +environments. You can use the @code{@@exampleindent} command to specify +this indentation. Write an @code{@@exampleindent} command at the +beginning of a line followed by either @samp{asis} or a number: + +@example +@@exampleindent @var{indent} +@end example + +The indentation is according to the value of @var{indent}: + +@table @asis +@item @code{asis} +Do not change the existing indentation (not implemented in @TeX{}). + +@item 0 +Omit all indentation. + +@item @var{n} +Indent environments by @var{n} space characters in Info output, by +@var{n} ems in @TeX{}. + +@end table + +The default value of @var{indent} is 5. @code{@@exampleindent} is +ignored for HTML output. + +Write the @code{@@exampleindent} command before or shortly after the +end-of-header line at the beginning of a Texinfo file. (If you write +the command between the start-of-header and end-of-header lines, the +region formatting commands indent examples as specified.) + + +@node End of Header @subsection End of Header @cindex End of header line @@ -2931,8 +3056,8 @@ variables that you can change.@refill @xref{Start of Header}. @end iftex -@node Info Summary and Permissions, Titlepage & Copyright Page, Header, Beginning a File -@comment node-name, next, previous, up + +@node Info Summary and Permissions @section Summary and Copying Permissions for Info The title page and the copyright page appear only in the printed copy of @@ -2959,8 +3084,8 @@ node. This mean that a reader does @emph{not} see this text when reading the file using Info, except when using the advanced Info command @kbd{g *}. -@node Titlepage & Copyright Page, The Top Node, Info Summary and Permissions, Beginning a File -@comment node-name, next, previous, up + +@node Titlepage & Copyright Page @section The Title and Copyright Pages A manual's name and author are usually printed on a title page. @@ -2974,6 +3099,12 @@ obscure @TeX{} typesetting commands that cannot be used in an Info file. In addition, this part of the beginning of a Texinfo file contains the text of the copying permissions that will appear in the printed manual.@refill +@cindex Titlepage, for plain text +You may wish to include titlepage-like information for plain text +output. Simply place any such leading material between @code{@@ifinfo} +and @code{@@end ifinfo}; @command{makeinfo} includes this in its plain +text output. It will not show up in the Info readers. + @xref{Titlepage Permissions, , Titlepage Copying Permissions}, for the standard text for the copyright permissions.@refill @@ -2991,6 +3122,7 @@ standard text for the copyright permissions.@refill and double or single sided printing. @end menu + @node titlepage, titlefont center sp, Titlepage & Copyright Page, Titlepage & Copyright Page @comment node-name, next, previous, up @subsection @code{@@titlepage} @@ -3003,53 +3135,57 @@ with @code{@@titlepage} on a line by itself and end it with The @code{@@end titlepage} command starts a new page and turns on page numbering. (@xref{Headings, , Page Headings}, for details about how to -generate page headings.) All the material that you want to -appear on unnumbered pages should be put between the -@code{@@titlepage} and @code{@@end titlepage} commands. By using the -@code{@@page} command you can force a page break within the region -delineated by the @code{@@titlepage} and @code{@@end titlepage} -commands and thereby create more than one unnumbered page. This is -how the copyright page is produced. (The @code{@@titlepage} command -might perhaps have been better named the -@code{@@titleandadditionalpages} command, but that would have been -rather long!)@refill - -@c !!! append refill to footnote when makeinfo can handle it. +generate page headings.) All the material that you want to appear on +unnumbered pages should be put between the @code{@@titlepage} and +@code{@@end titlepage} commands. You can force the table of contents to +appear there with the @code{@@setcontentsaftertitlepage} command +(@pxref{Contents}). + +@findex page@r{, within @code{@@titlepage}} +By using the @code{@@page} command you can force a page break within the +region delineated by the @code{@@titlepage} and @code{@@end titlepage} +commands and thereby create more than one unnumbered page. This is how +the copyright page is produced. (The @code{@@titlepage} command might +perhaps have been better named the @code{@@titleandadditionalpages} +command, but that would have been rather long!) + When you write a manual about a computer program, you should write the -version of the program to which the manual applies on the title -page. If the manual changes more frequently than the program or is -independent of it, you should also include an edition -number@footnote{We have found that it is helpful to refer to versions -of manuals as `editions' and versions of programs as `versions'; -otherwise, we find we are liable to confuse each other in conversation -by referring to both the documentation and the software with the same -words.} for the manual. This helps readers keep track of which manual -is for which version of the program. (The `Top' node -should also contain this information; see @ref{makeinfo top, , -@code{@@top}}.)@refill +version of the program to which the manual applies on the title page. +If the manual changes more frequently than the program or is independent +of it, you should also include an edition number@footnote{We have found +that it is helpful to refer to versions of manuals as `editions' and +versions of programs as `versions'; otherwise, we find we are liable to +confuse each other in conversation by referring to both the +documentation and the software with the same words.} for the manual. +This helps readers keep track of which manual is for which version of +the program. (The `Top' node should also contain this information; see +@ref{makeinfo top, , @code{@@top}}.) Texinfo provides two main methods for creating a title page. One method uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands to generate a title page in which the words on the page are -centered.@refill +centered. The second method uses the @code{@@title}, @code{@@subtitle}, and @code{@@author} commands to create a title page with black rules under the title and author lines and the subtitle text set flush to the right hand side of the page. With this method, you do not specify any of the actual formatting of the title page. You specify the text -you want, and Texinfo does the formatting. You may use either -method.@refill +you want, and Texinfo does the formatting. + +You may use either method, or you may combine them; see the examples in +the sections below. @findex shorttitlepage -For extremely simple applications, Texinfo also provides a command -@code{@@shorttitlepage} which takes a single argument as the title. -The argument is typeset on a page by itself and followed by a blank -page. +@cindex Bastard title page +@cindex Title page, bastard +For extremely simple applications, and for the bastard title page in +traditional book front matter, Texinfo also provides a command +@code{@@shorttitlepage} which takes a single argument as the title. The +argument is typeset on a page by itself and followed by a blank page. -@node titlefont center sp, title subtitle author, titlepage, Titlepage & Copyright Page -@comment node-name, next, previous, up +@node titlefont center sp @subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp} @findex titlefont @findex center @@ -3060,7 +3196,8 @@ commands to create a title page for a printed document. (This is the first of the two methods for creating a title page in Texinfo.)@refill Use the @code{@@titlefont} command to select a large font suitable for -the title itself.@refill +the title itself. You can use @code{@@titlefont} more than once if you +have an especially long title. @need 700 For example: @@ -3107,10 +3244,10 @@ A template for this method looks like this:@refill @end group @end example -The spacing of the example fits an 8 1/2 by 11 inch manual.@refill +The spacing of the example fits an 8.5 by 11 inch manual.@refill -@node title subtitle author, Copyright & Permissions, titlefont center sp, Titlepage & Copyright Page -@comment node-name, next, previous, up + +@node title subtitle author @subsection @code{@@title}, @code{@@subtitle}, and @code{@@author} @findex title @findex subtitle @@ -3119,9 +3256,8 @@ The spacing of the example fits an 8 1/2 by 11 inch manual.@refill You can use the @code{@@title}, @code{@@subtitle}, and @code{@@author} commands to create a title page in which the vertical and horizontal spacing is done for you automatically. This contrasts with the method -described in -the previous section, in which the @code{@@sp} command is needed to -adjust vertical spacing.@refill +described in the previous section, in which the @code{@@sp} command is +needed to adjust vertical spacing. Write the @code{@@title}, @code{@@subtitle}, or @code{@@author} commands at the beginning of a line followed by the title, subtitle, @@ -3129,7 +3265,11 @@ or author.@refill The @code{@@title} command produces a line in which the title is set flush to the left-hand side of the page in a larger than normal font. -The title is underlined with a black rule.@refill +The title is underlined with a black rule. Only a single line is +allowed; the @code{@@*} command may not be used to break the title into +two lines. To handle very long titles, you may find it profitable to +use both @code{@@title} and @code{@@titlefont}; see the final example in +this section. The @code{@@subtitle} command sets subtitles in a normal-sized font flush to the right-hand side of the page.@refill @@ -3179,29 +3319,28 @@ A template for this method looks like this:@refill @end group @end example -@ifinfo -@noindent -Contrast this form with the form of a title page written using the -@code{@@sp}, @code{@@center}, and @code{@@titlefont} commands:@refill +You may also combine the @code{@@titlefont} method described in the +previous section and @code{@@title} method described in this one. This +may be useful if you have a very long title. Here is a real-life example: @example +@group @@titlepage -@@sp 10 -@@center @@titlefont@{Name of Manual When Printed@} -@@sp 2 -@@center Subtitle, If Any +@@titlefont@{GNU Software@} @@sp 1 -@@center Second subtitle -@@sp 2 -@@center Author -@@page -@dots{} -@@end titlepage +@@title for MS-Windows and MS-DOS +@@subtitle Edition @@value@{edition@} for Release @@value@{cd-edition@} +@@author by Daniel Hagerty, Melissa Weisshaus +@@author and Eli Zaretskii +@end group @end example -@end ifinfo -@node Copyright & Permissions, end titlepage, title subtitle author, Titlepage & Copyright Page -@comment node-name, next, previous, up +@noindent +(The use of @code{@@value} here is explained in @ref{value +Example,,@code{@@value} Example}.) + + +@node Copyright & Permissions @subsection Copyright Page and Permissions @cindex Copyright page @cindex Printed permissions @@ -3248,19 +3387,17 @@ Copyright @copyright{} @var{year} @var{copyright-owner} @end example It is customary to put information on how to get a manual after the -copyright notice, followed by the copying permissions for the -manual.@refill +copyright notice, followed by the copying permissions for the manual. -Note that permissions must be given here as well as in the summary -segment within @code{@@ifinfo} and @code{@@end ifinfo} that -immediately follows the header since this text appears only in the -printed manual and the @samp{ifinfo} text appears only in the Info -file.@refill +Permissions must be given here as well as in the summary segment within +@code{@@ifinfo} and @code{@@end ifinfo} that immediately follows the +header since this text appears only in the printed manual and the +@samp{ifinfo} text appears only in the Info file. @xref{Sample Permissions}, for the standard text.@refill -@node end titlepage, headings on off, Copyright & Permissions, Titlepage & Copyright Page -@comment node-name, next, previous, up + +@node end titlepage @subsection Heading Generation @findex end titlepage @cindex Headings, page, begin to appear @@ -3327,6 +3464,7 @@ Turn on page headings appropriate for single-sided printing. @refill @item @@headings double +@itemx @@headings on Turn on page headings appropriate for double-sided printing. The two commands, @code{@@headings on} and @code{@@headings double}, are synonymous.@refill @@ -3365,8 +3503,8 @@ headings.@refill You can also specify your own style of page heading and footing. @xref{Headings, , Page Headings}, for more information.@refill -@node The Top Node, Software Copying Permissions, Titlepage & Copyright Page, Beginning a File -@comment node-name, next, previous, up + +@node The Top Node @section The `Top' Node and Master Menu @cindex @samp{@r{Top}} node @cindex Master menu @@ -3393,10 +3531,9 @@ strictly speaking, you are not required to enclose these parts between * Master Menu Parts:: A master menu has three or more parts. @end menu -@node Title of Top Node, Master Menu Parts, The Top Node, The Top Node -@ifinfo -@subheading `Top' Node Title -@end ifinfo + +@node Title of Top Node +@subsection `Top' Node Title Sometimes, you will want to place an @code{@@top} sectioning command line containing the title of the document immediately after the @@ -3412,7 +3549,7 @@ version information. It looks like this:@refill @dots{} @@end titlepage -@@ifinfo +@@ifnottex @@node Top, Copying, , (dir) @@top Texinfo @@ -3422,7 +3559,7 @@ Texinfo is a documentation system@dots{} @group This is edition@dots{} @dots{} -@@end ifinfo +@@end ifnottex @end group @group @@ -3559,10 +3696,10 @@ Usually, an introduction is put in an @code{@@unnumbered} section. @cindex File ending @findex bye -The end of a Texinfo file should include the commands that create -indices and generate detailed and summary tables of contents. -And it must include the @code{@@bye} command that marks the last line -processed by @TeX{}.@refill +The end of a Texinfo file should include commands to create indices and +(usually) to generate detailed and summary tables of contents. And it +must include the @code{@@bye} command that marks the last line processed +by @TeX{}.@refill @need 700 For example: @@ -3602,7 +3739,7 @@ accumulated. To generate an index, you must include the @code{@@printindex} command at the place in the document where you want the index to appear. Also, as part of the process of creating a printed manual, you must run a program called @code{texindex} -(@pxref{Format/Print Hardcopy}) to sort the raw data to produce a sorted +(@pxref{Hardcopy}) to sort the raw data to produce a sorted index file. The sorted index file is what is actually used to print the index.@refill @@ -3662,52 +3799,35 @@ For example: @@printindex cp @end group - -@group -@@summarycontents -@@contents -@@bye -@end group @end smallexample @noindent -(Readers often prefer that the concept index come last in a book, -since that makes it easiest to find.)@refill - -@ignore -@c TeX can do sorting, just not conveniently enough to handle sorting -@c Texinfo indexes. --karl, 5may97. -In @TeX{}, the @code{@@printindex} command needs a sorted index file -to work from. @TeX{} does not know how to do sorting; this is a -deficiency. @TeX{} writes output files of raw index data; use the -@code{texindex} program to convert these files to sorted index files. -(@xref{Format/Print Hardcopy}, for more information.)@refill -@end ignore +Readers often prefer that the concept index come last in a book, +since that makes it easiest to find. Having just one index helps +readers also, since then they have only one place to look +(@pxref{synindex}). -@node Contents, File End, Printing Indices & Menus, Ending a File -@comment node-name, next, previous, up +@node Contents @section Generating a Table of Contents @cindex Table of contents @cindex Contents, Table of +@cindex Short table of contents @findex contents @findex summarycontents @findex shortcontents The @code{@@chapter}, @code{@@section}, and other structuring commands supply the information to make up a table of contents, but they do not -cause an actual table to appear in the manual. To do this, you must -use the @code{@@contents} and @code{@@summarycontents} -commands:@refill +cause an actual table to appear in the manual. To do this, you must use +the @code{@@contents} and/or @code{@@summarycontents} command(s). @table @code @item @@contents Generate a table of contents in a printed manual, including all chapters, sections, subsections, etc., as well as appendices and unnumbered chapters. (Headings generated by the @code{@@heading} -series of commands do not appear in the table of contents.) The -@code{@@contents} command should be written on a line by -itself.@refill +series of commands do not appear in the table of contents.) @item @@shortcontents @itemx @@summarycontents @@ -3719,42 +3839,55 @@ chapters (and appendices and unnumbered chapters). Omit sections, subsections and subsubsections. Only a long manual needs a short table of contents in addition to the full table of contents.@refill -Write the @code{@@shortcontents} command on a line by itself right -@emph{before} the @code{@@contents} command.@refill @end table -The table of contents commands automatically generate a chapter-like -heading at the top of the first table of contents page. Write the table -of contents commands at the very end of a Texinfo file, just before the -@code{@@bye} command, following any index sections---anything in the -Texinfo file after the table of contents commands will be omitted from -the table of contents.@refill - -When you print a manual with a table of contents, the table of -contents are printed last and numbered with roman numerals. You need -to place those pages in their proper place, after the title page, -yourself. (This is the only collating you need to do for a printed -manual. The table of contents is printed last because it is generated -after the rest of the manual is typeset.)@refill - -@need 700 -Here is an example of where to write table of contents commands:@refill - -@example -@group -@var{indices}@dots{} -@@shortcontents -@@contents -@@bye -@end group -@end example +Both contents commands should be written on a line by themselves. +The contents commands automatically generate a chapter-like heading at +the top of the first table of contents page, so don't include any +sectioning command such as @code{@@unnumbered} before them. Since an Info file uses menus instead of tables of contents, the Info -formatting commands ignore the @code{@@contents} and -@code{@@shortcontents} commands.@refill - -@node File End, , Contents, Ending a File -@comment node-name, next, previous, up +formatting commands ignore the contents commands. But the contents are +included in plain text output (generated by @code{makeinfo --no-headers}). + +The contents commands can be placed either at the very end of the file, +after any indices (see the previous section) and just before the +@code{@@bye} (see the next section), or near the beginning of the file, +after the @code{@@end titlepage} (@pxref{titlepage}). The advantage to +the former is that then the contents output is always up to date, +because it reflects the processing just done. The advantage to the +latter is that the contents are printed in the proper place, thus you do +not need to rearrange the DVI file with @command{dviselect} or shuffle +paper. However, contents commands at the beginning of the document are +ignored when outputting to standard output. + +@findex setcontentsaftertitlepage +@findex setshortcontentsaftertitlepage +@cindex Contents, after title page +@cindex Table of contents, after title page +As an author, you can put the contents commands wherever you prefer. +But if you are a user simply printing a manual, you may wish to print +the contents after the title page even if the author put the contents +commands at the end of the document (as is the case in most existing +Texinfo documents). You can do this by specifying +@code{@@setcontentsaftertitlepage} and/or +@code{@@setshortcontentsaftertitlepage}. The first prints only the main +contents after the @code{@@end titlepage}; the second prints both the +short contents and the main contents. In either case, any subsequent +@code{@@contents} or @code{@@shortcontents} is ignored (unless no +@code{@@end titlepage} is ever encountered). + +You need to include the @code{@@set@dots{}contentsaftertitlepage} +commands early in the document (just after @code{@@setfilename}, for +example). Or, if you're using @command{texi2dvi} (@pxref{Format with +texi2dvi}), you can use its @option{--texinfo} option to specify this +without altering the source file at all. For example: +@example +texi2dvi --texinfo=@@setshortcontentsaftertitlepage foo.texi +@end example + + +@node File End @section @code{@@bye} File Ending @findex bye @@ -3769,8 +3902,8 @@ manual; it is as if text after @code{@@bye} were within @code{@@ignore} with a local variables list. @xref{Compile-Command, , Using Local Variables and the Compile Command}, for more information.@refill -@node Structuring, Nodes, Ending a File, Top -@comment node-name, next, previous, up + +@node Structuring @chapter Chapter Structuring @cindex Chapter structuring @cindex Structuring of chapters @@ -3809,8 +3942,8 @@ heading at the top of each node---but you don't need to.@refill * Raise/lower sections:: How to change commands' hierarchical level. @end menu -@node Tree Structuring, Structuring Command Types, Structuring, Structuring -@comment node-name, next, previous, up + +@node Tree Structuring @section Tree Structure of Sections @cindex Tree structuring @@ -3853,9 +3986,9 @@ The chapter structuring commands are described in the sections that follow; the @code{@@node} and @code{@@menu} commands are described in following chapters. (@xref{Nodes}, and see @ref{Menus}.)@refill -@node Structuring Command Types, makeinfo top, Tree Structuring, Structuring -@comment node-name, next, previous, up -@section Types of Structuring Commands + +@node Structuring Command Types +@section Structuring Command Types The chapter structuring commands fall into four groups or series, each of which contains structuring commands corresponding to the @@ -3900,119 +4033,43 @@ start new pages in the printed manual; the @code{@@heading} commands do not.@refill @end itemize -@need 1000 Here are the four groups of chapter structuring commands:@refill -@c Slightly different formatting for regular sized books and smallbooks. -@ifset smallbook -@sp 1 -@tex -{\let\rm=\indrm \let\tt=\indtt -\halign{\hskip\itemindent#\hfil& \hskip.5em#\hfil& \hskip.5em#\hfil& -\hskip.5em#\hfil\cr - -& & & \rm No new pages\cr -\rm Numbered& \rm Unnumbered& \rm Lettered and numbered& \rm Unnumbered\cr -\rm In contents& \rm In contents& \rm In contents& \rm Not in contents\cr - -& & & \cr - & \tt @@top& & \tt @@majorheading\cr -\tt @@chapter& \tt @@unnumbered& \tt @@appendix& \tt @@chapheading\cr -\tt @@section& \tt @@unnumberedsec& \tt @@appendixsec& \tt @@heading\cr -\tt @@subsection&\tt @@unnumberedsubsec&\tt @@appendixsubsec& -\tt @@subheading\cr -\tt @@subsubsection& \tt @@unnumberedsubsubsec& \tt @@appendixsubsubsec& -\tt @@subsubheading\cr}} -@end tex -@end ifset -@ifclear smallbook -@sp 1 -@tex -\vbox{ -\halign{\hskip\itemindent\hskip.5em#\hfil& \hskip.5em#\hfil& -\hskip.5em#\hfil& \hskip.5em #\hfil\cr - -& & & \cr -& & & \rm No new pages\cr -\rm Numbered& \rm Unnumbered& \rm Lettered and numbered& \rm Unnumbered\cr -\rm In contents& \rm In contents& \rm In contents& \rm Not in contents\cr - -& & & \cr - & \tt @@top& & \tt @@majorheading\cr -\tt @@chapter& \tt @@unnumbered& \tt @@appendix& \tt @@chapheading\cr -\tt @@section& \tt @@unnumberedsec& \tt @@appendixsec& \tt @@heading\cr -\tt @@subsection&\tt @@unnumberedsubsec&\tt @@appendixsubsec& -\tt @@subheading\cr -\tt @@subsubsection& \tt @@unnumberedsubsubsec& \tt @@appendixsubsubsec& -\tt @@subsubheading\cr}} -@end tex -@end ifclear -@ifinfo -@example -@group - @r{No new pages} -@r{Numbered} @r{Unnumbered} @r{Lettered and numbered} @r{Unnumbered} -@r{In contents} @r{In contents} @r{In contents} @r{Not in contents} - - @@top @@majorheading -@@chapter @@unnumbered @@appendix @@chapheading -@@section @@unnumberedsec @@appendixsec @@heading -@@subsection @@unnumberedsubsec @@appendixsubsec @@subheading -@@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading -@end group -@end example -@end ifinfo +@multitable @columnfractions .19 .30 .29 .22 + +@item @tab @tab @tab No new page +@item Numbered @tab Unnumbered @tab Lettered and numbered + @tab Unnumbered +@item In contents @tab In contents @tab In contents @tab Not in contents +@item @tab @code{@@top} @tab + @tab @code{@@majorheading} +@item @code{@@chapter} @tab @code{@@unnumbered} @tab @code{@@appendix} + @tab @code{@@chapheading} +@item @code{@@section} @tab @code{@@unnumberedsec} @tab @code{@@appendixsec} + @tab @code{@@heading} +@item @code{@@subsection} @tab @code{@@unnumberedsubsec} @tab @code{@@appendixsubsec} + @tab @code{@@subheading} +@item @code{@@subsubsection} @tab @code{@@unnumberedsubsubsec} @tab @code{@@appendixsubsubsec} + @tab @code{@@subsubheading} +@end multitable -@c Cannot line up columns properly inside of an example because of roman -@c proportional fonts. -@ignore -@ifset smallbook -@iftex -@smallexample -@group - @r{No new pages} -@r{Numbered} @r{Unnumbered} @r{Lettered and numbered} @r{Unnumbered} -@r{In contents} @r{In contents} @r{In contents} @r{Not in contents} - - @@top @@majorheading -@@chapter @@unnumbered @@appendix @@chapheading -@@section @@unnumberedsec @@appendixsec @@heading -@@subsection @@unnumberedsubsec @@appendixsubsec @@subheading -@@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading -@end group -@end smallexample -@end iftex -@end ifset -@ifclear smallbook -@iftex -@smallexample -@group - @r{No new pages} -@r{Numbered} @r{Unnumbered} @r{Lettered and numbered} @r{Unnumbered} -@r{In contents} @r{In contents} @r{In contents} @r{Not in contents} - - @@top @@majorheading -@@chapter @@unnumbered @@appendix @@chapheading -@@section @@unnumberedsec @@appendixsec @@heading -@@subsection @@unnumberedsubsec @@appendixsubsec @@subheading -@@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading -@end group -@end smallexample -@end iftex -@end ignore -@node makeinfo top, chapter, Structuring Command Types, Structuring -@comment node-name, next, previous, up +@node makeinfo top @section @code{@@top} The @code{@@top} command is a special sectioning command that you use only after an @samp{@@node Top} line at the beginning of a Texinfo file. -The @code{@@top} command tells the @code{makeinfo} formatter -which node is the `Top' -node. It has the same typesetting effect as @code{@@unnumbered} -(@pxref{unnumbered & appendix, , @code{@@unnumbered}, @code{@@appendix}}). -For detailed information, see -@ref{makeinfo top command, , The @code{@@top} Command}.@refill +The @code{@@top} command tells the @code{makeinfo} formatter which node +is the `Top' node, so it can use it as the root of the node tree if your +manual uses implicit pointers. It has the same typesetting effect as +@code{@@unnumbered} (@pxref{unnumbered & appendix, , @code{@@unnumbered} +and @code{@@appendix}}). For detailed information, see @ref{makeinfo +top command, , The @code{@@top} Command}. + +The @code{@@top} node and its menu (if any) is conventionally wrapped in +an @code{@@ifnottex} conditional so that it will appear only in Info and +HTML output, not @TeX{}. + @node chapter, unnumbered & appendix, makeinfo top, Structuring @comment node-name, next, previous, up @@ -4050,9 +4107,8 @@ This kind of stylistic choice is not usually offered by Texinfo. @c but the Hacker's Dictionary wanted it ... -@node unnumbered & appendix, majorheading & chapheading, chapter, Structuring -@comment node-name, next, previous, up -@section @code{@@unnumbered}, @code{@@appendix} +@node unnumbered & appendix +@section @code{@@unnumbered} and @code{@@appendix} @findex unnumbered @findex appendix @@ -4347,12 +4403,11 @@ An attempt to raise above `chapters' reproduces chapter commands; an attempt to lower below `subsubsections' reproduces subsubsection commands. -@node Nodes, Menus, Structuring, Top -@comment node-name, next, previous, up +@node Nodes @chapter Nodes @dfn{Nodes} are the primary segments of a Texinfo file. They do not -themselves impose a hierarchic or any other kind of structure on a file. +themselves impose a hierarchical or any other kind of structure on a file. Nodes contain @dfn{node pointers} that name other nodes, and can contain @dfn{menus} which are lists of nodes. In Info, the movement commands can carry you to a pointed-to node or to a node listed in a menu. Node @@ -4364,17 +4419,17 @@ books.@refill * Two Paths:: Different commands to structure Info output and printed output. * Node Menu Illustration:: A diagram, and sample nodes and menus. -* node:: How to write a node, in detail. -* makeinfo Pointer Creation:: How to create node pointers with @code{makeinfo}. +* node:: Creating nodes, in detail. +* makeinfo Pointer Creation:: Letting makeinfo determine node pointers. +* anchor:: Defining arbitrary cross-reference targets. @end menu -@node Two Paths, Node Menu Illustration, Nodes, Nodes -@ifinfo -@heading Two Paths -@end ifinfo + +@node Two Paths +@section Two Paths The node and menu commands and the chapter structuring commands are -independent of each other: +technically independent of each other: @itemize @bullet @item @@ -4391,26 +4446,26 @@ information for cross references; they do nothing else.@refill You can use node pointers and menus to structure an Info file any way you want; and you can write a Texinfo file so that its Info output has a -different structure than its printed output. However, most Texinfo -files are written such that the structure for the Info output -corresponds to the structure for the printed output. It is not -convenient to do otherwise.@refill +different structure than its printed output. However, virtually all +Texinfo files are written such that the structure for the Info output +corresponds to the structure for the printed output. It is neither +convenient nor understandable to the reader to do otherwise.@refill Generally, printed output is structured in a tree-like hierarchy in which the chapters are the major limbs from which the sections branch out. Similarly, node pointers and menus are organized to create a matching structure in the Info output.@refill -@node Node Menu Illustration, node, Two Paths, Nodes -@comment node-name, next, previous, up + +@node Node Menu Illustration @section Node and Menu Illustration Here is a copy of the diagram shown earlier that illustrates a Texinfo file with three chapters, each of which contains two sections.@refill -Note that the ``root'' is at the top of the diagram and the ``leaves'' -are at the bottom. This is how such a diagram is drawn conventionally; -it illustrates an upside-down tree. For this reason, the root node is +The ``root'' is at the top of the diagram and the ``leaves'' are at the +bottom. This is how such a diagram is drawn conventionally; it +illustrates an upside-down tree. For this reason, the root node is called the `Top' node, and `Up' node pointers carry you closer to the root.@refill @@ -4426,35 +4481,36 @@ root.@refill | | | | | | Section Section Section Section Section Section 1.1 1.2 2.1 2.2 3.1 3.2 - @end group @end example -Write the beginning of the node for Chapter 2 like this:@refill +The fully-written command to start Chapter 2 would be this: @example @group -@@node Chapter 2, Chapter 3, Chapter 1, top +@@node Chapter 2, Chapter 3, Chapter 1, Top @@comment node-name, next, previous, up @end group @end example @noindent -This @code{@@node} line says that the name of this node is ``Chapter 2'', the -name of the `Next' node is ``Chapter 3'', the name of the `Previous' -node is ``Chapter 1'', and the name of the `Up' node is ``Top''. +This @code{@@node} line says that the name of this node is ``Chapter +2'', the name of the `Next' node is ``Chapter 3'', the name of the +`Previous' node is ``Chapter 1'', and the name of the `Up' node is +``Top''. You can omit writing out these node names if your document is +hierarchically organized (@pxref{makeinfo Pointer Creation}), but the +pointer relationships still obtain. @quotation @strong{Please Note:} `Next' refers to the next node at the same hierarchical level in the manual, not necessarily to the next node within the Texinfo file. In the Texinfo file, the subsequent node may -be at a lower level---a section-level node may follow a chapter-level -node, and a subsection-level node may follow a section-level node. -`Next' and `Previous' refer to nodes at the @emph{same} hierarchical -level. (The `Top' node contains the exception to this rule. Since the -`Top' node is the only node at that level, `Next' refers to the first -following node, which is almost always a chapter or chapter-level -node.)@refill +be at a lower level---a section-level node most often follows a +chapter-level node, for example. `Next' and `Previous' refer to nodes +at the @emph{same} hierarchical level. (The `Top' node contains the +exception to this rule. Since the `Top' node is the only node at that +level, `Next' refers to the first following node, which is almost always +a chapter or chapter-level node.)@refill @end quotation To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter @@ -4507,11 +4563,13 @@ line, an @code{@@chapter} line, and then by indexing lines.@refill @end group @end example -@node node, makeinfo Pointer Creation, Node Menu Illustration, Nodes -@comment node-name, next, previous, up + +@node node @section The @code{@@node} Command @cindex Node, defined +@findex node + A @dfn{node} is a segment of text that begins at an @code{@@node} command and continues until the next @code{@@node} command. The definition of node is different from that for chapter or section. A @@ -4526,19 +4584,23 @@ several nodes, one for each section, subsection, and subsubsection.@refill To create a node, write an @code{@@node} command at the beginning of a -line, and follow it with four arguments, separated by commas, on the -rest of the same line. These arguments are the name of the node, and -the names of the `Next', `Previous', and `Up' pointers, in that order. -You may insert spaces before each pointer if you wish; the spaces are -ignored. You must write the name of the node, and the names of the -`Next', `Previous', and `Up' pointers, all on the same line. Otherwise, +line, and follow it with up to four arguments, separated by commas, on +the rest of the same line. The first argument is required; it is the +name of this node. The subsequent arguments are the names of the +`Next', `Previous', and `Up' pointers, in that order, and may be omitted +if your Texinfo document is hierarchically organized (@pxref{makeinfo +Pointer Creation}). + +You may insert spaces before each name if you wish; the spaces are +ignored. You must write the name of the node and the names of the +`Next', `Previous', and `Up' pointers all on the same line. Otherwise, the formatters fail. (@inforef{Top, info, info}, for more information -about nodes in Info.)@refill +about nodes in Info.) Usually, you write one of the chapter-structuring command lines immediately after an @code{@@node} line---for example, an @code{@@section} or @code{@@subsection} line. (@xref{Structuring -Command Types, , Types of Structuring Commands}.)@refill +Command Types}.) @quotation @strong{Please note:} The GNU Emacs Texinfo mode updating commands work @@ -4550,8 +4612,8 @@ structuring lines. @xref{Updating Requirements}.@refill references. For this reason, you must write @code{@@node} lines in a Texinfo file that you intend to format for printing, even if you do not intend to format it for Info. (Cross references, such as the one at the -end of this sentence, are made with @code{@@xref} and its related -commands; see @ref{Cross References}.)@refill +end of this sentence, are made with @code{@@xref} and related commands; +see @ref{Cross References}.)@refill @menu * Node Names:: How to choose node and pointer names. @@ -4563,11 +4625,11 @@ commands; see @ref{Cross References}.)@refill * Top Node Summary:: Write a brief description for readers. @end menu -@node Node Names, Writing a Node, node, node -@ifinfo -@subheading Choosing Node and Pointer Names -@end ifinfo +@node Node Names +@subsection Choosing Node and Pointer Names + +@cindex Node names, choosing The name of a node identifies the node. The pointers enable you to reach other nodes and consist of the names of those nodes.@refill @@ -4587,8 +4649,14 @@ Also, it is helpful to include a brief description of the manual in the `Top' node. @xref{First Node}, for information on how to write the first node of a Texinfo file.@refill -@node Writing a Node, Node Line Tips, Node Names, node -@comment node-name, next, previous, up +Even when you explicitly specify all pointers, that does not mean you +can write the nodes in the Texinfo source file in an arbitrary order! +Because @TeX{} processes the file sequentially, irrespective of node +pointers, you must write the nodes in the order you wish them to appear +in the printed output. + + +@node Writing a Node @subsection How to Write an @code{@@node} Line @cindex Writing an @code{@@node} line @cindex @code{@@node} line writing @@ -4616,8 +4684,8 @@ their proper order. The comment line helps you keep track of which arguments are for which pointers. This comment line is especially useful if you are not familiar with Texinfo.@refill -The template for a node line with `Next', `Previous', and `Up' pointers -looks like this:@refill +The template for a fully-written-out node line with `Next', `Previous', +and `Up' pointers looks like this:@refill @example @@node @var{node-name}, @var{next}, @var{previous}, @var{up} @@ -4625,22 +4693,21 @@ looks like this:@refill If you wish, you can ignore @code{@@node} lines altogether in your first draft and then use the @code{texinfo-insert-node-lines} command to -create @code{@@node} lines for you. However, we do not -recommend this practice. It is better to name the node itself -at the same time that you -write a segment so you can easily make cross references. A large number -of cross references are an especially important feature of a good Info -file.@refill +create @code{@@node} lines for you. However, we do not recommend this +practice. It is better to name the node itself at the same time that +you write a segment so you can easily make cross references. A large +number of cross references are an especially important feature of a good +Info file. After you have inserted an @code{@@node} line, you should immediately write an @@-command for the chapter or section and insert its name. Next (and this is important!), put in several index entries. Usually, you will find at least two and often as many as four or five ways of referring to the node in the index. Use them all. This will make it -much easier for people to find the node.@refill +much easier for people to find the node. -@node Node Line Tips, Node Line Requirements, Writing a Node, node -@comment node-name, next, previous, up + +@node Node Line Tips @subsection @code{@@node} Line Tips Here are three suggestions: @@ -4664,8 +4731,8 @@ section or chapter titles---initial and significant words are capitalized; others are not.@refill @end itemize + @node Node Line Requirements, First Node, Node Line Tips, node -@comment node-name, next, previous, up @subsection @code{@@node} Line Requirements @cindex Node line requirements @@ -4673,7 +4740,7 @@ Here are several requirements for @code{@@node} lines: @itemize @bullet @cindex Unique nodename requirement -@cindex Nodename must be unique +@cindex Node name must be unique @item All the node names for a single Info file must be unique.@refill @@ -4689,13 +4756,15 @@ different.@refill A pointer name must be the name of a node.@refill The node to which a pointer points may come before or after the -node containing the pointer.@refill +node containing the pointer. -@cindex @@-command in nodename -@cindex Nodename, cannot contain +@cindex @@-commands in nodename +@cindex Node name, should not contain @@-commands @item -You cannot use any of the Texinfo @@-commands in a node name; -@w{@@-commands} confuse Info.@refill +@w{@@-commands} used in node names generally confuse Info, so you should +avoid them. For a few rare cases when this is useful, Texinfo has +limited support for using @w{@@-commands} in node names; see +@ref{Pointer Validation}. @need 750 Thus, the beginning of the section called @code{@@chapter} looks like @@ -4710,11 +4779,15 @@ this:@refill @end group @end smallexample -@cindex Comma in nodename -@cindex Apostrophe in nodename @item -You cannot use commas or apostrophes within a node name; these -confuse @TeX{} or the Info formatters.@refill +@cindex Apostrophe in nodename +@cindex Colon in nodename +@cindex Comma in nodename +@cindex Period in nodename +@cindex Characters, invalid in node name +@cindex Invalid characters in node names +Unfortunately, you cannot use periods, commas, colons or apostrophes +within a node name; these confuse @TeX{} or the Info formatters.@refill @need 700 For example, the following is a section title: @@ -4833,69 +4906,100 @@ include an edition number for the manual. (The title page should also contain this information: see @ref{titlepage, , @code{@@titlepage}}.)@refill -@node makeinfo Pointer Creation, , node, Nodes +@node makeinfo Pointer Creation @section Creating Pointers with @code{makeinfo} @cindex Creating pointers with @code{makeinfo} @cindex Pointer creation with @code{makeinfo} @cindex Automatic pointer creation with @code{makeinfo} -The @code{makeinfo} program has a feature for automatically creating -node pointers for a hierarchically organized file that lacks -them.@refill +The @code{makeinfo} program has a feature for automatically defining +node pointers for a hierarchically organized file. When you take advantage of this feature, you do not need to write the `Next', `Previous', and `Up' pointers after the name of a node. However, you must write a sectioning command, such as @code{@@chapter} or @code{@@section}, on the line immediately following each truncated -@code{@@node} line. You cannot write a comment line after a node -line; the section line must follow it immediately.@refill +@code{@@node} line (except that comment lines may intervene). -In addition, you must follow the `Top' @code{@@node} line with a line beginning -with @code{@@top} to mark the `Top' node in the file. @xref{makeinfo -top, , @code{@@top}}. +In addition, you must follow the `Top' @code{@@node} line with a line +beginning with @code{@@top} to mark the `Top' node in the +file. @xref{makeinfo top, , @code{@@top}}. Finally, you must write the name of each node (except for the `Top' node) in a menu that is one or more hierarchical levels above the -node's hierarchical level.@refill +node's hierarchical level. + +This node pointer insertion feature in @code{makeinfo} relieves you from +the need to update menus and pointers manually or with Texinfo mode +commands. (@xref{Updating Nodes and Menus}.) + + +@node anchor +@section @code{@@anchor}: Defining Arbitrary Cross-reference Targets -This node pointer insertion feature in @code{makeinfo} is an -alternative to the menu and pointer creation and update commands in -Texinfo mode. (@xref{Updating Nodes and Menus}.) It is especially -helpful to people who do not use GNU Emacs for writing Texinfo -documents.@refill +@findex anchor +@cindex Anchors +@cindex Cross-reference targets, arbitrary +@cindex Targets for cross-references, arbitrary + +An @dfn{anchor} is a position in your document, labeled so that +cross-references can refer to it, just as they can to nodes. You create +an anchor with the @code{@@anchor} command, and give the label as a +normal brace-delimited argument. For example: + +@example +This marks the @@anchor@{x-spot@}spot. +@dots{} +@@xref@{x-spot,,the spot@}. +@end example -@node Menus, Cross References, Nodes, Top -@comment node-name, next, previous, up +@noindent produces: + +@example +This marks the spot. +@dots{} +See [the spot], page 1. +@end example + +As you can see, the @code{@@anchor} command itself produces no output. +This example defines an anchor `x-spot' just before the word `spot'. +You can refer to it later with an @code{@@xref} or other cross-reference +command, as shown. @xref{Cross References}, for details on the +cross-reference commands. + +It is best to put @code{@@anchor} commands just before the position you +wish to refer to; that way, the reader's eye is led on to the correct +text when they jump to the anchor. You can put the @code{@@anchor} +command on a line by itself if that helps readability of the source. +Spaces are always ignored after @code{@@anchor}. + +Anchor names and node names may not conflict. Anchors and nodes are +given similar treatment in some ways; for example, the @code{goto-node} +command in standalone Info takes either an anchor name or a node name as +an argument. (@xref{goto-node,,,info-stnd,GNU Info}.) + + +@node Menus @chapter Menus @cindex Menus @findex menu -@dfn{Menus} contain pointers to subordinate -nodes.@footnote{Menus can carry you to any node, regardless -of the hierarchical structure; even to nodes in a different -Info file. However, the GNU Emacs Texinfo mode updating -commands work only to create menus of subordinate nodes. -Conventionally, cross references are used to refer to other -nodes.} In Info, you use menus to go to such nodes. Menus -have no effect in printed manuals and do not appear in -them.@refill +@dfn{Menus} contain pointers to subordinate nodes.@footnote{Menus can +carry you to any node, regardless of the hierarchical structure; even to +nodes in a different Info file. However, the GNU Emacs Texinfo mode +updating commands work only to create menus of subordinate nodes. +Conventionally, cross references are used to refer to other nodes.} In +Info, you use menus to go to such nodes. Menus have no effect in +printed manuals and do not appear in them. By convention, a menu is put at the end of a node since a reader who -uses the menu may not see text that follows it.@refill - -@ifinfo -A node that has a menu should @emph{not} contain much text. If you -have a lot of text and a menu, move most of the text into a new -subnode---all but a few lines.@refill -@end ifinfo -@iftex -@emph{A node that has a menu should not contain much text.} If you -have a lot of text and a menu, move most of the text into a new -subnode---all but a few lines. Otherwise, a reader with a terminal -that displays only a few lines may miss the menu and its associated -text. As a practical matter, you should locate a menu within 20 lines -of the beginning of the node.@refill -@end iftex +uses the menu may not see text that follows it. Furthermore, a node +that has a menu should not contain much text. If you have a lot of text +and a menu, move most of the text into a new subnode---all but a few +lines. Otherwise, a reader with a terminal that displays only a few +lines may miss the menu and its associated text. As a practical matter, +you should locate a menu within 20 lines of the beginning of the +node. @menu * Menu Location:: Put a menu in a short node. @@ -4906,6 +5010,7 @@ of the beginning of the node.@refill * Other Info Files:: How to refer to a different Info file. @end menu + @node Menu Location, Writing a Menu, Menus, Menus @ifinfo @heading Menus Need Short Nodes @@ -4915,14 +5020,6 @@ of the beginning of the node.@refill @cindex Nodes for menus are short @cindex Short nodes for menus -@ifinfo -A reader can easily see a menu that is close to the beginning of the -node. The node should be short. As a practical matter, you should -locate a menu within 20 lines of the beginning of the node. -Otherwise, a reader with a terminal that displays only a few lines may -miss the menu and its associated text.@refill -@end ifinfo - The short text before a menu may look awkward in a printed manual. To avoid this, you can write a menu near the beginning of its node and follow the menu by an @code{@@node} line, and then an @code{@@heading} @@ -4954,7 +5051,8 @@ For example, the preceding two paragraphs follow an Info-only menu, The Texinfo file for this document contains more than a dozen examples of this procedure. One is at the beginning of this chapter; -another is at the beginning of the ``Cross References'' chapter.@refill +another is at the beginning of @ref{Cross References}. @refill + @node Writing a Menu, Menu Parts, Menu Location, Menus @section Writing a Menu @@ -4980,14 +5078,16 @@ Larger Units of Text @end group @end example -In a menu, every line that begins with an @w{@samp{* }} is a -@dfn{menu entry}. (Note the space after the asterisk.) A -line that does not start with an @w{@samp{* }} may also -appear in a menu. Such a line is not a menu entry but is a -menu comment line that appears in the Info file. In -the example above, the line @samp{Larger Units of Text} is a -menu comment line; the two lines starting with @w{@samp{* }} -are menu entries. +In a menu, every line that begins with an @w{@samp{* }} is a @dfn{menu +entry}. (Note the space after the asterisk.) A line that does not +start with an @w{@samp{* }} may also appear in a menu. Such a line is +not a menu entry but is a menu comment line that appears in the Info +file. In the example above, the line @samp{Larger Units of Text} is a +menu comment line; the two lines starting with @w{@samp{* }} are menu +@cindex Spaces, in menus +entries. Space characters in a menu are preserved as-is; this allows +you to format the menu as you wish. + @node Menu Parts, Less Cluttered Menu Entry, Writing a Menu, Menus @section The Parts of a Menu @@ -5196,20 +5296,20 @@ For example: not a Texinfo file, but a menu entry looks the same in both types of file.)@refill -Note that the GNU Emacs Texinfo mode menu updating commands only work -with nodes within the current buffer, so you cannot use them to create -menus that refer to other files. You must write such menus by hand.@refill +The GNU Emacs Texinfo mode menu updating commands only work with nodes +within the current buffer, so you cannot use them to create menus that +refer to other files. You must write such menus by hand. -@node Cross References, Marking Text, Menus, Top -@comment node-name, next, previous, up + +@node Cross References @chapter Cross References @cindex Making cross references @cindex Cross references @cindex References @dfn{Cross references} are used to refer the reader to other parts of the -same or different Texinfo files. In Texinfo, nodes are the -places to which cross references can refer.@refill +same or different Texinfo files. In Texinfo, nodes and anchors are the +places to which cross references can refer. @menu * References:: What cross references are for. @@ -5235,7 +5335,7 @@ it.@refill However, in any document, some information will be too detailed for the current context, or incidental to it; use cross references to -provide access to such information. Also, an on-line help system or a +provide access to such information. Also, an online help system or a reference manual is not like a novel; few read such documents in sequence from beginning to end. Instead, people look up what they need. For this reason, such creations should contain many cross @@ -5250,15 +5350,16 @@ In Info, a cross reference results in an entry that you can follow using the Info @samp{f} command. (@inforef{Help-Adv, Some advanced Info commands, info}.)@refill -The various cross reference commands use nodes to define cross -reference locations. This is evident in Info, in which a cross -reference takes you to the specified node. @TeX{} also uses nodes to -define cross reference locations, but the action is less obvious. When -@TeX{} generates a DVI file, it records nodes' page numbers and -uses the page numbers in making references. Thus, if you are writing -a manual that will only be printed, and will not be used on-line, you -must nonetheless write @code{@@node} lines to name the places to which -you make cross references.@refill +The various cross reference commands use nodes (or anchors, +@pxref{anchor,,@code{@@anchor}}) to define cross reference locations. +This is evident in Info, in which a cross reference takes you to the +specified location. @TeX{} also uses nodes to define cross reference +locations, but the action is less obvious. When @TeX{} generates a DVI +file, it records each node's page number and uses the page numbers in making +references. Thus, if you are writing a manual that will only be +printed, and will not be used online, you must nonetheless write +@code{@@node} lines to name the places to which you make cross +references.@refill @need 800 @node Cross Reference Commands, Cross Reference Parts, References, Cross References @@ -5359,7 +5460,7 @@ The five possible arguments for a cross reference are:@refill @enumerate @item -The node name (required). This is the node to which the +The node or anchor name (required). This is the location to which the cross reference takes you. In a printed document, the location of the node provides the page reference only for references within the same document.@refill @@ -5449,16 +5550,16 @@ or like this @noindent In @TeX{}, a cross reference looks like this: -@example +@quotation See Section @var{section-number} [@var{node-name}], page @var{page}. -@end example +@end quotation @noindent or like this -@example +@quotation See Section @var{section-number} [@var{title-or-topic}], page @var{page}. -@end example +@end quotation The @code{@@xref} command does not generate a period or comma to end the cross reference in either the Info file or the printed output. @@ -5536,6 +5637,9 @@ which produces *Note Tropical Storms::, for more info. @end example +@noindent +and + @quotation See Section 3.1 [Tropical Storms], page 24, for more info. @end quotation @@ -5583,7 +5687,7 @@ See Section 5.2 [Electrical Effects], page 57. @noindent (Note that in the preceding example the closing brace is followed by a -period; and that the node name is printed, not the cross reference name.)@refill +period; and that the node name is printed, not the cross reference name.) You can write a clause after the cross reference, like this:@refill @@ -5625,7 +5729,7 @@ within a title or other section will divide it into two arguments. In a reference, you need to write a title such as ``Clouds, Mist, and Fog'' without the commas.@refill -Also, remember to write a comma or period after the closing brace of a +Also, remember to write a comma or period after the closing brace of an @code{@@xref} to terminate the cross reference. In the following examples, a clause follows a terminating comma.@refill @@ -5875,6 +5979,7 @@ This makes it useful as the last part of a sentence.@refill @noindent For example, +@cindex Hurricanes @example For more information, see @@ref@{Hurricanes@}. @end example @@ -5883,7 +5988,7 @@ For more information, see @@ref@{Hurricanes@}. produces @example -For more information, see *Note Hurricanes. +For more information, see *Note Hurricanes::. @end example @noindent @@ -5902,6 +6007,7 @@ both the printed and the Info format.@refill @noindent For example, +@cindex Sea surges @example @group Sea surges are described in @@ref@{Hurricanes@}. @@ -5925,12 +6031,13 @@ Sea surges are described in *Note Hurricanes::. @end example @quotation -@strong{Caution:} You @emph{must} write a period or comma immediately -after an @code{@@ref} command with two or more arguments. Otherwise, -Info will not find the end of the cross reference entry and its -attempt to follow the cross reference will fail. As a general rule, -you should write a period or comma after every @code{@@ref} command. -This looks best in both the printed and the Info output.@refill +@strong{Caution:} You @emph{must} write a period, comma, or right +parenthesis immediately after an @code{@@ref} command with two or more +arguments. Otherwise, Info will not find the end of the cross reference +entry and its attempt to follow the cross reference will fail. As a +general rule, you should write a period or comma after every +@code{@@ref} command. This looks best in both the printed and the Info +output.@refill @end quotation @node pxref, inforef, ref, Cross References @@ -5975,6 +6082,7 @@ of the output and not the other.@refill With one argument, a parenthetical cross reference looks like this:@refill +@cindex Flooding @example @dots{} storms cause flooding (@@pxref@{Hurricanes@}) @dots{} @end example @@ -6130,64 +6238,113 @@ refer to printed works for which no Info form exists. @xref{cite, , @code{@@cite}}.@refill -@node uref, , inforef, Cross References -@section @code{@@uref@{@var{url}[, @var{displayed-text}]@}} +@node uref +@section @code{@@uref@{@var{url}[, @var{text}][, @var{replacement}]@}} @findex uref @cindex Uniform resource locator, referring to @cindex URL, referring to -@code{@@uref} produces a reference to a uniform resource locator (URL). -It takes one mandatory argument, the URL, and one optional argument, the -text to display (the default is the URL itself). In HTML output, -@code{@@uref} produces a link you can follow. For example: +@cindex @code{href}, producing HTML +@code{@@uref} produces a reference to a uniform resource locator (url). +It takes one mandatory argument, the url, and two optional arguments +which control the text that is displayed. In HTML output, @code{@@uref} +produces a link you can follow. + +The second argument, if specified, is the text to display (the default +is the url itself); in Info and DVI output, but not in HTML output, the +url is also output. + +@cindex Man page, reference to +The third argument, on the other hand, if specified is also the text to +display, but the url is @emph{not} output in any format. This is useful +when the text is already sufficiently referential, as in a man page. If +the third argument is given, the second argument is ignored. + +The simple one argument form, where the url is both the target and the +text of the link: @example -The official GNU ftp site is -@@uref@{ftp://ftp.gnu.ai.mit.edu/pub/gnu@} +The official GNU ftp site is @@uref@{ftp://ftp.gnu.org/gnu@}. @end example -@noindent produces (in text): +@noindent produces: @display -The official GNU ftp site is -@uref{ftp://ftp.gnu.ai.mit.edu/pub/gnu} +The official GNU ftp site is @uref{ftp://ftp.gnu.org/gnu}. @end display -@noindent whereas + +An example of the two-argument form: @example -The official -@@uref@{ftp://ftp.gnu.ai.mit.edu/pub/gnu, - GNU ftp site@} holds programs and texts. +The official @@uref@{ftp://ftp.gnu.org/gnu, GNU ftp site@} holds +programs and texts. @end example -@noindent produces (in text): +@noindent produces: @display -The official @uref{ftp://ftp.gnu.ai.mit.edu/pub/gnu, GNU ftp site} holds +The official @uref{ftp://ftp.gnu.org/gnu, GNU ftp site} holds programs and texts. @end display -@noindent and (in HTML): +@noindent that is, the Info output is this: @example -The official <A HREF="ftp://ftp.gnu.ai.mit.edu/pub/gnu">GNU ftp -site</A> holds programs and texts. +The official GNU ftp site (ftp://ftp.gnu.org/gnu) holds +programs and texts. @end example -To merely indicate a URL, use @code{@@url} (@pxref{url, @code{@@url}}). +@noindent and the HTML output is this: +@example +The official <a href="ftp://ftp.gnu.org/gnu">GNU ftp site</a> holds +programs and texts. +@end example -@node Marking Text, Quotations and Examples, Cross References, Top -@comment node-name, next, previous, up +An example of the three-argument form: +@example +The @@uref@{http://example.org/man.cgi/1/ls,,ls(1)@} program @dots{} +@end example + +@noindent produces: +@display +The @uref{http://example.org/man.cgi/1/ls,,ls(1)} program @dots{} +@end display + +@noindent but with HTML: +@example +The <a href="http://example.org/man.cgi/1/ls">ls(1)</a> program @dots{} +@end example + +To merely indicate a url without creating a link people can follow, use +@code{@@url} (@pxref{url, @code{@@url}}). + + +Some people prefer to display url's in the unambiguous format: + +@display +<URL:http://@var{host}/@var{path}> +@end display + +@noindent +@cindex <URL: convention, not used +You can use this form in the input file if you wish. We feel it's not +necessary to clutter up the output with the extra @samp{<URL:} and +@samp{>}, since any software that tries to detect url's in text already +has to detect them without the @samp{<URL:} to be useful. + + +@node Marking Text @chapter Marking Words and Phrases @cindex Paragraph, marking text within @cindex Marking words and phrases @cindex Words and phrases, marking them @cindex Marking text within a paragraph +@cindex Text, marking up In Texinfo, you can mark words and phrases in a variety of ways. The Texinfo formatters use this information to determine how to highlight the text. You can specify, for example, whether a word or phrase is a defining occurrence, a metasyntactic variable, or a symbol used in a -program. Also, you can emphasize text.@refill +program. Also, you can emphasize text, in several different ways. @menu * Indicating:: How to indicate definitions, files, etc. @@ -6212,7 +6369,7 @@ For example, in a printed manual, code is usually illustrated in a typewriter font; @code{@@code} tells @TeX{} to typeset this text in this font. But it would be easy to change the way @TeX{} highlights code to use another -font, and this change would not effect how keystroke examples are +font, and this change would not affect how keystroke examples are highlighted. If straight typesetting commands were used in the body of the file and you wanted to make a change, you would need to check every single occurrence to make sure that you were changing code and @@ -6220,24 +6377,29 @@ not something else that should not be changed.@refill @menu * Useful Highlighting:: Highlighting provides useful information. -* code:: How to indicate code. -* kbd:: How to show keyboard input. -* key:: How to specify keys. -* samp:: How to show a literal sequence of characters. -* var:: How to indicate a metasyntactic variable. -* file:: How to indicate the name of a file. -* dfn:: How to specify a definition. -* cite:: How to refer to a book that is not in Info. -* url:: How to indicate a world wide web reference. -* email:: How to indicate an electronic mail address. +* code:: Indicating program code. +* kbd:: Showing keyboard input. +* key:: Specifying keys. +* samp:: Showing a literal sequence of characters. +* var:: Indicating metasyntactic variables. +* env:: Indicating environment variables. +* file:: Indicating file names. +* command:: Indicating command names. +* option:: Indicating option names. +* dfn:: Specifying definitions. +* cite:: Referring to books not in the Info system. +* acronym:: Indicating acronyms. +* url:: Indicating a World Wide Web reference. +* email:: Indicating an electronic mail address. @end menu + @node Useful Highlighting, code, Indicating, Indicating @ifinfo @subheading Highlighting Commands are Useful @end ifinfo -The highlighting commands can be used to generate useful information +The highlighting commands can be used to extract useful information from the file, such as lists of functions or file names. It is possible, for example, to write a program in Emacs Lisp (or a keyboard macro) to insert an index entry after every paragraph that contains @@ -6263,14 +6425,17 @@ Indicate text that is a literal example of a sequence of characters.@refill @item @@var@{@var{metasyntactic-variable}@} Indicate a metasyntactic variable.@refill -@item @@url@{@var{uniform-resource-locator}@} -Indicate a uniform resource locator for the World Wide Web. +@item @@env@{@var{environment-variable}@} +Indicate an environment variable.@refill @item @@file@{@var{file-name}@} Indicate the name of a file.@refill -@item @@email@{@var{email-address}[, @var{displayed-text}]@} -Indicate an electronic mail address. +@item @@command@{@var{command-name}@} +Indicate the name of a command.@refill + +@item @@option@{@var{option}@} +Indicate a command-line option.@refill @item @@dfn@{@var{term}@} Indicate the introductory or defining use of a term.@refill @@ -6278,43 +6443,44 @@ Indicate the introductory or defining use of a term.@refill @item @@cite@{@var{reference}@} Indicate the name of a book.@refill +@item @@acronym@{@var{acronym}@} +Indicate an acronym.@refill + +@item @@url@{@var{uniform-resource-locator}@} +Indicate a uniform resource locator for the World Wide Web. + +@item @@email@{@var{email-address}[, @var{displayed-text}]@} +Indicate an electronic mail address. + @ignore @item @@ctrl@{@var{ctrl-char}@} Use for an @sc{ascii} control character.@refill @end ignore @end table -@node code, kbd, Useful Highlighting, Indicating -@comment node-name, next, previous, up + +@node code @subsection @code{@@code}@{@var{sample-code}@} @findex code +@cindex Syntactic tokens, indicating Use the @code{@@code} command to indicate text that is a piece of a program and which consists of entire syntactic tokens. Enclose the -text in braces.@refill +text in braces. +@cindex Expressions in a program, indicating +@cindex Keywords, indicating +@cindex Reserved words, indicating Thus, you should use @code{@@code} for an expression in a program, for the name of a variable or function used in a program, or for a -keyword. Also, you should use @code{@@code} for the name of a -program, such as @code{diff}, that is a name used in the machine. (You -should write the name of a program in the ordinary text font if you -regard it as a new English word, such as `Emacs' or `Bison'.)@refill - -Use @code{@@code} for environment variables such as @code{TEXINPUTS}, -and other variables.@refill - -Use @code{@@code} for command names in command languages that -resemble programming languages, such as Texinfo or the shell. -For example, @code{@@code} and @code{@@samp} are produced by writing -@samp{@@code@{@@@@code@}} and @samp{@@code@{@@@@samp@}} in the Texinfo -source, respectively.@refill - -Note, however, that you should not use @code{@@code} for shell options -such as @samp{-c} when such options stand alone. (Use @code{@@samp}.) -Also, an entire shell command often looks better if written using -@code{@@samp} rather than @code{@@code}. In this case, the rule is to -choose the more pleasing format.@refill +keyword in a programming language. +Use @code{@@code} for command names in languages that resemble +programming languages, such as Texinfo. For example, @code{@@code} and +@code{@@samp} are produced by writing @samp{@@code@{@@@@code@}} and +@samp{@@code@{@@@@samp@}} in the Texinfo source, respectively. + +@cindex Case, not altering in @code{@@code} It is incorrect to alter the case of a word inside an @code{@@code} command when it appears at the beginning of a sentence. Most computer languages are case sensitive. In C, for example, @code{Printf} is @@ -6322,24 +6488,8 @@ different from the identifier @code{printf}, and most likely is a misspelling of it. Even in languages which are not case sensitive, it is confusing to a human reader to see identifiers spelled in different ways. Pick one spelling and always use that. If you do not want to -start a sentence with a command written all in lower case, you should -rearrange the sentence.@refill - -Do not use the @code{@@code} command for a string of characters shorter -than a syntactic token. If you are writing about @samp{TEXINPU}, which -is just a part of the name for the @code{TEXINPUTS} environment -variable, you should use @code{@@samp}.@refill - -In particular, you should not use the @code{@@code} command when writing -about the characters used in a token; do not, for example, use -@code{@@code} when you are explaining what letters or printable symbols -can be used in the names of functions. (Use @code{@@samp}.) Also, you -should not use @code{@@code} to mark text that is considered input to -programs unless the input is written in a language that is like a -programming language. For example, you should not use @code{@@code} for -the keystroke commands of GNU Emacs (use @code{@@kbd} instead) although -you may use @code{@@code} for the names of the Emacs Lisp functions that -the keystroke commands invoke.@refill +start a sentence with a command name written all in lower case, you +should rearrange the sentence. In the printed manual, @code{@@code} causes @TeX{} to typeset the argument in a typewriter face. In the Info file, it causes the Info @@ -6349,30 +6499,73 @@ formatting commands to use single quotation marks around the text. For example, @example -Use @@code@{diff@} to compare two files. +The function returns @@code@{nil@}. @end example @noindent -produces this in the printed manual:@refill +produces this in the printed manual: @quotation -Use @code{diff} to compare two files. +The function returns @code{nil}. @end quotation -@iftex +@iftex @noindent -and this in the Info file:@refill - +and this in the Info file: @example -Use `diff' to compare two files. +The function returns `nil'. @end example @end iftex +Here are some cases for which it is preferable not to use @code{@@code}: + +@itemize @bullet +@item +For shell command names such as @command{ls} (use @code{@@command}). + +@item +For shell options such as @samp{-c} when such options stand alone (use +@code{@@option}). + +@item +Also, an entire shell command often looks better if written using +@code{@@samp} rather than @code{@@code}. In this case, the rule is to +choose the more pleasing format. + +@item +For environment variable such as @env{TEXINPUTS} (use @code{@@env}). + +@item +For a string of characters shorter than a syntactic token. For example, +if you are writing about @samp{goto-ch}, which is just a part of the +name for the @code{goto-char} Emacs Lisp function, you should use +@code{@@samp}. + +@item +In general, when writing about the characters used in a token; for +example, do not use @code{@@code} when you are explaining what letters +or printable symbols can be used in the names of functions. (Use +@code{@@samp}.) Also, you should not use @code{@@code} to mark text +that is considered input to programs unless the input is written in a +language that is like a programming language. For example, you should +not use @code{@@code} for the keystroke commands of GNU Emacs (use +@code{@@kbd} instead) although you may use @code{@@code} for the names +of the Emacs Lisp functions that the keystroke commands invoke. + +@end itemize + +Since @code{@@command}, @code{@@option}, and @code{@@env} were +introduced relatively recently, it is acceptable to use @code{@@code} or +@code{@@samp} for command names, options, and environment variables. +The new commands allow you to express the markup more precisely, but +there is no real harm in using the older commands, and of course the +long-standing manuals do so. + -@node kbd, key, code, Indicating +@node kbd @subsection @code{@@kbd}@{@var{keyboard-characters}@} @findex kbd -@cindex keyboard input +@cindex Keyboard input Use the @code{@@kbd} command for characters of input to be typed by users. For example, to refer to the characters @kbd{M-a}, @@ -6411,7 +6604,7 @@ Always use the same font for @code{@@kbd} as @code{@@code}. @item example Use the distinguishing font for @code{@@kbd} only in @code{@@example} and similar environments. -@item example +@item distinct (the default) Always use the distinguishing font for @code{@@kbd}. @end table @@ -6545,9 +6738,7 @@ To match @samp{foo} at the end of the line, use the regexp Any time you are referring to single characters, you should use @code{@@samp} unless @code{@@kbd} or @code{@@key} is more appropriate. -Use @code{@@samp} for the names of command-line options (except in an -@code{@@table}, where @code{@@code} seems to read more easily). Also, -you may use @code{@@samp} for entire statements in C and for entire +Also, you may use @code{@@samp} for entire statements in C and for entire shell commands---in this case, @code{@@samp} often looks better than @code{@@code}. Basically, @code{@@samp} is a catchall for whatever is not covered by @code{@@code}, @code{@@kbd}, or @code{@@key}.@refill @@ -6575,8 +6766,8 @@ In English, the vowels are @samp{a}, @samp{e}, @samp{y}. @end quotation -@node var, file, samp, Indicating -@comment node-name, next, previous, up + +@node var @subsection @code{@@var}@{@var{metasyntactic-variable}@} @findex var @@ -6588,26 +6779,30 @@ to that function.@refill Do not use @code{@@var} for the names of particular variables in programming languages. These are specific names from a program, so -@code{@@code} is correct for them. For example, the Emacs Lisp variable -@code{texinfo-tex-command} is not a metasyntactic variable; it is -properly formatted using @code{@@code}.@refill +@code{@@code} is correct for them (@pxref{code}). For example, the +Emacs Lisp variable @code{texinfo-tex-command} is not a metasyntactic +variable; it is properly formatted using @code{@@code}. -The effect of @code{@@var} in the Info file is to change the case of -the argument to all upper case; in the printed manual, to italicize it. +Do not use @code{@@var} for environment variables either; @code{@@env} +is correct for them (see the next section). + +The effect of @code{@@var} in the Info file is to change the case of the +argument to all upper case. In the printed manual and HTML output, the +argument is printed in slanted type. @need 700 For example, @example To delete file @@var@{filename@}, -type @@code@{rm @@var@{filename@}@}. +type @@samp@{rm @@var@{filename@}@}. @end example @noindent produces @quotation -To delete file @var{filename}, type @code{rm @var{filename}}. +To delete file @var{filename}, type @samp{rm @var{filename}}. @end quotation @noindent @@ -6647,11 +6842,32 @@ angle brackets, for example:@refill @noindent However, that is not the style that Texinfo uses. (You can, of -course, modify the sources to @TeX{} and the Info formatting commands +course, modify the sources to @file{texinfo.tex} and the Info formatting commands to output the @code{<@dots{}>} format if you wish.)@refill -@node file, dfn, var, Indicating -@comment node-name, next, previous, up + +@node env +@subsection @code{@@env}@{@var{environment-variable}@} +@findex env + +Use the @code{@@env} command to indicate environment variables, as used +by many operating systems, including GNU. Do not use it for +metasyntactic variables; use @code{@@var} instead (see the previous +section). + +@code{@@env} is equivalent to @code{@@code} in its effects. +For example: + +@example +The @@env@{PATH@} environment variable sets the search path for commands. +@end example +@noindent produces +@quotation +The @env{PATH} environment variable sets the search path for commands. +@end quotation + + +@node file @subsection @code{@@file}@{@var{file-name}@} @findex file @@ -6676,7 +6892,58 @@ The @file{.el} files are in the @file{/usr/local/emacs/lisp} directory. @end quotation -@node dfn, cite, file, Indicating + +@node command +@subsection @code{@@command}@{@var{command-name}@} +@findex command +@cindex Command names, indicating +@cindex Program names, indicating + +Use the @code{@@command} command to indicate command names, such as +@command{ls} or @command{cc}. + +@code{@@command} is equivalent to @code{@@code} in its effects. +For example: + +@example +The command @@command@{ls@} lists directory contents. +@end example +@noindent produces +@quotation +The command @command{ls} lists directory contents. +@end quotation + +You should write the name of a program in the ordinary text font, rather +than using @code{@@command}, if you regard it as a new English word, +such as `Emacs' or `Bison'. + +When writing an entire shell command invocation, as in @samp{ls -l}, +you should use either @code{@@samp} or @code{@@code} at your discretion. + + +@node option +@subsection @code{@@option}@{@var{option-name}@} +@findex option + +Use the @code{@@option} command to indicate a command-line option; for +example, @option{-l} or @option{--version} or +@option{--output=@var{filename}}. + +@code{@@option} is equivalent to @code{@@samp} in its effects. +For example: + +@example +The option @@option@{-l@} produces a long listing. +@end example +@noindent produces +@quotation +The option @option{-l} produces a long listing. +@end quotation + +In tables, putting options inside @code{@@code} produces a +more pleasing effect. + +@node dfn @comment node-name, next, previous, up @subsection @code{@@dfn}@{@var{term}@} @findex dfn @@ -6705,18 +6972,18 @@ term should be a definition of the term. The sentence does not need to say explicitly that it is a definition, but it should contain the information of a definition---it should make the meaning clear. -@node cite, url, dfn, Indicating -@comment node-name, next, previous, up +@node cite @subsection @code{@@cite}@{@var{reference}@} @findex cite Use the @code{@@cite} command for the name of a book that lacks a -companion Info file. The command produces italics in the printed -manual, and quotation marks in the Info file.@refill +companion Info file. The command produces italics in the printed +manual, and quotation marks in the Info file. -(If a book is written in Texinfo, it is better to use a cross reference +If a book is written in Texinfo, it is better to use a cross reference command since a reader can easily follow such a reference in Info. -@xref{xref, , @code{@@xref}}.)@refill +@xref{xref, , @code{@@xref}}. + @ignore @c node ctrl, , cite, Indicating @@ -6768,27 +7035,50 @@ identify that control character: an uparrow followed by the character @end ignore -@node url, email, cite, Indicating +@node acronym +@subsection @code{@@acronym}@{@var{acronym}@} +@findex acronym + +@cindex NASA, as acronym +@cindex F.B.I., as acronym +@cindex Abbreviations, tagging +@cindex Acronyms, tagging +Use the @code{@@acronym} command for abbreviations written in all +capital letters, such as `@acronym{NASA}'. The abbreviation is given as +the single argument in braces, as in @samp{@@acronym@{NASA@}}. As +a matter of style, or for particular abbreviations, you may prefer to +use periods, as in @samp{@@acronym@{F.B.I.@}}. + +In @TeX{} and HTML, the argument is printed in a slightly smaller font +size. In Info or plain text output, this command changes nothing. + + +@node url @subsection @code{@@url}@{@var{uniform-resource-locator}@} @findex url @cindex Uniform resource locator, indicating @cindex URL, indicating -Use the @code{@@url} to indicate a uniform resource locator on the World -Wide Web. This is analogous to @code{@@file}, @code{@@var}, etc., and -is purely for markup purposes. It does not produce a link you can -follow in HTML output (the @code{@@uref} command does, @pxref{uref,, -@code{@@uref}}). It is useful for example URL's which do not actually -exist. For example: +Use the @code{@@url} command to indicate a uniform resource locator on +the World Wide Web. This is analogous to @code{@@file}, @code{@@var}, +etc., and is purely for markup purposes. It does not produce a link you +can follow in HTML output (use the @code{@@uref} command for that, +@pxref{uref,, @code{@@uref}}). It is useful for url's which do +not actually exist. For example: @c Two lines because one is too long for smallbook format. @example -For example, the url might be -@@url@{http://host.domain.org/path@}. +For example, the url might be @@url@{http://example.org/path@}. @end example +@noindent which produces: -@node email, , url, Indicating +@display +For example, the url might be @url{http://example.org/path}. +@end display + + +@node email @subsection @code{@@email}@{@var{email-address}[, @var{displayed-text}]@} @findex email @@ -6807,10 +7097,10 @@ Send bug reports to @@email@{bug-texinfo@@@@gnu.org@}. Send suggestions to the @@email@{bug-texinfo@@@@gnu.org, same place@}. @end example @noindent produces -@example +@display Send bug reports to @email{bug-texinfo@@gnu.org}. Send suggestions to the @email{bug-texinfo@@gnu.org, same place}. -@end example +@end display @node Emphasis, , Indicating, Marking Text @@ -6824,27 +7114,24 @@ Most often, this is the best way to mark words. However, sometimes you will want to emphasize text without indicating a category. Texinfo has two commands to do this. Also, Texinfo has several commands that specify the font in which @TeX{} will typeset -text. These commands have no affect on Info and only one of them, +text. These commands have no effect on Info and only one of them, the @code{@@r} command, has any regular use.@refill @menu * emph & strong:: How to emphasize text in Texinfo. * Smallcaps:: How to use the small caps font. * Fonts:: Various font commands for printed output. -* Customized Highlighting:: How to define highlighting commands. @end menu -@node emph & strong, Smallcaps, Emphasis, Emphasis -@comment node-name, next, previous, up +@node emph & strong @subsection @code{@@emph}@{@var{text}@} and @code{@@strong}@{@var{text}@} @cindex Emphasizing text, font for @findex emph @findex strong The @code{@@emph} and @code{@@strong} commands are for emphasis; -@code{@@strong} is stronger. In printed output, @code{@@emph} -produces @emph{italics} and @code{@@strong} produces -@strong{bold}.@refill +@code{@@strong} is stronger. In printed output, @code{@@emph} produces +@emph{italics} and @code{@@strong} produces @strong{bold}. @need 800 For example, @@ -6863,7 +7150,7 @@ files in the directory. produces the following in printed output: @quotation -@strong{Caution}: @code{rm * .[^.]*} removes @emph{all} +@strong{Caution}: @samp{rm * .[^.]*} removes @emph{all} files in the directory. @end quotation @@ -6876,7 +7163,7 @@ produces: @end ifinfo @example - *Caution*: `rm * .[^.]*' removes *all* + *Caution*: `rm * .[^.]*' removes _all_ files in the directory. @end example @@ -6884,31 +7171,25 @@ The @code{@@strong} command is seldom used except to mark what is, in effect, a typographical element, such as the word `Caution' in the preceding example. -In the Info file, both @code{@@emph} and @code{@@strong} put asterisks -around the text.@refill +In the Info output, @code{@@emph} surrounds the text with underscores +(@samp{_}), and @code{@@strong} puts asterisks around the text. @quotation -@strong{Caution:} Do not use @code{@@emph} or @code{@@strong} with the -word @samp{Note}; Info will mistake the combination for a cross -reference. Use a phrase such as @strong{Please note} or -@strong{Caution} instead.@refill +@strong{Caution:} Do not use @code{@@strong} with the word @samp{Note}; +Info will mistake the combination for a cross reference. Use a phrase +such as @strong{Please note} or @strong{Caution} instead. @end quotation -@node Smallcaps, Fonts, emph & strong, Emphasis + +@node Smallcaps @subsection @code{@@sc}@{@var{text}@}: The Small Caps Font @cindex Small caps font @findex sc @r{(small caps font)} -@iftex -Use the @samp{@@sc} command to set text in the printed output in @sc{a -small caps font} and set text in the Info file in upper case letters.@refill -@end iftex -@ifinfo -Use the @samp{@@sc} command to set text in the printed output in a -small caps font and set text in the Info file in upper case letters.@refill -@end ifinfo - -Write the text between braces in lower case, like this:@refill +Use the @samp{@@sc} command to set text in the printed and the HTML +output in @sc{a small caps font} and set text in the Info file in upper +case letters. Write the text you want to be in small caps (where +possible) between braces in lower case, like this: @example The @@sc@{acm@} and @@sc@{ieee@} are technical societies. @@ -6923,32 +7204,28 @@ The @sc{acm} and @sc{ieee} are technical societies. @TeX{} typesets the small caps font in a manner that prevents the letters from `jumping out at you on the page'. This makes small caps -text easier to read than text in all upper case. The Info formatting -commands set all small caps text in upper case.@refill +text easier to read than text in all upper case---but it's usually +better to use regular mixed case anyway. The Info formatting commands +set all small caps text in upper case. In HTML, the text is upper-cased +and a smaller font is used to render it. -@ifinfo -If the text between the braces of an @code{@@sc} command is upper case, -@TeX{} typesets in full-size capitals. Use full-size capitals -sparingly.@refill -@end ifinfo -@iftex -If the text between the braces of an @code{@@sc} command is upper case, -@TeX{} typesets in @sc{FULL-SIZE CAPITALS}. Use full-size capitals -sparingly.@refill -@end iftex +If the text between the braces of an @code{@@sc} command is uppercase, +@TeX{} typesets in FULL-SIZE CAPITALS. Use full-size capitals +sparingly, if ever, and since it's redundant to mark all-uppercase text +with @code{@@sc}, @command{makeinfo} warns about such usage. You may also use the small caps font for a jargon word such as -@sc{ato} (a @sc{nasa} word meaning `abort to orbit').@refill +@sc{ato} (a @sc{nasa} word meaning `abort to orbit'). There are subtleties to using the small caps font with a jargon word such as @sc{cdr}, a word used in Lisp programming. In this case, you should use the small caps font when the word refers to the second and subsequent elements of a list (the @sc{cdr} of the list), but you should use @samp{@@code} when the word refers to the Lisp function of -the same spelling.@refill +the same spelling. -@node Fonts, Customized Highlighting, Smallcaps, Emphasis -@comment node-name, next, previous, up + +@node Fonts @subsection Fonts for Printing, Not Info @cindex Fonts for printing, not for Info @findex i @r{(italic font)} @@ -6992,124 +7269,7 @@ If possible, you should avoid using the other three font commands. If you need to use one, it probably indicates a gap in the Texinfo language.@refill -@node Customized Highlighting, , Fonts, Emphasis -@comment node-name, next, previous, up -@subsection Customized Highlighting -@cindex Highlighting, customized -@cindex Customized highlighting - -@c I think this whole section is obsolete with the advent of macros -@c --karl, 15sep96. -You can use regular @TeX{} commands inside of @code{@@iftex} @dots{} -@code{@@end iftex} to create your own customized highlighting commands -for Texinfo. The easiest way to do this is to equate your customized -commands with pre-existing commands, such as those for italics. Such -new commands work only with @TeX{}.@refill - -@findex definfoenclose -@cindex Enclosure command for Info -You can use the @code{@@definfoenclose} command inside of -@code{@@ifinfo} @dots{} @code{@@end ifinfo} to define commands for Info -with the same names as new commands for @TeX{}. -@code{@@definfoenclose} creates new commands for Info that mark text by -enclosing it in strings that precede and follow the text. -@footnote{Currently, @code{@@definfoenclose} works only with -@code{texinfo-format-buffer} and @code{texinfo-format-region}, not with -@code{makeinfo}.}@refill - -Here is how to create a new @@-command called @code{@@phoo} that causes -@TeX{} to typeset its argument in italics and causes Info to display the -argument between @samp{//} and @samp{\\}.@refill - -@need 1300 -For @TeX{}, write the following to equate the @code{@@phoo} command with -the existing @code{@@i} italics command:@refill - -@example -@group -@@iftex -@@global@@let@@phoo=@@i -@@end iftex -@end group -@end example - -@noindent -This defines @code{@@phoo} as a command that causes @TeX{} to typeset -the argument to @code{@@phoo} in italics. @code{@@global@@let} tells -@TeX{} to equate the next argument with the argument that follows the -equals sign. - -@need 1300 -For Info, write the following to tell the Info formatters to enclose the -argument between @samp{//} and @samp{\\}: - -@example -@group -@@ifinfo -@@definfoenclose phoo, //, \\ -@@end ifinfo -@end group -@end example - -@noindent -Write the @code{@@definfoenclose} command on a line and follow it with -three arguments separated by commas (commas are used as separators in an -@code{@@node} line in the same way).@refill - -@itemize @bullet -@item -The first argument to @code{@@definfoenclose} is the @@-command name -@strong{without} the @samp{@@}; - -@item -the second argument is the Info start delimiter string; and, - -@item -the third argument is the Info end delimiter string. -@end itemize - -@noindent -The latter two arguments enclose the highlighted text in the Info file. -A delimiter string may contain spaces. Neither the start nor end -delimiter is required. However, if you do not provide a start -delimiter, you must follow the command name with two commas in a row; -otherwise, the Info formatting commands will misinterpret the end -delimiter string as a start delimiter string.@refill - -After you have defined @code{@@phoo} both for @TeX{} and for Info, you -can then write @code{@@phoo@{bar@}} to see @samp{//bar\\} -in Info and see -@ifinfo -@samp{bar} in italics in printed output. -@end ifinfo -@iftex -@i{bar} in italics in printed output. -@end iftex - -Note that each definition applies to its own formatter: one for @TeX{}, -the other for Info. - -@need 1200 -Here is another example: - -@example -@group -@@ifinfo -@@definfoenclose headword, , : -@@end ifinfo -@@iftex -@@global@@let@@headword=@@b -@@end iftex -@end group -@end example - -@noindent -This defines @code{@@headword} as an Info formatting command that -inserts nothing before and a colon after the argument and as a @TeX{} -formatting command to typeset its argument in bold. - -@node Quotations and Examples, Lists and Tables, Marking Text, Top -@comment node-name, next, previous, up +@node Quotations and Examples @chapter Quotations and Examples Quotations and examples are blocks of text consisting of one or more @@ -7131,8 +7291,8 @@ line.@refill * quotation:: How to write a quotation. * example:: How to write an example in a fixed-width font. * noindent:: How to prevent paragraph indentation. -* Lisp Example:: How to illustrate Lisp code. -* smallexample & smalllisp:: Forms for the @code{@@smallbook} option. +* lisp:: How to illustrate Lisp code. +* small:: Forms for @code{@@smallbook}. * display:: How to write an example in the current font. * format:: How to write an example that does not narrow the margins. @@ -7141,10 +7301,11 @@ line.@refill * cartouche:: How to draw cartouches around examples. @end menu -@node Block Enclosing Commands, quotation, Quotations and Examples, Quotations and Examples -@section The Block Enclosing Commands +@node Block Enclosing Commands +@section Block Enclosing Commands -Here are commands for quotations and examples:@refill +Here are commands for quotations and examples, explained further in the +following sections: @table @code @item @@quotation @@ -7155,28 +7316,31 @@ printed in a roman font by default.@refill Illustrate code, commands, and the like. The text is printed in a fixed-width font, and indented but not filled.@refill -@item @@lisp -Illustrate Lisp code. The text is printed in a fixed-width font, -and indented but not filled.@refill - @item @@smallexample -Illustrate code, commands, and the like. Similar to -@code{@@example}, except that in @TeX{} this command typesets text in -a smaller font for the smaller @code{@@smallbook} format than for the -8.5 by 11 inch format.@refill +Same as @code{@@example}, except that in @TeX{} this command typesets +text in a smaller font for the @code{@@smallbook} format than for the +default 8.5 by 11 inch format. + +@item @@lisp +Like @code{@@example}, but specifically for illustrating Lisp code. The +text is printed in a fixed-width font, and indented but not filled. @item @@smalllisp -Illustrate Lisp code. Similar to @code{@@lisp}, except that -in @TeX{} this command typesets text in a smaller font for the smaller -@code{@@smallbook} format than for the 8.5 by 11 inch format.@refill +Is to @code{@@lisp} as @code{@@smallexample} is to @code{@@example}. @item @@display Display illustrative text. The text is indented but not filled, and -no font is specified (so, by default, the font is roman).@refill +no font is selected (so, by default, the font is roman).@refill + +@item @@smalldisplay +Is to @code{@@display} as @code{@@smallexample} is to @code{@@example}. @item @@format -Print illustrative text. The text is not indented and not filled -and no font is specified (so, by default, the font is roman).@refill +Like @code{@@display} (the text is not filled and no font is selected), +but the text is not indented. + +@item @@smallformat +Is to @code{@@format} as @code{@@smallexample} is to @code{@@example}. @end table The @code{@@exdent} command is used within the above constructs to @@ -7191,18 +7355,16 @@ paragraph.@refill You can use the @code{@@cartouche} command within one of the above constructs to highlight the example or quotation by drawing a box with -rounded corners around it. (The @code{@@cartouche} command affects -only the printed manual; it has no effect in the Info file; see -@ref{cartouche, , Drawing Cartouches Around Examples}.)@refill +rounded corners around it. @xref{cartouche, , Drawing Cartouches Around +Examples}. -@node quotation, example, Block Enclosing Commands, Quotations and Examples -@comment node-name, next, previous, up + +@node quotation @section @code{@@quotation} @cindex Quotations @findex quotation -The text of a quotation is -processed normally except that:@refill +The text of a quotation is processed normally except that: @itemize @bullet @item @@ -7244,8 +7406,8 @@ produces This is a foo. @end quotation -@node example, noindent, quotation, Quotations and Examples -@comment node-name, next, previous, up + +@node example @section @code{@@example} @cindex Examples, formatting them @cindex Formatting examples @@ -7271,10 +7433,9 @@ obtained by indenting each line with five spaces. @end example Write an @code{@@example} command at the beginning of a line by itself. -This line will disappear from the output. Mark the end of the example +Mark the end of the example with an @code{@@end example} command, also written at the beginning of a -line by itself. The @code{@@end example} will disappear from the -output.@refill +line by itself.@refill @need 700 For example, @@ -7292,12 +7453,14 @@ produces mv foo bar @end example -Since the lines containing @code{@@example} and @code{@@end example} -will disappear, you should put a blank line before the -@code{@@example} and another blank line after the @code{@@end -example}. (Remember that blank lines between the beginning +The lines containing @code{@@example} and @code{@@end example} +will disappear from the output. +To make the output look good, +you should put a blank line before the +@code{@@example} and another blank line after the @code{@@end example}. +Note that blank lines inside the beginning @code{@@example} and the ending @code{@@end example} will appear in -the output.)@refill +the output.@refill @quotation @strong{Caution:} Do not use tabs in the lines of an example (or anywhere @@ -7308,7 +7471,7 @@ convert tabs in a region to multiple spaces.)@refill @end quotation Examples are often, logically speaking, ``in the middle'' of a -paragraph, and the text continues after an example should not be +paragraph, and the text that continues after an example should not be indented. The @code{@@noindent} command prevents a piece of text from being indented as if it were a new paragraph. @ifinfo @@ -7319,8 +7482,8 @@ being indented as if it were a new paragraph. embedded within sentences, not set off from preceding and following text. @xref{code, , @code{@@code}}.) -@node noindent, Lisp Example, example, Quotations and Examples -@comment node-name, next, previous, up + +@node noindent @section @code{@@noindent} @findex noindent @@ -7377,11 +7540,11 @@ Do not put braces after an @code{@@noindent} command; they are not necessary, since @code{@@noindent} is a command used outside of paragraphs (@pxref{Command Syntax}).@refill -@node Lisp Example, smallexample & smalllisp, noindent, Quotations and Examples -@comment node-name, next, previous, up + +@node lisp @section @code{@@lisp} -@cindex Lisp example @findex lisp +@cindex Lisp example The @code{@@lisp} command is used for Lisp code. It is synonymous with the @code{@@example} command. @@ -7396,44 +7559,43 @@ regarding the nature of the example. This is useful, for example, if you write a function that evaluates only and all the Lisp code in a Texinfo file. Then you can use the Texinfo file as a Lisp library.@footnote{It would be straightforward to extend Texinfo to work -in a similar fashion for C, Fortran, or other languages.}@refill +in a similar fashion for C, Fortran, or other languages.} Mark the end of @code{@@lisp} with @code{@@end lisp} on a line by itself.@refill -@node smallexample & smalllisp, display, Lisp Example, Quotations and Examples -@comment node-name, next, previous, up -@section @code{@@smallexample} and @code{@@smalllisp} + +@node small +@section @code{@@small@dots{}} Block Commands @cindex Small book example @cindex Example for a small book @cindex Lisp example for a small book +@findex smalldisplay @findex smallexample +@findex smallformat @findex smalllisp In addition to the regular @code{@@example} and @code{@@lisp} commands, -Texinfo has two other ``example-style'' commands. These are the -@code{@@smallexample} and @code{@@smalllisp} commands. Both these -commands are designed for use with the @code{@@smallbook} command that -causes @TeX{} to produce a printed manual in a 7 by 9.25 inch format -rather than the regular 8.5 by 11 inch format.@refill - -In @TeX{}, the @code{@@smallexample} and @code{@@smalllisp} commands -typeset text in a smaller font for the smaller @code{@@smallbook} -format than for the 8.5 by 11 inch format. Consequently, many examples -containing long lines fit in a narrower, @code{@@smallbook} page -without needing to be shortened. Both commands typeset in the normal -font size when you format for the 8.5 by 11 inch size; indeed, -in this situation, the @code{@@smallexample} and @code{@@smalllisp} -commands are defined to be the @code{@@example} and @code{@@lisp} -commands.@refill - -In Info, the @code{@@smallexample} and @code{@@smalllisp} commands are -equivalent to the @code{@@example} and @code{@@lisp} commands, and work -exactly the same.@refill - -Mark the end of @code{@@smallexample} or @code{@@smalllisp} with -@code{@@end smallexample} or @code{@@end smalllisp}, -respectively.@refill +Texinfo has ``small'' example-style commands. These are +@code{@@smalldisplay}, @code{@@smallexample}, @code{@@smallformat}, and +@code{@@smalllisp}. All of these commands are designed for use with the +@code{@@smallbook} command (which causes @TeX{} to format a printed book for +a 7 by 9.25 inch trim size rather than the default 8.5 by 11 inch size). + +In @TeX{}, the @code{@@small@dots{}} commands typeset text in a smaller +font for the smaller @code{@@smallbook} format than for the 8.5 by 11 +inch format. Consequently, many examples containing long lines fit in a +narrower, @code{@@smallbook} page without needing to be shortened. Both +commands typeset in the normal font size when you format for the 8.5 by +11 inch size. Indeed, in this situation, the @code{@@small@dots{}} +commands are equivalent to their non-small versions. + +In Info, the @code{@@small@dots{}} commands are also equivalent to their +non-small companion commands. + +Mark the end of an @code{@@small@dots{}} block with a corresponding +@code{@@end small@dots{}}. For example, pair @code{@@smallexample} with +@code{@@end smallexample}. @iftex Here is an example written in the small font used by the @@ -7444,7 +7606,7 @@ Here is an example written in the small font used by the @tex % Remove extra vskip; this is a kludge to counter the effect of display \vskip-3\baselineskip -{\ninett +{\smalltt \dots{} to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source @@ -7474,21 +7636,21 @@ this text appears in a smaller font. @end smallexample @end ifinfo -The @code{@@smallexample} and @code{@@smalllisp} commands make it -easier to prepare smaller format manuals without forcing you to edit -examples by hand to fit them onto narrower pages.@refill +The @code{@@small@dots{}} commands make it easier to prepare smaller +format manuals without forcing you to edit examples by hand to fit them +onto narrower pages.@refill -As a general rule, a printed document looks better if you write all the -examples in a chapter consistently in @code{@@example} or in -@code{@@smallexample}. Only occasionally should you mix the two -formats.@refill +As a general rule, a printed document looks better if you use only one +of (for example) @code{@@example} or in @code{@@smallexample} +consistently within a chapter. Only occasionally should you mix the two +formats. @xref{smallbook, , Printing ``Small'' Books}, for more information about the @code{@@smallbook} command.@refill -@node display, format, smallexample & smalllisp, Quotations and Examples -@comment node-name, next, previous, up -@section @code{@@display} + +@node display +@section @code{@@display} and @code{@@smalldisplay} @cindex Display formatting @findex display @@ -7506,9 +7668,14 @@ and an @code{@@end display} command. The @code{@@display} command indents the text, but does not fill it. @end display -@node format, exdent, display, Quotations and Examples -@comment node-name, next, previous, up -@section @code{@@format} +@findex smalldisplay +Texinfo also provides a command @code{@@smalldisplay}, which is like +@code{@@display} but uses a smaller font in @code{@@smallbook} format. +@xref{small}. + + +@node format +@section @code{@@format} and @code{@@smallformat} @findex format The @code{@@format} command is similar to @code{@@example} except @@ -7522,7 +7689,14 @@ from this example, the @code{@@format} command does not fill the text. @end format -@node exdent, flushleft & flushright, format, Quotations and Examples +@findex smallformat +Texinfo also provides a command @code{@@smallformat}, which is like +@code{@@format} but uses a smaller font in @code{@@smallbook} format. +@xref{small}. + + + +@node exdent @section @code{@@exdent}: Undoing a Line's Indentation @cindex Indentation undoing @findex exdent @@ -7632,8 +7806,8 @@ further highlight an example or quotation. For instance, you could write a manual in which one type of example is surrounded by a cartouche for emphasis.@refill -The @code{@@cartouche} command affects only the printed manual; it has -no effect in the Info file.@refill +@code{@@cartouche} affects only the printed manual; it has no effect in +other output files. @need 1500 For example, @@ -7685,8 +7859,8 @@ the first column; multi-column tables are also supported. * Multi-column Tables:: How to construct generalized tables. @end menu -@ifinfo @node Introducing Lists, itemize, Lists and Tables, Lists and Tables +@ifinfo @heading Introducing Lists @end ifinfo @@ -7755,12 +7929,12 @@ Enumerated lists, using numbers or letters. @item @@table @itemx @@ftable @itemx @@vtable -Two-column tables with indexing. +Two-column tables, optionally with indexing. @end table -@node itemize, enumerate, Introducing Lists, Lists and Tables -@comment node-name, next, previous, up -@section Making an Itemized List + +@node itemize +@section @code{@@itemize}: Making an Itemized List @cindex Itemization @findex itemize @@ -7768,23 +7942,26 @@ The @code{@@itemize} command produces sequences of indented paragraphs, with a bullet or other mark inside the left margin at the beginning of each paragraph for which such a mark is desired.@refill +@cindex @code{@@w}, for blank items Begin an itemized list by writing @code{@@itemize} at the beginning of a line. Follow the command, on the same line, with a character or a Texinfo command that generates a mark. Usually, you will write @code{@@bullet} after @code{@@itemize}, but you can use -@code{@@minus}, or any character or any special symbol that results in -a single character in the Info file. (When you write @code{@@bullet} -or @code{@@minus} after an @code{@@itemize} command, you may omit the -@samp{@{@}}.)@refill +@code{@@minus}, or any command or character that results in a single +character in the Info file. If you don't want any mark at all, use +@code{@@w}. (When you write the mark command such as +@code{@@bullet} after an @code{@@itemize} command, you may omit the +@samp{@{@}}.) If you don't specify a mark command, the default is +@code{@@bullet}. Write the text of the indented paragraphs themselves after the @code{@@itemize}, up to another line that says @code{@@end itemize}.@refill -Before each paragraph for which a mark in the margin is desired, write -a line that says just @code{@@item}. Do not write any other text on this -line.@refill @findex item +Before each paragraph for which a mark in the margin is desired, write a +line that says just @code{@@item}. It is ok to have text following the +@code{@@item}. Usually, you should put a blank line before an @code{@@item}. This puts a blank line in the Info file. (@TeX{} inserts the proper @@ -7792,8 +7969,8 @@ interline whitespace in either case.) Except when the entries are very brief, these blank lines make the list look better.@refill Here is an example of the use of @code{@@itemize}, followed by the -output it produces. Note that @code{@@bullet} produces an @samp{*} in -Info and a round dot in @TeX{}.@refill +output it produces. @code{@@bullet} produces an @samp{*} in Info and a +round dot in @TeX{}. @example @group @@ -7866,9 +8043,9 @@ Second outer item. @end itemize @end quotation -@node enumerate, Two-column Tables, itemize, Lists and Tables -@comment node-name, next, previous, up -@section Making a Numbered or Lettered List + +@node enumerate +@section @code{@@enumerate}: Making a Numbered or Lettered List @cindex Enumeration @findex enumerate @@ -7882,18 +8059,18 @@ letter as an option. Without an argument, @code{@@enumerate} starts the list with the number @samp{1}. With a numeric argument, such as @samp{3}, the command starts the list with that number. With an upper or lower case letter, such as @samp{a} or @samp{A}, the command starts -the list with that letter.@refill +the list with that letter. Write the text of the enumerated list in the same way you write an itemized list: put @code{@@item} on a line of its own before the start of each paragraph that you want enumerated. Do not write any other text -on the line beginning with @code{@@item}.@refill +on the line beginning with @code{@@item}. You should put a blank line between entries in the list. -This generally makes it easier to read the Info file.@refill +This generally makes it easier to read the Info file. @need 1500 -Here is an example of @code{@@enumerate} without an argument:@refill +Here is an example of @code{@@enumerate} without an argument: @example @group @@ -8000,8 +8177,8 @@ exhibits, and command-line option summaries. * itemx:: How to put more entries in the first column. @end menu -@ifinfo @node table, ftable vtable, Two-column Tables, Two-column Tables +@ifinfo @subheading Using the @code{@@table} Command Use the @code{@@table} command to produce two-column tables.@refill @@ -8030,6 +8207,7 @@ commands output the first column entries without added highlighting listed here. However, you can only use commands that normally take arguments in braces.)@refill +@findex item Begin each table entry with an @code{@@item} command at the beginning of a line. Write the first column text on the same line as the @code{@@item} command. Write the second column text on the line @@ -8037,8 +8215,7 @@ following the @code{@@item} line and on subsequent lines. (You do not need to type anything for an empty second column entry.) You may write as many lines of supporting text as you wish, even several paragraphs. But only text on the same line as the @code{@@item} will -be placed in the first column.@refill -@findex item +be placed in the first column, including any footnote. Normally, you should put a blank line before an @code{@@item} line. This puts a blank like in the Info file. Except when the entries are @@ -8076,8 +8253,8 @@ If you want to list two or more named items with a single block of text, use the @code{@@itemx} command. (@xref{itemx, , @code{@@itemx}}.)@refill -@node ftable vtable, itemx, table, Two-column Tables -@comment node-name, next, previous, up + +@node ftable vtable @subsection @code{@@ftable} and @code{@@vtable} @cindex Tables with indexes @cindex Indexing table entries automatically @@ -8091,8 +8268,8 @@ functions and @code{@@vtable} automatically enters each of the items in the first column of the table into the index of variables. This simplifies the task of creating indices. Only the items on the same line as the @code{@@item} commands are indexed, and they are indexed in -exactly the form that they appear on that line. @xref{Indices, , -Creating Indices}, for more information about indices.@refill +exactly the form that they appear on that line. @xref{Indices}, +for more information about indices.@refill Begin a two-column table using @code{@@ftable} or @code{@@vtable} by writing the @@-command at the beginning of a line, followed on the same @@ -8103,8 +8280,7 @@ itself. See the example for @code{@@table} in the previous section. -@node itemx, , ftable vtable, Two-column Tables -@comment node-name, next, previous, up +@node itemx @subsection @code{@@itemx} @cindex Two named items for @code{@@table} @findex itemx @@ -8116,7 +8292,6 @@ line of its own. Use @code{@@itemx} for all but the first entry; @code{@@itemx} command works exactly like @code{@@item} except that it does not generate extra vertical space above the first column text. -@need 1000 For example, @example @@ -8165,7 +8340,7 @@ multitable} completes the table. Details in the sections below. * Multitable Rows:: Defining multitable rows, with examples. @end menu -@node Multitable Column Widths, Multitable Rows, Multi-column Tables, Multi-column Tables +@node Multitable Column Widths @subsection Multitable Column Widths @cindex Multitable column widths @cindex Column widths, defining for multitables @@ -8190,7 +8365,7 @@ To specify column widths as fractions of the line length, write @noindent The fractions need not add up exactly to 1.0, as these do not. This allows you to produce tables that do not need the full line -length. +length. You can use a leading zero if you wish. @item @cindex Prototype row, column widths defined by @@ -8220,7 +8395,7 @@ particularly likely to be useful. @cindex Rows, of a multitable @findex item -@cindex tab +@findex tab After the @code{@@multitable} command defining the column widths (see the previous section), you begin each row in the body of a multitable with @code{@@item}, and separate the column entries with @code{@@tab}. @@ -8270,9 +8445,8 @@ split that window. @node Indices, Insertions, Lists and Tables, Top @comment node-name, next, previous, up -@chapter Creating Indices +@chapter Indices @cindex Indices -@cindex Creating indices Using Texinfo, you can generate indices without having to sort and collate entries manually. In an index, the entries are listed in @@ -8408,17 +8582,6 @@ command; that would be a spelling error. Whichever case convention you use, please use it consistently! -@ignore -Concept index entries consist of English text. The usual convention -is to capitalize the first word of each such index entry, unless that -word is the name of a function, variable, or other such entity that -should not be capitalized. However, if your concept index entries are -consistently short (one or two words each) it may look better for each -regular entry to start with a lower case letter, aside from proper -names and acronyms that always call for upper case letters. Whichever -convention you adapt, please be consistent! -@end ignore - Entries in indices other than the concept index are symbol names in programming languages, or program names; these names are usually case-sensitive, so use upper and lower case as required for them. @@ -8463,24 +8626,11 @@ Make an entry in the data type index for @var{data type}.@refill @quotation @strong{Caution:} Do not use a colon in an index entry. In Info, a -colon separates the menu entry name from the node name. An extra -colon confuses Info. -@xref{Menu Parts, , The Parts of a Menu}, -for more information about the structure of a menu entry.@refill +colon separates the menu entry name from the node name, so a colon in +the entry itself confuses Info. @xref{Menu Parts, , The Parts of a +Menu}, for more information about the structure of a menu entry. @end quotation -If you write several identical index entries in different places in a -Texinfo file, the index in the printed manual will list all the pages to -which those entries refer. However, the index in the Info file will -list @strong{only} the node that references the @strong{first} of those -index entries. Therefore, it is best to write indices in which each -entry refers to only one place in the Texinfo file. Fortunately, this -constraint is a feature rather than a loss since it means that the index -will be easy to use. Otherwise, you could create an index that lists -several pages for one entry and your reader would not know to which page -to turn. If you have two identical entries for one topic, change the -topics slightly, or qualify them to indicate the difference.@refill - You are not actually required to use the predefined indices for their canonical purposes. For example, suppose you wish to index some C preprocessor macros. You could put them in the function index along @@ -8672,8 +8822,7 @@ You should define new indices within or right after the end-of-header line of a Texinfo file, before any @code{@@synindex} or @code{@@syncodeindex} commands (@pxref{Header}).@refill -@node Insertions, Breaks, Indices, Top -@comment node-name, next, previous, up +@node Insertions @chapter Special Insertions @cindex Inserting special characters and symbols @cindex Special insertions @@ -8686,12 +8835,17 @@ elements that do not correspond to simple characters you can type. These are: @itemize @bullet -@item Braces, @samp{@@} and periods. +@item Braces and @samp{@@}. @item Whitespace within and around a sentence. @item Accents. @item Dots and bullets. @item The @TeX{} logo and the copyright symbol. +@item The pounds currency symbol. +@item The minus sign. @item Mathematical expressions. +@item Glyphs for evaluation, macros, errors, etc. +@item Footnotes. +@item Images. @end itemize @end iftex @@ -8708,6 +8862,7 @@ These are: * math:: How to format a mathematical expression. * Glyphs:: How to indicate results of evaluation, expansion of macros, errors, etc. +* Footnotes:: How to include footnotes. * Images:: How to include graphics. @end menu @@ -8741,7 +8896,8 @@ output. Do not put braces after an @code{@@@@} command. -@node Inserting Braces, , Inserting An Atsign, Braces Atsigns + +@node Inserting Braces @subsection Inserting @samp{@{} and @samp{@}}with @@@{ and @@@} @findex @{ @r{(single @samp{@{})} @findex @} @r{(single @samp{@}})} @@ -8756,12 +8912,11 @@ Do not put braces after either an @code{@@@{} or an @code{@@@}} command. -@node Inserting Space, Inserting Accents, Braces Atsigns, Insertions +@node Inserting Space @section Inserting Space @cindex Inserting space @cindex Spacing, inserting -@cindex Whitespace, inserting The following sections describe commands that control spacing of various kinds within and after sentences. @@ -8772,7 +8927,8 @@ kinds within and after sentences. * dmn:: How to format a dimension. @end menu -@node Not Ending a Sentence, Ending a Sentence, Inserting Space, Inserting Space + +@node Not Ending a Sentence @subsection Not Ending a Sentence @cindex Not ending a sentence @@ -8780,13 +8936,13 @@ kinds within and after sentences. @cindex Periods, inserting Depending on whether a period or exclamation point or question mark is inside or at the end of a sentence, less or more space is inserted after -a period in a typeset manual. Since it is not always possible for -Texinfo to determine when a period ends a sentence and when it is used +a period in a typeset manual. Since it is not always possible +to determine when a period ends a sentence and when it is used in an abbreviation, special commands are needed in some circumstances. -(Usually, Texinfo can guess how to handle periods, so you do not need to +Usually, Texinfo can guess how to handle periods, so you do not need to use the special commands; you just enter a period as you would if you were using a typewriter, which means you put two spaces after the -period, question mark, or exclamation mark that ends a sentence.) +period, question mark, or exclamation mark that ends a sentence. @findex : @r{(suppress widening)} Use the @code{@@:}@: command after a period, question mark, @@ -8794,7 +8950,6 @@ exclamation mark, or colon that should not be followed by extra space. For example, use @code{@@:}@: after periods that end abbreviations which are not at the ends of sentences. -@need 700 For example, @example @@ -8865,8 +9020,7 @@ In the Info file output, @code{@@.}@: is equivalent to a simple The meanings of @code{@@:} and @code{@@.}@: in Texinfo are designed to work well with the Emacs sentence motion commands (@pxref{Sentences,,, -emacs, The GNU Emacs Manual}). This made it necessary for them to be -incompatible with some other formatting systems that use @@-commands. +emacs, The GNU Emacs Manual}). Do not put braces after any of these commands. @@ -8876,6 +9030,7 @@ Do not put braces after any of these commands. @cindex Multiple spaces @cindex Whitespace, inserting +@cindex Space, inserting horizontal @findex (space) @findex (tab) @findex (newline) @@ -8916,7 +9071,7 @@ Other possible uses of @code{@@@kbd{SPACE}} have been subsumed by Do not follow any of these commands with braces. -@node dmn, , Multiple Spaces, Inserting Space +@node dmn @subsection @code{@@dmn}@{@var{dimension}@}: Format a Dimension @cindex Thin space between number, dimension @cindex Dimension formatting @@ -8928,7 +9083,7 @@ At times, you may want to write @samp{12@dmn{pt}} or abbreviation for the dimension. You can use the @code{@@dmn} command to do this. On seeing the command, @TeX{} inserts just enough space for proper typesetting; the Info formatting commands insert no space -at all, since the Info file does not require it.@refill +at all, since the Info file does not require it. To use the @code{@@dmn} command, write the number and then follow it immediately, with no intervening space, by @code{@@dmn}, and then by @@ -8951,10 +9106,10 @@ In these cases, however, the formatters may insert a line break between the number and the dimension, so use @code{@@w} (@pxref{w}). Also, if you write a period after an abbreviation within a sentence, you should write @samp{@@:} after the period to prevent @TeX{} from inserting extra -whitespace, as shown here. @xref{Inserting Space}. +whitespace, as shown here. @xref{Not Ending a Sentence}. -@node Inserting Accents, Dots Bullets, Inserting Space, Insertions +@node Inserting Accents @section Inserting Accents @cindex Inserting accents @@ -8985,7 +9140,7 @@ possible, since accented characters are very common in some languages. @findex dotaccent @cindex Dot accent @findex H -@cindex Hungariam umlaut accent +@cindex Hungarian umlaut accent @findex ringaccent @cindex Ring accent @findex tieaccent @@ -9053,22 +9208,22 @@ commonly used in languages other than English. @cindex Es-zet @cindex Sharp S @cindex German S -@multitable {@@questiondown@{@}} {oe,OE} {es-zet or sharp S} +@multitable {x@@questiondown@{@} } {oe,OE} {es-zet or sharp S} @item @t{@@exclamdown@{@}} @tab @exclamdown{} @tab upside-down ! @item @t{@@questiondown@{@}} @tab @questiondown{} @tab upside-down ? -@item @t{@@aa@{@},@@AA@{@}} @tab @aa{},@AA{} @tab A,a with circle +@item @t{@@aa@{@},@@AA@{@}} @tab @aa{},@AA{} @tab a,A with circle @item @t{@@ae@{@},@@AE@{@}} @tab @ae{},@AE{} @tab ae,AE ligatures @item @t{@@dotless@{i@}} @tab @dotless{i} @tab dotless i @item @t{@@dotless@{j@}} @tab @dotless{j} @tab dotless j @item @t{@@l@{@},@@L@{@}} @tab @l{},@L{} @tab suppressed-L,l @item @t{@@o@{@},@@O@{@}} @tab @o{},@O{} @tab O,o with slash -@item @t{@@oe@{@},@@OE@{@}} @tab @oe{},@OE{} @tab OE,oe ligatures +@item @t{@@oe@{@},@@OE@{@}} @tab @oe{},@OE{} @tab oe,OE ligatures @item @t{@@ss@{@}} @tab @ss{} @tab es-zet or sharp S @end multitable -@node Dots Bullets, TeX and copyright, Inserting Accents, Insertions -@section Inserting Ellipsis, Dots, and Bullets +@node Dots Bullets +@section Inserting Ellipsis and Bullets @cindex Dots, inserting @cindex Bullets, inserting @cindex Ellipsis, inserting @@ -9092,9 +9247,10 @@ the braces, the formatters would be confused. @xref{Command Syntax, , @end menu -@node dots, bullet, Dots Bullets, Dots Bullets -@subsection @code{@@dots}@{@} (@dots{}) +@node dots +@subsection @code{@@dots}@{@} (@dots{}) and @code{@@enddots}@{@} (@enddots{}) @findex dots +@findex enddots @cindex Inserting dots @cindex Dots, inserting @@ -9116,7 +9272,7 @@ the dots in the ellipsis. @end iftex -@node bullet, , dots, Dots Bullets +@node bullet @subsection @code{@@bullet}@{@} (@bullet{}) @findex bullet @@ -9145,7 +9301,7 @@ braces.@refill @end menu -@node tex, copyright symbol, TeX and copyright, TeX and copyright +@node tex @subsection @code{@@TeX}@{@} (@TeX{}) @findex tex (command) @@ -9153,10 +9309,10 @@ Use the @code{@@TeX@{@}} command to generate `@TeX{}'. In a printed manual, this is a special logo that is different from three ordinary letters. In Info, it just looks like @samp{TeX}. The @code{@@TeX@{@}} command is unique among Texinfo commands in that the -@kbd{T} and the @kbd{X} are in upper case.@refill +@samp{T} and the @samp{X} are in upper case.@refill -@node copyright symbol, , tex, TeX and copyright +@node copyright symbol @subsection @code{@@copyright}@{@} (@copyright{}) @findex copyright @@ -9246,7 +9402,7 @@ remember to write the mathematical expression between one or two @samp{$} (dollar-signs) as appropriate. -@node Glyphs, Images, math, Insertions +@node Glyphs @section Glyphs for Examples @cindex Glyphs @@ -9303,12 +9459,12 @@ message.@refill @menu -* result:: -* expansion:: -* Print Glyph:: -* Error Glyph:: -* Equivalence:: -* Point Glyph:: +* result:: +* expansion:: +* Print Glyph:: +* Error Glyph:: +* Equivalence:: +* Point Glyph:: @end menu @node result, expansion, Glyphs Summary, Glyphs @@ -9317,6 +9473,7 @@ message.@refill @cindex Indicating evaluation @cindex Evaluation glyph @cindex Value of an expression, indicating +@findex result Use the @code{@@result@{@}} command to indicate the result of evaluating an expression.@refill @@ -9344,6 +9501,7 @@ may be read as ``@code{(cdr '(1 2 3))} evaluates to @code{(2 3)}''. @node expansion, Print Glyph, result, Glyphs @subsection @code{@@expansion@{@}} (@expansion{}): Indicating an Expansion @cindex Expansion, indicating it +@findex expansion When an expression is a macro call, it expands into a new expression. You can indicate the result of the expansion with the @@ -9399,6 +9557,7 @@ five spaces.@refill @node Print Glyph, Error Glyph, expansion, Glyphs @subsection @code{@@print@{@}} (@print{}): Indicating Printed Output @cindex Printed output, indicating it +@findex print Sometimes an expression will print output during its execution. You can indicate the printed output with the @code{@@print@{@}} command.@refill @@ -9444,6 +9603,7 @@ In a Texinfo source file, this example is written as follows: @node Error Glyph, Equivalence, Print Glyph, Glyphs @subsection @code{@@error@{@}} (@error{}): Indicating an Error Message @cindex Error message, indicating it +@findex error A piece of code may cause an error when you evaluate it. You can designate the error message with the @code{@@error@{@}} command.@refill @@ -9489,6 +9649,7 @@ Wrong type argument: integer-or-marker-p, x @node Equivalence, Point Glyph, Error Glyph, Glyphs @subsection @code{@@equiv@{@}} (@equiv{}): Indicating Equivalence @cindex Equivalence, indicating it +@findex equiv Sometimes two expressions produce identical results. You can indicate the exact equivalence of two forms with the @code{@@equiv@{@}} command.@refill @@ -9522,9 +9683,10 @@ This indicates that evaluating @code{(make-sparse-keymap)} produces identical results to evaluating @code{(list 'keymap)}. -@node Point Glyph, , Equivalence, Glyphs +@node Point Glyph @subsection @code{@@point@{@}} (@point{}): Indicating Point in a Buffer -@cindex Point, indicating it in a buffer +@cindex Point, indicating in a buffer +@findex point Sometimes you need to show an example of text in an Emacs buffer. In such examples, the convention is to include the entire contents of the @@ -9585,17 +9747,207 @@ This is the changed @@point@{@}contents of foo. @end example +@node Footnotes +@section Footnotes +@cindex Footnotes +@findex footnote + +A @dfn{footnote} is for a reference that documents or elucidates the +primary text.@footnote{A footnote should complement or expand upon +the primary text, but a reader should not need to read a footnote to +understand the primary text. For a thorough discussion of footnotes, +see @cite{The Chicago Manual of Style}, which is published by the +University of Chicago Press.}@refill + +@menu +* Footnote Commands:: How to write a footnote in Texinfo. +* Footnote Styles:: Controlling how footnotes appear in Info. +@end menu + +@node Footnote Commands +@subsection Footnote Commands + +In Texinfo, footnotes are created with the @code{@@footnote} command. +This command is followed immediately by a left brace, then by the text +of the footnote, and then by a terminating right brace. Footnotes may +be of any length (they will be broken across pages if necessary), but +are usually short. The template is: + +@example +ordinary text@@footnote@{@var{text of footnote}@} +@end example + +As shown here, the @code{@@footnote} command should come right after the +text being footnoted, with no intervening space; otherwise, the footnote +marker might end up starting a line. + +For example, this clause is followed by a sample footnote@footnote{Here +is the sample footnote.}; in the Texinfo source, it looks like +this:@refill + +@example +@dots{}a sample footnote@@footnote@{Here is the sample +footnote.@}; in the Texinfo source@dots{} +@end example + +In a printed manual or book, the reference mark for a footnote is a +small, superscripted number; the text of the footnote appears at the +bottom of the page, below a horizontal line.@refill + +In Info, the reference mark for a footnote is a pair of parentheses +with the footnote number between them, like this: @samp{(1)}. The +reference mark is followed by a cross-reference link to the footnote's +text. + +In the HTML output, footnote references are marked with a small, +superscripted number which is rendered as a hypertext link to the +footnote text. + +By the way, footnotes in the argument of an @code{@@item} command for a +@code{@@table} must be on the same line as the @code{@@item} +(as usual). @xref{Two-column Tables}. + + +@node Footnote Styles +@subsection Footnote Styles + +Info has two footnote styles, which determine where the text of the +footnote is located:@refill + +@itemize @bullet +@cindex @samp{@r{End}} node footnote style +@item +In the `End' node style, all the footnotes for a single node +are placed at the end of that node. The footnotes are separated from +the rest of the node by a line of dashes with the word +@samp{Footnotes} within it. Each footnote begins with an +@samp{(@var{n})} reference mark.@refill + +@need 700 +@noindent +Here is an example of a single footnote in the end of node style:@refill + +@example +@group + --------- Footnotes --------- + +(1) Here is a sample footnote. +@end group +@end example + +@cindex @samp{@r{Separate}} footnote style +@item +In the `Separate' node style, all the footnotes for a single +node are placed in an automatically constructed node of +their own. In this style, a ``footnote reference'' follows +each @samp{(@var{n})} reference mark in the body of the +node. The footnote reference is actually a cross reference +which you use to reach the footnote node.@refill + +The name of the node with the footnotes is constructed +by appending @w{@samp{-Footnotes}} to the name of the node +that contains the footnotes. (Consequently, the footnotes' +node for the @file{Footnotes} node is +@w{@file{Footnotes-Footnotes}}!) The footnotes' node has an +`Up' node pointer that leads back to its parent node.@refill + +@noindent +Here is how the first footnote in this manual looks after being +formatted for Info in the separate node style:@refill + +@smallexample +@group +File: texinfo.info Node: Overview-Footnotes, Up: Overview + +(1) The first syllable of "Texinfo" is pronounced like "speck", not +"hex". @dots{} +@end group +@end smallexample +@end itemize + +A Texinfo file may be formatted into an Info file with either footnote +style.@refill + +@findex footnotestyle +Use the @code{@@footnotestyle} command to specify an Info file's +footnote style. Write this command at the beginning of a line followed +by an argument, either @samp{end} for the end node style or +@samp{separate} for the separate node style. + +@need 700 +For example, + +@example +@@footnotestyle end +@end example +@noindent +or +@example +@@footnotestyle separate +@end example + +Write an @code{@@footnotestyle} command before or shortly after the +end-of-header line at the beginning of a Texinfo file. (If you +include the @code{@@footnotestyle} command between the start-of-header +and end-of-header lines, the region formatting commands will format +footnotes as specified.)@refill + +If you do not specify a footnote style, the formatting commands use +their default style. Currently, @code{texinfo-format-buffer} and +@code{texinfo-format-region} use the `separate' style and +@code{makeinfo} uses the `end' style.@refill + +@c !!! note: makeinfo's --footnote-style option overrides footnotestyle +@ignore +If you use @code{makeinfo} to create the Info file, the +@samp{--footnote-style} option determines which style is used, +@samp{end} for the end of node style or @samp{separate} for the +separate node style. Thus, to format the Texinfo manual in the +separate node style, you would use the following shell command:@refill + +@example +makeinfo --footnote-style=separate texinfo.texi +@end example + +@noindent +To format the Texinfo manual in the end of node style, you would +type:@refill + +@example +makeinfo --footnote-style=end texinfo.texi +@end example +@end ignore +@ignore +If you use @code{texinfo-format-buffer} or +@code{texinfo-format-region} to create the Info file, the value of the +@code{texinfo-footnote-style} variable controls the footnote style. +It can be either @samp{"separate"} for the separate node style or +@samp{"end"} for the end of node style. (You can change the value of +this variable with the @kbd{M-x edit-options} command (@pxref{Edit +Options, , Editing Variable Values, emacs, The GNU Emacs Manual}), or +with the @kbd{M-x set-variable} command (@pxref{Examining, , Examining +and Setting Variables, emacs, The GNU Emacs Manual}).@refill + +The @code{texinfo-footnote-style} variable also controls the style if +you use the @kbd{M-x makeinfo-region} or @kbd{M-x makeinfo-buffer} +command in Emacs.@refill +@end ignore +@ifinfo +This chapter contains two footnotes.@refill +@end ifinfo + + @c this should be described with figures when we have them @c perhaps in the quotation/example chapter. -@node Images, , Glyphs, Insertions +@node Images @section Inserting Images @cindex Images, inserting @cindex Pictures, inserting @findex image -You can insert an image in an external file with the @code{@@image} -command: +You can insert an image given in an external file with the +@code{@@image} command: @example @@image@{@var{filename}, @r{[}@var{width}@r{]}, @r{[}@var{height}@r{]}@} @@ -9605,17 +9957,32 @@ command: @cindex Image formats The @var{filename} argument is mandatory, and must not have an extension, because the different processors support different formats: +@itemize @bullet +@item @TeX{} reads the file @file{@var{filename}.eps} (Encapsulated PostScript -format); @code{makeinfo} uses @file{@var{filename}.txt} verbatim for -Info output (more or less as if it was an @code{@@example}). HTML -output requires @file{@var{filename}.jpg}. +format). +@item +@pindex pdftex@r{, and images} +PDF@TeX{} reads @file{@var{filename}.pdf} (Adobe's Portable Document Format). +@item +@code{makeinfo} uses @file{@var{filename}.txt} verbatim for +Info output (more or less as if it was an @code{@@example}). +@item +@cindex GIF, unsupported due to patents +@cindex PNG image format +@cindex JPEG image format +@code{makeinfo} producing HTML output tries @file{@var{filename}.png}; +if that does not exist, it tries @file{@var{filename}.jpg}. If that +does not exist either, it complains. (We cannot support GIF format due +to patents.) +@end itemize @cindex Width of images @cindex Height of images @cindex Aspect ratio of images @cindex Distorting images The optional @var{width} and @var{height} arguments specify the size to -scale the image to (they are ignored for Info output). If they are both +scale the image to (they are ignored for Info output). If neither is specified, the image is presented in its natural size (given in the file); if only one is specified, the other is scaled proportionately; and if both are specified, both are respected, thus possibly distorting @@ -9665,12 +10032,19 @@ inch vertically, with the width scaled proportionately: @pindex epsf.tex For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be -installed somewhere that @TeX{} can find it. This file is included in -the Texinfo distribution and is available from -@uref{ftp://ftp.tug.org/tex/epsf.tex}. +installed somewhere that @TeX{} can find it. (The standard location is +@file{@var{texmf}/tex/generic/dvips/epsf.tex}, where @var{texmf} is a +root of your @TeX{} directory tree.) This file is included in the +Texinfo distribution and is available from +@uref{ftp://tug.org/tex/epsf.tex}. + +@code{@@image} can be used within a line as well as for displayed +figures. Therefore, if you intend it to be displayed, be sure to leave +a blank line before the command, or the output will run into the +preceding text. -@node Breaks, Definition Commands, Insertions, Top +@node Breaks @chapter Making and Preventing Breaks @cindex Making line and page breaks @cindex Preventing line and page breaks @@ -9700,13 +10074,10 @@ commands.@refill * need:: Another way to prevent unwanted page breaks. @end menu -@ifinfo @node Break Commands, Line Breaks, Breaks, Breaks -@heading The Break Commands +@ifinfo +@heading Break Commands @end ifinfo -@iftex -@sp 1 -@end iftex The break commands create or allow line and paragraph breaks:@refill @@ -9839,8 +10210,7 @@ words match exactly, so give all necessary variants. Info output is not hyphenated, so these commands have no effect there. -@node w, sp, - and hyphenation, Breaks -@comment node-name, next, previous, up +@node w @section @code{@@w}@{@var{text}@}: Prevent Line Breaks @findex w @r{(prevent line break)} @cindex Line breaks, preventing @@ -9851,38 +10221,40 @@ within @var{text}.@refill You can use the @code{@@w} command to prevent @TeX{} from automatically hyphenating a long name or phrase that happens to fall near the end of a -line.@refill +line. For example: @example -You can copy GNU software from @@w@{@@samp@{ftp.gnu.ai.mit.edu@}@}. +You can copy GNU software from @@w@{@@samp@{ftp.gnu.org@}@}. @end example @noindent produces @quotation -You can copy GNU software from @w{@samp{ftp.gnu.ai.mit.edu}}. +You can copy GNU software from @w{@samp{ftp.gnu.org}}. @end quotation -@quotation -@strong{Caution:} Do not write an @code{@@refill} command at the end -of a paragraph containing an @code{@@w} command; it will cause the -paragraph to be refilled and may thereby negate the effect of the -@code{@@w} command.@refill -@end quotation +@cindex Non-breakable space +@cindex Unbreakable space +@cindex Tied space +You can also use @code{@@w} to produce a non-breakable space: -@node sp, page, w, Breaks -@comment node-name, next, previous, up +@example +None of the formatters will break at this@@w@{ @}space. +@end example + + +@node sp @section @code{@@sp} @var{n}: Insert Blank Lines @findex sp @r{(line spacing)} -@cindex Spaces (blank lines) +@cindex Space, inserting vertical @cindex Blank lines @cindex Line spacing A line beginning with and containing only @code{@@sp @var{n}} generates @var{n} blank lines of space in both the printed manual and the Info file. @code{@@sp} also forces a paragraph break. For -example,@refill +example, @example @@sp 2 @@ -10028,7 +10400,8 @@ This paragraph is preceded by @dots{} The @code{@@need} command is useful for preventing orphans (single lines at the bottoms of printed pages).@refill -@node Definition Commands, Footnotes, Breaks, Top + +@node Definition Commands @chapter Definition Commands @cindex Definition commands @@ -10287,7 +10660,7 @@ produces These two search commands are similar except @dots{} @end deffn -Each of the other definition commands has an `x' form: @code{@@defunx}, +Each definition command has an `x' form: @code{@@defunx}, @code{@@defvrx}, @code{@@deftypefunx}, etc. The `x' forms work just like @code{@@itemx}; see @ref{itemx, , @code{@@itemx}}. @@ -10434,8 +10807,8 @@ something like a variable---an entity that records a value. You must choose a term to describe the category of entity being defined; for example, ``Variable'' could be used if the entity is a variable. Write the @code{@@defvr} command at the beginning of a line and -followed it on the same line by the category of the entity and the -name of the entity.@refill +follow it on the same line by the category of the entity and the +name of the entity. Capitalize the category name like a title. If the name of the category contains spaces, as in the name ``User Option'', enclose it in braces. @@ -10798,7 +11171,7 @@ The template is: @var{name}.@refill @end table -@node Abstract Objects, Data Types, Typed Variables, Def Cmds in Detail +@node Abstract Objects @subsection Object-Oriented Programming Here are the commands for formatting descriptions about abstract @@ -10833,8 +11206,7 @@ name. Thus,@refill illustrates how you would write the first line of a definition of the @code{border-pattern} class option of the class @code{Window}.@refill -The template is - +The template is: @example @group @@defcv @var{category} @var{class} @var{name} @@ -10852,7 +11224,6 @@ variables in object-oriented programming. @code{@@defivar} is equivalent to @samp{@@defcv @{Instance Variable@} @dots{}}@refill The template is: - @example @group @@defivar @var{class} @var{instance-variable-name} @@ -10863,12 +11234,20 @@ The template is: @code{@@defivar} creates an entry in the index of variables. +@findex deftypeivar +@item @@deftypeivar @var{class} @var{data-type} @var{name} +The @code{@@deftypeivar} command is the definition command for typed +instance variables in object-oriented programming. It is similar to +@code{@@defivar} with the addition of the @var{data-type} parameter to +specify the type of the instance variable. @code{@@deftypeivar} creates an +entry in the index of variables. + @findex defop @item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} The @code{@@defop} command is the general definition command for entities that may resemble methods in object-oriented programming. -These entities take arguments, as functions do, but are associated -with particular classes of objects.@refill +These entities take arguments, as functions do, but are associated with +particular classes of objects.@refill For example, some systems have constructs called @dfn{wrappers} that are associated with classes as methods are, but that act more like @@ -10900,10 +11279,7 @@ is followed on the same line by the overall name of the category of operation, the name of the class of the operation, the name of the operation, and its arguments, if any.@refill -@need 800 -@noindent The template is: - @example @group @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} @@ -10915,23 +11291,34 @@ The template is: @code{@@defop} creates an entry, such as `@code{expose} on @code{windows}', in the index of functions.@refill +@findex deftypeop +@item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{} +The @code{@@deftypeop} command is the definition command for typed +operations in object-oriented programming. It is similar to +@code{@@defop} with the addition of the @var{data-type} parameter to +specify the return type of the method. @code{@@deftypeop} creates an +entry in the index of functions. + @item @@defmethod @var{class} @var{name} @var{arguments}@dots{} @findex defmethod The @code{@@defmethod} command is the definition command for methods in object-oriented programming. A method is a kind of function that implements an operation for a particular class of objects and its -subclasses. In the Lisp Machine, methods actually were functions, but +subclasses. +@ignore +@c ADR: Who cares?!? +@c KB: Oh, I don't know, I think this info is crucial! +In the Lisp Machine, methods actually were functions, but they were usually defined with @code{defmethod}. +@end ignore @code{@@defmethod} is equivalent to @samp{@@defop Method @dots{}}. The command is written at the beginning of a line and is followed by the name of the class of the method, the name of the method, and its arguments, if any.@refill -@need 800 @noindent -For example, - +For example: @example @group @@defmethod @code{bar-class} bar-method argument @@ -10957,6 +11344,7 @@ The template is: @code{@@defmethod} creates an entry, such as `@code{bar-method} on @code{bar-class}', in the index of functions.@refill + @item @@deftypemethod @var{class} @var{data-type} @var{name} @var{arguments}@dots{} @findex defmethod The @code{@@deftypemethod} command is the definition command for methods @@ -10967,7 +11355,7 @@ to the @code{@@defmethod} command with the addition of the @end table -@node Data Types, , Abstract Objects, Def Cmds in Detail +@node Data Types @subsection Data Types Here is the command for data types:@refill @@ -11077,7 +11465,6 @@ In the Texinfo source file, this example looks like this: @example @group @@defun apply function &rest arguments - @@code@{apply@} calls @@var@{function@} with @@var@{arguments@}, just like @@code@{funcall@} but with one difference: the last of @@var@{arguments@} is a list of @@ -11112,7 +11499,7 @@ sense in @@code@{apply@}. @group An interesting example of using @@code@{apply@} is found -in the description of @@code@{mapcar@}.@@refill +in the description of @@code@{mapcar@}. @@end defun @end group @end example @@ -11125,202 +11512,29 @@ Ordinary variables and user options are described using a format like that for functions except that variables do not take arguments. -@node Footnotes, Conditionals, Definition Commands, Top -@chapter Footnotes -@cindex Footnotes -@findex footnote - -A @dfn{footnote} is for a reference that documents or elucidates the -primary text.@footnote{A footnote should complement or expand upon -the primary text, but a reader should not need to read a footnote to -understand the primary text. For a thorough discussion of footnotes, -see @cite{The Chicago Manual of Style}, which is published by the -University of Chicago Press.}@refill - -@menu -* Footnote Commands:: How to write a footnote in Texinfo. -* Footnote Styles:: Controlling how footnotes appear in Info. -@end menu - -@node Footnote Commands, Footnote Styles, Footnotes, Footnotes -@section Footnote Commands - -In Texinfo, footnotes are created with the @code{@@footnote} command. -This command is followed immediately by a left brace, then by the text -of the footnote, and then by a terminating right brace. Footnotes may -be of any length (they will be broken across pages if necessary), but -are usually short. The template is: - -@example -ordinary text@@footnote@{@var{text of footnote}@} -@end example - -As shown here, the @code{@@footnote} command should come right after the -text being footnoted, with no intervening space; otherwise, the -formatters the footnote mark might end up starting up a line. - -For example, this clause is followed by a sample -footnote@footnote{Here is the sample footnote.}; in the Texinfo -source, it looks like this:@refill - -@example -@dots{}a sample footnote@@footnote@{Here is the sample -footnote.@}; in the Texinfo source@dots{} -@end example - -@strong{Warning:} Don't use footnotes in the argument of the -@code{@@item} command for a @code{@@table} table. This doesn't work, and -because of limitations of @TeX{}, there is no way to fix it. You must -put the footnote into the body text of the table. - -In a printed manual or book, the reference mark for a footnote is a -small, superscripted number; the text of the footnote appears at the -bottom of the page, below a horizontal line.@refill - -In Info, the reference mark for a footnote is a pair of parentheses -with the footnote number between them, like this: @samp{(1)}.@refill +@node Conditionals +@chapter Conditionally Visible Text +@cindex Conditionally visible text +@cindex Text, conditionally visible +@cindex Visibility of conditional text +@cindex If text conditionally visible +Sometimes it is good to use different text for different output formats. +For example, you can use the @dfn{conditional commands} to specify +different text for the printed manual and the Info output. -@node Footnote Styles, , Footnote Commands, Footnotes -@section Footnote Styles +Conditional commands may not be nested. -Info has two footnote styles, which determine where the text of the -footnote is located:@refill +The conditional commands comprise the following categories. @itemize @bullet -@cindex @samp{@r{End}} node footnote style +@item Commands for HTML, Info, or @TeX{}. +@item Commands for not HTML, Info, or @TeX{}. +@item Raw @TeX{} or HTML commands. @item -In the `End' node style, all the footnotes for a single node -are placed at the end of that node. The footnotes are separated from -the rest of the node by a line of dashes with the word -@samp{Footnotes} within it. Each footnote begins with an -@samp{(@var{n})} reference mark.@refill - -@need 700 -@noindent -Here is an example of a single footnote in the end of node style:@refill - -@example -@group - --------- Footnotes --------- - -(1) Here is a sample footnote. -@end group -@end example - -@cindex @samp{@r{Separate}} footnote style -@item -In the `Separate' node style, all the footnotes for a single -node are placed in an automatically constructed node of -their own. In this style, a ``footnote reference'' follows -each @samp{(@var{n})} reference mark in the body of the -node. The footnote reference is actually a cross reference -which you use to reach the footnote node.@refill - -The name of the node containing the footnotes is constructed -by appending @w{@samp{-Footnotes}} to the name of the node -that contains the footnotes. (Consequently, the footnotes' -node for the @file{Footnotes} node is -@w{@file{Footnotes-Footnotes}}!) The footnotes' node has an -`Up' node pointer that leads back to its parent node.@refill - -@noindent -Here is how the first footnote in this manual looks after being -formatted for Info in the separate node style:@refill - -@smallexample -@group -File: texinfo.info Node: Overview-Footnotes, Up: Overview - -(1) Note that the first syllable of "Texinfo" is -pronounced like "speck", not "hex". @dots{} -@end group -@end smallexample +Substituting text for all formats, and testing if a flag is set or clear. @end itemize -A Texinfo file may be formatted into an Info file with either footnote -style.@refill - -@findex footnotestyle -Use the @code{@@footnotestyle} command to specify an Info file's -footnote style. Write this command at the beginning of a line followed -by an argument, either @samp{end} for the end node style or -@samp{separate} for the separate node style. - -@need 700 -For example, - -@example -@@footnotestyle end -@end example -@noindent -or -@example -@@footnotestyle separate -@end example - -Write an @code{@@footnotestyle} command before or shortly after the -end-of-header line at the beginning of a Texinfo file. (If you -include the @code{@@footnotestyle} command between the start-of-header -and end-of-header lines, the region formatting commands will format -footnotes as specified.)@refill - -If you do not specify a footnote style, the formatting commands use -their default style. Currently, @code{texinfo-format-buffer} and -@code{texinfo-format-region} use the `separate' style and -@code{makeinfo} uses the `end' style.@refill - -@c !!! note: makeinfo's --footnote-style option overrides footnotestyle -@ignore -If you use @code{makeinfo} to create the Info file, the -@samp{--footnote-style} option determines which style is used, -@samp{end} for the end of node style or @samp{separate} for the -separate node style. Thus, to format the Texinfo manual in the -separate node style, you would use the following shell command:@refill - -@example -makeinfo --footnote-style=separate texinfo.texi -@end example - -@noindent -To format the Texinfo manual in the end of node style, you would -type:@refill - -@example -makeinfo --footnote-style=end texinfo.texi -@end example -@end ignore -@ignore -If you use @code{texinfo-format-buffer} or -@code{texinfo-format-region} to create the Info file, the value of the -@code{texinfo-footnote-style} variable controls the footnote style. -It can be either @samp{"separate"} for the separate node style or -@samp{"end"} for the end of node style. (You can change the value of -this variable with the @kbd{M-x edit-options} command (@pxref{Edit -Options, , Editing Variable Values, emacs, The GNU Emacs Manual}), or -with the @kbd{M-x set-variable} command (@pxref{Examining, , Examining -and Setting Variables, emacs, The GNU Emacs Manual}).@refill - -The @code{texinfo-footnote-style} variable also controls the style if -you use the @kbd{M-x makeinfo-region} or @kbd{M-x makeinfo-buffer} -command in Emacs.@refill -@end ignore -This chapter contains two footnotes.@refill - - -@node Conditionals, Macros, Footnotes, Top -@comment node-name, next, previous, up -@chapter Conditionally Visible Text -@cindex Conditionally visible text -@cindex Text, conditionally visible -@cindex Visibility of conditional text -@cindex If text conditionally visible - -Sometimes it is good to use different text for a printed manual and -its corresponding Info file. In this case, you can use the -@dfn{conditional commands} to specify which text is for the printed manual -and which is for the Info file.@refill - @menu * Conditional Commands:: Specifying text for HTML, Info, or @TeX{}. * Conditional Not Commands:: Specifying text for not HTML, Info, or @TeX{}. @@ -11330,21 +11544,18 @@ and which is for the Info file.@refill flag to a string that you can insert. @end menu -@node Conditional Commands, Conditional Not Commands, Conditionals, Conditionals -@ifinfo -@heading Conditional Commands -@end ifinfo + +@node Conditional Commands +@section Conditional Commands @findex ifinfo -@code{@@ifinfo} begins segments of text that should be ignored -by @TeX{} when it -typesets the printed manual. The segment of text appears only -in the Info file. -The @code{@@ifinfo} command should appear on a line by itself; end -the Info-only text with a line containing @code{@@end ifinfo} by -itself. At the beginning of a Texinfo file, the Info permissions are -contained within a region marked by @code{@@ifinfo} and @code{@@end -ifinfo}. (@xref{Info Summary and Permissions}.)@refill +@code{@@ifinfo} begins segments of text that should be ignored by @TeX{} +when it typesets the printed manual. The segment of text appears only +in the Info file. The @code{@@ifinfo} command should appear on a line +by itself; end the Info-only text with a line containing @code{@@end +ifinfo} by itself. At the beginning of a Texinfo file, the Info +permissions are contained within a region marked by @code{@@ifinfo} and +@code{@@end ifinfo}. (@xref{Info Summary and Permissions}.) @findex iftex @findex ifhtml @@ -11363,6 +11574,9 @@ This text will appear only in the printed manual. @@ifinfo However, this text will appear only in Info. @@end ifinfo +@@ifhtml +And this text will only appear in HTML. +@@end ifhtml @end example @noindent @@ -11373,18 +11587,16 @@ This text will appear only in the printed manual. @ifinfo However, this text will appear only in Info. @end ifinfo +@ifhtml +And this text will only appear in HTML. +@end ifhtml @noindent -Note how you only see one of the two lines, depending on whether you -are reading the Info version or the printed version of this -manual.@refill - -The @code{@@titlepage} command is a special variant of @code{@@iftex} that -is used for making the title and copyright pages of the printed -manual. (@xref{titlepage, , @code{@@titlepage}}.) @refill +Notice that you only see one of the input lines, depending on which +version of the manual you are reading. -@node Conditional Not Commands, Raw Formatter Commands, Conditional Commands, Conditionals +@node Conditional Not Commands @section Conditional Not Commands @findex ifnothtml @findex ifnotinfo @@ -11405,7 +11617,8 @@ If the output file is not being made for the given format, the region is included. Otherwise, it is ignored. The regions delimited by these commands are ordinary Texinfo source as -with @code{@@iftex}, not raw formatter source as with @code{@@tex}. +with @code{@@iftex}, not raw formatter source as with @code{@@tex} +(@pxref{Raw Formatter Commands}). @node Raw Formatter Commands, set clear value, Conditional Not Commands, Conditionals @@ -11437,8 +11650,8 @@ overridden by Texinfo features. You can enter plain @TeX{} completely, and use @samp{\} in the @TeX{} commands, by delineating a region with the @code{@@tex} and @code{@@end tex} commands. (The @code{@@tex} command also causes Info to ignore the -region, like the @code{@@iftex} command.) The sole exception is that -@code{@@} chracter still introduces a command, so that @code{@@end tex} +region, like the @code{@@iftex} command.) The sole exception is that the +@code{@@} character still introduces a command, so that @code{@@end tex} can be recognized properly. @cindex Mathematical expressions @@ -11472,13 +11685,12 @@ $$ \chi^2 = \sum_{i=1}^N @findex html Analogously, you can use @code{@@ifhtml @dots{} @@end ifhtml} to delimit a region to be included in HTML output only, and @code{@@html @dots{} -@@end ifhtml} for a region of raw HTML (again, except that @code{@@} is +@@end html} for a region of raw HTML (again, except that @code{@@} is still the escape character, so the @code{@@end} command can be recognized.) -@node set clear value, , Raw Formatter Commands, Conditionals -@comment node-name, next, previous, up +@node set clear value @section @code{@@set}, @code{@@clear}, and @code{@@value} You can direct the Texinfo formatting commands to format or ignore parts @@ -11493,12 +11705,12 @@ insert the date in several places in the Texinfo file.@refill @menu * ifset ifclear:: Format a region if a flag is set. -* value:: Replace a flag with a string. +* set value:: Expand a flag variable to a string. * value Example:: An easy way to update edition information. @end menu -@node ifset ifclear, value, set clear value, set clear value +@node ifset ifclear @subsection @code{@@ifset} and @code{@@ifclear} @findex ifset @@ -11508,8 +11720,10 @@ ifset} commands. When the @var{flag} is cleared, the Texinfo formatting commands do @emph{not} format the text. Use the @code{@@set @var{flag}} command to turn on, or @dfn{set}, a -@var{flag}; a @dfn{flag} can be any single word. The format for the -command looks like this:@refill +@var{flag}; a @dfn{flag} name can be any single word, containing +letters, numerals, hyphens, or underscores. + +The format for the command looks like this:@refill @findex set @example @@ -11613,13 +11827,17 @@ format the text up to the following @code{@@end ifclear} command.@refill @end table -@node value, value Example, ifset ifclear, set clear value -@subsection @code{@@value} + +@node set value +@subsection @code{@@set} and @code{@@value} @findex value You can use the @code{@@set} command to specify a value for a flag, -which is expanded by the @code{@@value} command. The value is a string -a characters. +which is expanded by the @code{@@value} command. A flag is an +identifier; for best results, use only letters and numerals in a flag +name, not @samp{-} or @samp{_}---they will work in some contexts, but +not all, due to limitations in @TeX{}. The value is just a string of +characters, the remainder of the input line. Write the @code{@@set} command like this: @@ -11628,12 +11846,11 @@ Write the @code{@@set} command like this: @end example @noindent -This sets the value of @code{foo} to ``This is a string.'' - -The Texinfo formatters replace an @code{@@value@{@var{flag}@}} command with -the string to which @var{flag} is set.@refill +This sets the value of the flag @code{foo} to ``This is a string.''. -Thus, when @code{foo} is set as shown above, the Texinfo formatters convert +The Texinfo formatters then replace an @code{@@value@{@var{flag}@}} +command with the string to which @var{flag} is set. Thus, when +@code{foo} is set as shown above, the Texinfo formatters convert @example @group @@ -11655,9 +11872,9 @@ If you write the @code{@@set} command like this: @noindent without specifying a string, the value of @code{foo} is an empty string. -If you clear a previously set flag with an @code{@@clear @var{flag}} -command, a subsequent @code{@@value@{flag@}} command is invalid and the -string is replaced with an error message that says @samp{@{No value for +If you clear a previously set flag with @code{@@clear @var{flag}}, a +subsequent @code{@@value@{flag@}} command is invalid and the string is +replaced with an error message that says @samp{@{No value for "@var{flag}"@}}. For example, if you set @code{foo} as follows:@refill @@ -11694,15 +11911,16 @@ It is a @{No value for "how-much"@} wet day. @end group @end example -@node value Example, , value, set clear value + +@node value Example @subsection @code{@@value} Example You can use the @code{@@value} command to limit the number of places you -need to change when you record an update to a manual. -Here is how it is done in @cite{The GNU Make Manual}: +need to change when you record an update to a manual. Here is how it is +done in @cite{The GNU Make Manual}: -@need 1000 -@noindent +@enumerate +@item Set the flags: @example @@ -11714,8 +11932,7 @@ Set the flags: @end group @end example -@need 750 -@noindent +@item Write text for the first @code{@@ifinfo} section, for people reading the Texinfo file: @@ -11724,12 +11941,11 @@ Texinfo file: This is Edition @@value@{EDITION@}, last updated @@value@{UPDATED@}, of @@cite@{The GNU Make Manual@}, -for @@code@{make@}, Version @@value@{VERSION@}. +for @@code@{make@}, version @@value@{VERSION@}. @end group @end example -@need 1000 -@noindent +@item Write text for the title page, for people reading the printed manual: @c List only the month and the year since that looks less fussy on a @c printed cover than a date that lists the day as well. @@ -11747,8 +11963,7 @@ Write text for the title page, for people reading the printed manual: (On a printed cover, a date listing the month and the year looks less fussy than a date listing the day as well as the month and year.) -@need 750 -@noindent +@item Write text for the Top node, for people reading the Info file: @example @@ -11760,7 +11975,6 @@ for @@code@{make@} Version @@value@{VERSION@}. @end group @end example -@need 950 After you format the manual, the text in the first @code{@@ifinfo} section looks like this: @@ -11770,49 +11984,336 @@ This is Edition 0.35 Beta, last updated 14 August 1992, of `The GNU Make Manual', for `make', Version 3.63 Beta. @end group @end example +@end enumerate When you update the manual, change only the values of the flags; you do -not need to rewrite the three sections. +not need to edit the three sections. + + +@node Internationalization +@chapter Internationalization + +@cindex Internationalization +Texinfo has some support for writing in languages other than English, +although this area still needs considerable work. + +For a list of the various accented and special characters Texinfo +supports, see @ref{Inserting Accents}. + +@menu +* documentlanguage:: Declaring the current language. +* documentencoding:: Declaring the input encoding. +@end menu + + +@node documentlanguage +@section @code{@@documentlanguage @var{cc}}: Set the Document Language + +@findex documentlanguage +@cindex Language, declaring +@cindex Document language, declaring + +The @code{@@documentlanguage} command declares the current document +language. Write it on a line by itself, with a two-letter ISO-639 +language code following (list is included below). If you have a +multilingual document, the intent is to be able to use this command +multiple times, to declare each language change. If the command is not +used at all, the default is @code{en} for English. + +@cindex @file{txi-@var{cc}.tex} +At present, this command is ignored in Info and HTML output. For +@TeX{}, it causes the file @file{txi-@var{cc}.tex} to be read (if it +exists). Such a file appropriately redefines the various English words +used in @TeX{} output, such as `Chapter', `See', and so on. + +@cindex Hyphenation patterns, language-dependent +It would be good if this command also changed @TeX{}'s ideas of the +current hyphenation patterns (via the @TeX{} primitive +@code{\language}), but this is unfortunately not currently implemented. + +@cindex ISO 639 codes +@cindex Language codes +@cindex African languages +Here is the list of valid language codes. This list comes from +@uref{http://www.iro.umontreal.ca/contrib/po/iso-639, the free +translation project}. In the future we may wish to allow the 3-letter +POV codes described at @uref{http://www.sil.org/ethnologue/#contents}. +This will be necessary to support African languages. + +@multitable @columnfractions .06 .27 .06 .27 .06 .27 +@item +@code{aa} @tab Afar @tab +@code{ab} @tab Abkhazian @tab +@code{af} @tab Afrikaans +@item +@code{am} @tab Amharic @tab +@code{ar} @tab Arabic @tab +@code{as} @tab Assamese +@item +@code{ay} @tab Aymara @tab +@code{az} @tab Azerbaijani @tab +@code{ba} @tab Bashkir +@item +@code{be} @tab Byelorussian @tab +@code{bg} @tab Bulgarian @tab +@code{bh} @tab Bihari +@item +@code{bi} @tab Bislama @tab +@code{bn} @tab Bengali; Bangla @tab +@code{bo} @tab Tibetan +@item +@code{br} @tab Breton @tab +@code{ca} @tab Catalan @tab +@code{co} @tab Corsican +@item +@code{cs} @tab Czech @tab +@code{cy} @tab Welsh @tab +@code{da} @tab Danish +@item +@code{de} @tab German @tab +@code{dz} @tab Bhutani @tab +@code{el} @tab Greek +@item +@code{en} @tab English @tab +@code{eo} @tab Esperanto @tab +@code{es} @tab Spanish +@item +@code{et} @tab Estonian @tab +@code{eu} @tab Basque @tab +@code{fa} @tab Persian +@item +@code{fi} @tab Finnish @tab +@code{fj} @tab Fiji @tab +@code{fo} @tab Faroese +@item +@code{fr} @tab French @tab +@code{fy} @tab Frisian @tab +@code{ga} @tab Irish +@item +@code{gd} @tab Scots Gaelic @tab +@code{gl} @tab Galician @tab +@code{gn} @tab Guarani +@item +@code{gu} @tab Gujarati @tab +@code{ha} @tab Hausa @tab +@code{he} @tab Hebrew +@item +@code{hi} @tab Hindi @tab +@code{hr} @tab Croatian @tab +@code{hu} @tab Hungarian +@item +@code{hy} @tab Armenian @tab +@code{ia} @tab Interlingua @tab +@code{id} @tab Indonesian +@item +@code{ie} @tab Interlingue @tab +@code{ik} @tab Inupiak @tab +@code{is} @tab Icelandic +@item +@code{it} @tab Italian @tab +@code{iu} @tab Inuktitut @tab +@code{ja} @tab Japanese +@item +@code{jw} @tab Javanese @tab +@code{ka} @tab Georgian @tab +@code{kk} @tab Kazakh +@item +@code{kl} @tab Greenlandic @tab +@code{km} @tab Cambodian @tab +@code{kn} @tab Kannada +@item +@code{ks} @tab Kashmiri @tab +@code{ko} @tab Korean @tab +@code{ku} @tab Kurdish +@item +@code{ky} @tab Kirghiz @tab +@code{la} @tab Latin @tab +@code{ln} @tab Lingala +@item +@code{lt} @tab Lithuanian @tab +@code{lo} @tab Laothian @tab +@code{lv} @tab Latvian, Lettish +@item +@code{mg} @tab Malagasy @tab +@code{mi} @tab Maori @tab +@code{mk} @tab Macedonian +@item +@code{ml} @tab Malayalam @tab +@code{mn} @tab Mongolian @tab +@code{mo} @tab Moldavian +@item +@code{mr} @tab Marathi @tab +@code{ms} @tab Malay @tab +@code{mt} @tab Maltese +@item +@code{my} @tab Burmese @tab +@code{na} @tab Nauru @tab +@code{ne} @tab Nepali +@item +@code{nl} @tab Dutch @tab +@code{no} @tab Norwegian @tab +@code{oc} @tab Occitan +@item +@code{om} @tab (Afan) Oromo @tab +@code{or} @tab Oriya @tab +@code{pa} @tab Punjabi +@item +@code{pl} @tab Polish @tab +@code{ps} @tab Pashto, Pushto @tab +@code{pt} @tab Portuguese +@item +@code{qu} @tab Quechua @tab +@code{rm} @tab Rhaeto-Romance @tab +@code{rn} @tab Kirundi +@item +@code{ro} @tab Romanian @tab +@code{ru} @tab Russian @tab +@code{rw} @tab Kinyarwanda +@item +@code{sa} @tab Sanskrit @tab +@code{sd} @tab Sindhi @tab +@code{sg} @tab Sangro +@item +@code{sh} @tab Serbo-Croatian @tab +@code{si} @tab Sinhalese @tab +@code{sk} @tab Slovak +@item +@code{sl} @tab Slovenian @tab +@code{sm} @tab Samoan @tab +@code{sn} @tab Shona +@item +@code{so} @tab Somali @tab +@code{sq} @tab Albanian @tab +@code{sr} @tab Serbian +@item +@code{ss} @tab Siswati @tab +@code{st} @tab Sesotho @tab +@code{su} @tab Sundanese +@item +@code{sv} @tab Swedish @tab +@code{sw} @tab Swahili @tab +@code{ta} @tab Tamil +@item +@code{te} @tab Telugu @tab +@code{tg} @tab Tajik @tab +@code{th} @tab Thai +@item +@code{ti} @tab Tigrinya @tab +@code{tk} @tab Turkmen @tab +@code{tl} @tab Tagalog +@item +@code{tn} @tab Setswana @tab +@code{to} @tab Tonga @tab +@code{tr} @tab Turkish +@item +@code{ts} @tab Tsonga @tab +@code{tt} @tab Tatar @tab +@code{tw} @tab Twi +@item +@code{ug} @tab Uighur @tab +@code{uk} @tab Ukrainian @tab +@code{ur} @tab Urdu +@item +@code{uz} @tab Uzbek @tab +@code{vi} @tab Vietnamese @tab +@code{vo} @tab Volapuk +@item +@code{wo} @tab Wolof @tab +@code{xh} @tab Xhosa @tab +@code{yi} @tab Yiddish +@item +@code{yo} @tab Yoruba @tab +@code{za} @tab Zhuang @tab +@code{zh} @tab Chinese +@item +@code{zu} @tab Zulu +@end multitable + + +@node documentencoding +@section @code{@@documentencoding @var{enc}}: Set Input Encoding + +@findex documentencoding +@cindex Encoding, declaring +@cindex Input encoding, declaring +@cindex Document input encoding + +The @code{@@documentencoding} command declares the input document +encoding. Write it on a line by itself, with a valid encoding +specification following, such as @samp{ISO-8859-1}. +@cindex http-equiv, and charset +@cindex meta HTML tag, and charset +At present, this is used only in HTML output from @code{makeinfo}. If a +document encoding @var{enc} is specified, it is used in the +@samp{<meta>} tag is included in the @samp{<head>} of the output: -@node Macros, Format/Print Hardcopy, Conditionals, Top -@chapter Macros: Defining New Texinfo Commands +@example +<meta http-equiv="Content-Type" content="text/html; charset=@var{enc}"> +@end example + + +@node Defining New Texinfo Commands +@chapter Defining New Texinfo Commands @cindex Macros @cindex Defining new Texinfo commands @cindex New Texinfo commands, defining @cindex Texinfo commands, defining new @cindex User-defined Texinfo commands +Texinfo provides several ways to define new commands: + +@itemize @bullet +@item A Texinfo @dfn{macro} allows you to define a new Texinfo command as any sequence of text and/or existing commands (including other macros). The macro can have any number of @dfn{parameters}---text you supply each -time you use the macro. (This has nothing to do with the -@code{@@defmac} command, which is for documenting macros in the subject -of the manual; @pxref{Def Cmd Template}.) +time you use the macro. + +Incidentally, these macros have nothing to do with the @code{@@defmac} +command, which is for documenting macros in the subject of the manual +(@pxref{Def Cmd Template}). + +@item +@samp{@@alias} is a convenient way to define a new name for an existing +command. + +@item +@samp{@@definfoenclose} allows you to define new commands with +customized output in the Info file. + +@end itemize @menu -* Defining Macros:: Both defining and undefining new commands. +* Defining Macros:: Defining and undefining new commands. * Invoking Macros:: Using a macro, once you've defined it. +* Macro Details:: Beyond basic macro usage. +* alias:: Command aliases. +* definfoenclose:: Customized highlighting. @end menu -@node Defining Macros, Invoking Macros, Macros, Macros +@node Defining Macros @section Defining Macros @cindex Defining macros @cindex Macro definitions +@cindex Definitions, a.k.a.@: macros @findex macro -You use the Texinfo @code{@@macro} command to define a macro. For example: +You use the Texinfo @code{@@macro} command to define a macro, like this: @example -@@macro @var{macro-name}@{@var{param1}, @var{param2}, @dots{}@} +@@macro @var{macroname}@{@var{param1}, @var{param2}, @dots{}@} @var{text} @dots{} \@var{param1}\ @dots{} @@end macro @end example The @dfn{parameters} @var{param1}, @var{param2}, @dots{} correspond to arguments supplied when the macro is subsequently used in the document -(see the next section). +(described in the next section). + +For a macro to work with @TeX{}, @var{macroname} must consist entirely +of letters: no digits, hyphens, underscores, or other special characters. If a macro needs no parameters, you can define it either with an empty list (@samp{@@macro foo @{@}}) or with no braces at all (@samp{@@macro @@ -11821,12 +12322,44 @@ foo}). @cindex Body of a macro @cindex Mutually recursive macros @cindex Recursion, mutual -The definition or @dfn{body} of the macro can contain any Texinfo -commands, including previously-defined macros. (It is not possible to -have mutually recursive Texinfo macros.) In the body, instances of a -parameter name surrounded by backslashes, as in @samp{\@var{param1}\} in -the example above, are replaced by the corresponding argument from the -macro invocation. +The definition or @dfn{body} of the macro can contain most Texinfo +commands, including previously-defined macros. Not-yet-defined macro +invocations are not allowed; thus, it is not possible to have mutually +recursive Texinfo macros. Also, a macro definition that defines another +macro does not work in @TeX{} due to limitations in the design of +@code{@@macro}. + +@cindex Parameters to macros +In the macro body, instances of a parameter name surrounded by +backslashes, as in @samp{\@var{param1}\} in the example above, are +replaced by the corresponding argument from the macro invocation. You +can use parameter names any number of times in the body, including zero. + +@cindex Backslash in macros +To get a single @samp{\} in the macro expansion, use @samp{\\}. Any +other use of @samp{\} in the body yields a warning. + +@cindex Spaces in macros +@cindex Whitespace in macros +The newlines after the @code{@@macro} line and before the @code{@@end +macro} line are ignored, that is, not included in the macro body. All +other whitespace is treated according to the usual Texinfo rules. + +@cindex Recursive macro invocations +@findex rmacro +To allow a macro to be used recursively, that is, in an argument to a +call to itself, you must define it with @samp{@@rmacro}, like this: + +@example +@@rmacro rmac +a\arg\b +@@end rmacro +@dots{} +@@rmac@{1@@rmac@{text@}2@} +@end example + +This produces the output `a1atextb2b'. With @samp{@@macro} instead of +@samp{@@rmacro}, an error message is given. @findex unmacro @cindex Macros, undefining @@ -11840,20 +12373,22 @@ For example: @end example -@node Invoking Macros, , Defining Macros, Macros +@node Invoking Macros @section Invoking Macros @cindex Invoking macros +@cindex Expanding macros +@cindex Running macros @cindex Macro invocation After a macro is defined (see the previous section), you can use (@dfn{invoke}) it in your document like this: @example -@@@var{macro-name} @{@var{arg1}, @var{arg2}, @dots{}@} +@@@var{macroname} @{@var{arg1}, @var{arg2}, @dots{}@} @end example @noindent and the result will be just as if you typed the body of -@var{macro-name} at that spot. For example: +@var{macroname} at that spot. For example: @example @@macro foo @{p, q@} @@ -11870,17 +12405,34 @@ Together: a & b. @cindex Backslash, and macros Thus, the arguments and parameters are separated by commas and delimited -by braces; any whitespace after (but not before) a comma is ignored. To -insert a comma, brace, or backslash in an argument, prepend a backslash, -as in +by braces; any whitespace after (but not before) a comma is ignored. +The braces are required in the invocation (but not the definition), even +when the macro takes no arguments, consistent with all other Texinfo +commands. For example: @example -@@@var{macro-name} @{\\\@{\@}\,@} +@@macro argless @{@} +No arguments here. +@@end macro +@@argless@{@} +@end example + +@noindent produces: + +@display +No arguments here. +@end display + +To insert a comma, brace, or backslash in an argument, prepend a +backslash, as in + +@example +@@@var{macname} @{\\\@{\@}\,@} @end example @noindent which will pass the (almost certainly error-producing) argument -@samp{\@{@},} to @var{macro-name}. +@samp{\@{@},} to @var{macname}. If the macro is defined to take a single argument, and is invoked without any braces, the entire rest of the line after the macro name is @@ -11888,22 +12440,199 @@ supplied as the argument. For example: @example @@macro bar @{p@} -Twice: \p\, \p\. +Twice: \p\ & \p\. @@end macro @@bar aah @end example @noindent produces: +@c Sorry for cheating, but let's not require macros to process the manual. @display -Twice: aah, aah. +Twice: aah & aah. @end display +If the macro is defined to take a single argument, and is invoked with +braces, the braced text is passed as the argument, regardless of +commas. For example: -@node Format/Print Hardcopy, Create an Info File, Macros, Top -@comment node-name, next, previous, up -@chapter Format and Print Hardcopy +@example +@@macro bar @{p@} +Twice: \p\ & \p\. +@@end macro +@@bar@{a,b@} +@end example + +@noindent produces: + +@display +Twice: a,b & a,b. +@end display + + +@node Macro Details +@section Macro Details +@cindex Macro details +@cindex Details of macro usage + +Due to unavoidable disparities in the @TeX{} and @command{makeinfo} +implementations, Texinfo macros have the following limitations. + +@itemize @bullet +@item +All macros are expanded inside at least one @TeX{} group. This means +that @set and other such commands will have no effect inside a macro. + +@item +Macros containing a command which must be on a line by itself, such as a +conditional, cannot be invoked in the middle of a line. + +@item +The @TeX{} implementation cannot construct macros that define macros in +the natural way. To do this, you must use conditionals and raw @TeX{}. +For example: + +@example +@@ifinfo +@@macro ctor @{name, arg@} +@@macro \name\ +something involving \arg\ somehow +@@end macro +@@end macro +@@end ifinfo +@@tex +\gdef\ctor#1@{\ctorx#1,@} +\gdef\ctorx#1,#2,@{\def#1@{something involving #2 somehow@}@} +@@end tex +@end example + +@item +It is best to avoid comments inside macro definitions. + +@end itemize + + +@node alias +@section @samp{@@alias @var{new}=@var{existing}} +@cindex Aliases, command +@cindex Command aliases +@findex alias + +The @samp{@@alias} command defines a new command to be just like an +existing one. This is useful for defining additional markup names, thus +preserving semantic information in the input even though the output +result may be the same. + +Write the @samp{@@alias} command on a line by itself, followed by the +new command name, an equals sign, and the existing command name. +Whitespace around the equals sign is ignored. Thus: +@example +@@alias @var{new} = @var{existing} +@end example + +For example, if your document contains citations for both books and +some other media (movies, for example), you might like to define a +macro @code{@@moviecite@{@}} that does the same thing as an ordinary +@code{@@cite@{@}} but conveys the extra semantic information as well. +You'd do this as follows: + +@example +@@alias moviecite = cite +@end example + +Macros do not always have the same effect due to vagaries of argument +parsing. Also, aliases are much simpler to define than macros. So the +command is not redundant. (It was also heavily used in the Jargon File!) + +Aliases must not be recursive, directly or indirectly. + +@node definfoenclose +@section @samp{definfoenclose}: Customized Highlighting +@cindex Highlighting, customized +@cindex Customized highlighting +@findex definfoenclose + +A @code{@@definfoenclose} command may be used to define a highlighting +command for Info, but not for TeX. A command defined using +@code{@@definfoenclose} marks text by enclosing it in strings that +precede and follow the text. You can use this to get closer control of +your Info output. + +Presumably, if you define a command with @code{@@definfoenclose} for Info, +you will create a corresponding command for @TeX{}, either in +@file{texinfo.tex}, @file{texinfo.cnf}, or within an @samp{@@iftex} in +your document. + +Write a @code{@@definfoenclose} command on a line and follow it with +three arguments separated by commas. The first argument to +@code{@@definfoenclose} is the @@-command name (without the @code{@@}); +the second argument is the Info start delimiter string; and the third +argument is the Info end delimiter string. The latter two arguments +enclose the highlighted text in the Info file. A delimiter string may +contain spaces. Neither the start nor end delimiter is required. If +you do not want a start delimiter but do want an end delimiter, you must +follow the command name with two commas in a row; otherwise, the Info +formatting commands will naturally misinterpret the end delimiter string +you intended as the start delimiter string. + +If you do a @code{@@definfoenclose} on the name of a pre-defined macro +(such as @code{@@emph}, @code{@@strong}, @code{@@t}, or @code{@@i}), the +enclosure definition will override the built-in definition. + +An enclosure command defined this way takes one argument in braces; this +is intended for new markup commands (@pxref{Marking Text}). + +@findex phoo +For example, you can write: + +@example +@@definfoenclose phoo,//,\\ +@end example + +@noindent +near the beginning of a Texinfo file to define @code{@@phoo} as an Info +formatting command that inserts `//' before and `\\' after the argument +to @code{@@phoo}. You can then write @code{@@phoo@{bar@}} wherever you +want `//bar\\' highlighted in Info. + +Also, for TeX formatting, you could write + +@example +@@iftex +@@global@@let@@phoo=@@i +@@end iftex +@end example + +@noindent +to define @code{@@phoo} as a command that causes TeX to typeset the +argument to @code{@@phoo} in italics. + +Note that each definition applies to its own formatter: one for TeX, +the other for @code{texinfo-format-buffer} or +@code{texinfo-format-region}. The @code{@@definfoenclose} command need +not be within @samp{@@ifinfo}, but the raw @TeX{} commands do need to be +in @samp{@@iftex}. + +@findex headword +Here is another example: write + +@example +@@definfoenclose headword, , : +@end example + +@noindent +near the beginning of the file, to define @code{@@headword} as an Info +formatting command that inserts nothing before and a colon after the +argument to @code{@@headword}. + +@samp{@@definfoenclose} definitions must not be recursive, directly or +indirectly. + + +@node Hardcopy +@chapter Formatting and Printing Hardcopy @cindex Format and print hardcopy +@cindex Printing hardcopy @cindex Hardcopy, printing it @cindex Making a printed manual @cindex Sorting indices @@ -11916,49 +12645,49 @@ Texinfo file: one for converting the Texinfo file into a file that will be printed, a second for sorting indices, and a third for printing the formatted document. When you use the shell commands, you can either work directly in the operating system shell or work within a shell -inside GNU Emacs.@refill +inside GNU Emacs. If you are using GNU Emacs, you can use commands provided by Texinfo mode instead of shell commands. In addition to the three commands to format a file, sort the indices, and print the result, Texinfo mode offers key bindings for commands to recenter the output buffer, show the -print queue, and delete a job from the print queue.@refill +print queue, and delete a job from the print queue. @menu * Use TeX:: Use @TeX{} to format for hardcopy. -* Format with tex/texindex:: How to format in a shell. -* Format with texi2dvi:: A simpler way to use the shell. +* Format with tex/texindex:: How to format with explicit shell commands. +* Format with texi2dvi:: A simpler way to format. * Print with lpr:: How to print. * Within Emacs:: How to format and print from an Emacs shell. * Texinfo Mode Printing:: How to format and print in Texinfo mode. * Compile-Command:: How to print using Emacs's compile command. * Requirements Summary:: @TeX{} formatting requirements summary. -* Preparing for TeX:: What you need to do to use @TeX{}. +* Preparing for TeX:: What to do before you use @TeX{}. * Overfull hboxes:: What are and what to do with overfull hboxes. * smallbook:: How to print small format books and manuals. * A4 Paper:: How to print on European A4 paper. +* pagesizes:: How to print with customized page sizes. * Cropmarks and Magnification:: How to print marks to indicate the size of pages and how to print scaled up output. +* PDF Output:: Portable Document Format output. @end menu -@node Use TeX, Format with tex/texindex, Format/Print Hardcopy, Format/Print Hardcopy -@ifinfo -@heading Use @TeX{} -@end ifinfo +@node Use TeX +@section Use @TeX{} The typesetting program called @TeX{} is used for formatting a Texinfo -file. @TeX{} is a very powerful typesetting program and, if used right, +file. @TeX{} is a very powerful typesetting program and, if used correctly, does an exceptionally good job. (@xref{Obtaining TeX, , How to Obtain @TeX{}}, for information on how to obtain @TeX{}.) The @code{makeinfo}, @code{texinfo-format-region}, and @code{texinfo-format-buffer} commands read the very same @@-commands in the Texinfo file as does @TeX{}, but process them differently to -make an Info file; see @ref{Create an Info File}.@refill +make an Info file (@pxref{Creating an Info File}). -@node Format with tex/texindex, Format with texi2dvi, Use TeX, Format/Print Hardcopy -@comment node-name, next, previous, up -@section Format using @code{tex} and @code{texindex} + +@node Format with tex/texindex +@section Format with @code{tex} and @code{texindex} @cindex Shell formatting with @code{tex} and @code{texindex} @cindex Formatting with @code{tex} and @code{texindex} @cindex DVI file @@ -11973,19 +12702,20 @@ tex foo.texi @noindent @TeX{} will produce a @dfn{DVI file} as well as several auxiliary files containing information for indices, cross references, etc. The DVI file (for @dfn{DeVice Independent} file) can be printed on virtually -any printe (see the following sections). +any device (see the following sections). @pindex texindex The @code{tex} formatting command itself does not sort the indices; it writes an output file of unsorted index data. (The @code{texi2dvi} -command automatically generates indices; see @ref{Format with texi2dvi,, -Format using @code{texi2dvi}}.) To generate a printed index after +command automatically generates indices; @pxref{Format with texi2dvi,, +Format with @code{texi2dvi}}.) To generate a printed index after running the @code{tex} command, you first need a sorted index to work from. The @code{texindex} command sorts indices. (The source file @file{texindex.c} comes as part of the standard Texinfo distribution, among other places.)@refill @cindex Names of index files +@cindex Index file names The @code{tex} formatting command outputs unsorted index files under names that obey a standard convention: the name of your main input file with any @samp{.tex} (or similar, @pxref{tex invocation,,, web2c, @@ -11993,14 +12723,14 @@ Web2c}) extension removed, followed by the two letter names of indices. For example, the raw index output files for the input file @file{foo.texinfo} would be @file{foo.cp}, @file{foo.vr}, @file{foo.fn}, @file{foo.tp}, @file{foo.pg} and @file{foo.ky}. Those are exactly the -arguments to give to @code{texindex}.@refill +arguments to give to @code{texindex}. @need 1000 @cindex Wildcards @cindex Globbing Instead of specifying all the unsorted index file names explicitly, you can use @samp{??} as shell wildcards and give the command in this -form:@refill +form: @example texindex foo.?? @@ -12012,13 +12742,13 @@ including any that you have defined yourself using @code{@@defindex} or @code{@@defcodeindex}. (You may execute @samp{texindex foo.??} even if there are similarly named files with two letter extensions that are not index files, such as @samp{foo.el}. The @code{texindex} -command reports but otherwise ignores such files.)@refill +command reports but otherwise ignores such files.) For each file specified, @code{texindex} generates a sorted index file whose name is made by appending @samp{s} to the input file name. The -@code{@@printindex} command knows to look for a file of that name +@code{@@printindex} command looks for a file with that name (@pxref{Printing Indices & Menus}). @code{texindex} does not alter the -raw index output file.@refill +raw index output file. After you have sorted the indices, you need to rerun the @code{tex} formatting command on the Texinfo file. This regenerates the DVI file, @@ -12027,7 +12757,7 @@ this time with up-to-date index entries. Finally, you may need to run @code{tex} one more time, to get the page numbers in the cross-references correct. -To summarize, this is a four step process: +To summarize, this is a five step process: @enumerate @item @@ -12045,43 +12775,84 @@ file, this time with indices and defined cross-references, but with page numbers for the cross-references from last time, generally incorrect. @item +Sort the indices again, with @code{texindex}. + +@item Run @code{tex} one last time. This time the correct page numbers are written for the cross-references. @end enumerate @pindex texi2dvi -Alternatively, it's a one-step process: run @code{texi2dvi}. +Alternatively, it's a one-step process: run @code{texi2dvi} +(@pxref{Format with texi2dvi}). You need not run @code{texindex} each time after you run @code{tex}. If you do not, on the next run, the @code{tex} formatting command will use whatever sorted index files happen to exist from the previous use of -@code{texindex}. This is usually ok while you are -debugging.@refill +@code{texindex}. This is usually ok while you are debugging. + +@cindex Auxiliary files, avoiding +@findex novalidate +@cindex Pointer validation, suppressing +@cindex Chapters, formatting one at a time +Sometimes you may wish to print a document while you know it is +incomplete, or to print just one chapter of a document. In that case, +the usual auxiliary files that @TeX{} creates and warnings @TeX{} gives +when cross-references are not satisfied are just nuisances. You can +avoid them with the @code{@@novalidate} command, which you must give +@emph{before} the @code{@@setfilename} command +(@pxref{setfilename,,@code{@@setfilename}}). Thus, the beginning of +your file would look approximately like this: +@example +\input texinfo +@@novalidate +@@setfilename myfile.info +@dots{} +@end example -@node Format with texi2dvi, Print with lpr, Format with tex/texindex, Format/Print Hardcopy -@comment node-name, next, previous, up -@section Format using @code{texi2dvi} +@noindent @code{@@novalidate} also turns off validation in +@code{makeinfo}, just like its @code{--no-validate} option +(@pxref{Pointer Validation}). + + +@node Format with texi2dvi +@section Format with @code{texi2dvi} @pindex texi2dvi @r{(shell script)} The @code{texi2dvi} command automatically runs both @code{tex} and @code{texindex} as many times as necessary to produce a DVI file with -up-to-date, sorted indices. It simplifies the -@code{tex}---@code{texindex}---@code{tex} sequence described in the -previous section. +sorted indices and all cross-references resolved. It simplifies the +@code{tex}---@code{texindex}---@code{tex}---@code{tex} sequence +described in the previous section. -The syntax for @code{texi2dvi} is like this (where @samp{prompt$} is your -shell prompt):@refill +To run @code{texi2dvi} on an input file @file{foo.texi}, do this (where +@samp{prompt$ } is your shell prompt): @example -prompt$ @kbd{texi2dvi @var{filename}@dots{}} +prompt$ @kbd{texi2dvi foo.texi} @end example -For a list of options, run @samp{texi2dvi --help}. +As shown in this example, the input filenames to @code{texi2dvi} must +include any extension (@samp{.texi}, @samp{.texinfo}, etc.). Under +MS-DOS and perhaps in other circumstances, you may need to run @samp{sh +texi2dvi foo.texi} instead of relying on the operating system to invoke +the shell on the @samp{texi2dvi} script. +Perhaps the most useful option to @code{texi2dvi} is +@samp{--texinfo=@var{cmd}}. This inserts @var{cmd} on a line by itself +after the @code{@@setfilename} in a temporary copy of the input file +before running @TeX{}. With this, you can specify different printing +formats, such as @code{@@smallbook} (@pxref{smallbook}), +@code{@@afourpaper} (@pxref{A4 Paper}), or @code{@@pageparams} +(@pxref{pagesizes}), without actually changing the document source. +(You can also do this on a site-wide basis with @file{texinfo.cnf}; +@pxref{Preparing for TeX,,Preparing for @TeX{}}). -@node Print with lpr, Within Emacs, Format with texi2dvi, Format/Print Hardcopy -@comment node-name, next, previous, up +For a list of other options, run @samp{texi2dvi --help}. + + +@node Print with lpr, Within Emacs, Format with texi2dvi, Hardcopy @section Shell Print Using @code{lpr -d} @pindex lpr @r{(DVI print command)} @@ -12090,7 +12861,7 @@ installation, but @samp{lpr -d} is common. The command may require the DVI file name without any extension or with a @samp{.dvi} extension. (If it is @samp{lpr}, you must include the @samp{.dvi}.) -The following commands, for example, will (probably) suffice to sort the +For example, the following commands, will (perhaps) suffice to sort the indices, format, and print the @cite{Bison Manual}: @example @@ -12116,8 +12887,41 @@ lpr -d bison.dvi @end group @end example -@node Within Emacs, Texinfo Mode Printing, Print with lpr, Format/Print Hardcopy -@comment node-name, next, previous, up +@cindex Shell printing, on MS-DOS/MS-Windows +@cindex Printing DVI files, on MS-DOS/MS-Windows +@pindex lpr@r{-d, replacements on MS-DOS/MS-Windows} +@code{lpr} is a standard program on Unix systems, but it is usually +absent on MS-DOS/MS-Windows. Some network packages come with a +program named @code{lpr}, but these are usually limited to sending files +to a print server over the network, and generally don't support the +@samp{-d} option. If you are unfortunate enough to work on one of these +systems, you have several alternative ways of printing DVI files: + +@itemize @bullet{} +@item Find and install a Unix-like @code{lpr} program, or its clone. +If you can do that, you will be able to print DVI files just like +described above. + +@item Send the DVI files to a network printer queue for DVI files. +Some network printers have special queues for printing DVI files. You +should be able to set up your network software to send files to that +queue. In some cases, the version of @code{lpr} which comes with your +network software will have a special option to send a file to specific +queues, like this: + +@example +lpr -Qdvi -hprint.server.domain bison.dvi +@end example + +@item Convert the DVI file to a Postscript or PCL file and send it to your +local printer. @xref{dvips invocation,,, dvips, Dvips}, and the man +pages for @code{dvilj}, for detailed description of these tools. Once +the DVI file is converted to the format your local printer understands +directly, just send it to the appropriate port, usually @samp{PRN}. +@end itemize + + +@node Within Emacs @section From an Emacs Shell @cindex Print, format from Emacs shell @cindex Format, print from Emacs shell @@ -12127,8 +12931,8 @@ lpr -d bison.dvi You can give formatting and printing commands from a shell within GNU Emacs. To create a shell within Emacs, type @kbd{M-x shell}. In this -shell, you can format and print the document. @xref{Format/Print -Hardcopy, , Format and Print Hardcopy}, for details.@refill +shell, you can format and print the document. @xref{Hardcopy, , Format +and Print Hardcopy}, for details. You can switch to and from the shell buffer while @code{tex} is running and do other editing. If you are formatting a long document @@ -12150,7 +12954,8 @@ lpr -d gcc.dvi and printing in Texinfo mode.@refill @end ifinfo -@node Texinfo Mode Printing, Compile-Command, Within Emacs, Format/Print Hardcopy + +@node Texinfo Mode Printing, Compile-Command, Within Emacs, Hardcopy @section Formatting and Printing in Texinfo Mode @cindex Region printing in Texinfo mode @cindex Format and print in Texinfo mode @@ -12193,7 +12998,7 @@ number shown by a preceding @kbd{C-c C-t C-q} command @item C-c C-t C-k @itemx M-x tex-kill-job -Kill the currently running @TeX{} job started by +Kill the currently running @TeX{} job started by either @code{texinfo-tex-region} or @code{texinfo-tex-buffer}, or any other process running in the Texinfo shell buffer.@refill @@ -12257,8 +13062,17 @@ emacs, The GNU Emacs Manual}), with the @kbd{M-x set-variable} command Emacs Manual}), or with your @file{.emacs} initialization file (@pxref{Init File, , , emacs, The GNU Emacs Manual}).@refill -@node Compile-Command, Requirements Summary, Texinfo Mode Printing, Format/Print Hardcopy -@comment node-name, next, previous, up +@cindex Customize Emacs package +@findex Development/Docs/Texinfo Customize group +Beginning with version 20, GNU Emacs offers a user-friendly interface, +called @dfn{Customize}, for changing values of user-definable variables. +@xref{Easy Customization, , Easy Customization Interface, emacs, The GNU +Emacs Manual}, for more details about this. The Texinfo variables can +be found in the @samp{Development/Docs/Texinfo} group, once you invoke +the @kbd{M-x customize} command. + + +@node Compile-Command, Requirements Summary, Texinfo Mode Printing, Hardcopy @section Using the Local Variables List @cindex Local variables @cindex Compile command for formatting @@ -12286,8 +13100,7 @@ This technique is most often used by programmers who also compile programs this way; see @ref{Compilation, , , emacs, The GNU Emacs Manual}.@refill -@node Requirements Summary, Preparing for TeX, Compile-Command, Format/Print Hardcopy -@comment node-name, next, previous, up +@node Requirements Summary @section @TeX{} Formatting Requirements Summary @cindex Requirements for formatting @cindex Minimal requirements for formatting @@ -12313,7 +13126,7 @@ processing and forces out unfinished pages: @end example Strictly speaking, these lines are all a Texinfo file needs to be -processed successfully by @TeX{}. +processed successfully by @TeX{}. Usually, however, the beginning includes an @code{@@settitle} command to define the title of the printed manual, an @code{@@setchapternewpage} @@ -12321,31 +13134,20 @@ command, a title page, a copyright page, and permissions. Besides an @code{@@bye}, the end of a file usually includes indices and a table of contents. (And of course most manuals contain a body of text as well.) -@iftex -For more information, see -@ref{settitle, , @code{@@settitle}}, -@ref{setchapternewpage, , @code{@@setchapternewpage}}, -@ref{Headings, ,Page Headings}, -@ref{Titlepage & Copyright Page}, -@ref{Printing Indices & Menus}, and -@ref{Contents}. -@end iftex -@noindent -@ifinfo -For more information, see@* -@ref{settitle, , @code{@@settitle}},@* -@ref{setchapternewpage, , @code{@@setchapternewpage}},@* -@ref{Headings, ,Page Headings},@* -@ref{Titlepage & Copyright Page},@* -@ref{Printing Indices & Menus}, and@* -@ref{Contents}. -@end ifinfo +For more information, see: +@itemize @bullet +@item @ref{settitle, , @code{@@settitle}} +@item @ref{setchapternewpage, , @code{@@setchapternewpage}} +@item @ref{Headings, ,Page Headings} +@item @ref{Titlepage & Copyright Page} +@item @ref{Printing Indices & Menus} +@item @ref{Contents} +@end itemize -@node Preparing for TeX, Overfull hboxes, Requirements Summary, Format/Print Hardcopy -@comment node-name, next, previous, up -@section Preparing to Use @TeX{} -@cindex Preparing to use @TeX{} +@node Preparing for TeX +@section Preparing for @TeX{} +@cindex Preparing for @TeX{} @cindex @TeX{} input initialization @cindex @code{TEXINPUTS} environment variable @vindex TEXINPUTS @@ -12378,14 +13180,14 @@ distribution. This file is needed to support the @code{@@image} command @cindex Customizing of @TeX{} for Texinfo @cindex Site-wide Texinfo configuration file Optionally, you may create an additional @file{texinfo.cnf}, and install -it as well. This file is read by @TeX{} at the @code{@@setfilename} -command (@pxref{setfilename,, @code{@@setfilename}}). You can put any -commands you like there according to local site-wide conventions, and -they will be read by @TeX{} when processing any Texinfo document. For -example, if @file{texinfo.cnf} contains the a single line -@samp{@@afourpaper} (@pxref{A4 Paper}), then all Texinfo documents will -be processed with that page size in effect. If you have nothing to put -in @file{texinfo.cnf}, you do not need to create it. +it as well. This file is read by @TeX{} when the @code{@@setfilename} +command is executed (@pxref{setfilename,, @code{@@setfilename}}). You can put any +commands you like there, according to local site-wide conventions. They +will be read by @TeX{} when processing any Texinfo document. For +example, if @file{texinfo.cnf} contains the line @samp{@@afourpaper} +(@pxref{A4 Paper}), then all Texinfo documents will be processed with +that page size in effect. If you have nothing to put in +@file{texinfo.cnf}, you do not need to create it. @vindex TEXINPUTS If neither of the above locations for these system files suffice for @@ -12420,14 +13222,45 @@ export TEXINPUTS @end group @end example +On MS-DOS/MS-Windows, you would say it like this@footnote{Note the use +of the @samp{;} character, instead of @samp{:}, as directory separator +on these systems.}: + +@example +@group +set TEXINPUTS=.;d:/home/me/mylib;c:/usr/lib/tex/macros +@end group +@end example + @noindent -This would cause @TeX{} to look for @file{\input} file first in the current -directory, indicated by the @samp{.}, then in a hypothetical user's -@file{me/mylib} directory, and finally in a system directory. +It is customary for DOS/Windows users to put such commands in the +@file{autoexec.bat} file, or in the Windows Registry.@refill +@noindent +These settings would cause @TeX{} to look for @file{\input} file first +in the current directory, indicated by the @samp{.}, then in a +hypothetical user's @file{me/mylib} directory, and finally in a system +directory @file{/usr/lib/tex/macros}. -@node Overfull hboxes, smallbook, Preparing for TeX, Format/Print Hardcopy -@comment node-name, next, previous, up +@cindex Dumping a .fmt file +@cindex Format file, dumping +Finally, you may wish to dump a @file{.fmt} file (@pxref{Memory dumps,,, +web2c, Web2c}) so that @TeX{} can load Texinfo faster. (The +disadvantage is that then updating @file{texinfo.tex} requires +redumping.) You can do this by running this command, assuming +@file{epsf.tex} is findable by @TeX{}: + +@example +initex texinfo @@dump +@end example + +(@code{@@dump} is a @TeX{} primitive.) You'll then need to move +@file{texinfo.fmt} to wherever your @code{.fmt} files are found; +typically this will be in the subdirectory @file{web2c} of your @TeX{} +installation, for example, @file{/usr/local/share/tex/web2c}. + + +@node Overfull hboxes @section Overfull ``hboxes'' @cindex Overfull @samp{hboxes} @cindex @samp{hboxes}, overfull @@ -12437,46 +13270,67 @@ directory, indicated by the @samp{.}, then in a hypothetical user's the right margin. This can occur when @TeX{} comes upon what it interprets as a long word that it cannot hyphenate, such as an electronic mail network address or a very long title. When this -happens, @TeX{} prints an error message like this:@refill +happens, @TeX{} prints an error message like this: @example -Overfull \hbox (20.76302pt too wide) +Overfull @@hbox (20.76302pt too wide) @end example +@findex hbox @noindent (In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''. -The backslash, @samp{\}, is the @TeX{} equivalent of @samp{@@}.)@refill +@samp{@@hbox} is a @TeX{} primitive not needed in the Texinfo language.) @TeX{} also provides the line number in the Texinfo source file and the text of the offending line, which is marked at all the places that -@TeX{} knows how to hyphenate words. +@TeX{} considered hyphenation. @xref{Debugging with TeX, , Catching Errors with @TeX{} Formatting}, -for more information about typesetting errors.@refill +for more information about typesetting errors. If the Texinfo file has an overfull hbox, you can rewrite the sentence so the overfull hbox does not occur, or you can decide to leave it. A small excursion into the right margin often does not matter and may not -even be noticeable.@refill +even be noticeable. + +If you have many overfull boxes and/or an antipathy to rewriting, you +can coerce @TeX{} into greatly increasing the allowable interword +spacing, thus (if you're lucky) avoiding many of the bad line breaks, +like this: + +@findex \emergencystretch +@example +@@tex +\global\emergencystretch = .9\hsize +@@end tex +@end example + +@noindent +(You can adjust the fraction as needed.) This huge value for +@code{\emergencystretch} cannot be the default, since then the typeset +output would generally be of noticeably lower quality. The default +value is @samp{.15\hsize}. @code{\hsize} is the @TeX{} dimension +containing the current line width. @cindex Black rectangle in hardcopy -@cindex Rectangle, ugly, black in hardcopy -However, unless told otherwise, @TeX{} will print a large, ugly, black -rectangle beside the line that contains the overfull hbox. This is so -you will notice the location of the problem if you are correcting a -draft.@refill +@cindex Rectangle, black in hardcopy +@cindex Box, ugly black in hardcopy +@cindex Ugly black rectangles in hardcopy +For what overfull boxes you have, however, @TeX{} will print a large, +ugly, black rectangle beside the line that contains the overfull hbox +unless told otherwise. This is so you will notice the location of the +problem if you are correcting a draft. -@need 1000 @findex finalout To prevent such a monstrosity from marring your final printout, write the following in the beginning of the Texinfo file on a line of its own, -before the @code{@@titlepage} command:@refill +before the @code{@@titlepage} command: @example @@finalout @end example -@node smallbook, A4 Paper, Overfull hboxes, Format/Print Hardcopy -@comment node-name, next, previous, up + +@node smallbook @section Printing ``Small'' Books @findex smallbook @cindex Small book size @@ -12495,43 +13349,35 @@ file, before the title page:@refill @end example @noindent -(Since regular sized books are often about 7 by 9.25 inches, this -command might better have been called the @code{@@regularbooksize} -command, but it came to be called the @code{@@smallbook} command by -comparison to the 8.5 by 11 inch format.)@refill +(Since many books are about 7 by 9.25 inches, this command might better +have been called the @code{@@regularbooksize} command, but it came to be +called the @code{@@smallbook} command by comparison to the 8.5 by 11 inch format.) If you write the @code{@@smallbook} command between the start-of-header and end-of-header lines, the Texinfo mode @TeX{} region formatting command, @code{texinfo-tex-region}, will format the region in ``small'' book size (@pxref{Start of Header}).@refill -The Free Software Foundation distributes printed copies of @cite{The GNU -Emacs Manual} and other manuals in the ``small'' book size. -@xref{smallexample & smalllisp, , @code{@@smallexample} and -@code{@@smalllisp}}, for information about commands that make it easier -to produce examples for a smaller manual.@refill +@xref{small}, for information about +commands that make it easier to produce examples for a smaller manual. -Alternatively, to avoid embedding this physical paper size in your -document, use @code{texi2dvi} to format your document (@pxref{Format -with texi2dvi}), and supply @samp{-t @@smallbook} as an argument. Then -other people do not have to change the document source file to format it -differently. +@xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for +@TeX{}}, for other ways to format with @code{@@smallbook} that do not +require changing the source file. -@node A4 Paper, Cropmarks and Magnification, smallbook, Format/Print Hardcopy -@comment node-name, next, previous, up +@node A4 Paper @section Printing on A4 Paper @cindex A4 paper, printing on @cindex Paper size, European A4 @cindex European A4 paper @findex afourpaper -You can tell @TeX{} to typeset a document for printing on European size +You can tell @TeX{} to format a document for printing on European size A4 paper with the @code{@@afourpaper} command. Write the command on a -line by itself between @code{@@iftex} and @code{@@end iftex} lines near -the beginning of the Texinfo file, before the title page:@refill - -For example, this is how you would write the header for this manual:@refill +line by itself near the beginning of the Texinfo file, before the title +page. For example, this is how you would write the header for this +manual: @example @group @@ -12539,35 +13385,70 @@ For example, this is how you would write the header for this manual:@refill @@c %**start of header @@setfilename texinfo @@settitle Texinfo -@@syncodeindex vr fn -@@iftex @@afourpaper -@@end iftex @@c %**end of header @end group @end example -Alternatively, to avoid embedding this physical paper size in your -document, use @code{texi2dvi} to format your document (@pxref{Format -with texi2dvi}), and supply @samp{-t @@afourpaper} as an argument. Then -other people do not have to change the document source file to format it -differently. +@xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for +@TeX{}}, for other ways to format with @code{@@afourpaper} that do not +require changing the source file. -@pindex texinfo.cnf -Another alternative: put the @code{@@afourpaper} command in the file -@file{texinfo.cnf} that @TeX{} will read. (No need for @code{@@iftex} -there.) This will automatically typeset all the Texinfo documents at -your site with that paper size in effect. +@findex afourlatex +You may or may not prefer the formatting that results from the command +@code{@@afourlatex}. There's also @code{@@afourwide} for A4 paper in +wide format. -@node Cropmarks and Magnification, , A4 Paper, Format/Print Hardcopy -@comment node-name, next, previous, up -@section Cropmarks and Magnification +@node pagesizes +@section @code{@@pagesizes} [@var{width}][, @var{height}]: Custom page sizes +@findex pagesizes +@cindex Custom page sizes +@cindex Page sizes, customized +@cindex Text width and height +@cindex Width of text area +@cindex Height of text area +@cindex Depth of text area + +You can explicitly specify the height and (optionally) width of the main +text area on the page with the @code{@@pagesizes} command. Write this +on a line by itself near the beginning of the Texinfo file, before the +title page. The height comes first, then the width if desired, +separated by a comma. Examples: + +@example +@@pagesizes 200mm,150mm @c for b5 paper +@end example +@noindent and +@example +@@pagesizes 11.5in @c for legal paper +@end example + +@cindex B5 paper, printing on +@cindex Legal paper, printing on +This would be reasonable for printing on B5-size paper. To emphasize, +this command specifies the size of the @emph{text area}, not the size of +the paper (which is 250@dmn{mm} by 177@dmn{mm} for B5, 14@dmn{in} by +8.5@dmn{in} for legal). + +@cindex Margins on page, not controllable +To make more elaborate changes, such as changing any of the page +margins, you must define a new command in @file{texinfo.tex} (or +@file{texinfo.cnf}, @pxref{Preparing for TeX,,Preparing for @TeX{}}). +@xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for +@TeX{}}, for other ways to specify @code{@@pagesizes} that do not +require changing the source file. + +@code{@@pagesizes} is ignored by @code{makeinfo}. + + +@node Cropmarks and Magnification +@section Cropmarks and Magnification @findex cropmarks @cindex Cropmarks for printing @cindex Printing cropmarks -You can attempt to direct @TeX{} to print cropmarks at the corners of +You can (attempt to) direct @TeX{} to print cropmarks at the corners of pages with the @code{@@cropmarks} command. Write the @code{@@cropmarks} command on a line by itself between @code{@@iftex} and @code{@@end iftex} lines near the beginning of the Texinfo file, before the title @@ -12587,8 +13468,8 @@ book set to 7 by 9.25 inches with the @code{@@smallbook} command. (Printers will not produce cropmarks for regular sized output that is printed on regular sized paper.) Since different printing machines work in different ways, you should explore the use of this command with a -spirit of adventure. You may have to redefine the command in the -@file{texinfo.tex} definitions file.@refill +spirit of adventure. You may have to redefine the command in +@file{texinfo.tex}. @findex mag @r{(@TeX{} command)} @cindex Magnified printing @@ -12604,7 +13485,7 @@ write this command between @code{@@tex} and @code{@@end tex} Follow the @code{\mag} command with an @samp{=} and then a number that is 1000 times the magnification you desire. For example, to print pages at 1.2 normal size, write the following near the beginning of the -Texinfo file, before the title page:@refill +Texinfo file, before the title page: @example @group @@ -12615,27 +13496,69 @@ Texinfo file, before the title page:@refill @end example With some printing technologies, you can print normal-sized copies that -look better than usual by using a larger-than-normal master.@refill +look better than usual by giving a larger-than-normal master to your +print shop. They do the reduction, thus effectively increasing the +resolution. -Depending on your system, @code{\mag} may not work or may work only at -certain magnifications. Be prepared to experiment.@refill +Depending on your system, DVI files prepared with a +nonstandard-@code{\mag} may not print or may print only with certain +magnifications. Be prepared to experiment. -@node Create an Info File, Install an Info File, Format/Print Hardcopy, Top -@comment node-name, next, previous, up -@chapter Creating an Info File + +@node PDF Output +@section PDF Output +@cindex PDF output + +@pindex pdftex +You can generate a PDF output file from Texinfo source by using the +@command{pdftex} program to process your file instead of plain +@command{tex}. Just run @samp{pdftex foo.texi} instead of @samp{tex +foo.texi}, or give the @samp{--pdf} option to @command{texi2dvi}. + +PDF stands for Portable Document Format, and was invented by Adobe +Systems. The +@uref{http://www.adobe.com/prodindex/acrobat/adobepdf.html, file format +definition} is freely available, as is a +@uref{http://www.foolabs.com/xpdf/, free viewer} for the X window +system. Since PDF is a binary format, there is no @samp{@@ifpdf} or +@samp{@@pdf} command by analogy with the other output formats. + +Despite the `portable' in the name, PDF files are nowhere near as +portable in practice as the plain ASCII formats (Info, HTML) Texinfo +also supports (portability relative to DVI is arguable). They also tend +to be much larger and do not support the bitmap fonts used by @TeX{} (by +default) very well. Nevertheless, a PDF file does preserve an actual +printed document on a screen as faithfully as possible, unlike HTML, +say, so have their place. + +PDF support in Texinfo is fairly rudimentary. + + +@node Creating and Installing Info Files +@chapter Creating and Installing Info Files + +This chapter describes how to create and install info files. @xref{Info +Files}, for general information about the file format itself. + + +@menu +* Creating an Info File:: +* Install an Info File:: +@end menu + +@node Creating an Info File +@section Creating an Info File @cindex Creating an Info file -@cindex Info, creating an on-line file +@cindex Info, creating an online file @cindex Formatting a file for Info -@code{makeinfo} is a utility that converts a Texinfo file into an Info -file; @code{texinfo-format-region} and @code{texinfo-format-buffer} are -GNU Emacs functions that do the same.@refill - -A Texinfo file must contain an @code{@@setfilename} line near its -beginning, otherwise the Info formatting commands will fail. +@code{makeinfo} is a program that converts a Texinfo file into an Info +file, HTML file, or plain text. @code{texinfo-format-region} and +@code{texinfo-format-buffer} are GNU Emacs functions that convert +Texinfo to Info. -For information on installing the Info file in the Info system, see -@ref{Install an Info File}.@refill +For information on installing the Info file in the Info system, +@pxref{Install an Info File}. @menu * makeinfo advantages:: @code{makeinfo} provides better error checking. @@ -12649,21 +13572,22 @@ For information on installing the Info file in the Info system, see * Batch Formatting:: How to format for Info in Emacs Batch mode. * Tag and Split Files:: How tagged and split files help Info to run better. +* makeinfo html:: Generating HTML output. @end menu -@node makeinfo advantages, Invoking makeinfo, Create an Info File, Create an Info File -@ifinfo -@heading @code{makeinfo} Preferred -@end ifinfo + +@node makeinfo advantages +@subsection @code{makeinfo} Preferred The @code{makeinfo} utility creates an Info file from a Texinfo source file more quickly than either of the Emacs formatting commands and provides better error messages. We recommend it. @code{makeinfo} is a C program that is independent of Emacs. You do not need to run Emacs to use @code{makeinfo}, which means you can use @code{makeinfo} on machines -that are too small to run Emacs. You can run @code{makeinfo} in -any one of three ways: from an operating system shell, from a shell -inside Emacs, or by typing a key command in Texinfo mode in Emacs. +that are too small to run Emacs. You can run @code{makeinfo} in any one +of three ways: from an operating system shell, from a shell inside +Emacs, or by typing the @kbd{C-c C-m C-r} or the @kbd{C-c C-m C-b} +command in Texinfo mode in Emacs. @refill The @code{texinfo-format-region} and the @code{texinfo-format-buffer} @@ -12671,13 +13595,12 @@ commands are useful if you cannot run @code{makeinfo}. Also, in some circumstances, they format short regions or buffers more quickly than @code{makeinfo}.@refill -@node Invoking makeinfo, makeinfo options, makeinfo advantages, Create an Info File -@section Running @code{makeinfo} from a Shell +@node Invoking makeinfo +@subsection Running @code{makeinfo} from a Shell To create an Info file from a Texinfo file, type @code{makeinfo} followed by the name of the Texinfo file. Thus, to create the Info file for Bison, type the following to the shell: -is the prompt):@refill @example makeinfo bison.texinfo @@ -12698,9 +13621,9 @@ makeinfo --version @end ifinfo -@node makeinfo options, Pointer Validation, Invoking makeinfo, Create an Info File +@node makeinfo options @comment node-name, next, previous, up -@section Options for @code{makeinfo} +@subsection Options for @code{makeinfo} @cindex @code{makeinfo} options @cindex Options for @code{makeinfo} @@ -12737,24 +13660,37 @@ The options are: Cause the variable @var{var} to be defined. This is equivalent to @code{@@set @var{var}} in the Texinfo file (@pxref{set clear value}). +@item --commands-in-node-names +@opindex --commands-in-node-names +Allow @code{@@}-commands in node names. This is not recommended, as it +can probably never be implemented in @TeX{}. It also makes +@code{makeinfo} much slower. Also, this option is ignored when +@samp{--no-validate} is used. @xref{Pointer Validation}, for more +details. + @item --error-limit=@var{limit} +@itemx -e @var{limit} @opindex --error-limit=@var{limit} +@opindex -e @var{limit} Set the maximum number of errors that @code{makeinfo} will report before exiting (on the assumption that continuing would be useless); default 100. -@need 150 @item --fill-column=@var{width} +@itemx -f @var{width} @opindex --fill-column=@var{width} +@opindex -f @var{width} Specify the maximum number of columns in a line; this is the right-hand edge of a line. Paragraphs that are filled will be filled to this width. (Filling is the process of breaking up and connecting lines so that lines are the same length as or shorter than the number specified as the fill column. Lines are broken between words.) The default value -is 72. +is 72. Ignored with @samp{--html}. @item --footnote-style=@var{style} +@itemx -s @var{style} @opindex --footnote-style=@var{style} +@opindex -s @var{style} Set the footnote style to @var{style}, either @samp{end} for the end node style (the default) or @samp{separate} for the separate node style. The value set by this option overrides the value set in a Texinfo file @@ -12762,45 +13698,78 @@ by an @code{@@footnotestyle} command (@pxref{Footnotes}). When the footnote style is @samp{separate}, @code{makeinfo} makes a new node containing the footnotes found in the current node. When the footnote style is @samp{end}, @code{makeinfo} places the footnote references at -the end of the current node. +the end of the current node. Ignored with @samp{--html}. @item --force +@itemx -F @opindex --force +@opindex -F Ordinarily, if the input file has errors, the output files are not created. With this option, they are preserved. @item --help +@itemx -h @opindex --help +@opindex -h Print a usage message listing all available options, then exit successfully. +@item --html +Generate HTML output rather than Info. @xref{makeinfo html}. + @item -I @var{dir} @opindex -I @var{dir} -Add @code{dir} to the directory search list for finding files that are -included using the @code{@@include} command. By default, -@code{makeinfo} searches only the current directory. +Append @var{dir} to the directory search list for finding files that +are included using the @code{@@include} command. By default, +@code{makeinfo} searches only the current directory. If @var{dir} is +not given, the current directory @file{.} is appended. Note that +@var{dir} can actually be a list of several directories separated by the +usual path separator character (@samp{:} on Unix, @samp{;} on +MS-DOS/MS-Windows). + +@item --macro-expand=@var{file} +@itemx -E @var{file} +Output the Texinfo source with all the macros expanded to the named +file. Normally, the results of macro expansion are used internally by +@code{makeinfo} and then discarded. This option is used by +@command{texi2dvi} if you are using an old version of @file{texinfo.tex} +that does not support @code{@@macro}. @item --no-headers @opindex --no-headers -Do not include menus or node lines in the output. This results in an -@sc{ascii} file that you cannot read in Info since it does not contain -the requisite nodes or menus. It is primarily useful to extract certain -pieces of a manual into separate files to be included in a distribution, -such as @file{INSTALL} files. +@cindex Plain text output +@cindex ASCII text output +@cindex Generating plain text files +@cindex @file{INSTALL} file, generating +For Info output, do not include menus or node lines in the output and +write to standard output (unless @option{--output} is specified). This +results in an @sc{ascii} file that you cannot read in Info since it does +not contain the requisite nodes or menus. It is primarily useful to +extract certain pieces of a manual into separate files to be included in +a distribution, such as @file{INSTALL} files. + +@cindex Navigation links, omitting +For HTML output, if @samp{--no-split} is also specified, do not include a +navigation links at the top of each node. @xref{makeinfo html}. @item --no-split @opindex --no-split +@cindex Splitting of output files +@cindex Output file splitting Suppress the splitting stage of @code{makeinfo}. By default, large output files (where the size is greater than 70k bytes) are split into -smaller subfiles, each one approximately 50k bytes. +smaller subfiles. For Info output, each one is approximately 50k bytes. +For HTML output, each file contains one node (@pxref{makeinfo html}). @item --no-pointer-validate @itemx --no-validate @opindex --no-pointer-validate @opindex --no-validate -Suppress the pointer-validation phase of @code{makeinfo}. Normally, -after a Texinfo file is processed, some consistency checks are made to -ensure that cross references can be resolved, etc. -@xref{Pointer Validation}.@refill +@cindex Pointer validation, suppressing +Suppress the pointer-validation phase of @code{makeinfo}. This can also +be done with the @code{@@novalidate} command (@pxref{Use TeX,,Use +@TeX{}}). Normally, after a Texinfo file is processed, some consistency +checks are made to ensure that cross references can be resolved, etc. +@xref{Pointer Validation}. @item --no-warn @opindex --no-warn @@ -12809,6 +13778,10 @@ want this if the file you are creating has examples of Texinfo cross references within it, and the nodes that are referenced do not actually exist. +@item --number-sections +@opindex --number-sections +Output chapter, section, and appendix numbers as in printed manuals. + @item --no-number-footnotes @opindex --no-number-footnotes Suppress automatic footnote numbering. By default, @code{makeinfo} @@ -12822,15 +13795,20 @@ current footnote number to 1 at the start of each node. Specify that the output should be directed to @var{file} and not to the file name specified in the @code{@@setfilename} command found in the Texinfo source (@pxref{setfilename}). If @var{file} is @samp{-}, output -goes to standard output and @samp{--no-split} is implied. +goes to standard output and @samp{--no-split} is implied. For split +HTML output, @var{file} is the name of the output file for the top node +(@pxref{makeinfo html}). @item -P @var{dir} @opindex -P @var{dir} -Prepend @code{dir} to the directory search list for @code{@@include}. +Prepend @var{dir} to the directory search list for @code{@@include}. +If @var{dir} is not given, the current directory @file{.} is prepended. See @samp{-I} for more details. @item --paragraph-indent=@var{indent} +@itemx -p @var{indent} @opindex --paragraph-indent=@var{indent} +@opindex -p @var{indent} Set the paragraph indentation style to @var{indent}. The value set by this option overrides the value set in a Texinfo file by an @code{@@paragraphindent} command (@pxref{paragraphindent}). The value @@ -12844,11 +13822,13 @@ Preserve any existing indentation at the starts of paragraphs. Delete any existing indentation. @item @var{num} -Indent each paragraph by that number of spaces. +Indent each paragraph by @var{num} spaces. @end table @item --reference-limit=@var{limit} +@itemx -r @var{limit} @opindex --reference-limit=@var{limit} +@opindex -r @var{limit} Set the value of the number of references to a node that @code{makeinfo} will make without reporting a warning. If a node has more than this number of references in it, @code{makeinfo} will make the @@ -12865,21 +13845,24 @@ Normally, @code{makeinfo} only outputs messages if there are errors or warnings. @item --version +@itemx -V @opindex --version +@opindex -V Print the version number, then exit successfully. @end table -@node Pointer Validation, makeinfo in Emacs, makeinfo options, Create an Info File -@section Pointer Validation +@node Pointer Validation +@subsection Pointer Validation @cindex Pointer validation with @code{makeinfo} @cindex Validation of pointers -If you do not suppress pointer-validation, @code{makeinfo} will check -the validity of the final Info file. Mostly, this means ensuring that -nodes you have referenced really exist. Here is a complete list of what -is checked:@refill +If you do not suppress pointer validation with the @samp{--no-validate} +option or the @code{@@novalidate} command in the source file (@pxref{Use +TeX,,Use @TeX{}}), @code{makeinfo} will check the validity of the final +Info file. Mostly, this means ensuring that nodes you have referenced +really exist. Here is a complete list of what is checked: @enumerate @item @@ -12889,15 +13872,16 @@ node in the current file and is not an external reference such as to @item In every node, if the `Previous' node is different from the `Up' node, -then the `Previous' node must also be pointed to by a `Next' node.@refill +then the node pointed to by the `Previous' field must have a `Next' +field which points back to this node.@refill @item Every node except the `Top' node must have an `Up' pointer.@refill @item -The node referenced by an `Up' pointer must contain a reference to the -current node in some manner other than through a `Next' reference. -This includes menu entries and cross references.@refill +The node referenced by an `Up' pointer must itself reference the current +node through a menu item, unless the node referenced by `Up' +has the form `(@var{file})'. @item If the `Next' reference of a node is not the same as the `Next' reference @@ -12905,10 +13889,62 @@ of the `Up' reference, then the node referenced by the `Next' pointer must have a `Previous' pointer that points back to the current node. This rule allows the last node in a section to point to the first node of the next chapter.@refill + +@item +Every node except `Top' should be referenced by at least one other node, +either via the `Previous' or `Next' links, or via a menu or a +cross-reference.@refill @end enumerate -@node makeinfo in Emacs, texinfo-format commands, Pointer Validation, Create an Info File -@section Running @code{makeinfo} inside Emacs +@cindex @@-commands in @@node, limited support +Some Texinfo documents might fail during the validation phase because +they use commands like @code{@@value} and @code{@@definfoenclose} in +node definitions and cross-references inconsistently. Consider the +following example: + +@example +@group +@@set nodename Node 1 + +@@node @@value@{nodename@}, Node 2, Top, Top + +This is node 1. + +@@node Node 2, , Node 1, Top + +This is node 2. +@end group +@end example + +@noindent +Here, the node ``Node 1'' was referenced both verbatim and through +@code{@@value}. + +By default, @code{makeinfo} fails such cases, because node names are not +fully expanded until they are written to the output file. You should +always try to reference nodes consistently; e.g., in the above example, +the second @code{@@node} line should have also used @code{@@value}. +However, if, for some reason, you @emph{must} reference node names +inconsistently, and @code{makeinfo} fails to validate the file, you can +use the @samp{--commands-in-node-names} option to force @code{makeinfo} +to perform the expensive expansion of all node names it finds in the +document. This might considerably slow down the program, though; +twofold increase in conversion time was measured for large documents +such as the Jargon file. + +@cindex @@value in @@node lines +The support for @code{@@}-commands in @code{@@node} directives is not +general enough to be freely used. For example, if the example above +redefined @code{nodename} somewhere in the document, @code{makeinfo} +will fail to convert it, even if invoked with the +@samp{--commands-in-node-names} option. + +@samp{--commands-in-node-names} has no effect if the @samp{--no-validate} +option is given. + + +@node makeinfo in Emacs +@subsection Running @code{makeinfo} inside Emacs @cindex Running @code{makeinfo} in Emacs @cindex @code{makeinfo} inside Emacs @cindex Shell, running @code{makeinfo} in @@ -12959,8 +13995,8 @@ output.@refill @item C-c C-m C-k @itemx M-x makeinfo-kill-job @findex makeinfo-kill-job -Kill the current running @code{makeinfo} job created by -@code{makeinfo-region} or @code{makeinfo-buffer}.@refill +Kill the current running @code{makeinfo} job +(from @code{makeinfo-region} or @code{makeinfo-buffer}).@refill @item C-c C-m C-l @itemx M-x makeinfo-recenter-output-buffer @@ -12993,8 +14029,8 @@ For example, you could write the following in your @file{.emacs} file:@refill @c three references to the same named manual, which looks strange. @iftex For more information, see @ref{makeinfo options, , Options for -@code{makeinfo}}, as well as ``Editing Variable Values,''``Examining and -Setting Variables,'' and ``Init File'' in the @cite{The GNU Emacs +@code{makeinfo}}, as well as ``Editing Variable Values,'' ``Examining +and Setting Variables,'' and ``Init File'' in @cite{The GNU Emacs Manual}. @end iftex @noindent @@ -13006,9 +14042,9 @@ For more information, see@* @ref{makeinfo options, , Options for @code{makeinfo}}. @end ifinfo -@node texinfo-format commands, Batch Formatting, makeinfo in Emacs, Create an Info File +@node texinfo-format commands @comment node-name, next, previous, up -@section The @code{texinfo-format@dots{}} Commands +@subsection The @code{texinfo-format@dots{}} Commands @findex texinfo-format-region @findex texinfo-format-buffer @@ -13043,9 +14079,9 @@ procedures are described in an appendix; see @ref{Catching Mistakes}. However, the @code{makeinfo} program is often faster and provides better error checking (@pxref{makeinfo in Emacs}).@refill -@node Batch Formatting, Tag and Split Files, texinfo-format commands, Create an Info File +@node Batch Formatting @comment node-name, next, previous, up -@section Batch Formatting +@subsection Batch Formatting @cindex Batch formatting for Info @cindex Info batch formatting @@ -13075,9 +14111,9 @@ you can continue working in it. (When you run @code{texinfo-format-region} or @code{texinfo-format-buffer}, you cannot use that Emacs for anything else until the command finishes.)@refill -@node Tag and Split Files, , Batch Formatting, Create an Info File +@node Tag and Split Files @comment node-name, next, previous, up -@section Tag Files and Split Files +@subsection Tag Files and Split Files @cindex Making a tag table automatically @cindex Tag table, making automatically @@ -13093,8 +14129,8 @@ bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the large Info file into shorter @dfn{indirect} subfiles of about 50,000 bytes each. Big files are split into smaller files so that Emacs does not need to make a large buffer to hold the whole of a large Info -file; instead, Emacs allocates just enough memory for the small, split -off file that is needed at the time. This way, Emacs avoids wasting +file; instead, Emacs allocates just enough memory for the small, split-off +file that is needed at the time. This way, Emacs avoids wasting memory when you run Info. (Before splitting was implemented, Info files were always kept short and @dfn{include files} were designed as a way to create a single, large printed manual out of the smaller Info @@ -13104,16 +14140,16 @@ Reference Manual}, in which each chapter is a separate file.)@refill When a file is split, Info itself makes use of a shortened version of the original file that contains just the tag table and references to -the files that were split off. The split off files are called +the files that were split off. The split-off files are called @dfn{indirect} files.@refill -The split off files have names that are created by appending @w{@samp{-1}}, +The split-off files have names that are created by appending @w{@samp{-1}}, @w{@samp{-2}}, @w{@samp{-3}} and so on to the file name specified by the @code{@@setfilename} command. The shortened version of the original file continues to have the name specified by @code{@@setfilename}.@refill At one stage in writing this document, for example, the Info file was saved -as @file{test-texinfo} and that file looked like this:@refill +as the file @file{test-texinfo} and that file looked like this:@refill @example @group @@ -13143,7 +14179,7 @@ Node: conventions^?6855 @noindent (But @file{test-texinfo} had far more nodes than are shown here.) Each of -the split off, indirect files, @file{test-texinfo-1}, +the split-off, indirect files, @file{test-texinfo-1}, @file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file after the line that says @samp{Indirect:}. The tag table is listed after the line that says @samp{Tag table:}. @refill @@ -13153,7 +14189,7 @@ records the cumulative number of bytes in the preceding indirect files, not counting the file list itself, the tag table, or the permissions text in each file. In the tag table, the number following the node name records the location of the beginning of the node, in bytes from the -beginning.@refill +beginning of the (unsplit) output. If you are using @code{texinfo-format-buffer} to create Info files, you may want to run the @code{Info-validate} command. (The @@ -13165,9 +14201,50 @@ validate the structure of the nodes, see @ref{Using Info-validate}.@refill -@node Install an Info File, Command List, Create an Info File, Top -@comment node-name, next, previous, up -@chapter Installing an Info File +@node makeinfo html +@subsection Generating HTML +@cindex HTML + +As an alternative to the normal Info format output you can use the +@samp{--html} option to generate output in HTML format, for installation +on a web site (for example). In this release, HTML output from +@code{makeinfo} is monolithic, splitting the output by chapter or node +is not supported. We hope to implement this feature soon. + +The HTML output file is named according to @code{@@setfilename}, but +with any @samp{.info} extension replaced with @samp{.html}. + +Texinfo input marked up with the @code{@@ifhtml} command will produce +output only with the @samp{--html} option supplied. Input marked up +with the @code{@@html} is passed literally to the output (suppressing +the normal escaping of input @samp{<}, @samp{>} and @samp{&} characters +which have special significance in HTML). + +The @samp{--footnote-style} option is currently ignored for HTML output; +footnotes are hyperlinked at the end of the output file. + +The HTML generated is mostly standard (i.e., HTML 2.0, RFC1866). The +exception is that HTML 3.2 tables are generated from the +@code{@@multitable} command, but tagged to degrade as well as possible +in browsers without table support. Please report output from an +error-free run of @code{makeinfo} which violates the HTML 3.2 DTD as a +bug. + +Navigation bars are inserted at the start of nodes, similarly to Info +output. The @samp{--no-headers} option will suppress this if used with +@samp{--no-split}. Header @code{<link>} elements in split output can +support info-like navigation with browsers like Lynx and @w{Emacs W3} +which implement this @w{HTML 1.0} feature. You still won't normally get +the multi-file regexp and index search facilities provided by Info +readers. Otherwise, hyperlinks are generated from Texinfo commands +where appropriate. @samp{@@xref} commands to other documents are +generated assuming the other document is available in HTML form too, and +@samp{.html} is appended to the @samp{@@xref} Info file name. This +presumably will often not work. + + +@node Install an Info File +@section Installing an Info File @cindex Installing an Info file @cindex Info file installation @cindex @file{dir} directory for Info installation @@ -13177,7 +14254,7 @@ Info files using the standalone Info program or the Info reader built into Emacs. (@inforef{Top, info, info}, for an introduction to Info.) @menu -* Directory file:: The top level menu for all Info files. +* Directory File:: The top level menu for all Info files. * New Info File:: Listing a new info file. * Other Info Directories:: How to specify Info files that are located in other directories. @@ -13186,10 +14263,9 @@ into Emacs. (@inforef{Top, info, info}, for an introduction to Info.) * Invoking install-info:: @code{install-info} options. @end menu -@node Directory file, New Info File, Install an Info File, Install an Info File -@ifinfo -@heading The @file{dir} File -@end ifinfo + +@node Directory File +@subsection The Directory File @file{dir} For Info to work, the @file{info} directory must contain a file that serves as a top level directory for the Info system. By convention, @@ -13204,7 +14280,6 @@ this:@refill @example @group * Menu: - * Info: (info). Documentation browsing system. * Emacs: (emacs). The extensible, self-documenting text editor. @@ -13234,21 +14309,17 @@ File: emacs Node: Top, Up: (DIR), Next: Distrib @end example @noindent -(Note that in this case, the @file{dir} file name is written in upper -case letters---it can be written in either upper or lower case. Info -has a feature that it will change the case of the file name to lower -case if it cannot find the name as written.)@refill -@c !!! Can any file name be written in upper or lower case, -@c or is dir a special case? -@c Yes, apparently so, at least with Gillespie's Info. --rjc 24mar92 +In this case, the @file{dir} file name is written in upper case +letters---it can be written in either upper or lower case. This is not +true in general, it is a special case for @file{dir}. -@node New Info File, Other Info Directories, Directory file, Install an Info File -@section Listing a New Info File +@node New Info File +@subsection Listing a New Info File @cindex Adding a new info file @cindex Listing a new info file @cindex New info file, listing it in @file{dir} file -@cindex Info file, listing new one +@cindex Info file, listing a new @cindex @file{dir} file listing To add a new Info file to your system, you must write a menu entry to @@ -13268,25 +14339,26 @@ followed by a period. The third part is the description. The name of an Info file often has a @file{.info} extension. Thus, the Info file for GDB might be called either @file{gdb} or @file{gdb.info}. The Info reader programs automatically try the file name both with and -without @file{.info}; so it is better to avoid clutter and not to write -@samp{.info} explicitly in the menu entry. For example, the GDB menu -entry should use just @samp{gdb} for the file name, not @samp{gdb.info}. +without @file{.info}@footnote{On MS-DOS/MS-Windows systems, Info will +try the @file{.inf} extension as well.}; so it is better to avoid +clutter and not to write @samp{.info} explicitly in the menu entry. For +example, the GDB menu entry should use just @samp{gdb} for the file +name, not @samp{gdb.info}. -@node Other Info Directories, Installing Dir Entries, New Info File, Install an Info File -@comment node-name, next, previous, up -@section Info Files in Other Directories +@node Other Info Directories +@subsection Info Files in Other Directories @cindex Installing Info in another directory @cindex Info installed in another directory @cindex Another Info directory +@cindex @file{dir} files and Info directories If an Info file is not in the @file{info} directory, there are three ways to specify its location:@refill -@itemize @bullet +@enumerate @item -Write the pathname in the @file{dir} file as the second part of the -menu.@refill +Write the pathname in the @file{dir} file as the second part of the menu. @item If you are using Emacs, list the name of the file in a second @file{dir} @@ -13294,58 +14366,63 @@ file, in its directory; and then add the name of that directory to the @code{Info-directory-list} variable in your personal or site initialization file. -This tells Emacs where to look for @file{dir} files. Emacs merges the -files named @file{dir} from each of the listed directories. (In Emacs -version 18, you can set the @code{Info-directory} variable to the name -of only one directory.)@refill +This variable tells Emacs where to look for @file{dir} files (the files +must be named @file{dir}). Emacs merges the files named @file{dir} from +each of the listed directories. (In Emacs version 18, you can set the +@code{Info-directory} variable to the name of only one +directory.)@refill @item Specify the Info directory name in the @code{INFOPATH} environment variable in your @file{.profile} or @file{.cshrc} initialization file. (Only you and others who set this environment variable will be able to -find Info files whose location is specified this way.)@refill -@end itemize +find Info files whose location is specified this way.) +@end enumerate -For example, to reach a test file in the @file{/home/bob/manuals} +For example, to reach a test file in the @file{/home/bob/info} directory, you could add an entry like this to the menu in the -@file{dir} file:@refill +standard @file{dir} file:@refill @example -* Test: (/home/bob/manuals/info-test). Bob's own test file. +* Test: (/home/bob/info/info-test). Bob's own test file. @end example @noindent In this case, the absolute file name of the @file{info-test} file is written as the second part of the menu entry.@refill -@vindex Info-directory-list Alternatively, you could write the following in your @file{.emacs} file:@refill +@vindex Info-directory-list @example @group +(require 'info) (setq Info-directory-list - '("/home/bob/manuals" - "/usr/local/info")) + (cons (expand-file-name "/home/bob/info") Info-directory-list)) @end group @end example -@c reworded to avoid overfill hbox This tells Emacs to merge the @file{dir} file from the -@file{/home/bob/manuals} directory with the @file{dir} file from the -@file{/usr/local/info} directory. Info will list the -@file{/home/bob/manuals/info-test} file as a menu entry in the -@file{/home/bob/manuals/dir} file.@refill +@file{/home/bob/info} directory with the system @file{dir} file. Info +will list the @file{/home/bob/info/info-test} file as a menu entry in +the @file{/home/bob/info/dir} file. Emacs does the merging only +when @kbd{M-x info} is first run, so if you want to set +@code{Info-directory-list} in an Emacs session where you've already run +@code{info}, you must @code{(setq Info-dir-contents nil)} to force Emacs +to recompose the @file{dir} file. @vindex INFOPATH Finally, you can tell Info where to look by setting the @code{INFOPATH} -environment variable in your @file{.cshrc} or @file{.profile} file. If -you use a Bourne-compatible shell such as @code{sh} or @code{bash} for -your shell command interpreter, you set the @code{INFOPATH} environment -variable in the @file{.profile} initialization file; but if you use -@code{csh} or @code{tcsh}, you must set the variable in the -@file{.cshrc} initialization file. The two types of shells use -different syntax. +environment variable in your shell startup file, such as @file{.cshrc}, +@file{.profile} or @file{autoexec.bat}. If you use a Bourne-compatible +shell such as @code{sh} or @code{bash} for your shell command +interpreter, you set the @code{INFOPATH} environment variable in the +@file{.profile} initialization file; but if you use @code{csh} or +@code{tcsh}, you set the variable in the @file{.cshrc} initialization +file. On MS-DOS/MS-Windows systems, you must set @code{INFOPATH} in +your @file{autoexec.bat} file or in the Registry. Each type of shell +uses a different syntax. @itemize @bullet @item @@ -13353,7 +14430,7 @@ In a @file{.cshrc} file, you could set the @code{INFOPATH} variable as follows:@refill @smallexample -setenv INFOPATH .:~/manuals:/usr/local/emacs/info +setenv INFOPATH .:~/info:/usr/local/emacs/info @end smallexample @item @@ -13361,21 +14438,35 @@ In a @file{.profile} file, you would achieve the same effect by writing:@refill @smallexample -INFOPATH=.:$HOME/manuals:/usr/local/emacs/info +INFOPATH=.:$HOME/info:/usr/local/emacs/info export INFOPATH @end smallexample + +@item +@pindex autoexec.bat +In a @file{autoexec.bat} file, you write this command@footnote{Note the +use of @samp{;} as the directory separator, and a different syntax for +using values of other environment variables.}: + +@smallexample +set INFOPATH=.;%HOME%/info;c:/usr/local/emacs/info +@end smallexample @end itemize @noindent The @samp{.} indicates the current directory as usual. Emacs uses the @code{INFOPATH} environment variable to initialize the value of Emacs's -own @code{Info-directory-list} variable. - -@cindex @samp{:} @r{last in @code{INFOPATH}} -However you set @code{INFOPATH}, if its last character is a colon, this +own @code{Info-directory-list} variable. The stand-alone Info reader +merges any files named @file{dir} in any directory listed in the +@env{INFOPATH} variable into a single menu presented to you in the node +called @samp{(dir)Top}. + +@cindex @samp{:} @r{last in @env{INFOPATH}} +However you set @env{INFOPATH}, if its last character is a +colon@footnote{On MS-DOS/MS-Windows systems, use semi-colon instead.}, this is replaced by the default (compiled-in) path. This gives you a way to augment the default path with new directories without having to list all -the standard places. For example (using @code{sh} syntax: +the standard places. For example (using @code{sh} syntax): @example INFOPATH=/local/info: @@ -13386,9 +14477,16 @@ export INFOPATH will search @file{/local/info} first, then the standard directories. Leading or doubled colons are not treated specially. +@cindex @file{dir} file, creating your own +When you create your own @file{dir} file for use with +@code{Info-directory-list} or @env{INFOPATH}, it's easiest to start by +copying an existing @file{dir} file and replace all the text after the +@samp{* Menu:} with your desired entries. That way, the punctuation and +special CTRL-_ characters that Info needs will be present. + @node Installing Dir Entries, Invoking install-info, Other Info Directories, Install an Info File -@section Installing Info Directory Files +@subsection Installing Info Directory Files When you install an Info file onto your system, you can use the program @code{install-info} to update the Info directory file @file{dir}. @@ -13398,11 +14496,12 @@ after copying the Info file into its proper installed location. @findex dircategory @findex direntry In order for the Info file to work with @code{install-info}, you should -use the commands @code{@@dircategory} and @code{@@direntry} in the -Texinfo source file. Use @code{@@direntry} to specify the menu entry to -add to the Info directory file, and use @code{@@dircategory} to specify -which part of the Info directory to put it in. Here is how these -commands are used in this manual: +use the commands @code{@@dircategory} and +@code{@@direntry}@dots{}@code{@@end direntry} in the Texinfo source +file. Use @code{@@direntry} to specify the menu entries to add to the +Info directory file, and use @code{@@dircategory} to specify which part +of the Info directory to put it in. Here is how these commands are used +in this manual: @smallexample @@dircategory Texinfo documentation system @@ -13434,38 +14533,50 @@ command. If you use them later on in the input, @code{install-info} will not notice them. If you use @code{@@dircategory} more than once in the Texinfo source, -each usage specifies one category; the new menu entry is added to the -Info directory file in each of the categories you specify. If you use -@code{@@direntry} more than once, each usage specifies one menu entry; -each of these menu entries is added to the directory in each of the -specified categories. +each usage specifies the `current' category; any subsequent +@code{@@direntry} commands will add to that category. +Here are some recommended @code{@@dircategory} categories: `GNU +packages', `GNU programming tools', `GNU programming documentation', +`GNU Emacs Lisp', `GNU libraries', `Linux', `TeX', `Individual +utilities'. The idea is to include the `invoking' node for every +program installed by a package under `Individual utilities', and an +entry for the manual as a whole in the appropriate other category. -@node Invoking install-info, , Installing Dir Entries, Install an Info File -@section Invoking install-info + +@node Invoking install-info +@subsection Invoking install-info @pindex install-info @code{install-info} inserts menu entries from an Info file into the top-level @file{dir} file in the Info system (see the previous sections for an explanation of how the @file{dir} file works). It's most often -run as part of software installation, or when constructing a dir file +run as part of software installation, or when constructing a @file{dir} file for all manuals on a system. Synopsis: @example install-info [@var{option}]@dots{} [@var{info-file} [@var{dir-file}]] @end example -If @var{info-file} or @var{dir-file} are not specified, the various -options (described below) that define them must be. There are no -compile-time defaults, and standard input is never used. -@code{install-info} can read only one info file and write only one dir -file per invocation. +If @var{info-file} or @var{dir-file} are not specified, the options +(described below) that define them must be. There are no compile-time +defaults, and standard input is never used. @code{install-info} can +read only one Info file and write only one @file{dir} file per invocation. @cindex @file{dir}, created by @code{install-info} If @var{dir-file} (however specified) does not exist, @code{install-info} creates it if possible (with no entries). +@cindex Compressed files, reading +@cindex Dir files, compressed +If any input file is compressed with @code{gzip} (@pxref{Invoking +gzip,,,gzip, Gzip}), @code{install-info} automatically uncompresses it +for reading. And if @var{dir-file} is compressed, @code{install-info} +also automatically leaves it compressed after writing any changes. +If @var{dir-file} itself does not exist, @code{install-info} tries to +open @file{@var{dir-file}.gz}. + Options: @table @code @@ -13476,12 +14587,16 @@ name in the entry in @var{dir-file} must be @var{info-file} (except for an optional @samp{.info} in either one). Don't insert any new entries. @item --dir-file=@var{name} +@itemx -d @var{name} @opindex --dir-file=@var{name} +@opindex -d @var{name} Specify file name of the Info directory file. This is equivalent to using the @var{dir-file} argument. @item --entry=@var{text} +@itemx -e @var{text} @opindex --entry=@var{text} +@opindex -e @var{text} Insert @var{text} as an Info directory entry; @var{text} should have the form of an Info menu item line plus zero or more extra lines starting with whitespace. If you specify more than one entry, they are all @@ -13489,17 +14604,24 @@ added. If you don't specify any entries, they are determined from information in the Info file itself. @item --help +@itemx -h @opindex --help +@opindex -h Display a usage message listing basic usage and all available options, then exit successfully. @item --info-file=@var{file} +@itemx -i @var{file} @opindex --info-file=@var{file} +@opindex -i @var{file} Specify Info file to install in the directory. -This is equivalent to using the @var{info-file} argument. +Equivalent to using the @var{info-file} argument. @item --info-dir=@var{dir} +@itemx -D @var{dir} @opindex --info-dir=@var{dir} +@opindex -D @var{dir} +Specify the directory where @file{dir} resides. Equivalent to @samp{--dir-file=@var{dir}/dir}. @item --item=@var{text} @@ -13512,33 +14634,40 @@ a menu item. Suppress warnings. @item --remove +@itemx -r @opindex --remove +@opindex -r Same as @samp{--delete}. @item --section=@var{sec} +@itemx -s @var{sec} @opindex --section=@var{sec} +@opindex -s @var{sec} Put this file's entries in section @var{sec} of the directory. If you specify more than one section, all the entries are added in each of the sections. If you don't specify any sections, they are determined from information in the Info file itself. @item --version +@itemx -V @opindex --version +@opindex -V @cindex version number, finding Display version information and exit successfully. @end table -@node Command List, Tips, Install an Info File, Top +@node Command List @appendix @@-Command List @cindex Alphabetical @@-command list @cindex List of @@-commands @cindex @@-command list +@cindex Reference to @@-commands Here is an alphabetical list of the @@-commands in Texinfo. Square brackets, @t{[}@w{ }@t{]}, indicate optional arguments; an ellipsis, -@samp{@dots{}}, indicates repeated text.@refill +@samp{@dots{}}, indicates repeated text. @sp 1 @table @code @@ -13575,10 +14704,10 @@ Indicate to @TeX{} that an immediately preceding period, question mark, exclamation mark, or colon does not end a sentence. Prevent @TeX{} from inserting extra whitespace as it does at the end of a sentence. The command has no effect on the Info file output. -@xref{Not Ending a Sentence}.@refill +@xref{Not Ending a Sentence}. @item @@= -Generate a macro (bar) accent over the next character, as in @=o. +Generate a macron (bar) accent over the next character, as in @=o. @xref{Inserting Accents}. @item @@? @@ -13603,7 +14732,7 @@ Stands for a left brace, @samp{@{}. Stands for a right-hand brace, @samp{@}}.@* @xref{Braces Atsigns, , Inserting @@ and braces}. -@item @@= +@item @@~ Generate a tilde accent over the next character, as in @~N. @xref{Inserting Accents}. @@ -13612,15 +14741,27 @@ Generate a tilde accent over the next character, as in @~N. Generate the uppercase and lowercase Scandinavian A-ring letters, respectively: @AA{}, @aa{}. @xref{Inserting Accents}. +@item @@acronym@{@var{abbrev}@} +Tag @var{abbrev} as an acronym, that is, an abbreviation written in all +capital letters, such as `NASA'. @xref{acronym,, @code{acronym}}. + @item @@AE@{@} @itemx @@ae@{@} Generate the uppercase and lowercase AE ligatures, respectively: @AE{}, @ae{}. @xref{Inserting Accents}. -@item @@afourpaper -Change page dimensions for the A4 paper size. -Only allowed inside @code{@@iftex} @dots{} @code{@@end iftex}. -@xref{A4 Paper}. +@item @@afourlatex +@itemx @@afourpaper +@itemx @@afourwide +Change page dimensions for the A4 paper size. @xref{A4 Paper}. + +@item @@alias @var{new}=@var{existing} +Make the command @samp{@@@var{new}} an alias for the existing command +@samp{@@@var{existing}}. @xref{alias}. + +@item @@anchor@{@var{name}@} +Define @var{name} as the current location for use as a cross-reference +target. @xref{anchor,, @code{@@anchor}}. @item @@appendix @var{title} Begin an appendix. The title appears in the table @@ -13724,10 +14865,14 @@ and @code{@@end ifset} commands, and preventing Highlight text that is an expression, a syntactically complete token of a program, or a program name. @xref{code, , @code{@@code}}.@refill +@item @@command@{@var{command-name}@} +Indicate a command name, such as @command{ls}. +@xref{command,, @code{@@command}}. + @item @@comment @var{comment} Begin a comment in Texinfo. The rest of the line does not appear in either the Info file or the printed manual. A synonym for @code{@@c}. -@xref{Comments, , Comments}.@refill +@xref{Comments}. @item @@contents Print a complete table of contents. Has no effect in Info, which uses @@ -13767,12 +14912,9 @@ entity, and its arguments, if any. @xref{Definition Commands}.@refill Define a new index and its indexing command. Print entries in a roman font. @xref{New Indices, , Defining New Indices}.@refill -@c Unused so far as I can see and unsupported by makeinfo -- karl, 15sep96. -@item @@definfoenclose @var{new-command}, @var{before}, @var{after}, -Create new @@-command for Info that marks text by enclosing it in -strings that precede and follow the text. Write definition inside of -@code{@@ifinfo} @dots{} @code{@@end ifinfo}. @xref{Customized -Highlighting}.@refill +@item @@definfoenclose @var{newcmd}, @var{before}, @var{after}, +Create new @@-command @var{newcmd} for Info that marks text by enclosing +it in strings that precede and follow the text. @xref{definfoenclose}. @item @@defivar @var{class} @var{instance-variable-name} @itemx @@defivarx @var{class} @var{instance-variable-name} @@ -13781,8 +14923,8 @@ object-oriented programming. The command is equivalent to @samp{@@defcv @{Instance Variable@} @dots{}}. @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}. -@item @@defmac @var{macro-name} @var{arguments}@dots{} -@itemx @@defmacx @var{macro-name} @var{arguments}@dots{} +@item @@defmac @var{macroname} @var{arguments}@dots{} +@itemx @@defmacx @var{macroname} @var{arguments}@dots{} Format a description for a macro. The command is equivalent to @samp{@@deffn Macro @dots{}}. @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}. @@ -13801,7 +14943,7 @@ Format a description for an operation in object-oriented programming. @code{@@defop} takes as arguments the overall name of the category of operation, the name of the class of the operation, the name of the operation, and its arguments, if any. @xref{Definition -Commands}, and @ref{deffnx,, Def Cmds in Detail}. +Commands}, and @ref{Abstract Objects}. @item @@defopt @var{option-name} @itemx @@defoptx @var{option-name} @@ -13820,7 +14962,7 @@ and @ref{deffnx,, Def Cmds in Detail}. Format a description for a data type. @code{@@deftp} takes as arguments the category, the name of the type (which is a word like @samp{int} or @samp{float}), and then the names of attributes of objects of that type. -@xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}. +@xref{Definition Commands}, and @ref{Data Types}. @item @@deftypefn @var{classification} @var{data-type} @var{name} @var{arguments}@dots{} @itemx @@deftypefnx @var{classification} @var{data-type} @var{name} @var{arguments}@dots{} @@ -13834,16 +14976,29 @@ entity, and its arguments, if any. @xref{Definition Commands}, and @itemx @@deftypefunx @var{data-type} @var{function-name} @var{arguments}@dots{} Format a description for a function in a typed language. The command is equivalent to @samp{@@deftypefn Function @dots{}}. -@xref{Definition Commands}, -and @ref{deffnx,, Def Cmds in Detail}. +@xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}. + +@item @@deftypeivar @var{class} @var{data-type} @var{variable-name} +@itemx @@deftypeivarx @var{class} @var{data-type} @var{variable-name} +Format a description for a typed instance variable in object-oriented +programming. @xref{Definition Commands}, and @ref{Abstract Objects}. @item @@deftypemethod @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{} @itemx @@deftypemethodx @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{} Format a description for a typed method in object-oriented programming. -Takes as arguments the name of the class of the method, the return type -of the method, the name of the method, and its arguments, if any. @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}. +@item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{} +@itemx @@deftypeopx @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{} +Format a description for a typed operation in object-oriented programming. +@xref{Definition Commands}, and @ref{Abstract Objects}. + +@item @@deftypevar @var{data-type} @var{variable-name} +@itemx @@deftypevarx @var{data-type} @var{variable-name} +Format a description for a variable in a typed language. The command is +equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition +Commands}, and @ref{deffnx,, Def Cmds in Detail}. + @item @@deftypevr @var{classification} @var{data-type} @var{name} @itemx @@deftypevrx @var{classification} @var{data-type} @var{name} Format a description for something like a variable in a typed @@ -13852,12 +15007,6 @@ classification of entity being described, the type, and the name of the entity. @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}. -@item @@deftypevar @var{data-type} @var{variable-name} -@itemx @@deftypevarx @var{data-type} @var{variable-name} -Format a description for a variable in a typed language. The command is -equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition -Commands}, and @ref{deffnx,, Def Cmds in Detail}. - @item @@defun @var{function-name} @var{arguments}@dots{} @itemx @@defunx @var{function-name} @var{arguments}@dots{} Format a description for functions. The command is equivalent to @@ -13877,7 +15026,7 @@ as arguments the category of the entity and the name of the entity. @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}. -@item @@detailmenu@{@} +@item @@detailmenu Avoid @code{makeinfo} confusion stemming from the detailed node listing in a master menu. @xref{Master Menu Parts}. @@ -13890,22 +15039,29 @@ Specify a part of the Info directory menu where this file's entry should go. @xref{Installing Dir Entries}. @item @@direntry -Begin the Info directory menu entry for this file. -@xref{Installing Dir Entries}. +Begin the Info directory menu entry for this file. Pair with +@code{@@end direntry}. @xref{Installing Dir Entries}. -@need 100 @item @@display -Begin a kind of example. Indent text, do not fill, do not select a -new font. Pair with @code{@@end display}. @xref{display, , -@code{@@display}}.@refill +Begin a kind of example. Like @code{@@example} (indent text, do not +fill), but do not select a new font. Pair with @code{@@end display}. +@xref{display, , @code{@@display}}. @item @@dmn@{@var{dimension}@} Format a unit of measure, as in 12@dmn{pt}. Causes @TeX{} to insert a thin space before @var{dimension}. No effect in Info. -@xref{dmn, , @code{@@dmn}}.@refill +@xref{dmn, , @code{@@dmn}}. + +@item @@documentencoding @var{enc} +Declare the input encoding as @var{enc}. +@xref{documentencoding,, @code{@@documentencoding}}. + +@item @@documentlanguage @var{CC} +Declare the document language as the two-character ISO-639 abbreviation +@var{CC}. @xref{documentlanguage,, @code{@@documentlanguage}}. @item @@dotaccent@{@var{c}@} -Generate a dot accent over the character @var{c}, as in @dotaccent{oo}. +Generate a dot accent over the character @var{c}, as in @dotaccent{o}. @xref{Inserting Accents}. @item @@dots@{@} @@ -13914,9 +15070,8 @@ Insert an ellipsis: @samp{@dots{}}. @item @@email@{@var{address}[, @var{displayed-text}]@} Indicate an electronic mail address. -@xref{email, , @code{@@email}}.@refill +@xref{email, , @code{@@email}}. -@need 100 @item @@emph@{@var{text}@} Highlight @var{text}; text is displayed in @emph{italics} in printed output, and surrounded by asterisks in Info. @xref{Emphasis, , @@ -13926,18 +15081,20 @@ Emphasizing Text}. Ends @var{environment}, as in @samp{@@end example}. @xref{Formatting Commands,,@@-commands}. +@item @@env@{@var{environment-variable}@} +Indicate an environment variable name, such as @env{PATH}. +@xref{env,, @code{@@env}}. + @item @@enddots@{@} Generate an end-of-sentence of ellipsis, like this @enddots{} @xref{dots,,@code{@@dots@{@}}}. -@need 100 @item @@enumerate [@var{number-or-letter}] Begin a numbered list, using @code{@@item} for each entry. Optionally, start list with @var{number-or-letter}. Pair with @code{@@end enumerate}. @xref{enumerate, , @code{@@enumerate}}.@refill -@need 100 @item @@equiv@{@} Indicate to the reader the exact equivalence of two forms with a glyph: @samp{@equiv{}}. @xref{Equivalence}.@refill @@ -13962,6 +15119,10 @@ Begin an example. Indent text, do not fill, and select fixed-width font. Pair with @code{@@end example}. @xref{example, , @code{@@example}}.@refill +@item @@exampleindent @var{indent} +Indent example-like environments by @var{indent} number of spaces +(perhaps 0). @xref{exampleindent,, Paragraph Indenting}. + @item @@exclamdown@{@} Produce an upside-down exclamation point. @xref{Inserting Accents}. @@ -13982,12 +15143,10 @@ Highlight the name of a file, buffer, node, or directory. @xref{file, , Prevent @TeX{} from printing large black warning rectangles beside over-wide lines. @xref{Overfull hboxes}.@refill -@need 100 @item @@findex @var{entry} Add @var{entry} to the index of functions. @xref{Index Entries, , Defining the Entries of an Index}.@refill -@need 200 @item @@flushleft @itemx @@flushright Left justify every line but leave the right end ragged. @@ -13996,7 +15155,6 @@ Leave font as is. Pair with @code{@@end flushleft}. @xref{flushleft & flushright, , @code{@@flushleft} and @code{@@flushright}}.@refill -@need 200 @item @@footnote@{@var{text-of-footnote}@} Enter a footnote. Footnote text is printed at the bottom of the page by @TeX{}; Info may format in either `End' node or `Separate' node style. @@ -14008,10 +15166,9 @@ node style or @samp{separate} for the separate node style. @xref{Footnotes}.@refill @item @@format -Begin a kind of example. Like @code{@@example} or @code{@@display}, -but do not narrow the margins and do not select the fixed-width font. -Pair with @code{@@end format}. @xref{example, , -@code{@@example}}.@refill +Begin a kind of example. Like @code{@@display}, but do not narrow the +margins. Pair with @code{@@end format}. @xref{example,, +@code{@@example}}. @item @@ftable @var{formatting-command} Begin a two-column table, using @code{@@item} for each entry. @@ -14154,16 +15311,15 @@ respectively: @L{}, @l{}. @item @@lisp Begin an example of Lisp code. Indent text, do not fill, and select -fixed-width font. Pair with @code{@@end lisp}. @xref{Lisp Example, , -@code{@@lisp}}.@refill +fixed-width font. Pair with @code{@@end lisp}. @xref{lisp, , @code{@@lisp}}. @item @@lowersections Change subsequent chapters to sections, sections to subsections, and so on. @xref{Raise/lower sections, , @code{@@raisesections} and @code{@@lowersections}}.@refill -@item @@macro @var{macro-name} @{@var{params}@} -Define a new Texinfo command @code{@@@var{macro-name}@{@var{params}@}}. +@item @@macro @var{macroname} @{@var{params}@} +Define a new Texinfo command @code{@@@var{macroname}@{@var{params}@}}. Only supported by @code{makeinfo} and @code{texi2dvi}. @xref{Defining Macros}. @@ -14194,7 +15350,7 @@ Start a new page in a printed manual if fewer than @var{n} mils (thousandths of an inch) remain on the current page. @xref{need, , @code{@@need}}.@refill -@item @@node @var{name, next, previous, up} +@item @@node @var{name}, @var{next}, @var{previous}, @var{up} Define the beginning of a new node in Info, and serve as a locator for references for @TeX{}. @xref{node, , @code{@@node}}.@refill @@ -14202,6 +15358,10 @@ references for @TeX{}. @xref{node, , @code{@@node}}.@refill Prevent text from being indented as if it were a new paragraph. @xref{noindent, , @code{@@noindent}}.@refill +@item @@novalidate +Suppress validation of node references, omit creation of auxiliary files +with @TeX{}. Use before @code{@@setfilename}. @xref{Pointer Validation}. + @item @@O@{@} @itemx @@o@{@} Generate the uppercase and lowercase O-with-slash letters, respectively: @@ -14218,15 +15378,21 @@ How to Make Your Own Headings}.@refill Generate the uppercase and lowercase OE ligatures, respectively: @OE{}, @oe{}. @xref{Inserting Accents}. +@item @@option@{@var{option-name}@} +Indicate a command-line option, such as @option{-l} or @option{--help}. +@xref{option,, @code{@@option}}. + @item @@page Start a new page in a printed manual. No effect in Info. @xref{page, , @code{@@page}}.@refill +@item @@pagesizes [@var{width}][, @var{height}] +Change page dimensions. @xref{pagesizes}. + @item @@paragraphindent @var{indent} -Indent paragraphs by @var{indent} number of spaces; delete indentation -if the value of @var{indent} is 0; and do not change indentation if -@var{indent} is @code{asis}. @xref{paragraphindent, , Paragraph -Indenting}.@refill +Indent paragraphs by @var{indent} number of spaces (perhaps 0); preserve +source file indentation if @var{indent} is @code{asis}. +@xref{paragraphindent,, Paragraph Indenting}. @item @@pindex @var{entry} Add @var{entry} to the index of programs. @xref{Index Entries, , Defining @@ -14266,7 +15432,6 @@ or imaginary work. Write command on a line of its own. Pair with @code{@@end quotation}. @xref{quotation, , @code{@@quotation}}.@refill -@need 100 @item @@r@{@var{text}@} Print @var{text} in @r{roman} font. No effect in Info. @xref{Fonts}.@refill @@ -14276,20 +15441,17 @@ Change subsequent sections to chapters, subsections to sections, and so on. @xref{Raise/lower sections, , @code{@@raisesections} and @code{@@lowersections}}.@refill -@need 300 @item @@ref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@} Make a reference. In a printed manual, the reference does not start with a `See'. Follow command with a punctuation mark. Only the first argument is mandatory. @xref{ref, , @code{@@ref}}.@refill -@need 300 @item @@refill In Info, refill and indent the paragraph after all the other processing has been done. No effect on @TeX{}, which always refills. This command is no longer needed, since all formatters now automatically refill. @xref{Refilling Paragraphs}.@refill -@need 300 @item @@result@{@} Indicate the result of an expression to the reader with a special glyph: @samp{@result{}}. @xref{result, , @code{@@result}}.@refill @@ -14319,17 +15481,26 @@ Make @var{flag} active, causing the Texinfo formatting commands to format text between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end ifset} commands. Optionally, set value of @var{flag} to @var{string}. -@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill +@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}. @item @@setchapternewpage @var{on-off-odd} Specify whether chapters start on new pages, and if so, whether on odd-numbered (right-hand) new pages. @xref{setchapternewpage, , -@code{@@setchapternewpage}}.@refill +@code{@@setchapternewpage}}. + +@item @@setcontentsaftertitlepage +Put the table of contents after the @samp{@@end titlepage} even if the +@code{@@contents} command is not there. @xref{Contents}. @item @@setfilename @var{info-file-name} Provide a name to be used by the Info file. This command is essential for @TeX{} formatting as well, even though it produces no output. -@xref{setfilename, , @code{@@setfilename}}.@refill +@xref{setfilename, , @code{@@setfilename}}. + +@item @@setshortcontentsaftertitlepage +Place the short table of contents after the @samp{@@end titlepage} +command even if the @code{@@shortcontents} command is not there. +@xref{Contents}. @item @@settitle @var{title} Provide a title for page headers in a printed manual. @@ -14341,40 +15512,45 @@ menus rather than tables of contents. A synonym for @code{@@summarycontents}. @xref{Contents, , Generating a Table of Contents}.@refill -@item @@shorttitlepage@{@var{title}@} +@item @@shorttitlepage @var{title} Generate a minimal title page. @xref{titlepage,,@code{@@titlepage}}. -@need 400 @item @@smallbook Cause @TeX{} to produce a printed manual in a 7 by 9.25 inch format rather than the regular 8.5 by 11 inch format. @xref{smallbook, , -Printing Small Books}. Also, see @ref{smallexample & smalllisp, , -@code{@@smallexample} and @code{@@smalllisp}}.@refill +Printing Small Books}. Also, see @ref{small}. + +@item @@smalldisplay +Begin a kind of example. Like @code{@@smallexample} (indent text, no +filling), but do not select the fixed-width font. In @code{@@smallbook} +format, print text in a smaller font than with @code{@@display}. Pair +with @code{@@end smalldisplay}. @xref{small}. -@need 400 @item @@smallexample Indent text to indicate an example. Do not fill, select fixed-width font. In @code{@@smallbook} format, print text in a smaller font than with @code{@@example}. Pair with @code{@@end smallexample}. -@xref{smallexample & smalllisp, , @code{@@smallexample} and -@code{@@smalllisp}}.@refill +@xref{small}. + +@item @@smallformat +Begin a kind of example. Like @code{@@smalldisplay}, but do not narrow +the margins and do not select the fixed-width font. +In @code{@@smallbook} format, print text in a smaller font than +with @code{@@format}. Pair with @code{@@end smallformat}. +@xref{small}. -@need 400 @item @@smalllisp Begin an example of Lisp code. Indent text, do not fill, select fixed-width font. In @code{@@smallbook} format, print text in a -smaller font. Pair with @code{@@end smalllisp}. @xref{smallexample & -smalllisp, , @code{@@smallexample} and @code{@@smalllisp}}.@refill +smaller font. Pair with @code{@@end smalllisp}. @xref{small}. -@need 700 @item @@sp @var{n} Skip @var{n} blank lines. @xref{sp, , @code{@@sp}}.@refill @item @@ss@{@} Generate the German sharp-S es-zet letter, @ss{}. @xref{Inserting Accents}. -@need 700 -@item @@strong @var{text} +@item @@strong @{@var{text}@} Emphasize @var{text} by typesetting it in a @strong{bold} font for the printed manual and by surrounding it with asterisks for Info. @xref{emph & strong, , Emphasizing Text}.@refill @@ -14416,19 +15592,16 @@ menus rather than tables of contents. A synonym for @code{@@shortcontents}. @xref{Contents, , Generating a Table of Contents}.@refill -@need 300 @item @@syncodeindex @var{from-index} @var{into-index} Merge the index named in the first argument into the index named in the second argument, printing the entries from the first index in @code{@@code} font. @xref{Combining Indices}.@refill -@need 300 @item @@synindex @var{from-index} @var{into-index} Merge the index named in the first argument into the index named in the second argument. Do not change the font of @var{from-index} entries. @xref{Combining Indices}.@refill -@need 100 @item @@t@{@var{text}@} Print @var{text} in a @t{fixed-width}, typewriter-like font. No effect in Info. @xref{Fonts}.@refill @@ -14436,7 +15609,6 @@ No effect in Info. @xref{Fonts}.@refill @item @@tab Separate columns in a multitable. @xref{Multitable Rows}. -@need 400 @item @@table @var{formatting-command} Begin a two-column table, using @code{@@item} for each entry. Write each first column entry on the same line as @code{@@item}. First @@ -14480,21 +15652,18 @@ Not relevant to Info, which does not have title pages. @xref{title subtitle author, , The @code{@@title} @code{@@subtitle} and @code{@@author} Commands}.@refill -@need 400 @item @@titlefont@{@var{text}@} In a printed manual, print @var{text} in a larger than normal font. Not relevant to Info, which does not have title pages. @xref{titlefont center sp, , The @code{@@titlefont} @code{@@center} and @code{@@sp} Commands}.@refill -@need 300 @item @@titlepage Indicate to Texinfo the beginning of the title page. Write command on a line of its own. Pair with @code{@@end titlepage}. Nothing between @code{@@titlepage} and @code{@@end titlepage} appears in Info. @xref{titlepage, , @code{@@titlepage}}.@refill -@need 150 @item @@today@{@} Insert the current date, in `1 Jan 1900' style. @xref{Custom Headings, , How to Make Your Own Headings}.@refill @@ -14544,9 +15713,9 @@ chapter. The title appears in the table of contents of a printed manual. In Info, the title is underlined with periods. @xref{subsubsection, , The `subsub' Commands}.@refill -@item @@uref@{@var{url}[, @var{displayed-text}@} +@item @@uref@{@var{url}[, @var{displayed-text}][, @var{replacement}@} Define a cross reference to an external uniform resource locator for the -World Wide Web. @xref{url, , @code{@@url}}.@refill +World Wide Web. @xref{uref, , @code{@@uref}}.@refill @item @@url@{@var{url}@} Indicate text that is a uniform resource locator for the World Wide @@ -14566,12 +15735,10 @@ Highlight a metasyntactic variable, which is something that stands for another piece of text. @xref{var, , Indicating Metasyntactic Variables}.@refill -@need 400 @item @@vindex @var{entry} Add @var{entry} to the index of variables. @xref{Index Entries, , Defining the Entries of an Index}.@refill -@need 400 @item @@vskip @var{amount} In a printed manual, insert whitespace so as to push text on the remainder of the page towards the bottom of the page. Used in @@ -14580,7 +15747,6 @@ formatting the copyright page with the argument @samp{0pt plus only in contexts ignored for Info. @xref{Copyright & Permissions, , The Copyright Page and Printed Permissions}.@refill -@need 400 @item @@vtable @var{formatting-command} Begin a two-column table, using @code{@@item} for each entry. Automatically enter each of the items in the first column into the @@ -14588,13 +15754,11 @@ index of variables. Pair with @code{@@end vtable}. The same as @code{@@table}, except for indexing. @xref{ftable vtable, , @code{@@ftable} and @code{@@vtable}}.@refill -@need 400 @item @@w@{@var{text}@} Prevent @var{text} from being split across two lines. Do not end a paragraph that uses @code{@@w} with an @code{@@refill} command. @xref{w, , @code{@@w}}.@refill -@need 400 @item @@xref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@} Make a reference that starts with `See' in a printed manual. Follow command with a punctuation mark. Only the first argument is @@ -14602,7 +15766,7 @@ mandatory. @xref{xref, , @code{@@xref}}.@refill @end table -@node Tips, Sample Texinfo File, Command List, Top +@node Tips @appendix Tips and Hints Here are some tips for writing Texinfo documentation:@refill @@ -14665,9 +15829,8 @@ Lisp. @item Write the indexing commands that refer to a whole section immediately after the section command, and write the indexing commands that refer to -the paragraph before the paragraph. +a paragraph before that paragraph. -@need 1000 In the example that follows, a blank line comes after the index entry for ``Leaping'': @@ -15045,7 +16208,7 @@ Write notes for yourself at the very end of a Texinfo file after the @end itemize -@node Sample Texinfo File, Sample Permissions, Tips, Top +@node Sample Texinfo File @appendix A Sample Texinfo File @cindex Sample Texinfo file, no comments @@ -15123,9 +16286,10 @@ manual. @end example -@node Sample Permissions, Include Files, Sample Texinfo File, Top +@node Sample Permissions @appendix Sample Permissions @cindex Permissions +@cindex Sample permissions @cindex Copying permissions Texinfo files should contain sections that tell the readers that they @@ -15149,7 +16313,7 @@ of how the copying conditions provide you with rights. @refill @node Inserting Permissions, ifinfo Permissions, Sample Permissions, Sample Permissions @ifinfo -@appendixsec Inserting Permissions +@section Inserting Permissions @end ifinfo In a Texinfo file, the first @code{@@ifinfo} section usually begins @@ -15183,18 +16347,18 @@ To make it simple to insert a permission notice into each section of the Texinfo file, sample permission notices for each section are reproduced in full below.@refill -Note that you may need to specify the correct name of a section -mentioned in the permission notice. For example, in @cite{The GDB -Manual}, the name of the section referring to the General Public -License is called the ``GDB General Public License'', but in the -sample shown below, that section is referred to generically as the -``GNU General Public License''. If the Texinfo file does not carry a -copy of the General Public License, leave out the reference to it, but -be sure to include the rest of the sentence.@refill +You may need to specify the correct name of a section mentioned in the +permission notice. For example, in @cite{The GDB Manual}, the name of +the section referring to the General Public License is called the ``GDB +General Public License'', but in the sample shown below, that section is +referred to generically as the ``GNU General Public License''. If the +Texinfo file does not carry a copy of the General Public License, leave +out the reference to it, but be sure to include the rest of the +sentence. @node ifinfo Permissions, Titlepage Permissions, Inserting Permissions, Sample Permissions @comment node-name, next, previous, up -@appendixsec @samp{ifinfo} Copying Permissions +@section @samp{ifinfo} Copying Permissions @cindex @samp{ifinfo} permissions In the @code{@@ifinfo} section of a Texinfo file, the standard Free @@ -15203,7 +16367,7 @@ Software Foundation permission notice reads as follows:@refill @example This file documents @dots{} -Copyright 1998 Free Software Foundation, Inc. +Copyright 1999 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and @@ -15235,7 +16399,7 @@ translation approved by the Free Software Foundation. @node Titlepage Permissions, , ifinfo Permissions, Sample Permissions @comment node-name, next, previous, up -@appendixsec Titlepage Copying Permissions +@section Titlepage Copying Permissions @cindex Titlepage permissions In the @code{@@titlepage} section of a Texinfo file, the standard Free @@ -15265,7 +16429,7 @@ translation approved by the Free Software Foundation. @end example -@node Include Files, Headings, Sample Permissions, Top +@node Include Files @appendix Include Files @cindex Include files @@ -15290,7 +16454,7 @@ conveniently small parts.@refill @end menu @node Using Include Files, texinfo-multiple-files-update, Include Files, Include Files -@appendixsec How to Use Include Files +@section How to Use Include Files @findex include To include another file within a Texinfo file, write the @@ -15331,7 +16495,7 @@ Texinfo mode command, @code{texinfo-multiple-files-update}, that is designed for @code{@@include} files.@refill @node texinfo-multiple-files-update, Include File Requirements, Using Include Files, Include Files -@appendixsec @code{texinfo-multiple-files-update} +@section @code{texinfo-multiple-files-update} @findex texinfo-multiple-files-update GNU Emacs Texinfo mode provides the @code{texinfo-multiple-files-update} @@ -15407,7 +16571,7 @@ updates @strong{every} pointer and menu in @strong{all} the files and then inser master menu.@refill @node Include File Requirements, Sample Include File, texinfo-multiple-files-update, Include Files -@appendixsec Include File Requirements +@section Include File Requirements @cindex Include file requirements @cindex Requirements for include files @@ -15433,7 +16597,7 @@ should @emph{not} contain any nodes besides the single `Top' node. The them.@refill @node Sample Include File, Include Files Evolution, Include File Requirements, Include Files -@appendixsec Sample File with @code{@@include} +@section Sample File with @code{@@include} @cindex Sample @code{@@include} file @cindex Include file sample @cindex @code{@@include} file sample @@ -15463,7 +16627,7 @@ would insert a main or master menu:@refill @group @@page @@vskip 0pt plus 1filll -Copyright @@copyright@{@} 1998 Free Software Foundation, Inc. +Copyright @@copyright@{@} 1999 Free Software Foundation, Inc. @@end titlepage @end group @@ -15504,7 +16668,7 @@ The full contents of @file{concept-index.texinfo} might be as simple as this: @example @group -@@node Concept Index, , Second, Top +@@node Concept Index @@unnumbered Concept Index @@printindex cp @@ -15518,7 +16682,7 @@ files.@refill @node Include Files Evolution, , Sample Include File, Include Files @comment node-name, next, previous, up -@appendixsec Evolution of Include Files +@section Evolution of Include Files When Info was first created, it was customary to create many small Info files on one subject. Each Info file was formatted from its own @@ -15557,7 +16721,7 @@ you can write menus and cross references without naming the different Texinfo files.@refill -@node Headings, Catching Mistakes, Include Files, Top +@node Headings @appendix Page Headings @cindex Headings @cindex Footings @@ -15616,7 +16780,7 @@ right part is set flushright.@refill @node Heading Format, Heading Choice, Headings Introduced, Headings @comment node-name, next, previous, up -@appendixsec Standard Heading Formats +@section Standard Heading Formats Texinfo provides two standard heading formats, one for manuals printed on one side of each sheet of paper, and the other for manuals printed @@ -15685,7 +16849,7 @@ manual.@refill @node Heading Choice, Custom Headings, Heading Format, Headings @comment node-name, next, previous, up -@appendixsec Specifying the Type of Heading +@section Specifying the Type of Heading @TeX{} does not begin to generate page headings for a standard Texinfo file until it reaches the @code{@@end titlepage} command. Thus, the @@ -15722,22 +16886,25 @@ Texinfo lacks an @code{@@setchapternewpage even} command.@refill @node Custom Headings, , Heading Choice, Headings @comment node-name, next, previous, up -@appendixsec How to Make Your Own Headings +@section How to Make Your Own Headings You can use the standard headings provided with Texinfo or specify your own. By default, Texinfo has no footers, so if you specify them, the available page size for the main text will be slightly reduced. -@c Following paragraph is verbose to prevent overfull hboxes. Texinfo provides six commands for specifying headings and -footings. The @code{@@everyheading} command and -@code{@@everyfooting} command generate page headers and footers -that are the same for both even- and odd-numbered pages. -The @code{@@evenheading} command and @code{@@evenfooting} -command generate headers and footers for even-numbered -(left-hand) pages; and the @code{@@oddheading} command and -@code{@@oddfooting} command generate headers and footers for -odd-numbered (right-hand) pages.@refill +footings: +@itemize @bullet +@item +@code{@@everyheading} @code{@@everyfooting} generate page headers and +footers that are the same for both even- and odd-numbered pages. +@item +@code{@@evenheading} and @code{@@evenfooting} command generate headers +and footers for even-numbered (left-hand) pages. +@item +@code{@@oddheading} and @code{@@oddfooting} generate headers and footers +for odd-numbered (right-hand) pages. +@end itemize Write custom heading specifications in the Texinfo file immediately after the @code{@@end titlepage} command. Enclose your specifications @@ -15869,7 +17036,7 @@ Beware of overlong titles: they may overlap another part of the header or footer and blot it out.@refill -@node Catching Mistakes, Refilling Paragraphs, Headings, Top +@node Catching Mistakes @appendix Formatting Mistakes @cindex Structure, catching mistakes in @cindex Nodes, catching mistakes @@ -15925,7 +17092,7 @@ may want to use the tools described in this appendix.@refill @node Debugging with Info, Debugging with TeX, makeinfo Preferred, Catching Mistakes @comment node-name, next, previous, up -@appendixsec Catching Errors with Info Formatting +@section Catching Errors with Info Formatting @cindex Catching errors with Info formatting @cindex Debugging with Info formatting @@ -16112,7 +17279,7 @@ Manual}, for more information.@refill @node Debugging with TeX, Using texinfo-show-structure, Debugging with Info, Catching Mistakes @comment node-name, next, previous, up -@appendixsec Catching Errors with @TeX{} Formatting +@section Catching Errors with @TeX{} Formatting @cindex Catching errors with @TeX{} formatting @cindex Debugging with @TeX{} formatting @@ -16194,9 +17361,8 @@ You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}} at the @samp{?} prompt.@refill @end enumerate -Please note that if you are running @TeX{} inside Emacs, you need to -switch to the shell buffer and line at which @TeX{} offers the @samp{?} -prompt.@refill +If you are running @TeX{} inside Emacs, you need to switch to the shell +buffer and line at which @TeX{} offers the @samp{?} prompt. Sometimes @TeX{} will format a file without producing error messages even though there is a problem. This usually occurs if a command is not ended @@ -16242,7 +17408,7 @@ directly with @TeX{}, not with Texinfo.)@refill @node Using texinfo-show-structure, Using occur, Debugging with TeX, Catching Mistakes @comment node-name, next, previous, up -@appendixsec Using @code{texinfo-show-structure} +@section Using @code{texinfo-show-structure} @cindex Showing the structure of a file @findex texinfo-show-structure @@ -16314,7 +17480,7 @@ or left out a section, you can correct the mistake.@refill @node Using occur, Running Info-Validate, Using texinfo-show-structure, Catching Mistakes @comment node-name, next, previous, up -@appendixsec Using @code{occur} +@section Using @code{occur} @cindex Occurrences, listing with @code{@@occur} @findex occur @@ -16354,7 +17520,7 @@ for more information.@refill @node Running Info-Validate, , Using occur, Catching Mistakes @comment node-name, next, previous, up -@appendixsec Finding Badly Referenced Nodes +@section Finding Badly Referenced Nodes @findex Info-validate @cindex Nodes, checking for badly referenced @cindex Checking for badly referenced nodes @@ -16383,7 +17549,7 @@ if you write an Info file from scratch.@refill @end menu @node Using Info-validate, Unsplit, Running Info-Validate, Running Info-Validate -@appendixsubsec Running @code{Info-validate} +@subsection Running @code{Info-validate} @cindex Running @code{Info-validate} @cindex Info validating a large file @cindex Validating a large file @@ -16396,9 +17562,9 @@ M-x Info-validate @end example @noindent -(Note that the @code{Info-validate} command requires an upper case +Note that the @code{Info-validate} command requires an upper case `I'. You may also need to create a tag table before running -@code{Info-validate}. @xref{Tagifying}.)@refill +@code{Info-validate}. @xref{Tagifying}. If your file is valid, you will receive a message that says ``File appears valid''. However, if you have a pointer that does not point to a node, @@ -16432,17 +17598,16 @@ This is because every `Next' pointer should be matched by a @code{Info-validate} also checks that all menu entries and cross references point to actual nodes.@refill -Note that @code{Info-validate} requires a tag table and does not work -with files that have been split. (The @code{texinfo-format-buffer} -command automatically splits large files.) In order to use -@code{Info-validate} on a large file, you must run -@code{texinfo-format-buffer} with an argument so that it does not split -the Info file; and you must create a tag table for the unsplit -file.@refill +@code{Info-validate} requires a tag table and does not work with files +that have been split. (The @code{texinfo-format-buffer} command +automatically splits large files.) In order to use @code{Info-validate} +on a large file, you must run @code{texinfo-format-buffer} with an +argument so that it does not split the Info file; and you must create a +tag table for the unsplit file. @node Unsplit, Tagifying, Using Info-validate, Running Info-Validate @comment node-name, next, previous, up -@appendixsubsec Creating an Unsplit File +@subsection Creating an Unsplit File @cindex Creating an unsplit file @cindex Unsplit file creation @@ -16479,7 +17644,7 @@ a tag table for it. @refill @cindex Tag table, making manually @node Tagifying, Splitting, Unsplit, Running Info-Validate -@appendixsubsec Tagifying a File +@subsection Tagifying a File After creating an unsplit Info file, you must create a tag table for it. Visit the Info file you wish to tagify and type:@refill @@ -16517,14 +17682,14 @@ table and split the file manually.@refill @node Splitting, , Tagifying, Running Info-Validate @comment node-name, next, previous, up -@appendixsubsec Splitting a File Manually +@subsection Splitting a File Manually @cindex Splitting an Info file manually @cindex Info file, splitting manually You should split a large file or else let the @code{texinfo-format-buffer} or @code{makeinfo-buffer} command do it for you automatically. (Generally you will let one of the formatting -commands do this job for you. @xref{Create an Info File}.)@refill +commands do this job for you. @xref{Creating an Info File}.)@refill The split-off files are called the indirect subfiles.@refill @@ -16567,10 +17732,11 @@ The primary file still functions as an Info file, but it contains just the tag table and a directory of subfiles.@refill -@node Refilling Paragraphs, Command Syntax, Catching Mistakes, Top +@node Refilling Paragraphs @appendix Refilling Paragraphs @cindex Refilling paragraphs @cindex Filling paragraphs +@cindex Paragraphs, filling @findex refill The @code{@@refill} command refills and, optionally, indents the first @@ -16606,10 +17772,11 @@ the ends of paragraphs that contain @code{@@*} or @w{@code{@@w@{ @dots{}@}}} and therefore do not refill or indent them.@refill -@node Command Syntax, Obtaining TeX, Refilling Paragraphs, Top -@comment node-name, next, previous, up +@node Command Syntax @appendix @@-Command Syntax @cindex @@-command syntax +@cindex Syntax, of @@-commands +@cindex Command syntax The character @samp{@@} is used to start special Texinfo commands. (It has the same meaning that @samp{\} has in plain @TeX{}.) Texinfo @@ -16670,7 +17837,7 @@ Emacs paragraph commands because it cannot appear at the beginning of a line.@refill -@node Obtaining TeX, Command and Variable Index, Command Syntax, Top +@node Obtaining TeX @appendix How to Obtain @TeX{} @cindex Obtaining @TeX{} @cindex @TeX{}, how to obtain @@ -16693,16 +17860,8 @@ available distributions: @end example The Free Software Foundation provides a core distribution on its Source -Code CD-ROM suitable for printing Texinfo manuals; the University of -Washington maintains and supports a tape distribution; the @TeX{} Users -Group co-sponsors a complete CD-ROM @TeX{} distribution. - -@itemize @bullet - -@item -For the FSF Source Code CD-ROM, please contact: +Code CD-ROM suitable for printing Texinfo manuals. To order it, contact: -@iftex @display @group Free Software Foundation, Inc. @@ -16717,53 +17876,6 @@ Free Dial Fax (in Japan): Electronic mail: @code{gnu@@gnu.org} @end group @end display -@end iftex -@ifinfo -@display -@group -Free Software Foundation, Inc. -59 Temple Place Suite 330 -Boston, MA @w{ } 02111-1307 -USA - -Telephone: @w{+1-617-542-5942} -Fax: (including Japan) @w{+1-617-542-2652} -Free Dial Fax (in Japan): -@w{ } @w{ } @w{ } 0031-13-2473 (KDD) -@w{ } @w{ } @w{ } 0066-3382-0158 (IDC) -Electronic mail: @code{gnu@@gnu.org} -@end group -@end display -@end ifinfo - -@item -To order a complete distribution on CD-ROM, please see -@uref{http://tug.org/tex-live.html}. (This distribution is also -available by FTP; see the URL's above.) - -@item -To order a full distribution from the University of Washington on either -a 1/4@dmn{in} 4-track QIC-24 cartridge or a 4@dmn{mm} DAT cartridge, -send $210 to: - -@display -@group -Pierre A. MacKay -Denny Hall, Mail Stop DH-10 -University of Washington -Seattle, WA @w{ } 98195 -USA -Telephone: +1-206-543-2268 -Electronic mail: @code{mackay@@cs.washington.edu} -@end group -@end display - -@noindent Please make checks payable to the University of Washington. -Checks must be in U.S.@: dollars, drawn on a U.S.@: bank. Overseas -sites: please add to the base cost, if desired, $20.00 for shipment via -air parcel post, or $30.00 for shipment via courier. - -@end itemize Many other @TeX{} distributions are available; see @uref{http://tug.org/}. @@ -16771,7 +17883,8 @@ Many other @TeX{} distributions are available; see @c These are no longer ``new'', and the explanations @c are all given elsewhere anyway, I think. --karl, 25apr97. -@ignore (the entire appendix) +@c So ignore the entire appendix. +@ignore @c node New Features, Command and Variable Index, Obtaining TeX, Top @c appendix Second Edition Features @@ -16789,10 +17902,10 @@ edition.@refill Here is a brief description of the new commands.@refill -@menu +@c menu * New Texinfo Mode Commands:: The updating commands are especially useful. * New Commands:: Many newly described @@-commands. -@end menu +@c end menu @c node New Texinfo Mode Commands, New Commands, Obtaining TeX, Obtaining TeX @c appendixsec New Texinfo Mode Commands @@ -16980,8 +18093,8 @@ Indent descriptions in menus. Insert node pointers in strict sequence. @end table -@c node New Commands, , New Texinfo Mode Commands, Obtaining TeX -@c appendixsec New Texinfo @@-Commands +@c no.de New Commands, , New Texinfo Mode Commands, Obtaining TeX +@c appendix.sec New Texinfo @@-Commands The second edition of the Texinfo manual describes more than 50 commands that were not described in the first edition. A third or so @@ -17258,8 +18371,8 @@ Insert the current date. @end tex @end ignore -@node Command and Variable Index, Concept Index, Obtaining TeX, Top -@comment node-name, next, previous, up + +@node Command and Variable Index @unnumbered Command and Variable Index This is an alphabetical list of all the @@-commands, assorted Emacs Lisp @@ -17269,12 +18382,10 @@ commands are listed without their preceding @samp{@@}.@refill @printindex fn -@node Concept Index, , Command and Variable Index, Top +@node Concept Index @unnumbered Concept Index @printindex cp -@summarycontents -@contents @bye diff --git a/contrib/texinfo/doc/version.texi b/contrib/texinfo/doc/version.texi new file mode 100644 index 0000000..2d7c149 --- /dev/null +++ b/contrib/texinfo/doc/version.texi @@ -0,0 +1,3 @@ +@set UPDATED 28 September 1999 +@set EDITION 4.0 +@set VERSION 4.0 diff --git a/contrib/texinfo/info/README b/contrib/texinfo/info/README index 7e1ab32..5cc0791 100644 --- a/contrib/texinfo/info/README +++ b/contrib/texinfo/info/README @@ -14,11 +14,6 @@ the advantages of smaller size, ease of portability, and a built in library which can be used in other programs (to get or display documentation from Info files, for example). -I eagerly await responses to this newer version of Info; comments on its -portability, ease of use and user interface, code quality, and general -usefulness are all of interest to me, and I will appreciate any comments -that you would care to make. - A full listing of the commands available in Info can be gotten by typing `?' while within an Info window. This produces a node in a window which can be viewed just like any Info node. diff --git a/contrib/texinfo/info/dir.c b/contrib/texinfo/info/dir.c index 651e48a..94380f5 100644 --- a/contrib/texinfo/info/dir.c +++ b/contrib/texinfo/info/dir.c @@ -1,7 +1,7 @@ -/* dir.c -- How to build a special "dir" node from "localdir" files. - $Id: dir.c,v 1.6 1997/07/27 21:09:20 karl Exp $ +/* dir.c -- how to build a special "dir" node from "localdir" files. + $Id: dir.c,v 1.7 1998/06/28 19:51:36 karl Exp $ - Copyright (C) 1993, 97 Free Software Foundation, Inc. + Copyright (C) 1993, 97, 98 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -125,7 +125,7 @@ maybe_build_dir_node (dirname) char *fullpath = xmalloc (3 + strlen (this_dir) + namelen); strcpy (fullpath, this_dir); - if (fullpath[strlen (fullpath) - 1] != '/') + if (!IS_SLASH (fullpath[strlen (fullpath) - 1])) strcat (fullpath, "/"); strcat (fullpath, from_file); @@ -135,8 +135,9 @@ maybe_build_dir_node (dirname) if (statable && S_ISREG (finfo.st_mode) && new_dir_file_p (&finfo)) { long filesize; + int compressed; char *contents = filesys_read_info_file (fullpath, &filesize, - &finfo); + &finfo, &compressed); if (contents) { update_tags++; diff --git a/contrib/texinfo/info/dribble.c b/contrib/texinfo/info/dribble.c index d1d5848..c4b5b9f 100644 --- a/contrib/texinfo/info/dribble.c +++ b/contrib/texinfo/info/dribble.c @@ -1,9 +1,6 @@ -/* dribble.c -- Dribble files for Info. */ +/* dribble.c -- dribble files for Info. -/* This file is part of GNU Info, a program for reading online documentation - stored in Info format. - - Copyright (C) 1993 Free Software Foundation, Inc. + Copyright (C) 1993, 98 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -37,7 +34,8 @@ open_dribble_file (name) /* Perhaps close existing dribble file. */ close_dribble_file (); - info_dribble_file = fopen (name, "w"); + /* Keystrokes can be non-printable characters, so we need binary I/O. */ + info_dribble_file = fopen (name, FOPEN_WBIN); #if defined (HAVE_SETVBUF) if (info_dribble_file) diff --git a/contrib/texinfo/info/echo-area.c b/contrib/texinfo/info/echo-area.c index 0d409e8..7500523 100644 --- a/contrib/texinfo/info/echo-area.c +++ b/contrib/texinfo/info/echo-area.c @@ -1,7 +1,7 @@ -/* echo-area.c -- How to read a line in the echo area. - $Id: echo-area.c,v 1.10 1998/02/26 22:47:02 karl Exp $ +/* echo-area.c -- how to read a line in the echo area. + $Id: echo-area.c,v 1.12 1999/03/03 22:22:14 karl Exp $ - Copyright (C) 1993, 97, 98 Free Software Foundation, Inc. + Copyright (C) 1993, 97, 98, 99 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -940,7 +940,8 @@ DECLARE_INFO_COMMAND (ea_possible_completions, _("List possible completions")) initialize_message_buffer (); printf_to_message_buffer (completions_found_index == 1 ? _("One completion:\n") - : _("%d completions:\n")); + : _("%d completions:\n"), + completions_found_index); /* Find the maximum length of a label. */ for (i = 0; i < completions_found_index; i++) @@ -1462,7 +1463,7 @@ echo_area_stack_contains_completions_p () static void pause_or_input () { -#if defined (FD_SET) +#ifdef FD_SET struct timeval timer; fd_set readfds; int ready; @@ -1470,14 +1471,14 @@ pause_or_input () FD_ZERO (&readfds); FD_SET (fileno (stdin), &readfds); timer.tv_sec = 2; - timer.tv_usec = 750; + timer.tv_usec = 0; ready = select (fileno (stdin) + 1, &readfds, (fd_set *) NULL, (fd_set *) NULL, &timer); #endif /* FD_SET */ } /* Print MESSAGE right after the end of the current line, and wait - for input or 2.75 seconds, whichever comes first. Then flush the + for input or a couple of seconds, whichever comes first. Then flush the informational message that was printed. */ void inform_in_echo_area (message) @@ -1487,8 +1488,9 @@ inform_in_echo_area (message) char *text; text = xstrdup (message); - for (i = 0; text[i] && text[i] != '\n'; i++); - text[i] = '\0'; + for (i = 0; text[i] && text[i] != '\n'; i++) + ; + text[i] = 0; echo_area_initialize_node (); sprintf (&input_line[input_line_end], "%s[%s]\n", diff --git a/contrib/texinfo/info/filesys.c b/contrib/texinfo/info/filesys.c index eb93fdf..96f0ed9 100644 --- a/contrib/texinfo/info/filesys.c +++ b/contrib/texinfo/info/filesys.c @@ -1,5 +1,5 @@ -/* filesys.c -- File system specific functions for hacking this system. - $Id: filesys.c,v 1.6 1998/02/21 22:52:46 karl Exp $ +/* filesys.c -- filesystem specific functions. + $Id: filesys.c,v 1.10 1998/12/06 21:58:30 karl Exp $ Copyright (C) 1993, 97, 98 Free Software Foundation, Inc. @@ -26,6 +26,7 @@ /* Local to this file. */ static char *info_file_in_path (), *lookup_info_filename (); +static char *info_absolute_file (); static void remember_info_filename (), maybe_initialize_infopath (); typedef struct @@ -35,18 +36,29 @@ typedef struct } COMPRESSION_ALIST; static char *info_suffixes[] = { - "", ".info", "-info", "/index", - (char *)NULL + ".inf", /* 8+3 file on filesystem which supports long file names */ +#ifdef __MSDOS__ + /* 8+3 file names strike again... */ + ".in", /* for .inz, .igz etc. */ + ".i", +#endif + "", + NULL }; static COMPRESSION_ALIST compress_suffixes[] = { + { ".gz", "gunzip" }, + { ".bz2", "bunzip2" }, + { ".z", "gunzip" }, { ".Z", "uncompress" }, { ".Y", "unyabba" }, - { ".z", "gunzip" }, - { ".gz", "gunzip" }, +#ifdef __MSDOS__ + { "gz", "gunzip" }, + { "z", "gunzip" }, +#endif { (char *)NULL, (char *)NULL } }; @@ -86,21 +98,22 @@ info_find_fullpath (partial) /* If we have the full path to this file, we still may have to add various extensions to it. I guess we have to stat this file after all. */ - if (initial_character == '/') - temp = info_file_in_path (partial + 1, "/"); + if (IS_ABSOLUTE (partial)) + temp = info_absolute_file (partial); else if (initial_character == '~') { expansion = tilde_expand_word (partial); - if (*expansion == '/') + if (IS_ABSOLUTE (expansion)) { - temp = info_file_in_path (expansion + 1, "/"); + temp = info_absolute_file (expansion); free (expansion); } else temp = expansion; } else if (initial_character == '.' && - (partial[1] == '/' || (partial[1] == '.' && partial[2] == '/'))) + (IS_SLASH (partial[1]) || + (partial[1] == '.' && IS_SLASH (partial[2])))) { if (local_temp_filename_size < 1024) local_temp_filename = (char *)xrealloc @@ -117,7 +130,9 @@ info_find_fullpath (partial) strcat (local_temp_filename, "/"); strcat (local_temp_filename, partial); - return (local_temp_filename); + temp = info_absolute_file (local_temp_filename); /* try extensions */ + if (!temp) + partial = local_temp_filename; } else temp = info_file_in_path (partial, infopath); @@ -167,7 +182,7 @@ info_file_in_path (filename, path) temp = (char *)xmalloc (30 + strlen (temp_dirname) + strlen (filename)); strcpy (temp, temp_dirname); - if (temp[(strlen (temp)) - 1] != '/') + if (!IS_SLASH (temp[(strlen (temp)) - 1])) strcat (temp, "/"); strcat (temp, filename); @@ -229,8 +244,26 @@ info_file_in_path (filename, path) return ((char *)NULL); } -/* Given a string containing units of information separated by colons, - return the next one pointed to by IDX, or NULL if there are no more. +/* Assume FNAME is an absolute file name, and check whether it is + a regular file. If it is, return it as a new string; otherwise + return a NULL pointer. We do it by taking the file name apart + into its directory and basename parts, and calling info_file_in_path.*/ +static char * +info_absolute_file (fname) + char *fname; +{ + char *containing_dir = xstrdup (fname); + char *base = filename_non_directory (containing_dir); + + if (base > containing_dir) + base[-1] = '\0'; + + return info_file_in_path (filename_non_directory (fname), containing_dir); +} + +/* Given a string containing units of information separated by + the PATH_SEP character, return the next one pointed to by + IDX, or NULL if there are no more. Advance IDX to the character after the colon. */ char * extract_colon_unit (string, idx) @@ -243,7 +276,7 @@ extract_colon_unit (string, idx) if ((i >= strlen (string)) || !string) return ((char *) NULL); - while (string[i] && string[i] != ':') + while (string[i] && string[i] != PATH_SEP[0]) i++; if (i == start) { @@ -285,7 +318,7 @@ lookup_info_filename (filename) register int i; for (i = 0; names_and_files[i]; i++) { - if (strcmp (names_and_files[i]->filename, filename) == 0) + if (FILENAME_CMP (names_and_files[i]->filename, filename) == 0) return (names_and_files[i]->expansion); } } @@ -354,14 +387,14 @@ info_add_path (path, where) strcpy (infopath, path); else if (where == INFOPATH_APPEND) { - strcat (infopath, ":"); + strcat (infopath, PATH_SEP); strcat (infopath, path); } else if (where == INFOPATH_PREPEND) { char *temp = xstrdup (infopath); strcpy (infopath, path); - strcat (infopath, ":"); + strcat (infopath, PATH_SEP); strcat (infopath, temp); free (temp); } @@ -378,28 +411,70 @@ zap_infopath () infopath_size = 0; } +/* Given a chunk of text and its length, convert all CRLF pairs at every + end-of-line into a single Newline character. Return the length of + produced text. + + This is required because the rest of code is too entrenched in having + a single newline at each EOL; in particular, searching for various + Info headers and cookies can become extremely tricky if that assumption + breaks. + + FIXME: this could also support Mac-style text files with a single CR + at the EOL, but what about random CR characters in non-Mac files? Can + we afford converting them into newlines as well? Maybe implement some + heuristics here, like in Emacs 20. + + FIXME: is it a good idea to show the EOL type on the modeline? */ +long +convert_eols (text, textlen) + char *text; + long textlen; +{ + register char *s = text; + register char *d = text; + + while (textlen--) + { + if (*s == '\r' && textlen && s[1] == '\n') + { + s++; + textlen--; + } + *d++ = *s++; + } + + return (long)(d - text); +} + /* Read the contents of PATHNAME, returning a buffer with the contents of that file in it, and returning the size of that buffer in FILESIZE. FINFO is a stat struct which has already been filled in by the caller. + If the file turns out to be compressed, set IS_COMPRESSED to non-zero. If the file cannot be read, return a NULL pointer. */ char * -filesys_read_info_file (pathname, filesize, finfo) +filesys_read_info_file (pathname, filesize, finfo, is_compressed) char *pathname; long *filesize; struct stat *finfo; + int *is_compressed; { long st_size; *filesize = filesys_error_number = 0; if (compressed_filename_p (pathname)) - return (filesys_read_compressed (pathname, filesize, finfo)); + { + *is_compressed = 1; + return (filesys_read_compressed (pathname, filesize, finfo)); + } else { int descriptor; char *contents; - descriptor = open (pathname, O_RDONLY, 0666); + *is_compressed = 0; + descriptor = open (pathname, O_RDONLY | O_BINARY, 0666); /* If the file couldn't be opened, give up. */ if (descriptor < 0) @@ -413,15 +488,24 @@ filesys_read_info_file (pathname, filesize, finfo) contents = (char *)xmalloc (1 + st_size); if ((read (descriptor, contents, st_size)) != st_size) { - filesys_error_number = errno; - close (descriptor); - free (contents); - return ((char *)NULL); + filesys_error_number = errno; + close (descriptor); + free (contents); + return ((char *)NULL); } close (descriptor); - *filesize = st_size; + /* Convert any DOS-style CRLF EOLs into Unix-style NL. + Seems like a good idea to have even on Unix, in case the Info + files are coming from some Windows system across a network. */ + *filesize = convert_eols (contents, st_size); + + /* EOL conversion can shrink the text quite a bit. We don't + want to waste storage. */ + if (*filesize < st_size) + contents = (char *)xrealloc (contents, 1 + *filesize); + return (contents); } } @@ -449,8 +533,11 @@ filesys_read_compressed (pathname, filesize, finfo) if (!decompressor) return ((char *)NULL); - command = (char *)xmalloc (10 + strlen (pathname) + strlen (decompressor)); - sprintf (command, "%s < %s", decompressor, pathname); + command = (char *)xmalloc (15 + strlen (pathname) + strlen (decompressor)); + /* Explicit .exe suffix makes the diagnostics of `popen' + better on systems where COMMAND.COM is the stock shell. */ + sprintf (command, "%s%s < %s", + decompressor, STRIP_DOT_EXE ? ".exe" : "", pathname); #if !defined (BUILDING_LIBRARY) if (info_windows_initialized_p) @@ -464,7 +551,7 @@ filesys_read_compressed (pathname, filesize, finfo) } #endif /* !BUILDING_LIBRARY */ - stream = popen (command, "r"); + stream = popen (command, FOPEN_RBIN); free (command); /* Read chunks from this file until there are none left to read. */ @@ -493,9 +580,18 @@ filesys_read_compressed (pathname, filesize, finfo) } free (chunk); - pclose (stream); - contents = (char *)xrealloc (contents, offset + 1); - *filesize = offset; + if (pclose (stream) == -1) + { + if (contents) + free (contents); + contents = (char *)NULL; + filesys_error_number = errno; + } + else + { + *filesize = convert_eols (contents, offset); + contents = (char *)xrealloc (contents, 1 + *filesize); + } } else { @@ -547,9 +643,19 @@ filesys_decompressor_for_file (filename) return ((char *)NULL); for (i = 0; compress_suffixes[i].suffix; i++) - if (strcmp (extension, compress_suffixes[i].suffix) == 0) + if (FILENAME_CMP (extension, compress_suffixes[i].suffix) == 0) return (compress_suffixes[i].decompressor); +#if defined (__MSDOS__) + /* If no other suffix matched, allow any extension which ends + with `z' to be decompressed by gunzip. Due to limited 8+3 DOS + file namespace, we can expect many such cases, and supporting + every weird suffix thus produced would be a pain. */ + if (extension[strlen (extension) - 1] == 'z' || + extension[strlen (extension) - 1] == 'Z') + return "gunzip"; +#endif + return ((char *)NULL); } @@ -582,3 +688,26 @@ filesys_error_string (filename, error_num) return (errmsg_buf); } + +/* Check for FILENAME eq "dir" first, then all the compression + suffixes. */ + +int +is_dir_name (filename) + char *filename; +{ + unsigned i; + if (strcasecmp (filename, "dir") == 0) + return 1; + + for (i = 0; compress_suffixes[i].suffix; i++) + { + char dir_compressed[50]; /* can be short */ + strcpy (dir_compressed, "dir"); + strcat (dir_compressed, compress_suffixes[i].suffix); + if (strcasecmp (filename, dir_compressed) == 0) + return 1; + } + + return 0; +} diff --git a/contrib/texinfo/info/filesys.h b/contrib/texinfo/info/filesys.h index 440eb9b..06573ef 100644 --- a/contrib/texinfo/info/filesys.h +++ b/contrib/texinfo/info/filesys.h @@ -1,10 +1,7 @@ -/* filesys.h -- External declarations of functions and vars in filesys.c. - $Id: filesys.h,v 1.3 1997/07/15 18:39:08 karl Exp $ +/* filesys.h -- external declarations for filesys.c. + $Id: filesys.h,v 1.5 1998/07/21 22:25:44 karl Exp $ - This file is part of GNU Info, a program for reading online documentation - stored in Info format. - - Copyright (C) 1993, 97 Free Software Foundation, Inc. + Copyright (C) 1993, 97, 98 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -46,6 +43,11 @@ extern void info_add_path (); If it can't find the file, it returns NULL. */ extern char *info_find_fullpath (); +/* Given a chunk of text and its length, convert all CRLF pairs at the + EOLs into a single Newline character. Return the length of produced + text. */ +long convert_eols (); + /* Read the contents of PATHNAME, returning a buffer with the contents of that file in it, and returning the size of that buffer in FILESIZE. FINFO is a stat struct which has already been filled in by the caller. @@ -69,6 +71,9 @@ extern int filesys_error_number; Advance IDX to the character after the colon. */ extern char *extract_colon_unit (); +/* Return true if FILENAME is `dir', with a possible compression suffix. */ +extern int is_dir_name (); + /* The default value of INFOPATH. */ #if !defined (DEFAULT_INFOPATH) # define DEFAULT_INFOPATH "/usr/local/info:/usr/info:/usr/local/lib/info:/usr/lib/info:/usr/local/gnu/info:/usr/local/gnu/lib/info:/usr/gnu/info:/usr/gnu/lib/info:/opt/gnu/info:/usr/share/info:/usr/share/lib/info:/usr/local/share/info:/usr/local/share/lib/info:/usr/gnu/lib/emacs/info:/usr/local/gnu/lib/emacs/info:/usr/local/lib/emacs/info:/usr/local/emacs/info:." diff --git a/contrib/texinfo/info/footnotes.c b/contrib/texinfo/info/footnotes.c index b646743..c891e39 100644 --- a/contrib/texinfo/info/footnotes.c +++ b/contrib/texinfo/info/footnotes.c @@ -1,7 +1,7 @@ /* footnotes.c -- Some functions for manipulating footnotes. - $Id: footnotes.c,v 1.4 1997/07/24 21:23:33 karl Exp $ + $Id: footnotes.c,v 1.9 1999/09/25 16:10:04 karl Exp $ - Copyright (C) 1993, 97 Free Software Foundation, Inc. + Copyright (C) 1993, 97, 98, 99 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -60,7 +60,7 @@ make_footnotes_node (node) /* See if this node contains the magic footnote label. */ fn_start = - info_search_in_node (FOOTNOTE_LABEL, node, 0, (WINDOW *)NULL, 1); + info_search_in_node (FOOTNOTE_LABEL, node, 0, (WINDOW *)NULL, 1, 0); /* If it doesn't, check to see if it has an associated footnotes node. */ if (fn_start == -1) @@ -73,16 +73,21 @@ make_footnotes_node (node) { register int i; char *refname; + int reflen = strlen ("-Footnotes") + strlen (node->nodename); - refname = (char *)xmalloc - (1 + strlen ("-Footnotes") + strlen (node->nodename)); + refname = (char *)xmalloc (reflen + 1); strcpy (refname, node->nodename); strcat (refname, "-Footnotes"); for (i = 0; refs[i]; i++) if ((refs[i]->nodename != (char *)NULL) && - (strcmp (refs[i]->nodename, refname) == 0)) + /* Support both the older "foo-Footnotes" and the new + style "foo-Footnote-NN" references. */ + (strcmp (refs[i]->nodename, refname) == 0 || + (strncmp (refs[i]->nodename, refname, reflen - 1) == 0 && + refs[i]->nodename[reflen - 1] == '-' && + isdigit (refs[i]->nodename[reflen])))) { char *filename; @@ -110,6 +115,7 @@ make_footnotes_node (node) /* Make the new node. */ result = (NODE *)xmalloc (sizeof (NODE)); result->flags = 0; + result->display_pos = 0; /* Get the size of the footnotes appearing within this node. */ { @@ -250,11 +256,11 @@ DECLARE_INFO_COMMAND (info_show_footnotes, switch (result) { case FN_UNFOUND: - info_error (NO_FOOT_NODE); + info_error (msg_no_foot_node); break; case FN_UNABLE: - info_error (WIN_TOO_SMALL); + info_error (msg_win_too_small); break; } } diff --git a/contrib/texinfo/info/footnotes.h b/contrib/texinfo/info/footnotes.h index 3406bcb..a0d4fb0 100644 --- a/contrib/texinfo/info/footnotes.h +++ b/contrib/texinfo/info/footnotes.h @@ -1,10 +1,7 @@ /* footnotes.h -- Some functions for manipulating footnotes. - $Id: footnotes.h,v 1.3 1997/07/15 18:40:27 karl Exp $ + $Id: footnotes.h,v 1.4 1998/11/29 21:44:49 karl Exp $ - This file is part of GNU Info, a program for reading online documentation - stored in Info format. - - Copyright (C) 1993, 97 Free Software Foundation, Inc. + Copyright (C) 1993, 97, 98 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -26,7 +23,7 @@ #define INFO_FOOTNOTES_H /* Magic string which indicates following text is footnotes. */ -#define FOOTNOTE_LABEL _("---------- Footnotes ----------") +#define FOOTNOTE_LABEL N_("---------- Footnotes ----------") #define FN_FOUND 0 #define FN_UNFOUND 1 diff --git a/contrib/texinfo/info/indices.c b/contrib/texinfo/info/indices.c index 37e9b03..6583da1 100644 --- a/contrib/texinfo/info/indices.c +++ b/contrib/texinfo/info/indices.c @@ -1,7 +1,7 @@ -/* indices.c -- Commands for dealing with an Info file Index. - $Id: indices.c,v 1.6 1997/07/24 21:25:53 karl Exp $ +/* indices.c -- deal with an Info file index. + $Id: indices.c,v 1.14 1999/09/25 16:10:04 karl Exp $ - Copyright (C) 1993, 97 Free Software Foundation, Inc. + Copyright (C) 1993, 97, 98, 99 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -199,7 +199,7 @@ do_info_index_search (window, count, search_string) index for, build and remember an index now. */ fb = file_buffer_of_window (window); if (!initial_index_filename || - (strcmp (initial_index_filename, fb->filename) != 0)) + (FILENAME_CMP (initial_index_filename, fb->filename) != 0)) { info_free_references (index_index); window_message_in_echo_area (_("Finding index entries...")); @@ -296,7 +296,7 @@ index_entry_exists (window, string) fb = file_buffer_of_window (window); if (!initial_index_filename - || (strcmp (initial_index_filename, fb->filename) != 0)) + || (FILENAME_CMP (initial_index_filename, fb->filename) != 0)) { info_free_references (index_index); index_index = info_indices_of_file_buffer (fb); @@ -439,15 +439,12 @@ DECLARE_INFO_COMMAND (info_next_index_match, if (!node) { - info_error (CANT_FILE_NODE, + info_error (msg_cant_file_node, index_index[i]->filename, index_index[i]->nodename); return; } - set_remembered_pagetop_and_point (window); - window_set_node_of_window (window, node); - remember_window_and_node (window, node); - + info_set_node_of_window (1, window, node); /* Try to find an occurence of LABEL in this node. */ { @@ -497,11 +494,13 @@ apropos_in_all_indices (search_string, inform) REFERENCE **this_index, *this_item; NODE *this_node; FILE_BUFFER *this_fb; + int dir_node_duplicated = 0; this_item = dir_menu[dir_index]; if (!this_item->filename) { + dir_node_duplicated = 1; if (dir_node->parent) this_item->filename = xstrdup (dir_node->parent); else @@ -517,7 +516,11 @@ apropos_in_all_indices (search_string, inform) this_node = info_get_node (this_item->label, "Top"); if (!this_node) - continue; + { + if (dir_node_duplicated) + free (this_item->filename); + continue; + } /* Get the file buffer associated with this node. */ { @@ -529,6 +532,19 @@ apropos_in_all_indices (search_string, inform) this_fb = info_find_file (files_name); + /* If we already scanned this file, don't do that again. + In addition to being faster, this also avoids having + multiple identical entries in the *Apropos* menu. */ + for (i = 0; i < dir_index; i++) + if (FILENAME_CMP (this_fb->filename, dir_menu[i]->filename) == 0) + break; + if (i < dir_index) + { + if (dir_node_duplicated) + free (this_item->filename); + continue; + } + if (this_fb && inform) message_in_echo_area (_("Scanning indices of \"%s\"..."), files_name); @@ -584,7 +600,7 @@ apropos_in_all_indices (search_string, inform) } #define APROPOS_NONE \ - _("No available info files reference \"%s\" in their indices.") + N_("No available info files have \"%s\" in their indices.") void info_apropos (string) @@ -596,7 +612,7 @@ info_apropos (string) if (!apropos_list) { - info_error (APROPOS_NONE, string); + info_error (_(APROPOS_NONE), string); } else { @@ -604,7 +620,7 @@ info_apropos (string) REFERENCE *entry; for (i = 0; (entry = apropos_list[i]); i++) - fprintf (stderr, "\"(%s)%s\" -- %s\n", + fprintf (stdout, "\"(%s)%s\" -- %s\n", entry->filename, entry->nodename, entry->label); } info_free_references (apropos_list); @@ -638,7 +654,7 @@ DECLARE_INFO_COMMAND (info_index_apropos, if (!apropos_list) { - info_error (APROPOS_NONE, line); + info_error (_(APROPOS_NONE), line); } else { @@ -653,10 +669,14 @@ DECLARE_INFO_COMMAND (info_index_apropos, for (i = 0; apropos_list[i]; i++) { int len; - sprintf (line_buffer, "* (%s)%s::", + /* The label might be identical to that of another index + entry in another Info file. Therefore, we make the file + name part of the menu entry, to make them all distinct. */ + sprintf (line_buffer, "* %s [%s]: ", + apropos_list[i]->label, apropos_list[i]->filename); + len = pad_to (40, line_buffer); + sprintf (line_buffer + len, "(%s)%s.", apropos_list[i]->filename, apropos_list[i]->nodename); - len = pad_to (36, line_buffer); - sprintf (line_buffer + len, "%s", apropos_list[i]->label); printf_to_message_buffer ("%s\n", line_buffer); } free (line_buffer); diff --git a/contrib/texinfo/info/info-utils.c b/contrib/texinfo/info/info-utils.c index d9ab9a0..a19c950 100644 --- a/contrib/texinfo/info/info-utils.c +++ b/contrib/texinfo/info/info-utils.c @@ -1,9 +1,7 @@ -/* info-utils.c -- Useful functions for manipulating Info file quirks. */ +/* info-utils.c -- miscellanous. + $Id: info-utils.c,v 1.7 1998/08/10 18:07:47 karl Exp $ -/* This file is part of GNU Info, a program for reading online documentation - stored in Info format. - - Copyright (C) 1993 Free Software Foundation, Inc. + Copyright (C) 1993, 98 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -29,7 +27,7 @@ /* When non-zero, various display and input functions handle ISO Latin character sets correctly. */ -int ISO_Latin_p = 0; +int ISO_Latin_p = 1; /* Variable which holds the most recent filename parsed as a result of calling info_parse_xxx (). */ @@ -300,8 +298,8 @@ info_references_internal (label, binding) return (refs); } -/* Get the entry associated with LABEL in MENU. Return a pointer to the - REFERENCE if found, or NULL. */ +/* Get the entry associated with LABEL in REFERENCES. Return a pointer + to the ENTRY if found, or NULL. */ REFERENCE * info_get_labeled_reference (label, references) char *label; @@ -444,19 +442,10 @@ printed_representation (character, hpos) int hpos; { register int i = 0; - int printable_limit; - - if (ISO_Latin_p) - printable_limit = 160; - else - printable_limit = 127; - - if (character == '\177') - { - the_rep[i++] = '^'; - the_rep[i++] = '?'; - } - else if (iscntrl (character)) + int printable_limit = ISO_Latin_p ? 255 : 127; + + /* Show CTRL-x as ^X. */ + if (iscntrl (character) && character < 127) { switch (character) { @@ -480,17 +469,23 @@ printed_representation (character, hpos) the_rep[i++] = (character | 0x40); } } + /* Show META-x as 0370. */ else if (character > printable_limit) { sprintf (the_rep + i, "\\%0o", character); i = strlen (the_rep); } + else if (character == DEL) + { + the_rep[i++] = '^'; + the_rep[i++] = '?'; + } else the_rep[i++] = character; - the_rep[i] = '\0'; + the_rep[i] = 0; - return (the_rep); + return the_rep; } @@ -604,14 +599,13 @@ char * filename_non_directory (pathname) char *pathname; { - char *filename; + register char *filename = pathname + strlen (pathname); - filename = (char *) strrchr (pathname, '/'); + if (HAVE_DRIVE (pathname)) + pathname += 2; - if (filename) - filename++; - else - filename = pathname; + while (filename > pathname && !IS_SLASH (filename[-1])) + filename--; return (filename); } @@ -663,3 +657,17 @@ get_internal_info_window (name) return (win); } + +/* Return a window displaying the node NODE. */ +WINDOW * +get_window_of_node (node) + NODE *node; +{ + WINDOW *win = (WINDOW *)NULL; + + for (win = windows; win; win = win->next) + if (win->node == node) + break; + + return (win); +} diff --git a/contrib/texinfo/info/info-utils.h b/contrib/texinfo/info/info-utils.h index 879587c..24cc482 100644 --- a/contrib/texinfo/info/info-utils.h +++ b/contrib/texinfo/info/info-utils.h @@ -1,10 +1,7 @@ -/* info-utils.h -- Exported functions and variables from info-util.c. - $Id: info-utils.h,v 1.3 1997/07/15 18:42:20 karl Exp $ +/* info-utils.h -- Exported functions and variables from info-utils.c. + $Id: info-utils.h,v 1.5 1998/08/10 18:07:28 karl Exp $ - This file is part of GNU Info, a program for reading online documentation - stored in Info format. - - Copyright (C) 1993, 96 Free Software Foundation, Inc. + Copyright (C) 1993, 96, 98 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -25,13 +22,6 @@ #ifndef INFO_UTILS_H #define INFO_UTILS_H -#if !defined (HAVE_STRCHR) -# undef strchr -# undef strrchr -# define strchr index -# define strrchr rindex -#endif /* !HAVE_STRCHR */ - #include "nodes.h" #include "window.h" #include "search.h" @@ -118,22 +108,22 @@ extern void name_internal_node (); Info window. */ extern WINDOW *get_internal_info_window (); +/* Return a window displaying the node NODE. */ +extern WINDOW *get_window_of_node (); + /* Return the node addressed by LABEL in NODE (usually one of "Prev:", "Next:", "Up:", "File:", or "Node:". After a call to this function, - the global INFO_PARSED_NODENAME and INFO_PARSED_FILENAME contain + the globals `info_parsed_nodename' and `info_parsed_filename' contain the information. */ extern void info_parse_label (/* label, node */); -#define info_label_was_found \ - (info_parsed_nodename != NULL || info_parsed_filename != NULL) - #define info_file_label_of_node(n) info_parse_label (INFO_FILE_LABEL, n) #define info_next_label_of_node(n) info_parse_label (INFO_NEXT_LABEL, n) #define info_up_label_of_node(n) info_parse_label (INFO_UP_LABEL, n) #define info_prev_label_of_node(n) \ do { \ info_parse_label (INFO_PREV_LABEL, n); \ - if (!info_label_was_found) \ + if (!info_parsed_nodename && !info_parsed_filename) \ info_parse_label (INFO_ALTPREV_LABEL, n); \ } while (0) diff --git a/contrib/texinfo/info/info.c b/contrib/texinfo/info/info.c index 81ab460..4f4999c 100644 --- a/contrib/texinfo/info/info.c +++ b/contrib/texinfo/info/info.c @@ -1,7 +1,7 @@ /* info.c -- Display nodes of Info files in multiple windows. - $Id: info.c,v 1.18 1998/02/27 21:37:27 karl Exp $ + $Id: info.c,v 1.41 1999/09/25 16:10:04 karl Exp $ - Copyright (C) 1993, 96, 97, 98 Free Software Foundation, Inc. + Copyright (C) 1993, 96, 97, 98, 99 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -27,12 +27,7 @@ # include "man.h" #endif /* HANDLE_MAN_PAGES */ -/* The version numbers of this version of Info. */ -int info_major_version = 2; -int info_minor_version = 18; - -/* basename (argv[0]) */ -static char *program_name = NULL; +static char *program_name = "info"; /* Non-zero means search all indices for APROPOS_SEARCH_STRING. */ static int apropos_p = 0; @@ -44,8 +39,13 @@ static char *apropos_search_string = (char *)NULL; apropos, this puts the user at the node, running info. */ static int index_search_p = 0; +/* Non-zero means look for the node which describes the invocation + and command-line options of the program, and start the info + session at that node. */ +static int goto_invocation_p = 0; + /* Variable containing the string to search for when index_search_p is - non-zero. */ + non-zero. */ static char *index_search_string = (char *)NULL; /* Non-zero means print version info only. */ @@ -73,6 +73,18 @@ static char *user_output_filename = (char *)NULL; dumped in the order encountered. This basically can print a book. */ int dump_subnodes = 0; +/* Non-zero means make default keybindings be loosely modeled on vi(1). */ +int vi_keys_p = 0; + +#ifdef __MSDOS__ +/* Non-zero indicates that screen output should be made 'speech-friendly'. + Since on MSDOS the usual behavior is to write directly to the video + memory, speech synthesizer software cannot grab the output. Therefore, + we provide a user option which tells us to avoid direct screen output + and use stdout instead (which loses the color output). */ +int speech_friendly = 0; +#endif + /* Structure describing the options that Info accepts. We pass this structure to getopt_long (). If you add or otherwise change this structure, you must also change the string which follows it. */ @@ -87,22 +99,33 @@ static struct option long_options[] = { { "file", 1, 0, 'f' }, { "subnodes", 0, &dump_subnodes, 1 }, { "output", 1, 0, 'o' }, + { "show-options", 0, 0, 'O' }, + { "usage", 0, 0, 'O' }, + { "vi-keys", 0, &vi_keys_p, 1 }, { "help", 0, &print_help_p, 1 }, { "version", 0, &print_version_p, 1 }, { "dribble", 1, 0, DRIBBLE_OPTION }, { "restore", 1, 0, RESTORE_OPTION }, +#ifdef __MSDOS__ + { "speech-friendly", 0, &speech_friendly, 1 }, +#endif { "index-search", 1, 0, IDXSRCH_OPTION }, {NULL, 0, NULL, 0} }; /* String describing the shorthand versions of the long options found above. */ -static char *short_options = "d:n:f:o:s"; +#ifdef __MSDOS__ +static char *short_options = "d:n:f:o:Osb"; +#else +static char *short_options = "d:n:f:o:Os"; +#endif /* When non-zero, the Info window system has been initialized. */ int info_windows_initialized_p = 0; /* Some "forward" declarations. */ static void info_short_help (), remember_info_program_name (); +static void init_messages (); /* **************************************************************** */ @@ -119,8 +142,6 @@ main (argc, argv) int getopt_long_index; /* Index returned by getopt_long (). */ NODE *initial_node; /* First node loaded by Info. */ - remember_info_program_name (argv[0]); - #ifdef HAVE_SETLOCALE /* Set locale via LC_ALL. */ setlocale (LC_ALL, ""); @@ -130,6 +151,8 @@ main (argc, argv) bindtextdomain (PACKAGE, LOCALEDIR); textdomain (PACKAGE); + init_messages (); + while (1) { int option_character; @@ -177,12 +200,25 @@ main (argc, argv) user_output_filename = xstrdup (optarg); break; + /* User has specified that she wants to find the "Options" + or "Invocation" node for the program. */ + case 'O': + goto_invocation_p = 1; + break; + /* User is specifying that she wishes to dump the subnodes of the node that she is dumping. */ case 's': dump_subnodes = 1; break; +#ifdef __MSDOS__ + /* User specifies that she wants speech-friendly output. */ + case 'b': + speech_friendly = 1; + break; +#endif /* __MSDOS__ */ + /* User has specified a string to search all indices for. */ case APROPOS_OPTION: apropos_p = 1; @@ -209,8 +245,8 @@ main (argc, argv) break; default: - fprintf (stderr, _("Try --help for more information.")); - exit (1); + fprintf (stderr, _("Try --help for more information.\n")); + xexit (1); } } @@ -226,23 +262,23 @@ main (argc, argv) /* If the user specified --version, then show the version and exit. */ if (print_version_p) { - printf ("%s (GNU %s %s) %s\n", program_name, PACKAGE, VERSION, - version_string ()); + printf ("%s (GNU %s) %s\n", program_name, PACKAGE, VERSION); + puts (""); printf (_("Copyright (C) %s Free Software Foundation, Inc.\n\ There is NO warranty. You may redistribute this software\n\ under the terms of the GNU General Public License.\n\ For more information about these matters, see the files named COPYING.\n"), - "1998"); - exit (0); + "1999"); + xexit (0); } /* If the `--help' option was present, show the help and exit. */ if (print_help_p) { info_short_help (); - exit (0); + xexit (0); } - + /* If the user hasn't specified a path for Info files, default it. Lowest priority is our messy hardwired list in filesys.h. Then comes the user's INFODIR from the Makefile. @@ -255,7 +291,7 @@ For more information about these matters, see the files named COPYING.\n"), { unsigned len = strlen (path_from_env); /* Trailing : on INFOPATH means insert the default path. */ - if (len && path_from_env[len - 1] == ':') + if (len && path_from_env[len - 1] == PATH_SEP[0]) { path_from_env[len - 1] = 0; info_add_path (DEFAULT_INFOPATH, INFOPATH_PREPEND); @@ -283,7 +319,14 @@ For more information about these matters, see the files named COPYING.\n"), if (temp != directory_name) { - *temp = 0; + if (HAVE_DRIVE (directory_name) && temp == directory_name + 2) + { + /* The directory of "d:foo" is stored as "d:.", to avoid + mixing it with "d:/" when a slash is appended. */ + *temp = '.'; + temp += 2; + } + temp[-1] = 0; info_add_path (directory_name, INFOPATH_PREPEND); } @@ -295,13 +338,13 @@ For more information about these matters, see the files named COPYING.\n"), if (apropos_p) { info_apropos (apropos_search_string); - exit (0); + xexit (0); } /* Get the initial Info node. It is either "(dir)Top", or what the user specifed with values in user_filename and user_nodenames. */ initial_node = info_get_node (user_filename, - user_nodenames ? user_nodenames[0] : NULL); + user_nodenames ? user_nodenames[0] : 0); /* If we couldn't get the initial node, this user is in trouble. */ if (!initial_node) @@ -309,9 +352,9 @@ For more information about these matters, see the files named COPYING.\n"), if (info_recent_file_error) info_error (info_recent_file_error); else - info_error - (CANT_FIND_NODE, user_nodenames ? user_nodenames[0] : "Top"); - exit (1); + info_error (msg_cant_find_node, + user_nodenames ? user_nodenames[0] : "Top"); + xexit (1); } /* Special cases for when the user specifies multiple nodes. If we @@ -328,228 +371,112 @@ For more information about these matters, see the files named COPYING.\n"), else begin_multiple_window_info_session (user_filename, user_nodenames); - exit (0); - } - - /* If the user specified `--index-search=STRING', start the info - session in the node corresponding to the first match. */ - if (index_search_p) - { - int status = 0; - - initialize_info_session (initial_node, 0); - - if (index_entry_exists (windows, index_search_string)) - { - terminal_clear_screen (); - terminal_prep_terminal (); - display_update_display (windows); - info_last_executed_command = (VFunction *)NULL; - - do_info_index_search (windows, 0, index_search_string); - - info_read_and_dispatch (); - - terminal_unprep_terminal (); - - /* On program exit, leave the cursor at the bottom of the - window, and restore the terminal IO. */ - terminal_goto_xy (0, screenheight - 1); - terminal_clear_to_eol (); - fflush (stdout); - } - else - { - fputs (_("no entries found\n"), stderr); - status = 2; - } - - close_dribble_file (); - exit (status); + xexit (0); } /* If there are arguments remaining, they are the names of menu items in sequential info files starting from the first one loaded. That file name is either "dir", or the contents of user_filename if one was specified. */ - while (optind != argc) - { - REFERENCE **menu; - REFERENCE *entry; - NODE *node; - char *arg; - static char *first_arg = (char *)NULL; - - /* Remember the name of the menu entry we want. */ - arg = argv[optind++]; - - if (!first_arg) - first_arg = arg; - - /* Build and return a list of the menu items in this node. */ - menu = info_menu_of_node (initial_node); - - /* If there wasn't a menu item in this node, stop here, but let - the user continue to use Info. Perhaps they wanted this node - and didn't realize it. */ - if (!menu) - { -#if defined (HANDLE_MAN_PAGES) - if (first_arg == arg) - { - node = make_manpage_node (first_arg); - if (node) - goto maybe_got_node; - } -#endif /* HANDLE_MAN_PAGES */ - begin_info_session_with_error - (initial_node, _("There is no menu in this node.")); - exit (0); - } - - /* Find the specified menu item. */ - entry = info_get_labeled_reference (arg, menu); - - /* If the item wasn't found, search the list sloppily. Perhaps this - user typed "buffer" when they really meant "Buffers". */ - if (!entry) - { - register int i; - int best_guess = -1; - - for (i = 0; (entry = menu[i]); i++) - { - if (strcasecmp (entry->label, arg) == 0) - break; - else - if (strncasecmp (entry->label, arg, strlen (arg)) == 0) - best_guess = i; - } - - if (!entry && best_guess != -1) - entry = menu[best_guess]; - } - - /* If we failed to find the reference, start Info with the current - node anyway. It is probably a misspelling. */ - if (!entry) - { - char *error_message = _("There is no menu item \"%s\" in this node."); - -#if defined (HANDLE_MAN_PAGES) - if (first_arg == arg) - { - node = make_manpage_node (first_arg); - if (node) - goto maybe_got_node; - } -#endif /* HANDLE_MAN_PAGES */ - - info_free_references (menu); - - /* If we were supposed to dump this node, complain. */ - if (user_output_filename) - info_error (error_message, arg); - else - begin_info_session_with_error (initial_node, error_message, arg); - - exit (0); - } - - /* We have found the reference that the user specified. Clean it - up a little bit. */ - if (!entry->filename) - { - if (initial_node->parent) - entry->filename = xstrdup (initial_node->parent); - else - entry->filename = xstrdup (initial_node->filename); - } - - /* Find this node. If we can find it, then turn the initial_node - into this one. If we cannot find it, try using the label of the - entry as a file (i.e., "(LABEL)Top"). Otherwise the Info file is - malformed in some way, and we will just use the current value of - initial node. */ - node = info_get_node (entry->filename, entry->nodename); - -#if defined (HANDLE_MAN_PAGES) - if ((first_arg == arg) && !node) - { - node = make_manpage_node (first_arg); - if (node) - goto maybe_got_node; - } -#endif /* HANDLE_MAN_PAGES */ - - if (!node && entry->nodename && - (strcmp (entry->label, entry->nodename) == 0)) - node = info_get_node (entry->label, "Top"); - - maybe_got_node: - if (node) - { - free (initial_node); - initial_node = node; - info_free_references (menu); - } - else - { - char *temp = xstrdup (entry->label); - char *error_message; - - error_message = _("Unable to find the node referenced by \"%s\"."); - - info_free_references (menu); - - /* If we were trying to dump the node, then give up. Otherwise, - start the session with an error message. */ - if (user_output_filename) - info_error (error_message, temp); - else - begin_info_session_with_error (initial_node, error_message, temp); - - exit (0); - } - } - - /* If the user specified that this node should be output, then do that - now. Otherwise, start the Info session with this node. */ - if (user_output_filename) - dump_node_to_file (initial_node, user_output_filename, dump_subnodes); - else - begin_info_session (initial_node); - - exit (0); -} - -/* Return a string describing the current version of Info. */ -char * -version_string () -{ - static char *vstring = (char *)NULL; - - if (!vstring) - { - vstring = (char *)xmalloc (50); - sprintf (vstring, "%d.%d", info_major_version, info_minor_version); - } - return (vstring); + { + char *errstr, *errarg1, *errarg2; + NODE *new_initial_node = info_follow_menus (initial_node, argv + optind, + &errstr, &errarg1, &errarg2); + if (new_initial_node && new_initial_node != initial_node) + initial_node = new_initial_node; + + /* If the user specified that this node should be output, then do that + now. Otherwise, start the Info session with this node. Or act + accordingly if the initial node was not found. */ + if (user_output_filename) + { + if (!errstr) + dump_node_to_file (initial_node, user_output_filename, + dump_subnodes); + else + info_error (errstr, errarg1, errarg2); + } + else + { + + if (errstr) + begin_info_session_with_error (initial_node, errstr, + errarg1, errarg2); + /* If the user specified `--index-search=STRING' or + --show-options, start the info session in the node + corresponding to what they want. */ + else if (index_search_p || goto_invocation_p) + { + int status = 0; + + initialize_info_session (initial_node, 0); + + if (goto_invocation_p + || index_entry_exists (windows, index_search_string)) + { + terminal_prep_terminal (); + terminal_clear_screen (); + info_last_executed_command = (VFunction *)NULL; + + if (index_search_p) + do_info_index_search (windows, 0, index_search_string); + else + { + /* If they said "info --show-options foo bar baz", + the last of the arguments is the program whose + options they want to see. */ + char **p = argv + optind; + char *program; + + if (*p) + { + while (p[1]) + p++; + program = xstrdup (*p); + } + else if (user_filename) + /* If there's no command-line arguments to + supply the program name, use the Info file + name (sans extension and leading directories) + instead. */ + program = program_name_from_file_name (user_filename); + else + program = xstrdup (""); + + info_intuit_options_node (windows, initial_node, program); + free (program); + } + + info_read_and_dispatch (); + + /* On program exit, leave the cursor at the bottom of the + window, and restore the terminal IO. */ + terminal_goto_xy (0, screenheight - 1); + terminal_clear_to_eol (); + fflush (stdout); + terminal_unprep_terminal (); + } + else + { + fprintf (stderr, _("no index entries found for `%s'\n"), + index_search_string); + status = 2; + } + + close_dribble_file (); + xexit (status); + } + else + begin_info_session (initial_node); + } + + xexit (0); + } } /* Error handling. */ -static void -remember_info_program_name (fullpath) - char *fullpath; -{ - char *filename; - - filename = filename_non_directory (fullpath); - program_name = xstrdup (filename); -} - /* Non-zero if an error has been signalled. */ int info_error_was_printed = 0; @@ -595,33 +522,99 @@ info_error (format, arg1, arg2) } } + /* Produce a scaled down description of the available options to Info. */ static void info_short_help () { printf (_("\ -Usage: %s [OPTION]... [INFO-FILE [MENU-ITEM...]]\n\ +Usage: %s [OPTION]... [MENU-ITEM...]\n\ \n\ Read documentation in Info format.\n\ -For more complete documentation on how to use Info, run `info info options'.\n\ \n\ Options:\n\ ---directory DIR add DIR to INFOPATH.\n\ ---dribble FILENAME remember user keystrokes in FILENAME.\n\ ---file FILENAME specify Info file to visit.\n\ ---node NODENAME specify nodes in first visited Info file.\n\ ---output FILENAME output selected nodes to FILENAME.\n\ ---restore FILENAME read initial keystrokes from FILENAME.\n\ ---subnodes recursively output menu items.\n\ ---help display this help and exit.\n\ ---version display version information and exit.\n\ + --apropos=SUBJECT look up SUBJECT in all indices of all manuals.\n\ + --directory=DIR add DIR to INFOPATH.\n\ + --dribble=FILENAME remember user keystrokes in FILENAME.\n\ + --file=FILENAME specify Info file to visit.\n\ + --help display this help and exit.\n\ + --index-search=STRING go to node pointed by index entry STRING.\n\ + --node=NODENAME specify nodes in first visited Info file.\n\ + --output=FILENAME output selected nodes to FILENAME.\n\ + --restore=FILENAME read initial keystrokes from FILENAME.\n\ + --show-options, --usage go to command-line options node.\n\ + --subnodes recursively output menu items.\n%s\ + --vi-keys use vi-like and less-like key bindings.\n\ + --version display version information and exit.\n\ \n\ -The first argument, if present, is the name of the Info file to read.\n\ +The first non-option argument, if present, is the menu entry to start from;\n\ +it is searched for in all `dir' files along INFOPATH.\n\ +If it is not present, info merges all `dir' files and shows the result.\n\ Any remaining arguments are treated as the names of menu\n\ -items in the initial node visited. For example, `info emacs buffers'\n\ -moves to the node `buffers' in the info file `emacs'.\n\ +items relative to the initial node visited.\n\ +\n\ +Examples:\n\ + info show top-level dir menu\n\ + info emacs start at emacs node from top-level dir\n\ + info emacs buffers start at buffers node within emacs manual\n\ + info --show-options emacs start at node with emacs' command line options\n\ + info -f ./foo.info show file ./foo.info, not searching dir\n\ \n\ -Email bug reports to bug-texinfo@gnu.org."), program_name); +Email bug reports to bug-texinfo@gnu.org,\n\ +general questions and discussion to help-texinfo@gnu.org.\n\ +"), + program_name, +#ifdef __MSDOS__ +"\ + --speech-friendly be friendly to speech synthesizers.\n" +#else +"" +#endif + ); - exit (0); + xexit (0); +} + + +/* Initialize strings for gettext. Because gettext doesn't handle N_ or + _ within macro definitions, we put shared messages into variables and + use them that way. This also has the advantage that there's only one + copy of the strings. */ + +char *msg_cant_find_node; +char *msg_cant_file_node; +char *msg_cant_find_window; +char *msg_cant_find_point; +char *msg_cant_kill_last; +char *msg_no_menu_node; +char *msg_no_foot_node; +char *msg_no_xref_node; +char *msg_no_pointer; +char *msg_unknown_command; +char *msg_term_too_dumb; +char *msg_at_node_bottom; +char *msg_at_node_top; +char *msg_one_window; +char *msg_win_too_small; +char *msg_cant_make_help; + +static void +init_messages () +{ + msg_cant_find_node = _("Cannot find node `%s'."); + msg_cant_file_node = _("Cannot find node `(%s)%s'."); + msg_cant_find_window = _("Cannot find a window!"); + msg_cant_find_point = _("Point doesn't appear within this window's node!"); + msg_cant_kill_last = _("Cannot delete the last window."); + msg_no_menu_node = _("No menu in this node."); + msg_no_foot_node = _("No footnotes in this node."); + msg_no_xref_node = _("No cross references in this node."); + msg_no_pointer = _("No `%s' pointer for this node."); + msg_unknown_command = _("Unknown Info command `%c'; try `?' for help."); + msg_term_too_dumb = _("Terminal type `%s' is not smart enough to run Info."); + msg_at_node_bottom = _("You are already at the last page of this node."); + msg_at_node_top = _("You are already at the first page of this node."); + msg_one_window = _("Only one window."); + msg_win_too_small = _("Resulting window would be too small."); + msg_cant_make_help = _("Not enough room for a help window, please delete a window."); } diff --git a/contrib/texinfo/info/info.h b/contrib/texinfo/info/info.h index 092ef41..2f85d80 100644 --- a/contrib/texinfo/info/info.h +++ b/contrib/texinfo/info/info.h @@ -1,10 +1,7 @@ /* info.h -- Header file which includes all of the other headers. - $Id: info.h,v 1.7 1998/02/27 21:36:04 karl Exp $ + $Id: info.h,v 1.14 1999/09/25 16:10:04 karl Exp $ - This file is part of GNU Info, a program for reading online documentation - stored in Info format. - - Copyright (C) 1993, 97, 98 Free Software Foundation, Inc. + Copyright (C) 1993, 97, 98, 99 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -22,7 +19,7 @@ Written by Brian Fox (bfox@ai.mit.edu). */ -#if !defined (INFO_H) +#ifndef INFO_H #define INFO_H /* We always want these, so why clutter up the compile command? */ @@ -119,6 +116,9 @@ extern int info_error_was_printed; /* Non-zero means ring terminal bell on errors. */ extern int info_error_rings_bell_p; +/* Non-zero means default keybindings are loosely modeled on vi(1). */ +extern int vi_keys_p; + /* Print FORMAT with ARG1 and ARG2. If the window system was initialized, then the message is printed in the echo area. Otherwise, a message is output to stderr. */ @@ -127,28 +127,23 @@ extern void info_error (); /* The version numbers of Info. */ extern int info_major_version, info_minor_version; -/* How to get the version string for this version of Info. Returns - something similar to "2.11". */ -extern char *version_string (); - /* Error message defines. */ -#define CANT_FIND_NODE _("Cannot find the node \"%s\".") -#define CANT_FILE_NODE _("Cannot find the node \"(%s)%s\".") -#define CANT_FIND_WIND _("Cannot find a window!") -#define CANT_FIND_POINT _("Point doesn't appear within this window's node!") -#define CANT_KILL_LAST _("Cannot delete the last window.") -#define NO_MENU_NODE _("No menu in this node.") -#define NO_FOOT_NODE _("No footnotes in this node.") -#define NO_XREF_NODE _("No cross references in this node.") -#define NO_POINTER _("No \"%s\" pointer for this node.") -#define UNKNOWN_COMMAND _("Unknown Info command `%c'. `?' for help.") -#define TERM_TOO_DUMB _("Terminal type \"%s\" is not smart enough to run Info.") -#define AT_NODE_BOTTOM _("You are already at the last page of this node.") -#define AT_NODE_TOP _("You are already at the first page of this node.") -#define ONE_WINDOW _("Only one window.") -#define WIN_TOO_SMALL _("Resulting window would be too small.") -#define CANT_MAKE_HELP \ -_("There isn't enough room to make a help window. Please delete a window.") +extern char *msg_cant_find_node; +extern char *msg_cant_file_node; +extern char *msg_cant_find_window; +extern char *msg_cant_find_point; +extern char *msg_cant_kill_last; +extern char *msg_no_menu_node; +extern char *msg_no_foot_node; +extern char *msg_no_xref_node; +extern char *msg_no_pointer; +extern char *msg_unknown_command; +extern char *msg_term_too_dumb; +extern char *msg_at_node_bottom; +extern char *msg_at_node_top; +extern char *msg_one_window; +extern char *msg_win_too_small; +extern char *msg_cant_make_help; /* Found in info-utils.c. */ diff --git a/contrib/texinfo/info/infodoc.c b/contrib/texinfo/info/infodoc.c index 4fc0419..2b70918 100644 --- a/contrib/texinfo/info/infodoc.c +++ b/contrib/texinfo/info/infodoc.c @@ -1,7 +1,7 @@ /* infodoc.c -- Functions which build documentation nodes. - $Id: infodoc.c,v 1.4 1997/07/25 21:08:40 karl Exp $ + $Id: infodoc.c,v 1.23 1999/09/25 16:10:04 karl Exp $ - Copyright (C) 1993, 97 Free Software Foundation, Inc. + Copyright (C) 1993, 97, 98, 99 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -21,14 +21,9 @@ #include "info.h" -/* Normally we do not define HELP_NODE_GETS_REGENERATED because the - contents of the help node currently can never change once an info - session has been started. You should consider defining this in - the case that you place information about dynamic variables in the - help text. When that happens, the contents of the help node will - change dependent on the value of those variables, and the user will - expect to see those changes. */ -/* #define HELP_NODE_GETS_REGENERATED 1 */ +/* HELP_NODE_GETS_REGENERATED is always defined now that keys may get + rebound, or other changes in the help text may occur. */ +#define HELP_NODE_GETS_REGENERATED 1 /* **************************************************************** */ /* */ @@ -47,40 +42,94 @@ static char *internal_info_help_node_contents = (char *)NULL; /* The static text which appears in the internal info help node. */ static char *info_internal_help_text[] = { - N_ ("Basic Commands in Info Windows"), - "******************************", - "", - " h Invoke the Info tutorial.", - " CTRL-x 0 Quit this help.", - " q Quit Info altogether.", - "", - "Selecting other nodes:", - "----------------------", - " n Move to the \"next\" node of this node.", - " p Move to the \"previous\" node of this node.", - " u Move \"up\" from this node.", - " m Pick menu item specified by name.", - " Picking a menu item causes another node to be selected.", - " f Follow a cross reference. Reads name of reference.", - " l Move to the last node seen in this window.", - " d Move to the `directory' node. Equivalent to `g(DIR)'.", - "", - "Moving within a node:", - "---------------------", - " SPC Scroll forward a page.", - " DEL Scroll backward a page.", - " b Go to the beginning of this node.", - " e Go to the end of this node.", - "", - "Other commands:", - "--------------------", - " 1 Pick first item in node's menu.", - " 2-9 Pick second ... ninth item in node's menu.", - " 0 Pick last item in node's menu.", - " g Move to node specified by name.", - " You may include a filename as well, as in (FILENAME)NODENAME.", - " s Search through this Info file for a specified string,", - " and select the node in which the next occurrence is found.", + N_("Basic Commands in Info Windows\n"), + N_("******************************\n"), + "\n", + N_(" %-10s Quit this help.\n"), + N_(" %-10s Quit Info altogether.\n"), + N_(" %-10s Invoke the Info tutorial.\n"), + "\n", + N_("Moving within a node:\n"), + N_("---------------------\n"), + N_(" %-10s Scroll forward a page.\n"), + N_(" %-10s Scroll backward a page.\n"), + N_(" %-10s Go to the beginning of this node.\n"), + N_(" %-10s Go to the end of this node.\n"), + N_(" %-10s Scroll forward 1 line.\n"), + N_(" %-10s Scroll backward 1 line.\n"), + "\n", + N_("Selecting other nodes:\n"), + N_("----------------------\n"), + N_(" %-10s Move to the `next' node of this node.\n"), + N_(" %-10s Move to the `previous' node of this node.\n"), + N_(" %-10s Move `up' from this node.\n"), + N_(" %-10s Pick menu item specified by name.\n"), + N_(" Picking a menu item causes another node to be selected.\n"), + N_(" %-10s Follow a cross reference. Reads name of reference.\n"), + N_(" %-10s Move to the last node seen in this window.\n"), + N_(" %-10s Skip to next hypertext link within this node.\n"), + N_(" %-10s Follow the hypertext link under cursor.\n"), + N_(" %-10s Move to the `directory' node. Equivalent to `g (DIR)'.\n"), + N_(" %-10s Move to the Top node. Equivalent to `g Top'.\n"), + "\n", + N_("Other commands:\n"), + N_("---------------\n"), + N_(" %-10s Pick first ... ninth item in node's menu.\n"), + N_(" %-10s Pick last item in node's menu.\n"), + N_(" %-10s Search for a specified string in the index entries of this Info\n"), + N_(" file, and select the node referenced by the first entry found.\n"), + N_(" %-10s Move to node specified by name.\n"), + N_(" You may include a filename as well, as in (FILENAME)NODENAME.\n"), + N_(" %-10s Search forward through this Info file for a specified string,\n"), + N_(" and select the node in which the next occurrence is found.\n"), + N_(" %-10s Search backward in this Info file for a specified string,\n"), + N_(" and select the node in which the next occurrence is found.\n"), + NULL +}; + +static char *info_help_keys_text[][2] = { + { "", "" }, + { "", "" }, + { "", "" }, + { "CTRL-x 0", "CTRL-x 0" }, + { "q", "q" }, + { "h", "ESC h" }, + { "", "" }, + { "", "" }, + { "", "" }, + { "SPC", "SPC" }, + { "DEL", "b" }, + { "b", "ESC b" }, + { "e", "ESC e" }, + { "ESC 1 SPC", "RET" }, + { "ESC 1 DEL", "y" }, + { "", "" }, + { "", "" }, + { "", "" }, + { "n", "CTRL-x n" }, + { "p", "CTRL-x p" }, + { "u", "CTRL-x u" }, + { "m", "ESC m" }, + { "", "" }, + { "f", "ESC f" }, + { "l", "l" }, + { "TAB", "TAB" }, + { "RET", "CTRL-x RET" }, + { "d", "ESC d" }, + { "t", "ESC t" }, + { "", "" }, + { "", "" }, + { "", "" }, + { "1-9", "ESC 1-9" }, + { "0", "ESC 0" }, + { "i", "CTRL-x i" }, + { "", "" }, + { "g", "CTRL-x g" }, + { "", "" }, + { "s", "/" }, + { "", "" }, + { "ESC - s", "?" }, + { "", "" }, NULL }; @@ -163,15 +212,21 @@ dump_map_to_message_buffer (prefix, map) } } -/* How to create internal_info_help_node. */ +/* How to create internal_info_help_node. HELP_IS_ONLY_WINDOW_P says + whether we're going to end up in a second (or more) window of our + own, or whether there's only one window and we're going to usurp it. + This determines how to quit the help window. Maybe we should just + make q do the right thing in both cases. */ + static void -create_internal_info_help_node () +create_internal_info_help_node (help_is_only_window_p) + int help_is_only_window_p; { register int i; - char *contents = (char *)NULL; NODE *node; + char *contents = NULL; -#if !defined (HELP_NODE_GETS_REGENERATED) +#ifndef HELP_NODE_GETS_REGENERATED if (internal_info_help_node_contents) contents = internal_info_help_node_contents; #endif /* !HELP_NODE_GETS_REGENERATED */ @@ -183,16 +238,30 @@ create_internal_info_help_node () initialize_message_buffer (); for (i = 0; info_internal_help_text[i]; i++) - printf_to_message_buffer ("%s\n", info_internal_help_text[i]); + { + /* Don't translate blank lines, gettext outputs the po file + header in that case. We want a blank line. */ + char *msg = *(info_internal_help_text[i]) + ? _(info_internal_help_text[i]) + : info_internal_help_text[i]; + char *key = info_help_keys_text[i][vi_keys_p]; + + /* If we have only one window (because the window size was too + small to split it), CTRL-x 0 doesn't work to `quit' help. */ + if (STREQ (key, "CTRL-x 0") && help_is_only_window_p) + key = "l"; + + printf_to_message_buffer (msg, key); + } printf_to_message_buffer ("---------------------\n\n"); - printf_to_message_buffer ("The current search path is:\n"); - printf_to_message_buffer (" \"%s\"\n", infopath); + printf_to_message_buffer (_("The current search path is:\n")); + printf_to_message_buffer (" %s\n", infopath); printf_to_message_buffer ("---------------------\n\n"); - printf_to_message_buffer ("Commands available in Info windows:\n\n"); + printf_to_message_buffer (_("Commands available in Info windows:\n\n")); dump_map_to_message_buffer ("", info_keymap); printf_to_message_buffer ("---------------------\n\n"); - printf_to_message_buffer ("Commands available in the echo area:\n\n"); + printf_to_message_buffer (_("Commands available in the echo area:\n\n")); dump_map_to_message_buffer ("", echo_area_keymap); #if defined (NAMED_FUNCTIONS) @@ -215,7 +284,11 @@ create_internal_info_help_node () printf_to_message_buffer ("M-x %s\n %s\n", function_doc_array[i].func_name, - replace_in_documentation (function_doc_array[i].doc)); + replace_in_documentation (strlen (function_doc_array[i].doc) + == 0 + ? function_doc_array[i].doc + : _(function_doc_array[i].doc))); + } } @@ -258,17 +331,22 @@ create_internal_info_help_node () } /* Return a window which is the window showing help in this Info. */ + +/* If the eligible window's height is >= this, split it to make the help + window. Otherwise display the help window in the current window. */ +#define HELP_SPLIT_SIZE 24 + static WINDOW * info_find_or_create_help_window () { - WINDOW *help_window, *eligible, *window; - - eligible = (WINDOW *)NULL; - help_window = get_internal_info_window (info_help_nodename); + int help_is_only_window_p; + WINDOW *eligible = NULL; + WINDOW *help_window = get_window_of_node (internal_info_help_node); /* If we couldn't find the help window, then make it. */ if (!help_window) { + WINDOW *window; int max = 0; for (window = windows; window; window = window->next) @@ -281,23 +359,29 @@ info_find_or_create_help_window () } if (!eligible) - return ((WINDOW *)NULL); + return NULL; } -#if !defined (HELP_NODE_GETS_REGENERATED) +#ifndef HELP_NODE_GETS_REGENERATED else - return (help_window); -#endif /* !HELP_NODE_GETS_REGENERATED */ - - /* Make sure that we have a node containing the help text. */ - create_internal_info_help_node (); + /* help window is static, just return it. */ + return help_window; +#endif /* not HELP_NODE_GETS_REGENERATED */ + + /* Make sure that we have a node containing the help text. The + argument is false if help will be the only window (so l must be used + to quit help), true if help will be one of several visible windows + (so CTRL-x 0 must be used to quit help). */ + help_is_only_window_p + = (help_window && !windows->next + || !help_window && eligible->height < HELP_SPLIT_SIZE); + create_internal_info_help_node (help_is_only_window_p); /* Either use the existing window to display the help node, or create a new window if there was no existing help window. */ if (!help_window) - { - /* Split the largest window into 2 windows, and show the help text + { /* Split the largest window into 2 windows, and show the help text in that window. */ - if (eligible->height > 30) + if (eligible->height >= HELP_SPLIT_SIZE) { active_window = eligible; help_window = window_make_window (internal_info_help_node); @@ -310,8 +394,7 @@ info_find_or_create_help_window () } } else - { - /* Case where help node always gets regenerated, and we have an + { /* Case where help node always gets regenerated, and we have an existing window in which to place the node. */ if (active_window != help_window) { @@ -321,7 +404,7 @@ info_find_or_create_help_window () window_set_node_of_window (active_window, internal_info_help_node); } remember_window_and_node (help_window, help_window->node); - return (help_window); + return help_window; } /* Create or move to the help window. */ @@ -337,7 +420,7 @@ DECLARE_INFO_COMMAND (info_get_help_window, _("Display help message")) } else { - info_error (CANT_MAKE_HELP); + info_error (msg_cant_make_help); } } @@ -381,7 +464,7 @@ DECLARE_INFO_COMMAND (info_get_info_help_node, _("Visit Info node `(info)Help'") if (info_recent_file_error) info_error (info_recent_file_error); else - info_error (CANT_FILE_NODE, "Info", nodename); + info_error (msg_cant_file_node, "Info", nodename); } else { @@ -418,7 +501,9 @@ function_documentation (function) if (function == function_doc_array[i].func) break; - return (replace_in_documentation (function_doc_array[i].doc)); + return replace_in_documentation ((strlen (function_doc_array[i].doc) == 0) + ? function_doc_array[i].doc + : _(function_doc_array[i].doc)); } #if defined (NAMED_FUNCTIONS) @@ -475,21 +560,21 @@ DECLARE_INFO_COMMAND (describe_key, _("Print documentation for KEY")) char *rep; Keymap map; - keyname[0] = '\0'; + keyname[0] = 0; map = window->keymap; - while (1) + for (;;) { message_in_echo_area (_("Describe key: %s"), keyname); keystroke = info_get_input_char (); unmessage_in_echo_area (); - if (Meta_p (keystroke) && (!ISO_Latin_p || key < 160)) + if (Meta_p (keystroke)) { if (map[ESC].type != ISKMAP) { window_message_in_echo_area - (_("ESC %s is undefined."), pretty_keyname (UnMeta (keystroke))); + (_("ESC %s is undefined."), pretty_keyname (UnMeta (keystroke))); return; } @@ -627,7 +712,7 @@ replace_in_documentation (string) /* Find a key which invokes this function in the info_keymap. */ function = named_function (fun_name); - /* If the internal documentation string fails, there is a + /* If the internal documentation string fails, there is a serious problem with the associated command's documentation. We croak so that it can be fixed immediately. */ if (!function) @@ -687,7 +772,7 @@ where_is_internal (map, function) VFunction *function; { register int i; - + /* If the function is directly invokable in MAP, return the representation of that keystroke. */ for (i = 0; i < 256; i++) @@ -718,13 +803,13 @@ where_is_internal (map, function) } } - return ((char *)NULL); + return NULL; } extern char *read_function_name (); DECLARE_INFO_COMMAND (info_where_is, - "Show what to type to execute a given command") + _("Show what to type to execute a given command")) { char *command_name; diff --git a/contrib/texinfo/info/m-x.c b/contrib/texinfo/info/m-x.c index 28b8e80..2fc5a60 100644 --- a/contrib/texinfo/info/m-x.c +++ b/contrib/texinfo/info/m-x.c @@ -1,7 +1,7 @@ -/* m-x.c -- Meta-X minibuffer reader. - $Id: m-x.c,v 1.5 1997/07/24 21:28:00 karl Exp $ +/* m-x.c -- Meta-x minibuffer reader. + $Id: m-x.c,v 1.8 1999/06/25 21:57:40 karl Exp $ - Copyright (C) 1993, 97 Free Software Foundation, Inc. + Copyright (C) 1993, 97, 98 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -149,7 +149,7 @@ DECLARE_INFO_COMMAND (info_execute_command, DECLARE_INFO_COMMAND (set_screen_height, _("Set the height of the displayed window")) { - int new_height; + int new_height, old_height = screenheight; if (info_explicit_arg || count != 1) new_height = count; @@ -185,6 +185,20 @@ DECLARE_INFO_COMMAND (set_screen_height, terminal_clear_screen (); display_clear_display (the_display); screenheight = new_height; - display_initialize_display (screenwidth, screenheight); - window_new_screen_size (screenwidth, screenheight); +#ifdef SET_SCREEN_SIZE_HELPER + SET_SCREEN_SIZE_HELPER; +#endif + if (screenheight == old_height) + { + /* Display dimensions didn't actually change, so + window_new_screen_size won't do anything, but we've + already cleared the display above. Undo the damage. */ + window_mark_chain (windows, W_UpdateWindow); + display_update_display (windows); + } + else + { + display_initialize_display (screenwidth, screenheight); + window_new_screen_size (screenwidth, screenheight); + } } diff --git a/contrib/texinfo/info/man.c b/contrib/texinfo/info/man.c index a669595..ee68cbb 100644 --- a/contrib/texinfo/info/man.c +++ b/contrib/texinfo/info/man.c @@ -1,7 +1,7 @@ /* man.c: How to read and format man files. - $Id: man.c,v 1.6 1997/07/31 23:49:59 karl Exp $ + $Id: man.c,v 1.13 1999/07/05 20:43:23 karl Exp $ - Copyright (C) 1995, 97 Free Software Foundation, Inc. + Copyright (C) 1995, 97, 98, 99 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -44,6 +44,14 @@ # endif /* !hpux */ #endif /* FD_SET */ +#if STRIP_DOT_EXE +static char const * const exec_extensions[] = { + ".exe", ".com", ".bat", ".btm", ".sh", ".ksh", ".pl", ".sed", "", NULL +}; +#else +static char const * const exec_extensions[] = { "", NULL }; +#endif + static char *read_from_fd (); static void clean_manpage (); static NODE *manpage_node_of_file_buffer (); @@ -76,6 +84,7 @@ get_manpage_node (file_buffer, pagename) char header[1024]; long oldsize, newsize; int hlen, plen; + char *old_contents = file_buffer->contents; sprintf (header, "\n\n%c\n%s %s, %s %s, %s (dir)\n\n", INFO_COOKIE, @@ -89,13 +98,49 @@ get_manpage_node (file_buffer, pagename) file_buffer->contents = (char *)xrealloc (file_buffer->contents, 1 + newsize); memcpy (file_buffer->contents + oldsize, header, hlen); - oldsize += hlen; - memcpy (file_buffer->contents + oldsize, page, plen); + memcpy (file_buffer->contents + oldsize + hlen, page, plen); file_buffer->contents[newsize] = '\0'; file_buffer->filesize = newsize; file_buffer->finfo.st_size = newsize; build_tags_and_nodes (file_buffer); free (page); + /* We have just relocated file_buffer->contents from under + the feet of info_windows[] array. Therefore, all the + nodes on that list which are showing man pages have their + contents member pointing into the blue. Undo that harm. */ + if (old_contents && oldsize && old_contents != file_buffer->contents) + { + int iw; + INFO_WINDOW *info_win; + char *old_contents_end = old_contents + oldsize; + + for (iw = 0; (info_win = info_windows[iw]); iw++) + { + int in; + + for (in = 0; in < info_win->nodes_index; in++) + { + NODE *node = info_win->nodes[in]; + + /* It really only suffices to see that node->filename + is "*manpages*". But after several hours of + debugging this, would you blame me for being a bit + paranoid? */ + if (node && node->filename && node->contents && + strcmp (node->filename, + MANPAGE_FILE_BUFFER_NAME) == 0 && + node->contents >= old_contents && + node->contents + node->nodelen <= old_contents_end) + { + info_win->nodes[in] = + manpage_node_of_file_buffer (file_buffer, + node->nodename); + free (node->nodename); + free (node); + } + } + } + } } node = manpage_node_of_file_buffer (file_buffer, pagename); @@ -134,6 +179,8 @@ executable_file_in_path (filename, path) while ((temp_dirname = extract_colon_unit (path, &dirname_index))) { char *temp; + char *temp_end; + int i; /* Expand a leading tilde if one is present. */ if (*temp_dirname == '~') @@ -145,22 +192,30 @@ executable_file_in_path (filename, path) temp_dirname = expanded_dirname; } - temp = (char *)xmalloc (30 + strlen (temp_dirname) + strlen (filename)); + temp = (char *)xmalloc (34 + strlen (temp_dirname) + strlen (filename)); strcpy (temp, temp_dirname); - if (temp[(strlen (temp)) - 1] != '/') + if (!IS_SLASH (temp[(strlen (temp)) - 1])) strcat (temp, "/"); strcat (temp, filename); + temp_end = temp + strlen (temp); free (temp_dirname); - statable = (stat (temp, &finfo) == 0); - - /* If we have found a regular executable file, then use it. */ - if ((statable) && (S_ISREG (finfo.st_mode)) && - (access (temp, X_OK) == 0)) - return (temp); - else - free (temp); + /* Look for FILENAME, possibly with any of the extensions + in EXEC_EXTENSIONS[]. */ + for (i = 0; exec_extensions[i]; i++) + { + if (exec_extensions[i][0]) + strcpy (temp_end, exec_extensions[i]); + statable = (stat (temp, &finfo) == 0); + + /* If we have found a regular executable file, then use it. */ + if ((statable) && (S_ISREG (finfo.st_mode)) && + (access (temp, X_OK) == 0)) + return (temp); + } + + free (temp); } return ((char *)NULL); } @@ -210,13 +265,14 @@ get_page_and_section (pagename) } } +#if PIPE_USE_FORK static void reap_children (sig) int sig; { - int status; - wait (&status); + wait (NULL); } +#endif static char * get_manpage_contents (pagename) @@ -225,7 +281,8 @@ get_manpage_contents (pagename) static char *formatter_args[4] = { (char *)NULL }; int pipes[2]; pid_t child; - char *formatted_page = (char *)NULL; + RETSIGTYPE (*sigsave) (); + char *formatted_page = NULL; int arg_index = 1; if (formatter_args[0] == (char *)NULL) @@ -245,12 +302,12 @@ get_manpage_contents (pagename) /* Open a pipe to this program, read the output, and save it away in FORMATTED_PAGE. The reader end of the pipe is pipes[0]; the writer end is pipes[1]. */ +#if PIPE_USE_FORK pipe (pipes); - signal (SIGCHLD, reap_children); + sigsave = signal (SIGCHLD, reap_children); child = fork (); - if (child == -1) return ((char *)NULL); @@ -261,14 +318,14 @@ get_manpage_contents (pagename) close (pipes[1]); formatted_page = read_from_fd (pipes[0]); close (pipes[0]); + signal (SIGCHLD, sigsave); } else - { - /* In the child, close the read end of the pipe, make the write end + { /* In the child, close the read end of the pipe, make the write end of the pipe be stdout, and execute the man page formatter. */ close (pipes[0]); - close (fileno (stderr)); - close (fileno (stdin)); /* Don't print errors. */ + freopen (NULL_DEVICE, "w", stderr); + freopen (NULL_DEVICE, "r", stdin); dup2 (pipes[1], fileno (stdout)); execv (formatter_args[0], formatter_args); @@ -276,8 +333,39 @@ get_manpage_contents (pagename) /* If we get here, we couldn't exec, so close out the pipe and exit. */ close (pipes[1]); - exit (0); + xexit (0); } +#else /* !PIPE_USE_FORK */ + /* Cannot fork/exec, but can popen/pclose. */ + { + FILE *fpipe; + char *cmdline = xmalloc (strlen (formatter_args[0]) + + strlen (manpage_pagename) + + (arg_index > 2 ? strlen (manpage_section) : 0) + + 3); + int save_stderr = dup (fileno (stderr)); + int fd_err = open (NULL_DEVICE, O_WRONLY, 0666); + + if (fd_err > 2) + dup2 (fd_err, fileno (stderr)); /* Don't print errors. */ + sprintf (cmdline, "%s %s %s", formatter_args[0], manpage_pagename, + arg_index > 2 ? manpage_section : ""); + fpipe = popen (cmdline, "r"); + free (cmdline); + if (fd_err > 2) + close (fd_err); + dup2 (save_stderr, fileno (stderr)); + if (fpipe == 0) + return ((char *)NULL); + formatted_page = read_from_fd (fileno (fpipe)); + if (pclose (fpipe) == -1) + { + if (formatted_page) + free (formatted_page); + return ((char *)NULL); + } + } +#endif /* !PIPE_USE_FORK */ /* If we have the page, then clean it up. */ if (formatted_page) @@ -342,10 +430,11 @@ manpage_node_of_file_buffer (file_buffer, pagename) { node = (NODE *)xmalloc (sizeof (NODE)); node->filename = file_buffer->filename; - node->nodename = tag->nodename; + node->nodename = xstrdup (tag->nodename); node->contents = file_buffer->contents + tag->nodestart; node->nodelen = tag->nodelen; node->flags = 0; + node->display_pos = 0; node->parent = (char *)NULL; node->flags = (N_HasTagsTable | N_IsManPage); node->contents += skip_node_separator (node->contents); diff --git a/contrib/texinfo/info/nodes.c b/contrib/texinfo/info/nodes.c index f2737e7..0aaee52 100644 --- a/contrib/texinfo/info/nodes.c +++ b/contrib/texinfo/info/nodes.c @@ -1,9 +1,7 @@ -/* nodes.c -- How to get an Info file and node. */ +/* nodes.c -- how to get an Info file and node. + $Id: nodes.c,v 1.14 1999/08/15 10:18:09 karl Exp $ -/* This file is part of GNU Info, a program for reading online documentation - stored in Info format. - - Copyright (C) 1993 Free Software Foundation, Inc. + Copyright (C) 1993, 98, 99 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -32,12 +30,6 @@ # include "man.h" #endif /* HANDLE_MAN_PAGES */ -/* **************************************************************** */ -/* */ -/* Functions Static to this File */ -/* */ -/* **************************************************************** */ - static void forget_info_file (), remember_info_file (); static void free_file_buffer_tags (), free_info_tag (); static void get_nodes_of_tags_table (), get_nodes_of_info_file (); @@ -50,8 +42,7 @@ static NODE *info_node_of_file_buffer_tags (); static long get_node_length (); /* Magic number that RMS used to decide how much a tags table pointer could - be off by. I feel that it should be much smaller, like on the order of - 4. */ + be off by. I feel that it should be much smaller, like 4. */ #define DEFAULT_INFO_FUDGE 1000 /* Passed to *_internal functions. INFO_GET_TAGS says to do what is @@ -59,46 +50,36 @@ static long get_node_length (); #define INFO_NO_TAGS 0 #define INFO_GET_TAGS 1 -/* **************************************************************** */ -/* */ -/* Global Variables */ -/* */ -/* **************************************************************** */ +/* Global variables. */ /* When non-zero, this is a string describing the recent file error. */ -char *info_recent_file_error = (char *)NULL; +char *info_recent_file_error = NULL; /* The list of already loaded nodes. */ -FILE_BUFFER **info_loaded_files = (FILE_BUFFER **)NULL; +FILE_BUFFER **info_loaded_files = NULL; /* The number of slots currently allocated to LOADED_FILES. */ int info_loaded_files_slots = 0; -/* **************************************************************** */ -/* */ -/* Public Functions for Node Manipulation */ -/* */ -/* **************************************************************** */ +/* Public functions for node manipulation. */ -/* Used to build "dir" menu from "localdir" files found in INFOPATH. */ +/* Used to build `dir' menu from `localdir' files found in INFOPATH. */ extern void maybe_build_dir_node (); /* Return a pointer to a NODE structure for the Info node (FILENAME)NODENAME. - FILENAME can be passed as NULL, in which case the filename of "dir" is used. - NODENAME can be passed as NULL, in which case the nodename of "Top" is used. - If the node cannot be found, return a NULL pointer. */ + If FILENAME is NULL, `dir' is used. + IF NODENAME is NULL, `Top' is used. + If the node cannot be found, return NULL. */ NODE * info_get_node (filename, nodename) char *filename, *nodename; { - FILE_BUFFER *file_buffer; NODE *node; + FILE_BUFFER *file_buffer = NULL; - file_buffer = (FILE_BUFFER *)NULL; - info_recent_file_error = (char *)NULL; - + info_recent_file_error = NULL; info_parse_node (nodename, DONT_SKIP_NEWLINES); - nodename = (char *)NULL; + nodename = NULL; if (info_parsed_filename) filename = info_parsed_filename; @@ -112,23 +93,23 @@ info_get_node (filename, nodename) /* If the file to be looked up is "dir", build the contents from all of the "dir"s and "localdir"s found in INFOPATH. */ - if (strcasecmp (filename, "dir") == 0) + if (is_dir_name (filename)) maybe_build_dir_node (filename); - /* Find the correct info file. */ + /* Find the correct info file, or give up. */ file_buffer = info_find_file (filename); - if (!file_buffer) { if (filesys_error_number) info_recent_file_error = filesys_error_string (filename, filesys_error_number); - return ((NODE *)NULL); + return NULL; } + /* Look for the node. */ node = info_get_node_of_file_buffer (nodename, file_buffer); - /* If the node looked for was "Top", try again looking for the node under - a slightly different name. */ + + /* If the node not found was "Top", try again with different case. */ if (!node && (nodename == NULL || strcasecmp (nodename, "Top") == 0)) { node = info_get_node_of_file_buffer ("Top", file_buffer); @@ -137,7 +118,8 @@ info_get_node (filename, nodename) if (!node) node = info_get_node_of_file_buffer ("TOP", file_buffer); } - return (node); + + return node; } /* Return a pointer to a NODE structure for the Info node NODENAME in @@ -149,12 +131,12 @@ info_get_node_of_file_buffer (nodename, file_buffer) char *nodename; FILE_BUFFER *file_buffer; { - NODE *node = (NODE *)NULL; + NODE *node = NULL; /* If we are unable to find the file, we have to give up. There isn't anything else we can do. */ if (!file_buffer) - return ((NODE *)NULL); + return NULL; /* If the file buffer was gc'ed, reload the contents now. */ if (!file_buffer->contents) @@ -171,11 +153,12 @@ info_get_node_of_file_buffer (nodename, file_buffer) { node = (NODE *)xmalloc (sizeof (NODE)); node->filename = file_buffer->fullpath; - node->parent = (char *)NULL; + node->parent = NULL; node->nodename = xstrdup ("*"); node->contents = file_buffer->contents; node->nodelen = file_buffer->filesize; node->flags = 0; + node->display_pos = 0; } #if defined (HANDLE_MAN_PAGES) /* If the file buffer is the magic one associated with manpages, call @@ -195,7 +178,7 @@ info_get_node_of_file_buffer (nodename, file_buffer) } /* Return the results of our node search. */ - return (node); + return node; } /* Locate the file named by FILENAME, and return the information structure @@ -207,7 +190,7 @@ FILE_BUFFER * info_find_file (filename) char *filename; { - return (info_find_file_internal (filename, INFO_GET_TAGS)); + return info_find_file_internal (filename, INFO_GET_TAGS); } /* Load the info file FILENAME, remembering information about it in a @@ -216,15 +199,11 @@ FILE_BUFFER * info_load_file (filename) char *filename; { - return (info_load_file_internal (filename, INFO_GET_TAGS)); + return info_load_file_internal (filename, INFO_GET_TAGS); } -/* **************************************************************** */ -/* */ -/* Private Functions Implementation */ -/* */ -/* **************************************************************** */ +/* Private functions implementation. */ /* The workhorse for info_find_file (). Non-zero 2nd argument says to try to build a tags table (or otherwise glean the nodes) for this @@ -236,30 +215,30 @@ info_find_file_internal (filename, get_tags) char *filename; int get_tags; { - register int i; - register FILE_BUFFER *file_buffer; + int i; + FILE_BUFFER *file_buffer; /* First try to find the file in our list of already loaded files. */ if (info_loaded_files) { for (i = 0; (file_buffer = info_loaded_files[i]); i++) - if ((strcmp (filename, file_buffer->filename) == 0) || - (strcmp (filename, file_buffer->fullpath) == 0) || - ((*filename != '/') && - strcmp (filename, - filename_non_directory (file_buffer->fullpath)) == 0)) + if ((FILENAME_CMP (filename, file_buffer->filename) == 0) || + (FILENAME_CMP (filename, file_buffer->fullpath) == 0) || + (!IS_ABSOLUTE (filename) && + FILENAME_CMP (filename, + filename_non_directory (file_buffer->fullpath)) == 0)) { struct stat new_info, *old_info; /* This file is loaded. If the filename that we want is specifically "dir", then simply return the file buffer. */ - if (strcasecmp (filename_non_directory (filename), "dir") == 0) - return (file_buffer); + if (is_dir_name (filename_non_directory (filename))) + return file_buffer; #if defined (HANDLE_MAN_PAGES) /* Do the same for the magic MANPAGE file. */ if (file_buffer->flags & N_IsManPage) - return (file_buffer); + return file_buffer; #endif /* HANDLE_MAN_PAGES */ /* The file appears to be already loaded, and it is not "dir". @@ -268,7 +247,7 @@ info_find_file_internal (filename, get_tags) if (stat (file_buffer->fullpath, &new_info) == -1) { filesys_error_number = errno; - return ((FILE_BUFFER *)NULL); + return NULL; } old_info = &file_buffer->finfo; @@ -288,10 +267,18 @@ info_find_file_internal (filename, get_tags) for this file, and there isn't one here, build the nodes for this file_buffer. In any case, return the file_buffer object. */ + if (!file_buffer->contents) + { + /* The file's contents have been gc'ed. Reload it. */ + info_reload_file_buffer_contents (file_buffer); + if (!file_buffer->contents) + return NULL; + } + if (get_tags && !file_buffer->tags) build_tags_and_nodes (file_buffer); - return (file_buffer); + return file_buffer; } } } @@ -310,7 +297,7 @@ info_find_file_internal (filename, get_tags) if (file_buffer) remember_info_file (file_buffer); - return (file_buffer); + return file_buffer; } /* The workhorse function for info_load_file (). Non-zero second argument @@ -325,8 +312,8 @@ info_load_file_internal (filename, get_tags) char *fullpath, *contents; long filesize; struct stat finfo; - int retcode; - FILE_BUFFER *file_buffer = (FILE_BUFFER *)NULL; + int retcode, compressed; + FILE_BUFFER *file_buffer = NULL; /* Get the full pathname of this file, as known by the info system. That is to say, search along INFOPATH and expand tildes, etc. */ @@ -338,18 +325,16 @@ info_load_file_internal (filename, get_tags) /* If the file referenced by the name returned from info_find_fullpath () doesn't exist, then try again with the last part of the filename appearing in lowercase. */ + /* This is probably not needed at all on those systems which define + FILENAME_CMP to be strcasecmp. But let's do it anyway, lest some + network redirector supports case sensitivity. */ if (retcode < 0) { char *lowered_name; char *basename; lowered_name = xstrdup (filename); - basename = (char *) strrchr (lowered_name, '/'); - - if (basename) - basename++; - else - basename = lowered_name; + basename = filename_non_directory (lowered_name); while (*basename) { @@ -369,14 +354,14 @@ info_load_file_internal (filename, get_tags) if (retcode < 0) { filesys_error_number = errno; - return ((FILE_BUFFER *)NULL); + return NULL; } /* Otherwise, try to load the file. */ - contents = filesys_read_info_file (fullpath, &filesize, &finfo); + contents = filesys_read_info_file (fullpath, &filesize, &finfo, &compressed); if (!contents) - return ((FILE_BUFFER *)NULL); + return NULL; /* The file was found, and can be read. Allocate FILE_BUFFER and fill in the various members. */ @@ -386,16 +371,16 @@ info_load_file_internal (filename, get_tags) file_buffer->finfo = finfo; file_buffer->filesize = filesize; file_buffer->contents = contents; - if (file_buffer->filesize != file_buffer->finfo.st_size) + if (compressed) file_buffer->flags |= N_IsCompressed; /* If requested, build the tags and nodes for this file buffer. */ if (get_tags) build_tags_and_nodes (file_buffer); - return (file_buffer); + return file_buffer; } - + /* Grovel FILE_BUFFER->contents finding tags and nodes, and filling in the various slots. This can also be used to rebuild a tag or node table. */ void @@ -527,6 +512,7 @@ get_nodes_of_info_file (file_buffer) int start, end; char *nodeline; TAG *entry; + int anchor = 0; /* Skip past the characters just found. */ binding.start = nodestart; @@ -537,6 +523,13 @@ get_nodes_of_info_file (file_buffer) /* Find "Node:" */ start = string_in_line (INFO_NODE_LABEL, nodeline); + /* No Node:. Maybe it's a Ref:. */ + if (start == -1) + { + start = string_in_line (INFO_REF_LABEL, nodeline); + if (start != -1) + anchor = 1; + } /* If not there, this is not the start of a node. */ if (start == -1) @@ -550,21 +543,24 @@ get_nodes_of_info_file (file_buffer) skip_node_characters (nodeline + start, DONT_SKIP_NEWLINES); /* Okay, we have isolated the node name, and we know where the - node starts. Remember this information in a NODE structure. */ - entry = (TAG *)xmalloc (sizeof (TAG)); - entry->nodename = (char *)xmalloc (1 + (end - start)); + node starts. Remember this information. */ + entry = xmalloc (sizeof (TAG)); + entry->nodename = xmalloc (1 + (end - start)); strncpy (entry->nodename, nodeline + start, end - start); - entry->nodename[end - start] = '\0'; + entry->nodename[end - start] = 0; entry->nodestart = nodestart; - { - SEARCH_BINDING node_body; + if (anchor) + entry->nodelen = 0; + else + { + SEARCH_BINDING node_body; - node_body.buffer = binding.buffer + binding.start; - node_body.start = 0; - node_body.end = binding.end - binding.start; - node_body.flags = S_FoldCase; - entry->nodelen = get_node_length (&node_body); - } + node_body.buffer = binding.buffer + binding.start; + node_body.start = 0; + node_body.end = binding.end - binding.start; + node_body.flags = S_FoldCase; + entry->nodelen = get_node_length (&node_body); + } entry->filename = file_buffer->fullpath; @@ -579,17 +575,16 @@ static long get_node_length (binding) SEARCH_BINDING *binding; { - register int i; + int i; char *body; - /* From the Info-RFC file: - [A node] ends with either a ^_, a ^L, or the end of file. */ + /* [A node] ends with either a ^_, a ^L, or end of file. */ for (i = binding->start, body = binding->buffer; i < binding->end; i++) { if (body[i] == INFO_FF || body[i] == INFO_COOKIE) break; } - return ((long) i - binding->start); + return i - binding->start; } /* Build and save the array of nodes in FILE_BUFFER by searching through the @@ -599,9 +594,10 @@ get_nodes_of_tags_table (file_buffer, buffer_binding) FILE_BUFFER *file_buffer; SEARCH_BINDING *buffer_binding; { - int offset, tags_index = 0; + int name_offset; SEARCH_BINDING *search; long position; + int tags_index = 0; search = copy_binding (buffer_binding); @@ -624,6 +620,8 @@ get_nodes_of_tags_table (file_buffer, buffer_binding) { TAG *entry; char *nodedef; + unsigned p; + int anchor = 0; /* Prepare to skip this line. */ search->start = position; @@ -634,36 +632,45 @@ get_nodes_of_tags_table (file_buffer, buffer_binding) continue; /* Find the label preceding the node name. */ - offset = + name_offset = string_in_line (INFO_NODE_LABEL, search->buffer + search->start); + /* If no node label, maybe it's an anchor. */ + if (name_offset == -1) + { + name_offset = string_in_line (INFO_REF_LABEL, + search->buffer + search->start); + if (name_offset != -1) + anchor = 1; + } + /* If not there, not a defining line, so we must be out of the - tags table. */ - if (offset == -1) + tags table. */ + if (name_offset == -1) break; - /* Point to the beginning of the node definition. */ - search->start += offset; + entry = xmalloc (sizeof (TAG)); + + /* Find the beginning of the node definition. */ + search->start += name_offset; nodedef = search->buffer + search->start; nodedef += skip_whitespace (nodedef); - /* Move past the node's name. */ - for (offset = 0; - (nodedef[offset]) && (nodedef[offset] != INFO_TAGSEP); - offset++); - - if (nodedef[offset] != INFO_TAGSEP) + /* Move past the node's name in this tag to the TAGSEP character. */ + for (p = 0; nodedef[p] && nodedef[p] != INFO_TAGSEP; p++) + ; + if (nodedef[p] != INFO_TAGSEP) continue; - entry = (TAG *)xmalloc (sizeof (TAG)); - entry->nodename = (char *)xmalloc (1 + offset); - strncpy (entry->nodename, nodedef, offset); - entry->nodename[offset] = '\0'; - offset++; - entry->nodestart = (long) atol (nodedef + offset); + entry->nodename = xmalloc (p + 1); + strncpy (entry->nodename, nodedef, p); + entry->nodename[p] = 0; + p++; + entry->nodestart = atol (nodedef + p); - /* We don't know the length of this node yet. */ - entry->nodelen = -1; + /* If a node, we don't know the length yet, but if it's an + anchor, the length is 0. */ + entry->nodelen = anchor ? 0 : -1; /* The filename of this node is currently known as the same as the name of this file. */ @@ -677,7 +684,7 @@ get_nodes_of_tags_table (file_buffer, buffer_binding) free (search); } -/* A structure used only in get_tags_of_indirect_tags_table () to hold onto +/* A structure used only in `get_tags_of_indirect_tags_table' to hold onto an intermediate value. */ typedef struct { char *filename; @@ -692,8 +699,8 @@ get_tags_of_indirect_tags_table (file_buffer, indirect_binding, tags_binding) FILE_BUFFER *file_buffer; SEARCH_BINDING *indirect_binding, *tags_binding; { - register int i; - SUBFILE **subfiles = (SUBFILE **)NULL; + int i; + SUBFILE **subfiles = NULL; int subfiles_index = 0, subfiles_slots = 0; TAG *entry; @@ -723,7 +730,7 @@ get_tags_of_indirect_tags_table (file_buffer, indirect_binding, tags_binding) subfile = (SUBFILE *)xmalloc (sizeof (SUBFILE)); subfile->filename = (char *)xmalloc (colon); strncpy (subfile->filename, line, colon - 1); - subfile->filename[colon - 1] = '\0'; + subfile->filename[colon - 1] = 0; subfile->first_byte = (long) atol (line + colon); add_pointer_to_array @@ -742,7 +749,7 @@ get_tags_of_indirect_tags_table (file_buffer, indirect_binding, tags_binding) } else { - register int tags_index; + int tags_index; long header_length; SEARCH_BINDING binding; @@ -762,14 +769,21 @@ get_tags_of_indirect_tags_table (file_buffer, indirect_binding, tags_binding) /* Build the file buffer's list of subfiles. */ { - char *containing_dir, *temp; + char *containing_dir = xstrdup (file_buffer->fullpath); + char *temp = filename_non_directory (containing_dir); int len_containing_dir; - containing_dir = xstrdup (file_buffer->fullpath); - temp = (char *) strrchr (containing_dir, '/'); - - if (temp) - *temp = '\0'; + if (temp > containing_dir) + { + if (HAVE_DRIVE (file_buffer->fullpath) && + temp == containing_dir + 2) + { + /* Avoid converting "d:foo" into "d:/foo" below. */ + *temp = '.'; + temp += 2; + } + temp[-1] = 0; + } len_containing_dir = strlen (containing_dir); @@ -789,7 +803,7 @@ get_tags_of_indirect_tags_table (file_buffer, indirect_binding, tags_binding) file_buffer->subfiles[i] = fullpath; } - file_buffer->subfiles[i] = (char *)NULL; + file_buffer->subfiles[i] = NULL; free (containing_dir); } @@ -814,7 +828,7 @@ get_tags_of_indirect_tags_table (file_buffer, indirect_binding, tags_binding) free (subfiles[i]); free (file_buffer->subfiles[i]); } - file_buffer->subfiles = (char **)NULL; + file_buffer->subfiles = NULL; free_file_buffer_tags (file_buffer); return; } @@ -825,9 +839,8 @@ get_tags_of_indirect_tags_table (file_buffer, indirect_binding, tags_binding) preceding this one is the one containing the node. */ entry->filename = file_buffer->subfiles[i - 1]; - entry->nodestart -= subfiles[i -1]->first_byte; + entry->nodestart -= subfiles[i - 1]->first_byte; entry->nodestart += header_length; - entry->nodelen = -1; } /* We have successfully built the tags table. Remember that it @@ -845,18 +858,89 @@ get_tags_of_indirect_tags_table (file_buffer, indirect_binding, tags_binding) free (subfiles); } + +/* Return the node that contains TAG in FILE_BUFFER, else + (pathologically) NULL. Called from info_node_of_file_buffer_tags. */ +static NODE * +find_node_of_anchor (file_buffer, tag) + FILE_BUFFER *file_buffer; + TAG *tag; +{ + int anchor_pos, node_pos; + TAG *node_tag; + NODE *node; + + /* Look through the tag list for the anchor. */ + for (anchor_pos = 0; file_buffer->tags[anchor_pos]; anchor_pos++) + { + TAG *t = file_buffer->tags[anchor_pos]; + if (t->nodestart == tag->nodestart) + break; + } + + /* Should not happen, because we should always find the anchor. */ + if (!file_buffer->tags[anchor_pos]) + return NULL; + + /* We've found the anchor. Look backwards in the tag table for the + preceding node (we're assuming the tags are given in order), + skipping over any preceding anchors. */ + for (node_pos = anchor_pos - 1; + node_pos >= 0 && file_buffer->tags[node_pos]->nodelen == 0; + node_pos--) + ; + + /* An info file with an anchor before any nodes is pathological, but + it's possible, so don't crash. */ + if (node_pos < 0) + return NULL; + + /* We have the tag for the node that contained the anchor tag. */ + node_tag = file_buffer->tags[node_pos]; + + /* Look up the node name in the tag table to get the actual node. + This is a recursive call, but it can't recurse again, because we + call it with a real node. */ + node = info_node_of_file_buffer_tags (file_buffer, node_tag->nodename); + + /* Start displaying the node at the anchor position. */ + if (node) + { /* The nodestart for real nodes is three characters before the `F' + in the `File:' line (a newline, the CTRL-_, and another + newline). The nodestart for anchors is the actual position. + But we offset by only 2, rather than 3, because if an anchor is + at the beginning of a paragraph, it's nicer for it to end up on + the beginning of the first line of the paragraph rather than + the blank line before it. (makeinfo has no way of knowing that + a paragraph is going to start, so we can't fix it there.) */ + node->display_pos = file_buffer->tags[anchor_pos]->nodestart + - (node_tag->nodestart + 2); + + /* Otherwise an anchor at the end of a node ends up displaying at + the end of the last line of the node (way over on the right of + the screen), which looks wrong. */ + if (node->display_pos >= node->nodelen) + node->display_pos = node->nodelen - 1; + + /* Don't search in the node for the xref text, it's not there. */ + node->flags |= N_FromAnchor; + } + + return node; +} + + /* Return the node from FILE_BUFFER which matches NODENAME by searching - the tags table in FILE_BUFFER. If the node could not be found, return - a NULL pointer. */ + the tags table in FILE_BUFFER, or NULL. */ static NODE * info_node_of_file_buffer_tags (file_buffer, nodename) FILE_BUFFER *file_buffer; char *nodename; { - register int i; TAG *tag; + int i; - for (i = 0; (tag = file_buffer->tags[i]); i++) + for (i = 0; (tag = file_buffer->tags[i]); i++) if (strcmp (nodename, tag->nodename) == 0) { FILE_BUFFER *subfile; @@ -864,27 +948,26 @@ info_node_of_file_buffer_tags (file_buffer, nodename) subfile = info_find_file_internal (tag->filename, INFO_NO_TAGS); if (!subfile) - return ((NODE *)NULL); + return NULL; if (!subfile->contents) { info_reload_file_buffer_contents (subfile); if (!subfile->contents) - return ((NODE *)NULL); + return NULL; } /* If we were able to find this file and load it, then return the node within it. */ { - NODE *node; - - node = (NODE *)xmalloc (sizeof (NODE)); - node->filename = (subfile->fullpath); - node->nodename = tag->nodename; - node->contents = subfile->contents + tag->nodestart; - node->flags = 0; - node->parent = (char *)NULL; + NODE *node = xmalloc (sizeof (NODE)); + node->filename = subfile->fullpath; + node->parent = NULL; + node->nodename = tag->nodename; + node->contents = subfile->contents + tag->nodestart; + node->display_pos = 0; + node->flags = 0; if (file_buffer->flags & N_HasTagsTable) { @@ -923,14 +1006,14 @@ info_node_of_file_buffer_tags (file_buffer, nodename) max = subfile->filesize - tag->nodestart; /* NODE_SEP gets the address of the separator which defines - this node, or (char *)NULL if the node wasn't found. + this node, or NULL if the node wasn't found. NODE->contents is side-effected to point to right after the separator. */ node_sep = adjust_nodestart (node, min, max); - if (node_sep == (char *)NULL) + if (node_sep == NULL) { free (node); - return ((NODE *)NULL); + return NULL; } /* Readjust tag->nodestart. */ tag->nodestart = node_sep - subfile->contents; @@ -943,46 +1026,49 @@ info_node_of_file_buffer_tags (file_buffer, nodename) node_body.end = buff_end - node_body.buffer; node_body.flags = 0; tag->nodelen = get_node_length (&node_body); + node->nodelen = tag->nodelen; } + + else if (tag->nodelen == 0) /* anchor, return containing node */ + { + free (node); + node = find_node_of_anchor (file_buffer, tag); + } + else { /* Since we know the length of this node, we have already adjusted tag->nodestart to point to the exact start of it. Simply skip the node separator. */ node->contents += skip_node_separator (node->contents); + node->nodelen = tag->nodelen; } - node->nodelen = tag->nodelen; - return (node); + return node; } } /* There was a tag table for this file, and the node wasn't found. Return NULL, since this file doesn't contain the desired node. */ - return ((NODE *)NULL); + return NULL; } -/* **************************************************************** */ -/* */ -/* Managing file_buffers, nodes, and tags. */ -/* */ -/* **************************************************************** */ +/* Managing file_buffers, nodes, and tags. */ /* Create a new, empty file buffer. */ FILE_BUFFER * make_file_buffer () { - FILE_BUFFER *file_buffer; + FILE_BUFFER *file_buffer = xmalloc (sizeof (FILE_BUFFER)); - file_buffer = (FILE_BUFFER *)xmalloc (sizeof (FILE_BUFFER)); - file_buffer->filename = file_buffer->fullpath = (char *)NULL; - file_buffer->contents = (char *)NULL; - file_buffer->tags = (TAG **)NULL; - file_buffer->subfiles = (char **)NULL; + file_buffer->filename = file_buffer->fullpath = NULL; + file_buffer->contents = NULL; + file_buffer->tags = NULL; + file_buffer->subfiles = NULL; file_buffer->tags_slots = 0; file_buffer->flags = 0; - return (file_buffer); + return file_buffer; } /* Add FILE_BUFFER to our list of already loaded info files. */ @@ -1004,15 +1090,15 @@ static void forget_info_file (filename) char *filename; { - register int i; + int i; FILE_BUFFER *file_buffer; if (!info_loaded_files) return; - for (i = 0; (file_buffer = info_loaded_files[i]); i++) - if ((strcmp (filename, file_buffer->filename) == 0) || - (strcmp (filename, file_buffer->fullpath) == 0)) + for (i = 0; file_buffer = info_loaded_files[i]; i++) + if (FILENAME_CMP (filename, file_buffer->filename) == 0 + || FILENAME_CMP (filename, file_buffer->fullpath) == 0) { free (file_buffer->filename); free (file_buffer->fullpath); @@ -1020,13 +1106,17 @@ forget_info_file (filename) if (file_buffer->contents) free (file_buffer->contents); - /* Note that free_file_buffer_tags () also kills the subfiles - list, since the subfiles list is only of use in conjunction - with tags. */ + /* free_file_buffer_tags () also kills the subfiles list, since + the subfiles list is only of use in conjunction with tags. */ free_file_buffer_tags (file_buffer); - while ((info_loaded_files[i] = info_loaded_files[++i])) - ; + /* Move rest of list down. */ + while (info_loaded_files[i + 1]) + { + info_loaded_files[i] = info_loaded_files[i + 1]; + i++; + } + info_loaded_files[i] = 0; break; } @@ -1037,17 +1127,17 @@ static void free_file_buffer_tags (file_buffer) FILE_BUFFER *file_buffer; { - register int i; + int i; if (file_buffer->tags) { - register TAG *tag; + TAG *tag; for (i = 0; (tag = file_buffer->tags[i]); i++) free_info_tag (tag); free (file_buffer->tags); - file_buffer->tags = (TAG **)NULL; + file_buffer->tags = NULL; file_buffer->tags_slots = 0; } @@ -1057,7 +1147,7 @@ free_file_buffer_tags (file_buffer) free (file_buffer->subfiles[i]); free (file_buffer->subfiles); - file_buffer->subfiles = (char **)NULL; + file_buffer->subfiles = NULL; } } @@ -1084,6 +1174,7 @@ static void info_reload_file_buffer_contents (fb) FILE_BUFFER *fb; { + int is_compressed; #if defined (HANDLE_MAN_PAGES) /* If this is the magic manpage node, don't try to reload, just give up. */ @@ -1095,8 +1186,9 @@ info_reload_file_buffer_contents (fb) /* Let the filesystem do all the work for us. */ fb->contents = - filesys_read_info_file (fb->fullpath, &(fb->filesize), &(fb->finfo)); - if (fb->filesize != (long) (fb->finfo.st_size)) + filesys_read_info_file (fb->fullpath, &(fb->filesize), &(fb->finfo), + &is_compressed); + if (is_compressed) fb->flags |= N_IsCompressed; } @@ -1157,7 +1249,7 @@ adjust_nodestart (node, min, max) (strncmp (node->nodename, nodedef, offset) == 0)) { node->contents = nodestart; - return (node_body.buffer + position); + return node_body.buffer + position; } } } @@ -1173,7 +1265,7 @@ adjust_nodestart (node, min, max) /* If the node couldn't be found, we lose big. */ if (position == -1) - return ((char *)NULL); + return NULL; /* Otherwise, the node was found, but the tags table could need updating (if we used a tag to get here, that is). Set the flag in NODE->flags. */ @@ -1181,5 +1273,5 @@ adjust_nodestart (node, min, max) node->contents += skip_node_separator (node->contents); if (node->flags & N_HasTagsTable) node->flags |= N_UpdateTags; - return (node_body.buffer + position); + return node_body.buffer + position; } diff --git a/contrib/texinfo/info/nodes.h b/contrib/texinfo/info/nodes.h index a96c07c..7fd625d 100644 --- a/contrib/texinfo/info/nodes.h +++ b/contrib/texinfo/info/nodes.h @@ -1,10 +1,7 @@ /* nodes.h -- How we represent nodes internally. - $Id: nodes.h,v 1.5 1997/07/18 14:33:44 karl Exp $ + $Id: nodes.h,v 1.8 1998/07/10 20:28:43 karl Exp $ - This file is part of GNU Info, a program for reading online documentation - stored in Info format. - - Copyright (C) 1993, 97 Free Software Foundation, Inc. + Copyright (C) 1993, 97, 98 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -22,16 +19,12 @@ Written by Brian Fox (bfox@ai.mit.edu). */ -#if !defined (NODES_H) +#ifndef NODES_H #define NODES_H #include "info.h" -/* **************************************************************** */ -/* */ -/* User Code Interface */ -/* */ -/* **************************************************************** */ +/* User code interface. */ /* Callers generally only want the node itself. This structure is used to pass node information around. None of the information in this @@ -47,6 +40,7 @@ typedef struct { char *nodename; /* The name of this node. */ char *contents; /* Characters appearing in this node. */ long nodelen; /* The length of the CONTENTS member. */ + unsigned long display_pos; /* Where to display at, if nonzero. */ int flags; /* See immediately below. */ } NODE; @@ -57,18 +51,14 @@ typedef struct { #define N_IsCompressed 0x08 /* The file is compressed on disk. */ #define N_IsInternal 0x10 /* This node was made by Info. */ #define N_CannotGC 0x20 /* File buffer cannot be gc'ed. */ -#define N_IsManPage 0x40 /* This node is a Un*x manpage. */ +#define N_IsManPage 0x40 /* This node is a manpage. */ +#define N_FromAnchor 0x80 /* Synthesized for an anchor reference. */ -/* **************************************************************** */ -/* */ -/* Internal Data Structures */ -/* */ -/* **************************************************************** */ - -/* Some defines describing details about Info file contents. */ +/* Internal data structures. */ -/* String Constants. */ +/* String constants. */ #define INFO_FILE_LABEL "File:" +#define INFO_REF_LABEL "Ref:" #define INFO_NODE_LABEL "Node:" #define INFO_PREV_LABEL "Prev:" #define INFO_ALTPREV_LABEL "Previous:" @@ -82,7 +72,7 @@ typedef struct { #define INDIRECT_TAGS_TABLE_LABEL "Indirect:\n" #define TAGS_TABLE_IS_INDIRECT_LABEL "(Indirect)" -/* Character Constants. */ +/* Character constants. */ #define INFO_COOKIE '\037' #define INFO_FF '\014' #define INFO_TAGSEP '\177' @@ -119,12 +109,8 @@ typedef struct { int tags_slots; /* Number of slots allocated for TAGS. */ int flags; /* Various flags. Mimics of N_* flags. */ } FILE_BUFFER; - -/* **************************************************************** */ -/* */ -/* Externally Visible Functions */ -/* */ -/* **************************************************************** */ + +/* Externally visible functions. */ /* Array of FILE_BUFFER * which represents the currently loaded info files. */ extern FILE_BUFFER **info_loaded_files; @@ -166,4 +152,4 @@ extern char *info_recent_file_error; /* Create a new, empty file buffer. */ extern FILE_BUFFER *make_file_buffer (); -#endif /* !NODES_H */ +#endif /* not NODES_H */ diff --git a/contrib/texinfo/info/search.c b/contrib/texinfo/info/search.c index 0e8e619..2866704 100644 --- a/contrib/texinfo/info/search.c +++ b/contrib/texinfo/info/search.c @@ -1,9 +1,7 @@ -/* search.c -- How to search large bodies of text. */ +/* search.c -- searching large bodies of text. + $Id: search.c,v 1.5 1999/03/05 19:56:59 karl Exp $ -/* This file is part of GNU Info, a program for reading online documentation - stored in Info format. - - Copyright (C) 1993, 97 Free Software Foundation, Inc. + Copyright (C) 1993, 97, 98 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -198,7 +196,7 @@ search_backward (input_string, binding) { c = *(buff - i); - if (c != string[i] && (alternate && c != alternate[i])) + if (c != string[i] && (!alternate || c != alternate[i])) break; } @@ -292,7 +290,7 @@ skip_whitespace_and_newlines (string) { register int i; - for (i = 0; string && (whitespace (string[i]) || string[i] == '\n'); i++); + for (i = 0; string && whitespace_or_newline (string[i]); i++); return (i); } diff --git a/contrib/texinfo/info/search.h b/contrib/texinfo/info/search.h index 6425536..757ec5c 100644 --- a/contrib/texinfo/info/search.h +++ b/contrib/texinfo/info/search.h @@ -1,10 +1,7 @@ /* search.h -- Structure used to search large bodies of text, with bounds. - $Id: search.h,v 1.3 1997/07/15 18:43:49 karl Exp $ + $Id: search.h,v 1.4 1998/04/19 20:50:23 karl Exp $ - This file is part of GNU Info, a program for reading online documentation - stored in Info format. - - Copyright (C) 1993, 97 Free Software Foundation, Inc. + Copyright (C) 1993, 97, 98 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -53,11 +50,6 @@ extern int looking_at (); after the string. */ extern int string_in_line (); -/* Some unixes don't have strcasecmp or strncasecmp. */ -#if !defined (HAVE_STRCASECMP) -extern int strcasecmp (), strncasecmp (); -#endif /* !HAVE_STRCASECMP */ - /* Function names that start with "skip" are passed a string, and return an offset from the start of that string. Function names that start with "find" are passed a SEARCH_BINDING, and return an absolute position diff --git a/contrib/texinfo/info/session.h b/contrib/texinfo/info/session.h index f1e5b23..07ffd5f 100644 --- a/contrib/texinfo/info/session.h +++ b/contrib/texinfo/info/session.h @@ -1,9 +1,7 @@ -/* session.h -- Functions found in session.c. */ +/* session.h -- Functions found in session.c. + $Id: session.h,v 1.9 1999/06/25 21:57:40 karl Exp $ -/* This file is part of GNU Info, a program for reading online documentation - stored in Info format. - - Copyright (C) 1993 Free Software Foundation, Inc. + Copyright (C) 1993, 98, 99 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -21,7 +19,7 @@ Written by Brian Fox (bfox@ai.mit.edu). */ -#if !defined (SESSION_H) +#ifndef SESSION_H #define SESSION_H #include "info.h" @@ -76,6 +74,7 @@ extern void info_select_reference (); extern int info_any_buffered_input_p (); extern void print_node (); extern void dump_node_to_file (), dump_nodes_to_file (); +extern char *program_name_from_file_name (); /* Do the physical deletion of WINDOW, and forget this window and associated nodes. */ @@ -110,6 +109,8 @@ extern void info_move_to_prev_xref (), info_move_to_next_xref (); extern void info_scroll_forward (), info_scroll_backward (); extern void info_redraw_display (), info_toggle_wrap (); extern void info_move_to_window_line (); +extern void info_up_line (), info_down_line (); +extern void info_scroll_half_screen_down (), info_scroll_half_screen_up (); /* Manipulating multiple windows. */ extern void info_split_window (), info_delete_window (); @@ -123,6 +124,8 @@ extern void info_last_node (), info_first_node (), info_history_node (); extern void info_goto_node (), info_top_node (), info_dir_node (); extern void info_global_next_node (), info_global_prev_node (); extern void info_kill_node (), info_view_file (); +extern void info_menu_sequence (); +extern NODE *info_follow_menus (/* initial_node, menus, errstr, errarg */); /* Selecting cross references. */ extern void info_menu_digit (), info_menu_item (), info_xref_item (); @@ -136,6 +139,8 @@ extern void info_initialize_numeric_arg (), info_numeric_arg_digit_loop (); /* Searching commands. */ extern void info_search (), isearch_forward (), isearch_backward (); +extern void info_search_case_sensitively (), info_search_backward (); +extern void info_search_next (), info_search_previous (); /* Dumping and printing nodes. */ extern void info_print_node (); @@ -143,4 +148,4 @@ extern void info_print_node (); /* Miscellaneous commands. */ extern void info_abort_key (), info_quit (), info_do_lowercase_version (); -#endif /* SESSION_H */ +#endif /* not SESSION_H */ diff --git a/contrib/texinfo/info/termdep.h b/contrib/texinfo/info/termdep.h index fc0f992..5f4b41a 100644 --- a/contrib/texinfo/info/termdep.h +++ b/contrib/texinfo/info/termdep.h @@ -1,10 +1,7 @@ /* termdep.h -- System things that terminal.c depends on. - $Id: termdep.h,v 1.3 1997/07/05 21:17:14 karl Exp $ + $Id: termdep.h,v 1.4 1998/04/13 22:02:57 karl Exp $ - This file is part of GNU Info, a program for reading online documentation - stored in Info format. - - Copyright (C) 1993, 96, 97 Free Software Foundation, Inc. + Copyright (C) 1993, 96, 97, 98 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -33,6 +30,9 @@ #ifdef HAVE_TERMIOS_H # include <termios.h> +# ifdef GWINSZ_IN_SYS_IOCTL +# include <sys/ioctl.h> +# endif #else # if defined (HAVE_TERMIO_H) # include <termio.h> diff --git a/contrib/texinfo/info/tilde.c b/contrib/texinfo/info/tilde.c index 401f7e1..bba285a 100644 --- a/contrib/texinfo/info/tilde.c +++ b/contrib/texinfo/info/tilde.c @@ -1,10 +1,7 @@ -/* tilde.c -- Tilde expansion code (~/foo := $HOME/foo). - $Id: tilde.c,v 1.9 1998/02/22 23:03:21 karl Exp $ +/* tilde.c -- tilde expansion code (~/foo := $HOME/foo). + $Id: tilde.c,v 1.13 1999/03/03 22:42:21 karl Exp $ - This file is part of GNU Info, a program for reading online documentation - stored in Info format. - - Copyright (C) 1988, 89, 90, 91, 92, 93, 96, 98 + Copyright (C) 1988, 89, 90, 91, 92, 93, 96, 98, 99 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify @@ -23,27 +20,9 @@ Written by Brian Fox (bfox@ai.mit.edu). */ -/* Indent #pragma so that older Cpp's don't try to parse it. */ -#ifdef _AIX - #pragma alloca -#endif /* _AIX */ - /* Include config.h before doing alloca. */ #include "info.h" -#ifdef __GNUC__ -# undef alloca -# define alloca __builtin_alloca -#else -# ifdef HAVE_ALLOCA_H -# include <alloca.h> -# else -# ifndef _AIX -char *alloca (); -# endif -# endif -#endif - #if defined (TEST) || defined (STATIC_MALLOC) static void *xmalloc (), *xrealloc (); #endif /* TEST || STATIC_MALLOC */ @@ -123,7 +102,7 @@ tilde_find_suffix (string) for (i = 0; i < string_len; i++) { - if (string[i] == '/' || !string[i]) + if (IS_SLASH (string[i]) || !string[i]) break; for (j = 0; suffixes && suffixes[j]; j++) @@ -203,14 +182,12 @@ char * tilde_expand_word (filename) char *filename; { - char *dirname; - - dirname = filename ? xstrdup (filename) : (char *)NULL; + char *dirname = filename ? xstrdup (filename) : NULL; if (dirname && *dirname == '~') { char *temp_name; - if (!dirname[1] || dirname[1] == '/') + if (!dirname[1] || IS_SLASH (dirname[1])) { /* Prepend $HOME to the rest of the string. */ char *temp_home = getenv ("HOME"); @@ -226,30 +203,31 @@ tilde_expand_word (filename) temp_home = entry->pw_dir; } - temp_name = (char *) - alloca (1 + strlen (&dirname[1]) - + (temp_home ? strlen (temp_home) : 0)); - temp_name[0] = '\0'; + temp_name = xmalloc (1 + strlen (&dirname[1]) + + (temp_home ? strlen (temp_home) : 0)); if (temp_home) strcpy (temp_name, temp_home); + else + temp_name[0] = 0; strcat (temp_name, &dirname[1]); free (dirname); dirname = xstrdup (temp_name); + free (temp_name); } else { struct passwd *user_entry; - char *username = (char *)alloca (257); + char *username = xmalloc (257); int i, c; for (i = 1; (c = dirname[i]); i++) { - if (c == '/') + if (IS_SLASH (c)) break; else username[i - 1] = c; } - username[i - 1] = '\0'; + username[i - 1] = 0; if (!(user_entry = (struct passwd *) getpwnam (username))) { @@ -264,8 +242,8 @@ tilde_expand_word (filename) if (expansion) { - temp_name = (char *)alloca - (1 + strlen (expansion) + strlen (&dirname[i])); + temp_name = xmalloc (1 + strlen (expansion) + + strlen (&dirname[i])); strcpy (temp_name, expansion); strcat (temp_name, &dirname[i]); free (expansion); @@ -276,18 +254,22 @@ tilde_expand_word (filename) } else { - temp_name = (char *)alloca - (1 + strlen (user_entry->pw_dir) + strlen (&dirname[i])); + temp_name = xmalloc (1 + strlen (user_entry->pw_dir) + + strlen (&dirname[i])); strcpy (temp_name, user_entry->pw_dir); strcat (temp_name, &dirname[i]); + return_name: free (dirname); dirname = xstrdup (temp_name); + free (temp_name); } - endpwent (); + + endpwent (); + free (username); } } - return (dirname); + return dirname; } @@ -322,7 +304,7 @@ main (argc, argv) printf (" --> %s\n", result); free (result); } - exit (0); + xexit (0); } static void memory_error_and_abort (); diff --git a/contrib/texinfo/info/variables.c b/contrib/texinfo/info/variables.c index 248c8af..9412797 100644 --- a/contrib/texinfo/info/variables.c +++ b/contrib/texinfo/info/variables.c @@ -1,5 +1,5 @@ /* variables.c -- How to manipulate user visible variables in Info. - $Id: variables.c,v 1.5 1997/07/18 14:34:23 karl Exp $ + $Id: variables.c,v 1.7 1999/06/25 21:57:40 karl Exp $ This file is part of GNU Info, a program for reading online documentation stored in Info format. diff --git a/contrib/texinfo/info/window.c b/contrib/texinfo/info/window.c index dbe706e..1b6d062 100644 --- a/contrib/texinfo/info/window.c +++ b/contrib/texinfo/info/window.c @@ -1,10 +1,7 @@ -/* window.c -- Windows in Info. - $Id: window.c,v 1.5 1998/02/23 22:43:38 karl Exp $ +/* window.c -- windows in Info. + $Id: window.c,v 1.11 1999/06/25 21:57:40 karl Exp $ - This file is part of GNU Info, a program for reading online documentation - stored in Info format. - - Copyright (C) 1993, 97 Free Software Foundation, Inc. + Copyright (C) 1993, 97, 98 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -30,16 +27,16 @@ #include "infomap.h" /* The window which describes the screen. */ -WINDOW *the_screen = (WINDOW *)NULL; +WINDOW *the_screen = NULL; /* The window which describes the echo area. */ -WINDOW *the_echo_area = (WINDOW *)NULL; +WINDOW *the_echo_area = NULL; /* The list of windows in Info. */ -WINDOW *windows = (WINDOW *)NULL; +WINDOW *windows = NULL; /* Pointer to the active window in WINDOW_LIST. */ -WINDOW *active_window = (WINDOW *)NULL; +WINDOW *active_window = NULL; /* The size of the echo area in Info. It never changes, irregardless of the size of the screen. */ @@ -56,9 +53,9 @@ void window_initialize_windows (width, height) int width, height; { - the_screen = (WINDOW *)xmalloc (sizeof (WINDOW)); - the_echo_area = (WINDOW *)xmalloc (sizeof (WINDOW)); - windows = (WINDOW *)xmalloc (sizeof (WINDOW)); + the_screen = xmalloc (sizeof (WINDOW)); + the_echo_area = xmalloc (sizeof (WINDOW)); + windows = xmalloc (sizeof (WINDOW)); active_window = windows; zero_mem (the_screen, sizeof (WINDOW)); @@ -85,7 +82,7 @@ window_initialize_windows (width, height) area. */ the_echo_area->height = ECHO_AREA_HEIGHT; active_window->height = the_screen->height - 1 - the_echo_area->height; - window_new_screen_size (width, height, (VFunction *)NULL); + window_new_screen_size (width, height, NULL); /* The echo area uses a different keymap than normal info windows. */ the_echo_area->keymap = echo_area_keymap; @@ -102,7 +99,7 @@ window_initialize_windows (width, height) /* If non-null, a function to call with WINDOW as argument when the function window_new_screen_size () has deleted WINDOW. */ -VFunction *window_deletion_notifier = (VFunction *)NULL; +VFunction *window_deletion_notifier = NULL; void window_new_screen_size (width, height) @@ -139,7 +136,7 @@ window_new_screen_size (width, height) { windows->height = 0; maybe_free (windows->line_starts); - windows->line_starts = (char **)NULL; + windows->line_starts = NULL; windows->line_count = 0; break; } @@ -187,7 +184,7 @@ window_new_screen_size (width, height) { win->width = width; maybe_free (win->modeline); - win->modeline = (char *)xmalloc (1 + width); + win->modeline = xmalloc (1 + width); } win->height += delta_each; @@ -274,14 +271,14 @@ window_make_window (node) /* If there isn't enough room to make another window, return now. */ if ((active_window->height / 2) < WINDOW_MIN_SIZE) - return ((WINDOW *)NULL); + return (NULL); /* Make and initialize the new window. The fudging about with -1 and +1 is because the following window in the chain cannot start at window->height, since that is where the modeline for the previous window is displayed. The inverse adjustment is made in window_delete_window (). */ - window = (WINDOW *)xmalloc (sizeof (WINDOW)); + window = xmalloc (sizeof (WINDOW)); window->width = the_screen->width; window->height = (active_window->height / 2) - 1; #if defined (SPLIT_BEFORE_ACTIVE) @@ -292,8 +289,8 @@ window_make_window (node) #endif window->keymap = info_keymap; window->goal_column = -1; - window->modeline = (char *)xmalloc (1 + window->width); - window->line_starts = (char **)NULL; + window->modeline = xmalloc (1 + window->width); + window->line_starts = NULL; window->flags = W_UpdateWindow | W_WindowVisible; window_set_node_of_window (window, node); @@ -538,7 +535,7 @@ window_tile_windows (style) per_win_height = avail / numwins; leftover = avail - (per_win_height * numwins); - last_adjusted = (WINDOW *)NULL; + last_adjusted = NULL; for (win = windows; win; win = win->next) { if (do_internals || !win->node || @@ -610,10 +607,12 @@ window_set_node_of_window (window, node) window->point = 0; recalculate_line_starts (window); window->flags |= W_UpdateWindow; + /* The display_pos member is nonzero if we're displaying an anchor. */ + window->point = node ? node->display_pos : 0; window_adjust_pagetop (window); window_make_modeline (window); } - + /* Delete WINDOW from the list of known windows. If this window was the active window, make the next window in the chain be the active window. If the active window is the next or previous window, choose that window @@ -766,7 +765,7 @@ string_width (string, hpos) return (width); } -/* Quickly guess the approximate number of lines to that NODE would +/* Quickly guess the approximate number of lines that NODE would take to display. This really only counts carriage returns. */ int window_physical_lines (node) @@ -793,12 +792,12 @@ calculate_line_starts (window) WINDOW *window; { register int i, hpos; - char **line_starts = (char **)NULL; + char **line_starts = NULL; int line_starts_index = 0, line_starts_slots = 0; int bump_index; NODE *node; - window->line_starts = (char **)NULL; + window->line_starts = NULL; window->line_count = 0; node = window->node; @@ -1079,9 +1078,9 @@ window_make_modeline (window) /* Calculate the maximum size of the information to stick in MODELINE. */ { int modeline_len = 0; - char *parent = (char *)NULL, *filename = "*no file*"; + char *parent = NULL, *filename = "*no file*"; char *nodename = "*no node*"; - char *update_message = (char *)NULL; + char *update_message = NULL; NODE *node = window->node; if (node) @@ -1113,7 +1112,7 @@ window_make_modeline (window) modeline_len += 10 + strlen (_("-----Info: (), lines ----, ")); modeline_len += window->width; - modeline = (char *)xmalloc (1 + modeline_len); + modeline = xmalloc (1 + modeline_len); /* Special internal windows have no filename. */ if (!parent && !*filename) @@ -1194,14 +1193,10 @@ window_set_state (window, state) } -/* **************************************************************** */ -/* */ -/* Manipulating Home-Made Nodes */ -/* */ -/* **************************************************************** */ +/* Manipulating home-made nodes. */ /* A place to buffer echo area messages. */ -static NODE *echo_area_node = (NODE *)NULL; +static NODE *echo_area_node = NULL; /* Make the node of the_echo_area be an empty one. */ static void @@ -1213,7 +1208,7 @@ free_echo_area () free (echo_area_node); } - echo_area_node = (NODE *)NULL; + echo_area_node = NULL; window_set_node_of_window (the_echo_area, echo_area_node); } @@ -1245,7 +1240,7 @@ window_message_in_echo_area (format, arg1, arg2) and ARG2. The message appears immediately, but does not destroy any existing message. A future call to unmessage_in_echo_area () restores the old contents. */ -static NODE **old_echo_area_nodes = (NODE **)NULL; +static NODE **old_echo_area_nodes = NULL; static int old_echo_area_nodes_index = 0; static int old_echo_area_nodes_slots = 0; @@ -1260,7 +1255,7 @@ message_in_echo_area (format, arg1, arg2) old_echo_area_nodes, old_echo_area_nodes_slots, 4, NODE *); } - echo_area_node = (NODE *)NULL; + echo_area_node = NULL; window_message_in_echo_area (format, arg1, arg2); } @@ -1277,7 +1272,7 @@ unmessage_in_echo_area () } /* A place to build a message. */ -static char *message_buffer = (char *)NULL; +static char *message_buffer = NULL; static int message_buffer_index = 0; static int message_buffer_size = 0; @@ -1290,7 +1285,7 @@ message_buffer_resize (length) if (!message_buffer) { message_buffer_size = length + 1; - message_buffer = (char *)xmalloc (message_buffer_size); + message_buffer = xmalloc (message_buffer_size); message_buffer_index = 0; } @@ -1328,14 +1323,44 @@ build_message_buffer (format, arg1, arg2) else { char c; + char *fmt_start = format + i; + char *fmt; + int fmt_len, formatted_len; + + i++; + while (format[i] && strchr ("-. +0123456789", format[i])) + i++; + c = format[i]; + + if (c == '\0') + abort (); + + fmt_len = format + i - fmt_start + 1; + fmt = (char *) xmalloc (fmt_len + 1); + strncpy (fmt, fmt_start, fmt_len); + fmt[fmt_len] = '\0'; - c = format[++i]; + /* If we have "%-98s", maybe 98 calls for a longer string. */ + if (fmt_len > 2) + { + int j; + + for (j = 0; j < fmt_len; j++) + if (isdigit (fmt[j])) + break; + + formatted_len = atoi (fmt + j); + } + else + formatted_len = c == 's' ? 0 : 1; /* %s can produce empty string */ switch (c) { case '%': /* Insert a percent sign. */ - message_buffer_resize (len + 1); - message_buffer[message_buffer_index++] = '%'; + message_buffer_resize (len + formatted_len); + sprintf + (message_buffer + message_buffer_index, fmt, "%"); + message_buffer_index += formatted_len; break; case 's': /* Insert the current arg as a string. */ @@ -1346,9 +1371,11 @@ build_message_buffer (format, arg1, arg2) string = (char *)args[arg_index++]; string_len = strlen (string); + if (formatted_len > string_len) + string_len = formatted_len; message_buffer_resize (len + string_len); sprintf - (message_buffer + message_buffer_index, "%s", string); + (message_buffer + message_buffer_index, fmt, string); message_buffer_index += string_len; } break; @@ -1361,9 +1388,10 @@ build_message_buffer (format, arg1, arg2) long_val = (long)args[arg_index++]; integer = (int)long_val; - message_buffer_resize (len + 32); + message_buffer_resize (len + formatted_len > 32 + ? formatted_len : 32); sprintf - (message_buffer + message_buffer_index, "%d", integer); + (message_buffer + message_buffer_index, fmt, integer); message_buffer_index = strlen (message_buffer); } break; @@ -1376,14 +1404,17 @@ build_message_buffer (format, arg1, arg2) long_val = (long)args[arg_index++]; character = (int)long_val; - message_buffer_resize (len + 1); - message_buffer[message_buffer_index++] = character; + message_buffer_resize (len + formatted_len); + sprintf + (message_buffer + message_buffer_index, fmt, character); + message_buffer_index += formatted_len; } break; default: abort (); } + free (fmt); } } message_buffer[message_buffer_index] = '\0'; @@ -1411,15 +1442,16 @@ message_buffer_to_node () { NODE *node; - node = (NODE *)xmalloc (sizeof (NODE)); - node->filename = (char *)NULL; - node->parent = (char *)NULL; - node->nodename = (char *)NULL; + node = xmalloc (sizeof (NODE)); + node->filename = NULL; + node->parent = NULL; + node->nodename = NULL; node->flags = 0; + node->display_pos =0; /* Make sure that this buffer ends with a newline. */ node->nodelen = 1 + strlen (message_buffer); - node->contents = (char *)xmalloc (1 + node->nodelen); + node->contents = xmalloc (1 + node->nodelen); strcpy (node->contents, message_buffer); node->contents[node->nodelen - 1] = '\n'; node->contents[node->nodelen] = '\0'; diff --git a/contrib/texinfo/lib/getopt.c b/contrib/texinfo/lib/getopt.c index fc87ce6..03effcb 100644 --- a/contrib/texinfo/lib/getopt.c +++ b/contrib/texinfo/lib/getopt.c @@ -1,13 +1,13 @@ /* Getopt for GNU. NOTE: getopt is now part of the C library, so if you don't know what - "Keep this file name-space clean" means, talk to roland@gnu.ai.mit.edu + "Keep this file name-space clean" means, talk to drepper@gnu.org before changing it! - Copyright (C) 1987, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97 + Copyright (C) 1987, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98 Free Software Foundation, Inc. NOTE: The canonical source of this file is maintained with the GNU C Library. - Bugs can be reported to bug-glibc@prep.ai.mit.edu. + Bugs can be reported to bug-glibc@gnu.org. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the @@ -27,19 +27,19 @@ /* This tells Alpha OSF/1 not to define a getopt prototype in <stdio.h>. Ditto for AIX 3.2 and <stdlib.h>. */ #ifndef _NO_PROTO -#define _NO_PROTO +# define _NO_PROTO #endif #ifdef HAVE_CONFIG_H -#include <config.h> +# include <config.h> #endif -#if !defined (__STDC__) || !__STDC__ +#if !defined __STDC__ || !__STDC__ /* This is a separate conditional since some stdc systems reject `defined (const)'. */ -#ifndef const -#define const -#endif +# ifndef const +# define const +# endif #endif #include <stdio.h> @@ -53,11 +53,11 @@ it is simpler to just do this in the source for each such file. */ #define GETOPT_INTERFACE_VERSION 2 -#if !defined (_LIBC) && defined (__GLIBC__) && __GLIBC__ >= 2 -#include <gnu-versions.h> -#if _GNU_GETOPT_INTERFACE_VERSION == GETOPT_INTERFACE_VERSION -#define ELIDE_CODE -#endif +#if !defined _LIBC && defined __GLIBC__ && __GLIBC__ >= 2 +# include <gnu-versions.h> +# if _GNU_GETOPT_INTERFACE_VERSION == GETOPT_INTERFACE_VERSION +# define ELIDE_CODE +# endif #endif #ifndef ELIDE_CODE @@ -68,26 +68,26 @@ #ifdef __GNU_LIBRARY__ /* Don't include stdlib.h for non-GNU C libraries because some of them contain conflicting prototypes for getopt. */ -#include <stdlib.h> -#include <unistd.h> +# include <stdlib.h> +# include <unistd.h> #endif /* GNU C library. */ #ifdef VMS -#include <unixlib.h> -#if HAVE_STRING_H - 0 -#include <string.h> -#endif +# include <unixlib.h> +# if HAVE_STRING_H - 0 +# include <string.h> +# endif #endif #ifndef _ /* This is for other GNU distributions with internationalized messages. When compiling libc, the _ macro is predefined. */ -#ifdef HAVE_LIBINTL_H -# include <libintl.h> -# define _(msgid) gettext (msgid) -#else -# define _(msgid) (msgid) -#endif +# ifdef HAVE_LIBINTL_H +# include <libintl.h> +# define _(msgid) gettext (msgid) +# else +# define _(msgid) (msgid) +# endif #endif /* This version of `getopt' appears to the caller like standard Unix `getopt' @@ -197,14 +197,22 @@ static char *posixly_correct; because there are many ways it can cause trouble. On some systems, it contains special magic macros that don't work in GCC. */ -#include <string.h> -#define my_index strchr +# include <string.h> +# define my_index strchr #else +# if HAVE_STRING_H +# include <string.h> +# else +# include <strings.h> +# endif + /* Avoid depending on library functions or files whose names are inconsistent. */ -char *getenv (); +#ifndef getenv +extern char *getenv (); +#endif static char * my_index (str, chr) @@ -225,11 +233,11 @@ my_index (str, chr) #ifdef __GNUC__ /* Note that Motorola Delta 68k R3V7 comes with GCC but not stddef.h. That was relevant to code that was here before. */ -#if !defined (__STDC__) || !__STDC__ +# if (!defined __STDC__ || !__STDC__) && !defined strlen /* gcc with -traditional declares the built-in strlen to return int, and has done so at least since version 2.4.5. -- rms. */ extern int strlen (const char *); -#endif /* not __STDC__ */ +# endif /* not __STDC__ */ #endif /* __GNUC__ */ #endif /* not __GNU_LIBRARY__ */ @@ -292,7 +300,7 @@ text_set_element (__libc_subinit, store_args_and_env); `first_nonopt' and `last_nonopt' are relocated so that they describe the new indices of the non-options in ARGV after they are moved. */ -#if defined (__STDC__) && __STDC__ +#if defined __STDC__ && __STDC__ static void exchange (char **); #endif @@ -378,7 +386,7 @@ exchange (argv) /* Initialize the internal data when the first call is made. */ -#if defined (__STDC__) && __STDC__ +#if defined __STDC__ && __STDC__ static const char *_getopt_initialize (int, char *const *, const char *); #endif static const char * @@ -527,11 +535,11 @@ _getopt_internal (argc, argv, optstring, longopts, longind, long_only) from the shell indicating it is not an option. The later information is only used when the used in the GNU libc. */ #ifdef _LIBC -#define NONOPTION_P (argv[optind][0] != '-' || argv[optind][1] == '\0' \ - || (optind < nonoption_flags_len \ - && __getopt_nonoption_flags[optind] == '1')) +# define NONOPTION_P (argv[optind][0] != '-' || argv[optind][1] == '\0' \ + || (optind < nonoption_flags_len \ + && __getopt_nonoption_flags[optind] == '1')) #else -#define NONOPTION_P (argv[optind][0] != '-' || argv[optind][1] == '\0') +# define NONOPTION_P (argv[optind][0] != '-' || argv[optind][1] == '\0') #endif if (nextchar == NULL || *nextchar == '\0') diff --git a/contrib/texinfo/lib/getopt.h b/contrib/texinfo/lib/getopt.h index c4adc30..fb30719 100644 --- a/contrib/texinfo/lib/getopt.h +++ b/contrib/texinfo/lib/getopt.h @@ -2,7 +2,7 @@ Copyright (C) 1989,90,91,92,93,94,96,97 Free Software Foundation, Inc. NOTE: The canonical source of this file is maintained with the GNU C Library. - Bugs can be reported to bug-glibc@prep.ai.mit.edu. + Bugs can be reported to bug-glibc@gnu.org. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the diff --git a/contrib/texinfo/lib/getopt1.c b/contrib/texinfo/lib/getopt1.c index af8e681..ff25737 100644 --- a/contrib/texinfo/lib/getopt1.c +++ b/contrib/texinfo/lib/getopt1.c @@ -1,8 +1,9 @@ /* getopt_long and getopt_long_only entry points for GNU getopt. - Copyright (C) 1987,88,89,90,91,92,93,94,96,97 Free Software Foundation, Inc. + Copyright (C) 1987,88,89,90,91,92,93,94,96,97,98 + Free Software Foundation, Inc. NOTE: The canonical source of this file is maintained with the GNU C Library. - Bugs can be reported to bug-glibc@prep.ai.mit.edu. + Bugs can be reported to bug-glibc@gnu.org. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the @@ -25,7 +26,7 @@ #include "getopt.h" -#if !defined (__STDC__) || !__STDC__ +#if !defined __STDC__ || !__STDC__ /* This is a separate conditional since some stdc systems reject `defined (const)'. */ #ifndef const @@ -44,7 +45,7 @@ it is simpler to just do this in the source for each such file. */ #define GETOPT_INTERFACE_VERSION 2 -#if !defined (_LIBC) && defined (__GLIBC__) && __GLIBC__ >= 2 +#if !defined _LIBC && defined __GLIBC__ && __GLIBC__ >= 2 #include <gnu-versions.h> #if _GNU_GETOPT_INTERFACE_VERSION == GETOPT_INTERFACE_VERSION #define ELIDE_CODE diff --git a/contrib/texinfo/lib/libintl.h b/contrib/texinfo/lib/libintl.h new file mode 100644 index 0000000..3a92960 --- /dev/null +++ b/contrib/texinfo/lib/libintl.h @@ -0,0 +1,182 @@ +/* Message catalogs for internationalization. + Copyright (C) 1995, 1996, 1997, 1998 Free Software Foundation, Inc. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software Foundation, + Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ + +/* Because on some systems (e.g. Solaris) we sometimes have to include + the systems libintl.h as well as this file we have more complex + include protection above. But the systems header might perhaps also + define _LIBINTL_H and therefore we have to protect the definition here. */ + +#if !defined _LIBINTL_H || !defined _LIBGETTEXT_H +#ifndef _LIBINTL_H +# define _LIBINTL_H 1 +#endif +#define _LIBGETTEXT_H 1 + +/* We define an additional symbol to signal that we use the GNU + implementation of gettext. */ +#define __USE_GNU_GETTEXT 1 + +#include <sys/types.h> + +#if HAVE_LOCALE_H +# include <locale.h> +#endif + + +#ifdef __cplusplus +extern "C" { +#endif + +/* @@ end of prolog @@ */ + +#ifndef PARAMS +# if __STDC__ || defined __cplusplus +# define PARAMS(args) args +# else +# define PARAMS(args) () +# endif +#endif + +#ifndef NULL +# if !defined __cplusplus || defined __GNUC__ +# define NULL ((void *) 0) +# else +# define NULL (0) +# endif +#endif + +#if !HAVE_LC_MESSAGES +/* This value determines the behaviour of the gettext() and dgettext() + function. But some system does not have this defined. Define it + to a default value. */ +# define LC_MESSAGES (-1) +#endif + + +/* Declarations for gettext-using-catgets interface. Derived from + Jim Meyering's libintl.h. */ +struct _msg_ent +{ + const char *_msg; + int _msg_number; +}; + + +#if HAVE_CATGETS +/* These two variables are defined in the automatically by po-to-tbl.sed + generated file `cat-id-tbl.c'. */ +extern const struct _msg_ent _msg_tbl[]; +extern int _msg_tbl_length; +#endif + + +/* For automatical extraction of messages sometimes no real + translation is needed. Instead the string itself is the result. */ +#define gettext_noop(Str) (Str) + +/* Look up MSGID in the current default message catalog for the current + LC_MESSAGES locale. If not found, returns MSGID itself (the default + text). */ +extern char *gettext PARAMS ((const char *__msgid)); +extern char *gettext__ PARAMS ((const char *__msgid)); + +/* Look up MSGID in the DOMAINNAME message catalog for the current + LC_MESSAGES locale. */ +extern char *dgettext PARAMS ((const char *__domainname, const char *__msgid)); +extern char *dgettext__ PARAMS ((const char *__domainname, + const char *__msgid)); + +/* Look up MSGID in the DOMAINNAME message catalog for the current CATEGORY + locale. */ +extern char *dcgettext PARAMS ((const char *__domainname, const char *__msgid, + int __category)); +extern char *dcgettext__ PARAMS ((const char *__domainname, + const char *__msgid, int __category)); + + +/* Set the current default message catalog to DOMAINNAME. + If DOMAINNAME is null, return the current default. + If DOMAINNAME is "", reset to the default of "messages". */ +extern char *textdomain PARAMS ((const char *__domainname)); +extern char *textdomain__ PARAMS ((const char *__domainname)); + +/* Specify that the DOMAINNAME message catalog will be found + in DIRNAME rather than in the system locale data base. */ +extern char *bindtextdomain PARAMS ((const char *__domainname, + const char *__dirname)); +extern char *bindtextdomain__ PARAMS ((const char *__domainname, + const char *__dirname)); + +#if ENABLE_NLS + +/* Solaris 2.3 has the gettext function but dcgettext is missing. + So we omit this optimization for Solaris 2.3. BTW, Solaris 2.4 + has dcgettext. */ +# if !HAVE_CATGETS && (!HAVE_GETTEXT || HAVE_DCGETTEXT) + +# define gettext(Msgid) \ + dgettext (NULL, Msgid) + +# define dgettext(Domainname, Msgid) \ + dcgettext (Domainname, Msgid, LC_MESSAGES) + +# if defined __GNUC__ && __GNUC__ == 2 && __GNUC_MINOR__ >= 7 +/* This global variable is defined in loadmsgcat.c. We need a sign, + whether a new catalog was loaded, which can be associated with all + translations. */ +extern int _nl_msg_cat_cntr; + +# define dcgettext(Domainname, Msgid, Category) \ + (__extension__ \ + ({ \ + char *__result; \ + if (__builtin_constant_p (Msgid)) \ + { \ + static char *__translation__; \ + static int __catalog_counter__; \ + if (! __translation__ || __catalog_counter__ != _nl_msg_cat_cntr) \ + { \ + __translation__ = \ + dcgettext__ (Domainname, Msgid, Category); \ + __catalog_counter__ = _nl_msg_cat_cntr; \ + } \ + __result = __translation__; \ + } \ + else \ + __result = dcgettext__ (Domainname, Msgid, Category); \ + __result; \ + })) +# endif +# endif + +#else + +# define gettext(Msgid) (Msgid) +# define dgettext(Domainname, Msgid) (Msgid) +# define dcgettext(Domainname, Msgid, Category) (Msgid) +# define textdomain(Domainname) ((char *) Domainname) +# define bindtextdomain(Domainname, Dirname) ((char *) Dirname) + +#endif + +/* @@ begin of epilog @@ */ + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/contrib/texinfo/lib/substring.c b/contrib/texinfo/lib/substring.c new file mode 100644 index 0000000..089961f --- /dev/null +++ b/contrib/texinfo/lib/substring.c @@ -0,0 +1,37 @@ +/* substring.c -- extract substring. + $Id: substring.c,v 1.1 1999/02/17 22:30:10 karl Exp $ + + Copyright (C) 1999 Free Software Foundation, Inc. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License along + with this program; if not, write to the Free Software Foundation, Inc., + 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ + +#include "system.h" + +char * +substring (start, end) + char *start; + char *end; +{ + char *result = xmalloc (end - start + 1); + char *scan_result = result; + char *scan = start; + + while (scan < end) + *scan_result++ = *scan++; + + *scan_result = 0; + return result; +} + diff --git a/contrib/texinfo/lib/system.h b/contrib/texinfo/lib/system.h index 109e393..4ca1837 100644 --- a/contrib/texinfo/lib/system.h +++ b/contrib/texinfo/lib/system.h @@ -1,7 +1,7 @@ -/* system.h: System-dependent declarations. Include this first. - $Id: system.h,v 1.5 1997/07/31 20:34:36 karl Exp $ +/* system.h: system-dependent declarations; include this first. + $Id: system.h,v 1.14 1999/07/17 21:11:34 karl Exp $ - Copyright (C) 1997 Free Software Foundation, Inc. + Copyright (C) 1997, 98, 99 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -37,7 +37,22 @@ #ifdef HAVE_LOCALE_H #include <locale.h> #endif +#ifndef HAVE_SETLOCALE +#define setlocale(category,locale) /* empty */ +#endif + +/* For gettext (NLS). */ #include <libintl.h> +#define _(String) gettext (String) +#define N_(String) (String) + +#ifdef STDC_HEADERS +#define getopt system_getopt +#include <stdlib.h> +#undef getopt +#else +extern char *getenv (); +#endif /* Don't use bcopy! Use memmove if source and destination may overlap, memcpy otherwise. */ @@ -51,18 +66,6 @@ char *memchr (); #endif -#ifdef STDC_HEADERS -#define getopt system_getopt -#include <stdlib.h> -#undef getopt -#else -extern char *getenv (); -#endif - -#ifndef HAVE_STRERROR -extern char *strerror (); -#endif - #include <errno.h> #ifndef errno extern int errno; @@ -71,7 +74,29 @@ extern int errno; #include <perror.h> #endif +#ifndef HAVE_DECL_STRERROR +extern char *strerror (); +#endif + +#ifndef HAVE_DECL_STRCASECMP +extern int strcasecmp (); +#endif + +#ifndef HAVE_DECL_STRNCASECMP +extern int strncasecmp (); +#endif + +#ifndef HAVE_DECL_STRCOLL +extern int strcoll (); +#endif + #include <sys/stat.h> +#if STAT_MACROS_BROKEN +# undef S_ISDIR +#endif +#if !defined(S_ISDIR) && defined(S_IFDIR) +# define S_ISDIR(mode) (((mode) & S_IFMT) == S_IFDIR) +#endif #ifdef HAVE_SYS_FILE_H #include <sys/file.h> @@ -89,6 +114,77 @@ extern int errno; #endif /* not HAVE_FCNTL_H */ #endif /* not O_RDONLY */ +/* MS-DOS and similar non-Posix systems have some peculiarities: + - they distinguish between binary and text files; + - they use both `/' and `\\' as directory separator in file names; + - they can have a drive letter X: prepended to a file name; + - they have a separate root directory on each drive; + - their filesystems are case-insensitive; + - directories in environment variables (like INFOPATH) are separated + by `;' rather than `:'; + - text files can have their lines ended either with \n or with \r\n pairs; + + These are all parameterized here except the last, which is + handled by the source code as appropriate (mostly, in info/). */ +#ifndef O_BINARY +# ifdef _O_BINARY +# define O_BINARY _O_BINARY +# else +# define O_BINARY 0 +# endif +#endif /* O_BINARY */ + +#if O_BINARY +# include <io.h> +# ifdef __MSDOS__ +# include <limits.h> +# ifdef __DJGPP__ +# define HAVE_LONG_FILENAMES(dir) (pathconf (dir, _PC_NAME_MAX) > 12) +# define NULL_DEVICE "/dev/null" +# else /* !__DJGPP__ */ +# define HAVE_LONG_FILENAMES(dir) (0) +# define NULL_DEVICE "NUL" +# endif /* !__DJGPP__ */ +# define SET_SCREEN_SIZE_HELPER terminal_prep_terminal() +# define DEFAULT_INFO_PRINT_COMMAND ">PRN" +# else /* !__MSDOS__ */ +# define setmode(f,m) _setmode(f,m) +# define HAVE_LONG_FILENAMES(dir) (1) +# define NULL_DEVICE "NUL" +# endif /* !__MSDOS__ */ +# define SET_BINARY(f) do {if (!isatty(f)) setmode(f,O_BINARY);} while(0) +# define FOPEN_RBIN "rb" +# define FOPEN_WBIN "wb" +# define IS_SLASH(c) ((c) == '/' || (c) == '\\') +# define HAVE_DRIVE(n) ((n)[0] && (n)[1] == ':') +# define IS_ABSOLUTE(n) (IS_SLASH((n)[0]) || ((n)[0] && (n)[1] == ':')) +# define FILENAME_CMP strcasecmp +# define FILENAME_CMPN strncasecmp +# define PATH_SEP ";" +# define STRIP_DOT_EXE 1 +# define DEFAULT_TMPDIR "c:/" +# define PIPE_USE_FORK 0 +#else /* not O_BINARY */ +# define SET_BINARY(f) (void)0 +# define FOPEN_RBIN "r" +# define FOPEN_WBIN "w" +# define IS_SLASH(c) ((c) == '/') +# define HAVE_DRIVE(n) (0) +# define IS_ABSOLUTE(n) ((n)[0] == '/') +# define FILENAME_CMP strcmp +# define FILENAME_CMPN strncmp +# define HAVE_LONG_FILENAMES(dir) (1) +# define PATH_SEP ":" +# define STRIP_DOT_EXE 0 +# ifdef VMS +# define DEFAULT_TMPDIR "sys$scratch:" +# else +# define DEFAULT_TMPDIR "/tmp/" +# endif +# define NULL_DEVICE "/dev/null" +# define PIPE_USE_FORK 1 +#endif /* not O_BINARY */ + #ifdef HAVE_PWD_H #include <pwd.h> #endif @@ -98,5 +194,10 @@ struct passwd *getpwnam (); /* Our library routines not included in any system library. */ extern void *xmalloc (), *xrealloc (); extern char *xstrdup (); +extern void xexit (); +extern char *substring (); + +/* For convenience. */ +#define STREQ(s1,s2) (strcmp (s1, s2) == 0) #endif /* TEXINFO_SYSTEM_H */ diff --git a/contrib/texinfo/lib/xexit.c b/contrib/texinfo/lib/xexit.c new file mode 100644 index 0000000..0fea809 --- /dev/null +++ b/contrib/texinfo/lib/xexit.c @@ -0,0 +1,86 @@ +/* xexit.c -- exit with attention to return values and closing stdout. + $Id: xexit.c,v 1.5 1999/02/19 14:13:51 karl Exp $ + + Copyright (C) 1999 Free Software Foundation, Inc. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License along + with this program; if not, write to the Free Software Foundation, Inc., + 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ + +#include "system.h" + +/* SunOS 4.1.1 gets STDC_HEADERS defined, but it doesn't provide + EXIT_FAILURE. So far no system has defined one of EXIT_FAILURE and + EXIT_SUCCESS without the other. */ +#ifdef EXIT_SUCCESS + /* The following test is to work around the gross typo in + systems like Sony NEWS-OS Release 4.0C, whereby EXIT_FAILURE + is defined to 0, not 1. */ +# if !EXIT_FAILURE +# undef EXIT_FAILURE +# define EXIT_FAILURE 1 +# endif +#else /* not EXIT_SUCCESS */ +# ifdef VMS /* these values suppress some messages; from gnuplot */ +# define EXIT_SUCCESS 1 +# define EXIT_FAILURE 0x10000002 +# else /* not VMS */ +# define EXIT_SUCCESS 0 +# define EXIT_FAILURE 1 +# endif /* not VMS */ +#endif /* not EXIT_SUCCESS */ + + +/* Flush stdout first, exit if failure. Otherwise, if EXIT_STATUS is + zero, exit successfully, else unsuccessfully. */ + +void +xexit (exit_status) + int exit_status; +{ + if (ferror (stdout)) + { + fprintf (stderr, "ferror on stdout"); + exit_status = 1; + } + else if (fflush (stdout) != 0) + { + fprintf (stderr, "fflush error on stdout"); + exit_status = 1; + } + + exit_status = exit_status == 0 ? EXIT_SUCCESS : EXIT_FAILURE; + + exit (exit_status); +} + + +/* Why do we care about stdout you may ask? Here's why, from Jim + Meyering in the lib/closeout.c file. */ + +/* If a program writes *anything* to stdout, that program should close + stdout and make sure that the close succeeds. Otherwise, suppose that + you go to the extreme of checking the return status of every function + that does an explicit write to stdout. The last printf can succeed in + writing to the internal stream buffer, and yet the fclose(stdout) could + still fail (due e.g., to a disk full error) when it tries to write + out that buffered data. Thus, you would be left with an incomplete + output file and the offending program would exit successfully. + + Besides, it's wasteful to check the return value from every call + that writes to stdout -- just let the internal stream state record + the failure. That's what the ferror test is checking below. + + It's important to detect such failures and exit nonzero because many + tools (most notably `make' and other build-management systems) depend + on being able to detect failure in other tools via their exit status. */ diff --git a/contrib/texinfo/makeinfo/README b/contrib/texinfo/makeinfo/README index 2bfe6e1..a6f97eb 100644 --- a/contrib/texinfo/makeinfo/README +++ b/contrib/texinfo/makeinfo/README @@ -1,8 +1,8 @@ makeinfo is a standalone program to convert Texinfo source into Info files readable with standalone info or M-x info in Emacs. -makeinfo can also output plain ASCII. Work to support HTML and Troff -output is almost complete. +makeinfo can also output plain ASCII (with --no-headers) +or HTML (with --html). The Emacs function M-x texinfo-format-buffer does more or less the same job, but makeinfo is faster and gives better error messages. diff --git a/contrib/texinfo/makeinfo/cmds.c b/contrib/texinfo/makeinfo/cmds.c new file mode 100644 index 0000000..65d382e --- /dev/null +++ b/contrib/texinfo/makeinfo/cmds.c @@ -0,0 +1,1121 @@ +/* cmds.c -- Texinfo commands. + $Id: cmds.c,v 1.57 1999/09/19 16:39:35 karl Exp $ + + Copyright (C) 1998, 99 Free Software Foundation, Inc. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software Foundation, + Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ + +#include "system.h" +#include "cmds.h" +#include "defun.h" +#include "files.h" +#include "footnote.h" +#include "insertion.h" +#include "lang.h" +#include "macro.h" +#include "makeinfo.h" +#include "node.h" +#include "sectioning.h" +#include "toc.h" + +#ifdef TM_IN_SYS_TIME +#include <sys/time.h> +#else +#include <time.h> +#endif + + +void insert_self (), insert_space (), cm_ignore_line (), cm_ignore_arg (); + +void + cm_TeX (), cm_acronym (), cm_asterisk (), cm_b (), cm_bullet (), cm_cite (), + cm_code (), cm_copyright (), cm_ctrl (), cm_dfn (), cm_dircategory (), + cm_direntry (), cm_dmn (), cm_dots (), cm_emph (), cm_enddots (), cm_i (), + cm_image (), cm_kbd (), cm_key (), cm_no_op (), + cm_novalidate (), cm_not_fixed_width (), cm_r (), + cm_strong (), cm_var (), cm_sc (), cm_w (), cm_email (), cm_url (); + +void + cm_anchor (), cm_node (), cm_menu (), cm_xref (), cm_ftable (), + cm_vtable (), cm_pxref (), cm_inforef (), cm_uref (), cm_email (), + cm_quotation (), cm_display (), cm_smalldisplay (), cm_itemize (), + cm_enumerate (), cm_tab (), cm_table (), cm_itemx (), cm_noindent (), + cm_setfilename (), cm_br (), cm_sp (), cm_page (), cm_group (), + cm_center (), cm_ref (), cm_include (), cm_bye (), cm_item (), cm_end (), + cm_kindex (), cm_cindex (), cm_findex (), cm_pindex (), cm_vindex (), + cm_tindex (), cm_synindex (), cm_printindex (), cm_minus (), + cm_example (), cm_smallexample (), cm_smalllisp (), cm_lisp (), + cm_format (), cm_smallformat (), cm_exdent (), cm_defindex (), + cm_defcodeindex (), cm_result (), cm_expansion (), cm_equiv (), + cm_print (), cm_error (), cm_point (), cm_today (), cm_flushleft (), + cm_flushright (), cm_finalout (), cm_cartouche (), cm_detailmenu (), + cm_multitable (), cm_settitle (), cm_titlefont (), cm_tt (); + +/* Conditionals. */ +void cm_set (), cm_clear (), cm_ifset (), cm_ifclear (); +void cm_value (), cm_ifeq (); + +/* Options. */ +static void cm_paragraphindent (), cm_exampleindent (); + +/* Internals. */ +static void cm_obsolete (); + +/* A random string. */ +static const char small_tag[] = "small"; + +/* The dispatch table. */ +COMMAND command_table[] = { + { "\t", insert_space, NO_BRACE_ARGS }, + { "\n", insert_space, NO_BRACE_ARGS }, + { " ", insert_self, NO_BRACE_ARGS }, + { "!", insert_self, NO_BRACE_ARGS }, + { "\"", cm_accent_umlaut, MAYBE_BRACE_ARGS }, + { "'", cm_accent_acute, MAYBE_BRACE_ARGS }, + { "*", cm_asterisk, NO_BRACE_ARGS }, + { ",", cm_accent_cedilla, MAYBE_BRACE_ARGS }, + { "-", cm_no_op, NO_BRACE_ARGS }, + { ".", insert_self, NO_BRACE_ARGS }, + { ":", cm_no_op, NO_BRACE_ARGS }, + { "=", cm_accent, MAYBE_BRACE_ARGS }, + { "?", insert_self, NO_BRACE_ARGS }, + { "@", insert_self, NO_BRACE_ARGS }, + { "^", cm_accent_hat, MAYBE_BRACE_ARGS }, + { "`", cm_accent_grave, MAYBE_BRACE_ARGS }, + { "{", insert_self, NO_BRACE_ARGS }, + { "|", cm_no_op, NO_BRACE_ARGS }, + { "}", insert_self, NO_BRACE_ARGS }, + { "~", cm_accent_tilde, MAYBE_BRACE_ARGS }, + { "AA", cm_special_char, BRACE_ARGS }, + { "AE", cm_special_char, BRACE_ARGS }, + { "H", cm_accent, MAYBE_BRACE_ARGS }, + { "L", cm_special_char, BRACE_ARGS }, + { "O", cm_special_char, BRACE_ARGS }, + { "OE", cm_special_char, BRACE_ARGS }, + { "TeX", cm_TeX, BRACE_ARGS }, + { "aa", cm_special_char, BRACE_ARGS }, + { "acronym", cm_acronym, BRACE_ARGS }, + { "ae", cm_special_char, BRACE_ARGS }, + { "afourpaper", cm_ignore_line, NO_BRACE_ARGS }, + { "alias", cm_alias, NO_BRACE_ARGS }, + { "anchor", cm_anchor, BRACE_ARGS }, + { "appendix", cm_appendix, NO_BRACE_ARGS }, + { "appendixsection", cm_appendixsec, NO_BRACE_ARGS }, + { "appendixsec", cm_appendixsec, NO_BRACE_ARGS }, + { "appendixsubsec", cm_appendixsubsec, NO_BRACE_ARGS }, + { "appendixsubsubsec", cm_appendixsubsubsec, NO_BRACE_ARGS }, + { "asis", cm_no_op, BRACE_ARGS }, + { "b", cm_b, BRACE_ARGS }, + { "bullet", cm_bullet, BRACE_ARGS }, + { "bye", cm_bye, NO_BRACE_ARGS }, + { "c", cm_ignore_line, NO_BRACE_ARGS }, + { "cartouche", cm_cartouche, NO_BRACE_ARGS }, + { "center", cm_center, NO_BRACE_ARGS }, + { "centerchap", cm_unnumbered, NO_BRACE_ARGS }, + { "chapheading", cm_chapheading, NO_BRACE_ARGS }, + { "chapter", cm_chapter, NO_BRACE_ARGS }, + { "cindex", cm_cindex, NO_BRACE_ARGS }, + { "cite", cm_cite, BRACE_ARGS }, + { "clear", cm_clear, NO_BRACE_ARGS }, + { "code", cm_code, BRACE_ARGS }, + { "command", cm_code, BRACE_ARGS }, + { "comment", cm_ignore_line, NO_BRACE_ARGS }, + { "contents", cm_contents, NO_BRACE_ARGS }, + { "copyright", cm_copyright, BRACE_ARGS }, + { "ctrl", cm_obsolete, BRACE_ARGS }, + { "defcodeindex", cm_defcodeindex, NO_BRACE_ARGS }, + { "defcv", cm_defun, NO_BRACE_ARGS }, + { "defcvx", cm_defun, NO_BRACE_ARGS }, + { "deffn", cm_defun, NO_BRACE_ARGS }, + { "deffnx", cm_defun, NO_BRACE_ARGS }, + { "defindex", cm_defindex, NO_BRACE_ARGS }, + { "definfoenclose", cm_definfoenclose, NO_BRACE_ARGS }, + { "defivar", cm_defun, NO_BRACE_ARGS }, + { "defivarx", cm_defun, NO_BRACE_ARGS }, + { "defmac", cm_defun, NO_BRACE_ARGS }, + { "defmacx", cm_defun, NO_BRACE_ARGS }, + { "defmethod", cm_defun, NO_BRACE_ARGS }, + { "defmethodx", cm_defun, NO_BRACE_ARGS }, + { "defop", cm_defun, NO_BRACE_ARGS }, + { "defopt", cm_defun, NO_BRACE_ARGS }, + { "defoptx", cm_defun, NO_BRACE_ARGS }, + { "defopx", cm_defun, NO_BRACE_ARGS }, + { "defspec", cm_defun, NO_BRACE_ARGS }, + { "defspecx", cm_defun, NO_BRACE_ARGS }, + { "deftp", cm_defun, NO_BRACE_ARGS }, + { "deftpx", cm_defun, NO_BRACE_ARGS }, + { "deftypefn", cm_defun, NO_BRACE_ARGS }, + { "deftypefnx", cm_defun, NO_BRACE_ARGS }, + { "deftypefun", cm_defun, NO_BRACE_ARGS }, + { "deftypefunx", cm_defun, NO_BRACE_ARGS }, + { "deftypeivar", cm_defun, NO_BRACE_ARGS }, + { "deftypeivarx", cm_defun, NO_BRACE_ARGS }, + { "deftypemethod", cm_defun, NO_BRACE_ARGS }, + { "deftypemethodx", cm_defun, NO_BRACE_ARGS }, + { "deftypeop", cm_defun, NO_BRACE_ARGS }, + { "deftypeopx", cm_defun, NO_BRACE_ARGS }, + { "deftypevar", cm_defun, NO_BRACE_ARGS }, + { "deftypevarx", cm_defun, NO_BRACE_ARGS }, + { "deftypevr", cm_defun, NO_BRACE_ARGS }, + { "deftypevrx", cm_defun, NO_BRACE_ARGS }, + { "defun", cm_defun, NO_BRACE_ARGS }, + { "defunx", cm_defun, NO_BRACE_ARGS }, + { "defvar", cm_defun, NO_BRACE_ARGS }, + { "defvarx", cm_defun, NO_BRACE_ARGS }, + { "defvr", cm_defun, NO_BRACE_ARGS }, + { "defvrx", cm_defun, NO_BRACE_ARGS }, + { "detailmenu", cm_detailmenu, NO_BRACE_ARGS }, + { "dfn", cm_dfn, BRACE_ARGS }, + { "dircategory", cm_dircategory, NO_BRACE_ARGS }, + { "direntry", cm_direntry, NO_BRACE_ARGS }, + { "display", cm_display, NO_BRACE_ARGS }, + { "dmn", cm_no_op, BRACE_ARGS }, + { "documentencoding", cm_documentencoding, NO_BRACE_ARGS }, + { "documentlanguage", cm_documentlanguage, NO_BRACE_ARGS }, + { "dotaccent", cm_accent, MAYBE_BRACE_ARGS }, + { "dotless", cm_dotless, BRACE_ARGS }, + { "dots", cm_dots, BRACE_ARGS }, + { "email", cm_email, BRACE_ARGS }, + { "emph", cm_emph, BRACE_ARGS }, + { "end", cm_end, NO_BRACE_ARGS }, + { "enddots", cm_enddots, BRACE_ARGS }, + { "enumerate", cm_enumerate, NO_BRACE_ARGS }, + { "env", cm_code, BRACE_ARGS }, + { "equiv", cm_equiv, BRACE_ARGS }, + { "error", cm_error, BRACE_ARGS }, + { "example", cm_example, NO_BRACE_ARGS }, + { "exampleindent", cm_exampleindent, NO_BRACE_ARGS }, + { "exclamdown", cm_special_char, BRACE_ARGS }, + { "exdent", cm_exdent, NO_BRACE_ARGS }, + { "expansion", cm_expansion, BRACE_ARGS }, + { "file", cm_code, BRACE_ARGS }, + { "finalout", cm_no_op, NO_BRACE_ARGS }, + { "findex", cm_findex, NO_BRACE_ARGS }, + { "flushleft", cm_flushleft, NO_BRACE_ARGS }, + { "flushright", cm_flushright, NO_BRACE_ARGS }, + { "footnote", cm_footnote, NO_BRACE_ARGS}, /* self-arg eater */ + { "footnotestyle", cm_footnotestyle, NO_BRACE_ARGS }, + { "format", cm_format, NO_BRACE_ARGS }, + { "ftable", cm_ftable, NO_BRACE_ARGS }, + { "group", cm_group, NO_BRACE_ARGS }, + { "heading", cm_heading, NO_BRACE_ARGS }, + { "headings", cm_ignore_line, NO_BRACE_ARGS }, + { "html", cm_html, NO_BRACE_ARGS }, + { "hyphenation", cm_ignore_arg, BRACE_ARGS }, + { "i", cm_i, BRACE_ARGS }, + { "ifclear", cm_ifclear, NO_BRACE_ARGS }, + { "ifeq", cm_ifeq, NO_BRACE_ARGS }, + { "ifhtml", cm_ifhtml, NO_BRACE_ARGS }, + { "ifinfo", cm_ifinfo, NO_BRACE_ARGS }, + { "ifnothtml", cm_ifnothtml, NO_BRACE_ARGS }, + { "ifnotinfo", cm_ifnotinfo, NO_BRACE_ARGS }, + { "ifnottex", cm_ifnottex, NO_BRACE_ARGS }, + { "ifset", cm_ifset, NO_BRACE_ARGS }, + { "iftex", cm_iftex, NO_BRACE_ARGS }, + { "ignore", command_name_condition, NO_BRACE_ARGS }, + { "image", cm_image, BRACE_ARGS }, + { "include", cm_include, NO_BRACE_ARGS }, + { "inforef", cm_inforef, BRACE_ARGS }, + { "item", cm_item, NO_BRACE_ARGS }, + { "itemize", cm_itemize, NO_BRACE_ARGS }, + { "itemx", cm_itemx, NO_BRACE_ARGS }, + { "kbd", cm_kbd, BRACE_ARGS }, + { "kbdinputstyle", cm_ignore_line, NO_BRACE_ARGS }, + { "key", cm_key, BRACE_ARGS }, + { "kindex", cm_kindex, NO_BRACE_ARGS }, + { "l", cm_special_char, BRACE_ARGS }, + { "lisp", cm_lisp, NO_BRACE_ARGS }, + { "lowersections", cm_lowersections, NO_BRACE_ARGS }, + { "macro", cm_macro, NO_BRACE_ARGS }, + { "majorheading", cm_majorheading, NO_BRACE_ARGS }, + { "math", cm_no_op, BRACE_ARGS }, + { "menu", cm_menu, NO_BRACE_ARGS }, + { "minus", cm_minus, BRACE_ARGS }, + { "multitable", cm_multitable, NO_BRACE_ARGS }, + { "need", cm_ignore_line, NO_BRACE_ARGS }, + { "node", cm_node, NO_BRACE_ARGS }, + { "noindent", cm_noindent, NO_BRACE_ARGS }, + { "noindent", cm_novalidate, NO_BRACE_ARGS }, + { "nwnode", cm_node, NO_BRACE_ARGS }, + { "o", cm_special_char, BRACE_ARGS }, + { "oe", cm_special_char, BRACE_ARGS }, + { "option", cm_code, BRACE_ARGS }, + { "page", cm_no_op, NO_BRACE_ARGS }, + { "pagesizes", cm_ignore_line, NO_BRACE_ARGS }, + { "paragraphindent", cm_paragraphindent, NO_BRACE_ARGS }, + { "pindex", cm_pindex, NO_BRACE_ARGS }, + { "point", cm_point, BRACE_ARGS }, + { "pounds", cm_special_char, BRACE_ARGS }, + { "print", cm_print, BRACE_ARGS }, + { "printindex", cm_printindex, NO_BRACE_ARGS }, + { "pxref", cm_pxref, BRACE_ARGS }, + { "questiondown", cm_special_char, BRACE_ARGS }, + { "quotation", cm_quotation, NO_BRACE_ARGS }, + { "r", cm_r, BRACE_ARGS }, + { "raisesections", cm_raisesections, NO_BRACE_ARGS }, + { "ref", cm_ref, BRACE_ARGS }, + { "refill", cm_no_op, NO_BRACE_ARGS }, + { "result", cm_result, BRACE_ARGS }, + { "ringaccent", cm_accent, MAYBE_BRACE_ARGS }, + { "rmacro", cm_rmacro, NO_BRACE_ARGS }, + { "samp", cm_code, BRACE_ARGS }, + { "sc", cm_sc, BRACE_ARGS }, + { "section", cm_section, NO_BRACE_ARGS }, + { "set", cm_set, NO_BRACE_ARGS }, + { "setchapternewpage", cm_ignore_line, NO_BRACE_ARGS }, + { "setchapterstyle", cm_obsolete, NO_BRACE_ARGS }, + { "setcontentsaftertitlepage", cm_no_op, NO_BRACE_ARGS }, + { "setfilename", cm_setfilename, NO_BRACE_ARGS }, + { "setshortcontentsaftertitlepage", cm_no_op, NO_BRACE_ARGS }, + { "settitle", cm_settitle, NO_BRACE_ARGS }, + { "shortcontents", cm_shortcontents, NO_BRACE_ARGS }, + { "shorttitlepage", cm_ignore_line, NO_BRACE_ARGS }, + { "smallbook", cm_ignore_line, NO_BRACE_ARGS }, + { "smalldisplay", cm_smalldisplay, NO_BRACE_ARGS }, + { "smallexample", cm_smallexample, NO_BRACE_ARGS }, + { "smallformat", cm_smallformat, NO_BRACE_ARGS }, + { "smalllisp", cm_smalllisp, NO_BRACE_ARGS }, + { "sp", cm_sp, NO_BRACE_ARGS }, + { "ss", cm_special_char, BRACE_ARGS }, + { "strong", cm_strong, BRACE_ARGS }, + { "subheading", cm_subheading, NO_BRACE_ARGS }, + { "subsection", cm_subsection, NO_BRACE_ARGS }, + { "subsubheading", cm_subsubheading, NO_BRACE_ARGS }, + { "subsubsection", cm_subsubsection, NO_BRACE_ARGS }, + { "summarycontents", cm_no_op, NO_BRACE_ARGS }, + { "syncodeindex", cm_synindex, NO_BRACE_ARGS }, + { "synindex", cm_synindex, NO_BRACE_ARGS }, + { "t", cm_tt, BRACE_ARGS }, + { "tab", cm_tab, NO_BRACE_ARGS }, + { "table", cm_table, NO_BRACE_ARGS }, + { "tex", cm_tex, NO_BRACE_ARGS }, + { "tieaccent", cm_accent, MAYBE_BRACE_ARGS }, + { "tindex", cm_tindex, NO_BRACE_ARGS }, + { "titlefont", cm_titlefont, BRACE_ARGS }, + { "titlepage", command_name_condition, NO_BRACE_ARGS }, + { "today", cm_today, BRACE_ARGS }, + { "top", cm_top, NO_BRACE_ARGS }, + { "u", cm_accent, MAYBE_BRACE_ARGS }, + { "ubaraccent", cm_accent, MAYBE_BRACE_ARGS }, + { "udotaccent", cm_accent, MAYBE_BRACE_ARGS }, + { "unmacro", cm_unmacro, NO_BRACE_ARGS }, + { "unnumbered", cm_unnumbered, NO_BRACE_ARGS }, + { "unnumberedsec", cm_unnumberedsec, NO_BRACE_ARGS }, + { "unnumberedsubsec", cm_unnumberedsubsec, NO_BRACE_ARGS }, + { "unnumberedsubsubsec", cm_unnumberedsubsubsec, NO_BRACE_ARGS }, + { "uref", cm_uref, BRACE_ARGS }, + { "url", cm_url, BRACE_ARGS }, + { "v", cm_accent, MAYBE_BRACE_ARGS }, + { "value", cm_value, BRACE_ARGS }, + { "var", cm_var, BRACE_ARGS }, + { "vindex", cm_vindex, NO_BRACE_ARGS }, + { "vtable", cm_vtable, NO_BRACE_ARGS }, + { "w", cm_w, BRACE_ARGS }, + { "xref", cm_xref, BRACE_ARGS }, + + /* Deprecated commands. These used to be for italics. */ + { "iappendix", cm_ideprecated, NO_BRACE_ARGS }, + { "iappendixsec", cm_ideprecated, NO_BRACE_ARGS }, + { "iappendixsection", cm_ideprecated, NO_BRACE_ARGS }, + { "iappendixsubsec", cm_ideprecated, NO_BRACE_ARGS }, + { "iappendixsubsubsec", cm_ideprecated, NO_BRACE_ARGS }, + { "ichapter", cm_ideprecated, NO_BRACE_ARGS }, + { "isection", cm_ideprecated, NO_BRACE_ARGS }, + { "isubsection", cm_ideprecated, NO_BRACE_ARGS }, + { "isubsubsection", cm_ideprecated, NO_BRACE_ARGS }, + { "iunnumbered", cm_ideprecated, NO_BRACE_ARGS }, + { "iunnumberedsec", cm_ideprecated, NO_BRACE_ARGS }, + { "iunnumberedsubsec", cm_ideprecated, NO_BRACE_ARGS }, + { "iunnumberedsubsubsec", cm_ideprecated, NO_BRACE_ARGS }, + + /* Now @include does what this was used to. */ + { "infoinclude", cm_obsolete, NO_BRACE_ARGS }, + { "titlespec", cm_obsolete, NO_BRACE_ARGS }, + + { NULL, NULL, NO_BRACE_ARGS } +}; + +/* The bulk of the Texinfo commands. */ + +/* Commands which insert their own names. */ +void +insert_self (arg) + int arg; +{ + if (arg == START) + add_word (command); +} + +void +insert_space (arg) + int arg; +{ + if (arg == START) + add_char (' '); +} + +/* Force a line break in the output. */ +void +cm_asterisk () +{ + if (html) + add_word ("<br>"); + else + { + close_single_paragraph (); + cm_noindent (); + } +} + +/* Insert ellipsis. */ +void +cm_dots (arg) + int arg; +{ + if (arg == START) + add_word (html ? "<small>...</small>" : "..."); +} + +/* Insert ellipsis for sentence end. */ +void +cm_enddots (arg) + int arg; +{ + if (arg == START) + add_word (html ? "<small>...</small>." : "...."); +} + +void +cm_bullet (arg) + int arg; +{ + if (arg == START) + { + if (html) + add_word ("•"); + else + add_char ('*'); + } +} + +void +cm_minus (arg) + int arg; +{ + if (arg == START) + add_char ('-'); +} + +/* Insert "TeX". */ +void +cm_TeX (arg) + int arg; +{ + if (arg == START) + add_word ("TeX"); +} + +/* Copyright symbol. */ +void +cm_copyright (arg) + int arg; +{ + if (arg == START) + if (html) + add_word ("©"); + else + add_word ("(C)"); +} + +void +cm_today (arg) + int arg; +{ + static char *months[12] = + { N_("January"), N_("February"), N_("March"), N_("April"), N_("May"), + N_("June"), N_("July"), N_("August"), N_("September"), N_("October"), + N_("November"), N_("December") }; + if (arg == START) + { + time_t timer = time (0); + struct tm *ts = localtime (&timer); + add_word_args ("%d %s %d", ts->tm_mday, _(months[ts->tm_mon]), + ts->tm_year + 1900); + } +} + +void +cm_acronym (arg) + int arg; +{ + if (html) + insert_html_tag (arg, small_tag); +} + +void +cm_tt (arg) + int arg; +{ + /* @t{} is a no-op in Info. */ + if (html) + insert_html_tag (arg, "tt"); +} + +void +cm_code (arg) + int arg; +{ + extern int printing_index; + + if (arg == START) + { + in_fixed_width_font++; + + if (html) + insert_html_tag (arg, "code"); + else if (!printing_index) + add_char ('`'); + } + else if (html) + insert_html_tag (arg, "code"); + else + { + if (!printing_index) + add_meta_char ('\''); + } +} + +void +cm_kbd (arg) + int arg; +{ + if (html) + { /* Seems like we should increment in_fixed_width_font for Info + format too, but then the quote-omitting special case gets + confused. Punt. */ + if (arg == START) + in_fixed_width_font++; + insert_html_tag (arg, "kbd"); + } + else + { /* People use @kbd in an example to get the "user input" font. + We don't want quotes in that case. */ + if (!in_fixed_width_font) + cm_code (arg); + } +} + +void +cm_url (arg, start, end) +{ + if (html) + { + if (arg == START) + add_word ("<<code>"); + else + add_word ("</code>>"); + } + else + if (arg == START) + add_word ("<"); + else + add_word (">"); +} + +void +cm_key (arg) + int arg; +{ + if (html) + add_word (arg == START ? "<" : ">"); + else + add_char (arg == START ? '<' : '>'); +} + +/* Handle a command that switches to a non-fixed-width font. */ +void +not_fixed_width (arg) + int arg; +{ + if (arg == START) + in_fixed_width_font = 0; +} + +/* @var in makeinfo just uppercases the text. */ +void +cm_var (arg, start_pos, end_pos) + int arg, start_pos, end_pos; +{ + not_fixed_width (arg); + + if (html) + insert_html_tag (arg, "var"); + else if (arg == END) + { + while (start_pos < end_pos) + { + unsigned char c = output_paragraph[start_pos]; + if (strchr ("[](),", c)) + warning (_("unlikely character %c in @var"), c); + output_paragraph[start_pos] = coerce_to_upper (c); + start_pos++; + } + } +} + +void +cm_sc (arg, start_pos, end_pos) + int arg, start_pos, end_pos; +{ + not_fixed_width (arg); + + if (arg == START) + { + if (html) + insert_html_tag (arg, small_tag); + } + else + { + int all_upper = 1; + + if (html) + start_pos += sizeof (small_tag) + 2 - 1; /* skip <small> */ + + while (start_pos < end_pos) + { + unsigned char c = output_paragraph[start_pos]; + if (!isupper (c)) + all_upper = 0; + output_paragraph[start_pos] = coerce_to_upper (c); + start_pos++; + } + if (all_upper) + warning (_("@sc argument all uppercase, thus no effect")); + + if (html) + insert_html_tag (arg, small_tag); + } +} + +void +cm_dfn (arg, position) + int arg, position; +{ + if (html) + insert_html_tag (arg, "dfn"); + else if (arg == START) + add_char ('"'); + else + add_meta_char ('"'); +} + +void +cm_emph (arg) + int arg; +{ + if (html) + insert_html_tag (arg, "em"); + else + add_char ('_'); +} + +void +cm_strong (arg, position) + int arg, position; +{ + if (html) + insert_html_tag (arg, "strong"); + else + add_char ('*'); +} + +void +cm_cite (arg, position) + int arg, position; +{ + if (html) + insert_html_tag (arg, "cite"); + else + { + if (arg == START) + add_char ('`'); + else + add_char ('\''); + } +} + +/* No highlighting, but argument switches fonts. */ +void +cm_not_fixed_width (arg, start, end) + int arg, start, end; +{ + not_fixed_width (arg); +} + +void +cm_i (arg) + int arg; +{ + if (html) + insert_html_tag (arg, "i"); + else + not_fixed_width (arg); +} + +void +cm_b (arg) + int arg; +{ + if (html) + insert_html_tag (arg, "b"); + else + not_fixed_width (arg); +} + +void +cm_r (arg) + int arg; +{ + extern int printing_index; + + /* People use @r{} in index entries like this: + + @findex foo@r{, some text} + + This is supposed to produce output as if the entry were saying + "@code{foo}, some text", since the "fn" index is typeset as + @code. The following attempts to do the same in HTML. Note that + this relies on the fact that only @code bumps up the variable + in_fixed_width_font while processing index entries in HTML mode. */ + if (html && printing_index) + { + int level = in_fixed_width_font; + + while (level--) + insert_html_tag (arg == START ? END : START, "code"); + } + + not_fixed_width (arg); +} + +void +cm_titlefont (arg) + int arg; +{ + not_fixed_width (arg); +} + +/* Various commands are no-op's. */ +void +cm_no_op () +{ +} + + +/* For proofing single chapters, etc. */ +void +cm_novalidate () +{ + validating = 0; +} + + +/* Prevent the argument from being split across two lines. */ +void +cm_w (arg, start, end) + int arg, start, end; +{ + if (arg == START) + non_splitting_words++; + else + non_splitting_words--; +} + + +/* Explain that this command is obsolete, thus the user shouldn't + do anything with it. */ +static void +cm_obsolete (arg, start, end) + int arg, start, end; +{ + if (arg == START) + warning (_("%c%s is obsolete"), COMMAND_PREFIX, command); +} + + +/* This says to inhibit the indentation of the next paragraph, but + not of following paragraphs. */ +void +cm_noindent () +{ + if (!inhibit_paragraph_indentation) + inhibit_paragraph_indentation = -1; +} + +/* I don't know exactly what to do with this. Should I allow + someone to switch filenames in the middle of output? Since the + file could be partially written, this doesn't seem to make sense. + Another option: ignore it, since they don't *really* want to + switch files. Finally, complain, or at least warn. It doesn't + really matter, anyway, since this doesn't get executed. */ +void +cm_setfilename () +{ + char *filename; + get_rest_of_line (1, &filename); + /* warning ("`@%s %s' encountered and ignored", command, filename); */ + free (filename); +} + +void +cm_settitle () +{ + get_rest_of_line (0, &title); +} + +/* Ignore argument in braces. */ +void +cm_ignore_arg (arg, start_pos, end_pos) + int arg, start_pos, end_pos; +{ + if (arg == END) + output_paragraph_offset = start_pos; +} + +/* Ignore argument on rest of line. */ +void +cm_ignore_line () +{ + discard_until ("\n"); +} + +/* Insert the number of blank lines passed as argument. */ +void +cm_sp () +{ + int lines; + char *line; + + get_rest_of_line (1, &line); + + if (sscanf (line, "%d", &lines) != 1 || lines <= 0) + line_error (_("@sp requires a positive numeric argument, not `%s'"), line); + else + { /* Must disable filling since otherwise multiple newlines is like + multiple spaces. Must close paragraph since that's what the + manual says and that's what TeX does. */ + int save_filling_enabled = filling_enabled; + filling_enabled = 0; + + close_paragraph (); + + while (lines--) + { + if (html) + insert_string ("<br><p>\n"); + else + add_char ('\n'); + } + + filling_enabled = save_filling_enabled; + } + free (line); +} + +/* @dircategory LINE outputs INFO-DIR-SECTION LINE, unless --no-headers. */ +void +cm_dircategory () +{ + char *line; + + if (html) + cm_ignore_line (); + else + { + get_rest_of_line (1, &line); + + if (!no_headers && !html) + { + kill_self_indent (-1); /* make sure there's no indentation */ + insert_string ("INFO-DIR-SECTION "); + insert_string (line); + insert ('\n'); + } + + free (line); + } +} + +/* Start a new line with just this text on it. + Then center the line of text. + This always ends the current paragraph. */ +void +cm_center () +{ + int i, start, length; + unsigned char *line; + int save_indented_fill = indented_fill; + int save_filling_enabled = filling_enabled; + int fudge_factor = 1; + + close_paragraph (); + filling_enabled = indented_fill = 0; + cm_noindent (); + start = output_paragraph_offset; + + if (html) + add_word ("<p align=\"center\">"); + + inhibit_output_flushing (); + get_rest_of_line (0, (char **)&line); + execute_string ("%s", (char *)line); + free (line); + uninhibit_output_flushing (); + if (html) + add_word ("</p>"); + + else + { + i = output_paragraph_offset - 1; + while (i > (start - 1) && output_paragraph[i] == '\n') + i--; + + output_paragraph_offset = ++i; + length = output_paragraph_offset - start; + + if (length < (fill_column - fudge_factor)) + { + line = xmalloc (1 + length); + memcpy (line, (char *)(output_paragraph + start), length); + + i = (fill_column - fudge_factor - length) / 2; + output_paragraph_offset = start; + + while (i--) + insert (' '); + + for (i = 0; i < length; i++) + insert (line[i]); + + free (line); + } + } + + insert ('\n'); + close_paragraph (); + filling_enabled = save_filling_enabled; + indented_fill = save_indented_fill; +} + +/* Show what an expression returns. */ +void +cm_result (arg) + int arg; +{ + if (arg == END) + add_word (html ? "=>" : "=>"); +} + +/* What an expression expands to. */ +void +cm_expansion (arg) + int arg; +{ + if (arg == END) + add_word (html ? "==>" : "==>"); +} + +/* Indicates two expressions are equivalent. */ +void +cm_equiv (arg) + int arg; +{ + if (arg == END) + add_word ("=="); +} + +/* What an expression may print. */ +void +cm_print (arg) + int arg; +{ + if (arg == END) + add_word ("-|"); +} + +/* An error signaled. */ +void +cm_error (arg) + int arg; +{ + if (arg == END) + add_word (html ? "error-->" : "error-->"); +} + +/* The location of point in an example of a buffer. */ +void +cm_point (arg) + int arg; +{ + if (arg == END) + add_word ("-!-"); +} + +/* @exdent: Start a new line with just this text on it. + The text is outdented one level if possible. */ +void +cm_exdent () +{ + char *line; + int save_indent = current_indent; + int save_in_fixed_width_font = in_fixed_width_font; + + /* Read argument */ + get_rest_of_line (0, &line); + + /* Exdent the output. Actually this may be a no-op. */ + if (current_indent) + current_indent -= default_indentation_increment; + + /* @exdent arg is supposed to be in roman. */ + in_fixed_width_font = 0; + + /* The preceding newline already inserted the `current_indent'. + Remove one level's worth. */ + kill_self_indent (default_indentation_increment); + + if (html) + add_word ("<br>"); + + /* Can't close_single_paragraph, then we lose preceding blank lines. */ + flush_output (); + execute_string ("%s", line); + free (line); + + if (html) + add_word ("<br>"); + close_single_paragraph (); + + current_indent = save_indent; + in_fixed_width_font = save_in_fixed_width_font; +} + + +/* Remember this file, and move onto the next. */ +void +cm_include () +{ + char *filename; + + if (macro_expansion_output_stream && !executing_string) + me_append_before_this_command (); + + close_paragraph (); + get_rest_of_line (0, &filename); + + if (macro_expansion_output_stream && !executing_string) + remember_itext (input_text, input_text_offset); + + pushfile (); + + /* In verbose mode we print info about including another file. */ + if (verbose_mode) + { + int i = 0; + FSTACK *stack = filestack; + + for (i = 0, stack = filestack; stack; stack = stack->next, i++); + + i *= 2; + + printf ("%*s", i, ""); + printf ("%c%s %s\n", COMMAND_PREFIX, command, filename); + fflush (stdout); + } + + if (!find_and_load (filename)) + { + extern int errno; + + popfile (); + line_number--; + + /* Cannot "@include foo", in line 5 of "/wh/bar". */ + line_error ("%c%s %s: %s", COMMAND_PREFIX, command, filename, + strerror (errno)); + + free (filename); + return; + } + else + { + if (macro_expansion_output_stream && !executing_string) + remember_itext (input_text, input_text_offset); + reader_loop (); + } + free (filename); + popfile (); +} + + +/* @bye: Signals end of processing. Easy to make this happen. */ + +void +cm_bye () +{ + discard_braces (); /* should not have any unclosed braces left */ + flush_output (); + input_text_offset = input_text_length; +} + +/* @paragraphindent */ + +static void +cm_paragraphindent () +{ + char *arg; + + get_rest_of_line (1, &arg); + if (set_paragraph_indent (arg) != 0) + line_error (_("Bad argument to %c%s"), COMMAND_PREFIX, command); + + free (arg); +} + +/* @exampleindent: change indentation of example-like environments. */ +static int +set_default_indentation_increment (string) + char *string; +{ + if (strcmp (string, "asis") == 0 || strcmp (string, _("asis")) == 0) + ; + else if (strcmp (string, "none") == 0 || strcmp (string, _("none")) == 0) + default_indentation_increment = 0; + else if (sscanf (string, "%d", &default_indentation_increment) != 1) + return -1; + return 0; +} + +static void +cm_exampleindent () +{ + char *arg; + + get_rest_of_line (1, &arg); + if (set_default_indentation_increment (arg) != 0) + line_error (_("Bad argument to %c%s"), COMMAND_PREFIX, command); + + free (arg); +} diff --git a/contrib/texinfo/makeinfo/cmds.h b/contrib/texinfo/makeinfo/cmds.h new file mode 100644 index 0000000..7edc810 --- /dev/null +++ b/contrib/texinfo/makeinfo/cmds.h @@ -0,0 +1,50 @@ +/* cmds.h -- declarations for cmds.c. + $Id: cmds.h,v 1.4 1999/04/25 20:43:51 karl Exp $ + + Copyright (C) 1998, 99 Free Software Foundation, Inc. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License along + with this program; if not, write to the Free Software Foundation, Inc., + 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ + +#ifndef CMDS_H +#define CMDS_H + +/* The three arguments a command can get are a flag saying whether it is + before argument parsing (START) or after (END), the starting position + of the arguments, and the ending position. */ +typedef void COMMAND_FUNCTION (); /* So we can say COMMAND_FUNCTION *foo; */ + +/* Each command has an associated function. When the command is + encountered in the text, the associated function is called with START + as the argument. If the function expects arguments in braces, it + remembers itself on the stack. When the corresponding close brace is + encountered, the function is called with END as the argument. */ +#define START 0 +#define END 1 + +/* Does the command expect braces? */ +#define NO_BRACE_ARGS 0 +#define BRACE_ARGS 1 +#define MAYBE_BRACE_ARGS 2 + +typedef struct +{ + char *name; + COMMAND_FUNCTION *proc; + int argument_in_braces; +} COMMAND; + +extern COMMAND command_table[]; + +#endif /* !CMDS_H */ diff --git a/contrib/texinfo/makeinfo/defun.c b/contrib/texinfo/makeinfo/defun.c new file mode 100644 index 0000000..c62aba7 --- /dev/null +++ b/contrib/texinfo/makeinfo/defun.c @@ -0,0 +1,663 @@ +/* defun.c -- @defun and friends. + $Id: defun.c,v 1.11 1999/07/11 16:50:19 karl Exp $ + + Copyright (C) 1998, 99 Free Software Foundation, Inc. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software Foundation, + Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ + +#include "system.h" +#include "defun.h" +#include "insertion.h" +#include "makeinfo.h" + + +#define DEFUN_SELF_DELIMITING(c) \ + ((c) == '(' || (c) == ')' || (c) == '[' || (c) == ']') + +struct token_accumulator +{ + unsigned int length; + unsigned int index; + char **tokens; +}; + +static void +initialize_token_accumulator (accumulator) + struct token_accumulator *accumulator; +{ + accumulator->length = 0; + accumulator->index = 0; + accumulator->tokens = NULL; +} + +static void +accumulate_token (accumulator, token) + struct token_accumulator *accumulator; + char *token; +{ + if (accumulator->index >= accumulator->length) + { + accumulator->length += 10; + accumulator->tokens = xrealloc (accumulator->tokens, + (accumulator->length * sizeof (char *))); + } + accumulator->tokens[accumulator->index] = token; + accumulator->index += 1; +} + +/* Given STRING_POINTER pointing at an open brace, skip forward and return a + pointer to just past the matching close brace. */ +static int +scan_group_in_string (string_pointer) + char **string_pointer; +{ + char *scan_string = (*string_pointer) + 1; + unsigned int level = 1; + + for (;;) + { + int c; + if (level == 0) + { + *string_pointer = scan_string; + return 1; + } + c = *scan_string++; + if (c == 0) + { + /* Tweak line_number to compensate for fact that + we gobbled the whole line before coming here. */ + line_number -= 1; + line_error (_("Missing `}' in @def arg")); + line_number += 1; + *string_pointer = scan_string - 1; + return 0; + } + + if (c == '{') + level += 1; + if (c == '}') + level -= 1; + } +} + +/* Return a list of tokens from the contents of STRING. + Commands and brace-delimited groups count as single tokens. + Contiguous whitespace characters are converted to a token + consisting of a single space. */ +static char ** +args_from_string (string) + char *string; +{ + struct token_accumulator accumulator; + char *token_start, *token_end; + char *scan_string = string; + + initialize_token_accumulator (&accumulator); + + while (*scan_string) + { /* Replace arbitrary whitespace by a single space. */ + if (whitespace (*scan_string)) + { + scan_string += 1; + while (whitespace (*scan_string)) + scan_string += 1; + accumulate_token ((&accumulator), (xstrdup (" "))); + continue; + } + + /* Commands count as single tokens. */ + if (*scan_string == COMMAND_PREFIX) + { + token_start = scan_string; + scan_string += 1; + if (self_delimiting (*scan_string)) + scan_string += 1; + else + { + int c; + while (1) + { + c = *scan_string++; + + if ((c == 0) || (c == '{') || (whitespace (c))) + { + scan_string -= 1; + break; + } + } + + if (*scan_string == '{') + { + char *s = scan_string; + (void) scan_group_in_string (&s); + scan_string = s; + } + } + token_end = scan_string; + } + + /* Parentheses and brackets are self-delimiting. */ + else if (DEFUN_SELF_DELIMITING (*scan_string)) + { + token_start = scan_string; + scan_string += 1; + token_end = scan_string; + } + + /* Open brace introduces a group that is a single token. */ + else if (*scan_string == '{') + { + char *s = scan_string; + int balanced = scan_group_in_string (&s); + + token_start = scan_string + 1; + scan_string = s; + token_end = balanced ? (scan_string - 1) : scan_string; + } + + /* Otherwise a token is delimited by whitespace, parentheses, + brackets, or braces. A token is also ended by a command. */ + else + { + token_start = scan_string; + + for (;;) + { + int c; + + c = *scan_string++; + + /* Do not back up if we're looking at a }; since the only + valid }'s are those matched with {'s, we want to give + an error. If we back up, we go into an infinite loop. */ + if (!c || whitespace (c) || DEFUN_SELF_DELIMITING (c) + || c == '{') + { + scan_string--; + break; + } + + /* If we encounter a command embedded within a token, + then end the token. */ + if (c == COMMAND_PREFIX) + { + scan_string--; + break; + } + } + token_end = scan_string; + } + + accumulate_token (&accumulator, substring (token_start, token_end)); + } + accumulate_token (&accumulator, NULL); + return accumulator.tokens; +} + +static void +process_defun_args (defun_args, auto_var_p) + char **defun_args; + int auto_var_p; +{ + int pending_space = 0; + + for (;;) + { + char *defun_arg = *defun_args++; + + if (defun_arg == NULL) + break; + + if (defun_arg[0] == ' ') + { + pending_space = 1; + continue; + } + + if (pending_space) + { + add_char (' '); + pending_space = 0; + } + + if (DEFUN_SELF_DELIMITING (defun_arg[0])) + add_char (defun_arg[0]); + else if (defun_arg[0] == '&') + if (html) + { + defun_arg = escape_string (xstrdup (defun_arg)); + add_word (defun_arg); + free (defun_arg); + } + else + add_word (defun_arg); + else if (defun_arg[0] == COMMAND_PREFIX) + execute_string ("%s", defun_arg); + else if (auto_var_p) + if (html) + { + defun_arg = escape_string (xstrdup (defun_arg)); + add_word (defun_arg); + free (defun_arg); + } + else + add_word (defun_arg); + else + add_word (defun_arg); + } +} + +static char * +next_nonwhite_defun_arg (arg_pointer) + char ***arg_pointer; +{ + char **scan = (*arg_pointer); + char *arg = (*scan++); + + if ((arg != 0) && (*arg == ' ')) + arg = *scan++; + + if (arg == 0) + scan -= 1; + + *arg_pointer = scan; + + return (arg == 0) ? "" : arg; +} + + +/* This is needed also in insertion.c. */ + +enum insertion_type +get_base_type (type) + enum insertion_type type; +{ + enum insertion_type base_type; + switch (type) + { + case defivar: base_type = defcv; break; + case defmac: base_type = deffn; break; + case defmethod: base_type = defop; break; + case defopt: base_type = defvr; break; + case defspec: base_type = deffn; break; + case deftypefun: base_type = deftypefn; break; + case deftypeivar: base_type = deftypeivar; break; + case deftypemethod: base_type = deftypemethod; break; + case deftypeop: base_type = deftypeop; break; + case deftypevar: base_type = deftypevr; break; + case defun: base_type = deffn; break; + case defvar: base_type = defvr; break; + default: + base_type = type; + break; + } + + return base_type; +} + +/* Make the defun type insertion. + TYPE says which insertion this is. + X_P, if nonzero, says not to start a new insertion. */ +static void +defun_internal (type, x_p) + enum insertion_type type; + int x_p; +{ + enum insertion_type base_type; + char **defun_args, **scan_args; + char *category, *defined_name, *type_name, *type_name2; + + { + char *line; + + /* The @def.. line is the only place in Texinfo where you are + allowed to use unquoted braces that don't delimit arguments of + a command or a macro; in any other place it will trigger an + error message from the reader loop. The special handling of + this case inside `args_from_string' is an extra special hack + which allows this. The side effect is that if we try to expand + the rest of the line below, the recursive reader loop will + signal an error if there are brace-delimited arguments on that line. + + The best solution to this would be to change the syntax of + @def.. commands so that it doesn't violate Texinfo's own rules. + But it's probably too late for this now, as it will break a lot + of existing manuals. + + Unfortunately, this means that you can't call macros, use @value, etc. + inside @def.. commands, sigh. */ + get_rest_of_line (0, &line); + defun_args = (args_from_string (line)); + free (line); + } + + scan_args = defun_args; + + /* Get base type and category string. */ + base_type = get_base_type (type); + + /* xx all these const strings should be determined upon + documentlanguage argument and NOT via gettext (kama). */ + switch (type) + { + case defun: + case deftypefun: + category = _("Function"); + break; + case defmac: + category = _("Macro"); + break; + case defspec: + category = _("Special Form"); + break; + case defvar: + case deftypevar: + category = _("Variable"); + break; + case defopt: + category = _("User Option"); + break; + case defivar: + case deftypeivar: + category = _("Instance Variable"); + break; + case defmethod: + case deftypemethod: + category = _("Method"); + break; + default: + category = next_nonwhite_defun_arg (&scan_args); + break; + } + + /* The class name. */ + if ((base_type == deftypefn) + || (base_type == deftypevr) + || (base_type == defcv) + || (base_type == defop) + || (base_type == deftypeivar) + || (base_type == deftypemethod) + || (base_type == deftypeop) + ) + type_name = next_nonwhite_defun_arg (&scan_args); + + /* The type name for typed languages. */ + if (base_type == deftypemethod + || base_type == deftypeivar + || base_type == deftypeop + ) + type_name2 = next_nonwhite_defun_arg (&scan_args); + + /* The function or whatever that's actually being defined. */ + defined_name = next_nonwhite_defun_arg (&scan_args); + + /* This hack exists solely for the purposes of formatting the Texinfo + manual. I couldn't think of a better way. The token might be a + simple @@ followed immediately by more text. If this is the case, + then the next defun arg is part of this one, and we should + concatenate them. */ + if (*scan_args && **scan_args && !whitespace (**scan_args) + && STREQ (defined_name, "@@")) + { + char *tem = xmalloc (3 + strlen (scan_args[0])); + + sprintf (tem, "@@%s", scan_args[0]); + + free (scan_args[0]); + scan_args[0] = tem; + scan_args++; + defined_name = tem; + } + + if (!x_p) + begin_insertion (type); + + /* Write the definition header line. + This should start at the normal indentation. */ + current_indent -= default_indentation_increment; + start_paragraph (); + + if (html && !x_p) + /* Start the definition on new paragraph. */ + add_word ("<p>\n"); + + if (!html) + switch (base_type) + { + case deffn: + case defvr: + case deftp: + execute_string (" -- %s: %s", category, defined_name); + break; + case deftypefn: + case deftypevr: + execute_string (" -- %s: %s %s", category, type_name, defined_name); + break; + case defcv: + execute_string (" -- %s %s %s: %s", category, _("of"), type_name, + defined_name); + break; + case deftypeivar: + execute_string (" -- %s %s %s: %s %s", category, _("of"), type_name, + type_name2, defined_name); + break; + case defop: + execute_string (" -- %s %s %s: %s", category, _("on"), type_name, + defined_name); + break; + case deftypeop: + execute_string (" -- %s %s %s: %s %s", category, _("on"), type_name, + type_name2, defined_name); + break; + case deftypemethod: + execute_string (" -- %s %s %s: %s %s", category, _("on"), type_name, + type_name2, defined_name); + break; + } + + if (html) + { + /* If this is not a @def...x version, it could only + be a normal version @def.... So start the table here. */ + if (!x_p) + add_word ("<table width=\"100%\">\n"); + + /* If this is an @def...x there has to be an other @def... before + it, so this is only a new row within an existing table. With + two complete standalone tables the gap between them is too big. */ + add_word ("<tr>\n"); + add_word ("<td align=\"left\">"); + + switch (base_type) + { + case deffn: + case defvr: + case deftp: + /* <i> is for the following function arguments. */ + add_word_args ("<b>%s</b><i>", defined_name); + break; + case deftypefn: + case deftypevr: + add_word_args ("%s <b>%s</b><i>", type_name, defined_name); + break; + case defcv: + case defop: + add_word_args ("<b>%s</b><i>", defined_name); + break; + case deftypemethod: + case deftypeop: + case deftypeivar: + add_word_args ("%s <b>%s</b><i>", type_name2, defined_name); + break; + } + } /* if (html)... */ + + current_indent += default_indentation_increment; + + /* Now process the function arguments, if any. If these carry onto + the next line, they should be indented by two increments to + distinguish them from the body of the definition, which is indented + by one increment. */ + current_indent += default_indentation_increment; + + switch (base_type) + { + case deffn: + case defop: + process_defun_args (scan_args, 1); + break; + + /* Through Makeinfo 1.67 we processed remaining args only for deftp, + deftypefn, and deftypemethod. But the libc manual, for example, + needs to say: + @deftypevar {char *} tzname[2] + And simply allowing the extra text seems far simpler than trying + to invent yet more defn commands. In any case, we should either + output it or give an error, not silently ignore it. */ + default: + process_defun_args (scan_args, 0); + break; + } + + current_indent -= default_indentation_increment; + close_single_paragraph (); + + if (html) + { + /* xx The single words (on, off) used here, should depend on + documentlanguage and NOT on gettext --kama. */ + switch (base_type) + { + case deffn: + case defvr: + case deftp: + case deftypefn: + case deftypevr: + add_word ("</i>"); /* close italic area for arguments */ + /* put the rest into the second column */ + add_word_args ("</td>\n<td align=\"right\">%s", category); + break; + + case defcv: + add_word ("</td>\n<td align=\"right\">"); + add_word_args ("%s %s %s", category, _("of"), type_name); + break; + + case defop: + case deftypemethod: + case deftypeop: + add_word ("</i>"); + add_word ("</td>\n<td align=\"right\">"); + add_word_args ("%s %s %s", category, _("on"), type_name); + break; + + case deftypeivar: + add_word ("</i>"); + add_word ("</td>\n<td align=\"right\">"); + add_word_args ("%s %s %s", category, _("of"), type_name); + break; + } /* switch (base_type)... */ + + add_word ("</td>\n"); /* close second column */ + add_word ("</tr>\n"); /* close row */ + + /* This is needed because I have to know if the next line is + normal text or another @def..x. If text follows, create a new + table to get the indentation for the following text. + + This construction would fail if someone uses: + @deffn + @sp 2 + @deffnx + . + @end deffn + But we don't care. */ + if (!looking_at ("@def")) + { + add_word ("</table>\n"); + add_word ("<table width=\"95%\" align=\"center\">\n"); + add_word ("<tr><td>\n"); + } + + } /* if (html)... */ + + /* Make an entry in the appropriate index. */ + switch (base_type) + { + case deffn: + case deftypefn: + execute_string ("@findex %s\n", defined_name); + break; + case defvr: + case deftypevr: + case defcv: + execute_string ("@vindex %s\n", defined_name); + break; + case deftypeivar: + execute_string ("@vindex %s %s %s\n", defined_name, _("of"), type_name); + break; + case defop: + case deftypeop: + case deftypemethod: + execute_string ("@findex %s %s %s\n", defined_name, _("on"), type_name); + break; + case deftp: + execute_string ("@tindex %s\n", defined_name); + break; + } + + /* Deallocate the token list. */ + scan_args = defun_args; + while (1) + { + char * arg = (*scan_args++); + if (arg == NULL) + break; + free (arg); + } + free (defun_args); +} + +/* Add an entry for a function, macro, special form, variable, or option. + If the name of the calling command ends in `x', then this is an extra + entry included in the body of an insertion of the same type. */ +void +cm_defun () +{ + int x_p; + enum insertion_type type; + char *temp = xstrdup (command); + + x_p = (command[strlen (command) - 1] == 'x'); + + if (x_p) + temp[strlen (temp) - 1] = 0; + + type = find_type_from_name (temp); + free (temp); + + /* If we are adding to an already existing insertion, then make sure + that we are already in an insertion of type TYPE. */ + if (x_p && (!insertion_level || insertion_stack->insertion != type)) + { + line_error (_("Must be in `%s' insertion to use `%sx'"), + command, command); + discard_until ("\n"); + return; + } + + defun_internal (type, x_p); +} diff --git a/contrib/texinfo/makeinfo/defun.h b/contrib/texinfo/makeinfo/defun.h new file mode 100644 index 0000000..ebff9d6 --- /dev/null +++ b/contrib/texinfo/makeinfo/defun.h @@ -0,0 +1,31 @@ +/* defun.h -- declaration for defuns. + $Id: defun.h,v 1.2 1999/03/25 22:49:10 karl Exp $ + + Copyright (C) 1999 Free Software Foundation, Inc. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + + Written by Karl Heinz Marbaise <kama@hippo.fido.de>. */ + +#ifndef DEFUN_H +#define DEFUN_H + +#include "insertion.h" + +extern enum insertion_type get_base_type (); +extern void cm_defun (); + +#endif /* !DEFUN_H */ + diff --git a/contrib/texinfo/makeinfo/files.c b/contrib/texinfo/makeinfo/files.c new file mode 100644 index 0000000..ce8ace0 --- /dev/null +++ b/contrib/texinfo/makeinfo/files.c @@ -0,0 +1,529 @@ +/* files.c -- file-related functions for Texinfo. + $Id: files.c,v 1.5 1999/03/23 21:42:44 karl Exp $ + + Copyright (C) 1998, 99 Free Software Foundation, Inc. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software Foundation, + Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ + +#include "system.h" +#include "files.h" +#include "macro.h" +#include "makeinfo.h" + +FSTACK *filestack = NULL; + +static int node_filename_stack_index = 0; +static int node_filename_stack_size = 0; +static char **node_filename_stack = NULL; + + +/* Looking for include files. */ + +/* Given a string containing units of information separated by colons, + return the next one pointed to by INDEX, or NULL if there are no more. + Advance INDEX to the character after the colon. */ +static char * +extract_colon_unit (string, index) + char *string; + int *index; +{ + int start; + int path_sep_char = PATH_SEP[0]; + int i = *index; + + if (!string || (i >= strlen (string))) + return NULL; + + /* Each call to this routine leaves the index pointing at a colon if + there is more to the path. If i > 0, then increment past the + `:'. If i == 0, then the path has a leading colon. Trailing colons + are handled OK by the `else' part of the if statement; an empty + string is returned in that case. */ + if (i && string[i] == path_sep_char) + i++; + + start = i; + while (string[i] && string[i] != path_sep_char) i++; + *index = i; + + if (i == start) + { + if (string[i]) + (*index)++; + + /* Return "" in the case of a trailing `:'. */ + return xstrdup (""); + } + else + { + char *value; + + value = xmalloc (1 + (i - start)); + memcpy (value, &string[start], (i - start)); + value [i - start] = 0; + + return value; + } +} + +/* Return the full pathname for FILENAME by searching along PATH. + When found, return the stat () info for FILENAME in FINFO. + If PATH is NULL, only the current directory is searched. + If the file could not be found, return a NULL pointer. */ +static char * +get_file_info_in_path (filename, path, finfo) + char *filename, *path; + struct stat *finfo; +{ + char *dir; + int result, index = 0; + + if (path == NULL) + path = "."; + + /* Handle absolute pathnames. */ + if (IS_ABSOLUTE (filename) + || (*filename == '.' + && (IS_SLASH (filename[1]) + || (filename[1] == '.' && IS_SLASH (filename[2]))))) + { + if (stat (filename, finfo) == 0) + return xstrdup (filename); + else + return NULL; + } + + while ((dir = extract_colon_unit (path, &index))) + { + char *fullpath; + + if (!*dir) + { + free (dir); + dir = xstrdup ("."); + } + + fullpath = xmalloc (2 + strlen (dir) + strlen (filename)); + sprintf (fullpath, "%s/%s", dir, filename); + free (dir); + + result = stat (fullpath, finfo); + + if (result == 0) + return fullpath; + else + free (fullpath); + } + return NULL; +} + +/* Find and load the file named FILENAME. Return a pointer to + the loaded file, or NULL if it can't be loaded. */ +char * +find_and_load (filename) + char *filename; +{ + struct stat fileinfo; + long file_size; + int file = -1, count = 0; + char *fullpath, *result; +#if O_BINARY || defined (VMS) + int n; +#endif + + result = fullpath = NULL; + + fullpath = get_file_info_in_path (filename, include_files_path, &fileinfo); + + if (!fullpath) + goto error_exit; + + filename = fullpath; + file_size = (long) fileinfo.st_size; + + file = open (filename, O_RDONLY); + if (file < 0) + goto error_exit; + + /* Load the file, with enough room for a newline and a null. */ + result = xmalloc (file_size + 2); + + /* VMS stat lies about the st_size value. The actual number of + readable bytes is always less than this value. The arcane + mysteries of VMS/RMS are too much to probe, so this hack + suffices to make things work. */ +#if O_BINARY || defined (VMS) +#ifdef VMS + while ((n = read (file, result + count, file_size)) > 0) +#else /* !VMS */ +#ifndef WIN32 + while ((n = read (file, result + count, file_size)) > 0) +#else /* WIN32 */ + /* Does WIN32 really need reading 1 character at a time?? */ + while ((n = read (file, result + count, 1)) > 0) +#endif /* WIN32 */ +#endif /* !VMS */ + count += n; + if (0 < count && count < file_size) + result = xrealloc (result, count + 2); /* why waste the slack? */ + else if (n == -1) +#else /* !VMS && !O_BINARY */ + count = file_size; + if (read (file, result, file_size) != file_size) +#endif /* !VMS && !WIN32 */ + + error_exit: + { + if (result) + free (result); + + if (fullpath) + free (fullpath); + + if (file != -1) + close (file); + + return NULL; + } + close (file); + + /* Set the globals to the new file. */ + input_text = result; + input_text_length = count; + input_filename = fullpath; + node_filename = xstrdup (fullpath); + input_text_offset = 0; + line_number = 1; + /* Not strictly necessary. This magic prevents read_token () from doing + extra unnecessary work each time it is called (that is a lot of times). + INPUT_TEXT_LENGTH is one past the actual end of the text. */ + input_text[input_text_length] = '\n'; + /* This, on the other hand, is always necessary. */ + input_text[input_text_length+1] = 0; + return result; +} + +/* Pushing and popping files. */ +void +push_node_filename () +{ + if (node_filename_stack_index + 1 > node_filename_stack_size) + node_filename_stack = xrealloc + (node_filename_stack, (node_filename_stack_size += 10) * sizeof (char *)); + + node_filename_stack[node_filename_stack_index] = node_filename; + node_filename_stack_index++; +} + +void +pop_node_filename () +{ + node_filename = node_filename_stack[--node_filename_stack_index]; +} + +/* Save the state of the current input file. */ +void +pushfile () +{ + FSTACK *newstack = xmalloc (sizeof (FSTACK)); + newstack->filename = input_filename; + newstack->text = input_text; + newstack->size = input_text_length; + newstack->offset = input_text_offset; + newstack->line_number = line_number; + newstack->next = filestack; + + filestack = newstack; + push_node_filename (); +} + +/* Make the current file globals be what is on top of the file stack. */ +void +popfile () +{ + FSTACK *tos = filestack; + + if (!tos) + abort (); /* My fault. I wonder what I did? */ + + if (macro_expansion_output_stream) + { + maybe_write_itext (input_text, input_text_offset); + forget_itext (input_text); + } + + /* Pop the stack. */ + filestack = filestack->next; + + /* Make sure that commands with braces have been satisfied. */ + if (!executing_string && !me_executing_string) + discard_braces (); + + /* Get the top of the stack into the globals. */ + input_filename = tos->filename; + input_text = tos->text; + input_text_length = tos->size; + input_text_offset = tos->offset; + line_number = tos->line_number; + free (tos); + + /* Go back to the (now) current node. */ + pop_node_filename (); +} + +/* Flush all open files on the file stack. */ +void +flush_file_stack () +{ + while (filestack) + { + char *fname = input_filename; + char *text = input_text; + popfile (); + free (fname); + free (text); + } +} + +/* Return the index of the first character in the filename + which is past all the leading directory characters. */ +static int +skip_directory_part (filename) + char *filename; +{ + int i = strlen (filename) - 1; + + while (i && !IS_SLASH (filename[i])) + i--; + if (IS_SLASH (filename[i])) + i++; + else if (filename[i] && HAVE_DRIVE (filename)) + i = 2; + + return i; +} + +char * +filename_non_directory (name) + char *name; +{ + return xstrdup (name + skip_directory_part (name)); +} + +/* Return just the simple part of the filename; i.e. the + filename without the path information, or extensions. + This conses up a new string. */ +char * +filename_part (filename) + char *filename; +{ + char *basename = filename_non_directory (filename); + +#ifdef REMOVE_OUTPUT_EXTENSIONS + /* See if there is an extension to remove. If so, remove it. */ + { + char *temp; + + temp = strrchr (basename, '.'); + if (temp) + *temp = 0; + } +#endif /* REMOVE_OUTPUT_EXTENSIONS */ + return basename; +} + +/* Return the pathname part of filename. This can be NULL. */ +char * +pathname_part (filename) + char *filename; +{ + char *expand_filename (); + char *result = NULL; + int i; + + filename = expand_filename (filename, ""); + + i = skip_directory_part (filename); + if (i) + { + result = xmalloc (1 + i); + strncpy (result, filename, i); + result[i] = 0; + } + free (filename); + return result; +} + +/* Return the expansion of FILENAME. */ +char * +expand_filename (filename, input_name) + char *filename, *input_name; +{ + int i; + char *full_pathname (); + + if (filename) + { + filename = full_pathname (filename); + if (IS_ABSOLUTE (filename) + || (*filename == '.' && + (IS_SLASH (filename[1]) || + (filename[1] == '.' && IS_SLASH (filename[2]))))) + return filename; + } + else + { + filename = filename_non_directory (input_name); + + if (!*filename) + { + free (filename); + filename = xstrdup ("noname.texi"); + } + + for (i = strlen (filename) - 1; i; i--) + if (filename[i] == '.') + break; + + if (!i) + i = strlen (filename); + + if (i + 6 > (strlen (filename))) + filename = xrealloc (filename, i + 6); + strcpy (filename + i, html ? ".html" : ".info"); + return filename; + } + + if (IS_ABSOLUTE (input_name)) + { + /* Make it so that relative names work. */ + char *result; + + i = strlen (input_name) - 1; + + result = xmalloc (1 + strlen (input_name) + strlen (filename)); + strcpy (result, input_name); + + while (!IS_SLASH (result[i]) && i) + i--; + if (IS_SLASH (result[i])) + i++; + + strcpy (&result[i], filename); + free (filename); + return result; + } + return filename; +} + +/* Return the full path to FILENAME. */ +char * +full_pathname (filename) + char *filename; +{ + int initial_character; + char *result; + + /* No filename given? */ + if (!filename || !*filename) + return xstrdup (""); + + /* Already absolute? */ + if (IS_ABSOLUTE (filename) || + (*filename == '.' && + (IS_SLASH (filename[1]) || + (filename[1] == '.' && IS_SLASH (filename[2]))))) + return xstrdup (filename); + + initial_character = *filename; + if (initial_character != '~') + { + char *localdir = xmalloc (1025); +#ifdef HAVE_GETCWD + if (!getcwd (localdir, 1024)) +#else + if (!getwd (localdir)) +#endif + { + fprintf (stderr, _("%s: getwd: %s, %s\n"), + progname, filename, localdir); + xexit (1); + } + + strcat (localdir, "/"); + strcat (localdir, filename); + result = xstrdup (localdir); + free (localdir); + } + else + { /* Does anybody know why WIN32 doesn't want to support $HOME? + If the reason is they don't have getpwnam, they should + only disable the else clause below. */ +#ifndef WIN32 + if (IS_SLASH (filename[1])) + { + /* Return the concatenation of the environment variable HOME + and the rest of the string. */ + char *temp_home; + + temp_home = (char *) getenv ("HOME"); + result = xmalloc (strlen (&filename[1]) + + 1 + + temp_home ? strlen (temp_home) + : 0); + *result = 0; + + if (temp_home) + strcpy (result, temp_home); + + strcat (result, &filename[1]); + } + else + { + struct passwd *user_entry; + int i, c; + char *username = xmalloc (257); + + for (i = 1; (c = filename[i]); i++) + { + if (IS_SLASH (c)) + break; + else + username[i - 1] = c; + } + if (c) + username[i - 1] = 0; + + user_entry = getpwnam (username); + + if (!user_entry) + return xstrdup (filename); + + result = xmalloc (1 + strlen (user_entry->pw_dir) + + strlen (&filename[i])); + strcpy (result, user_entry->pw_dir); + strcat (result, &filename[i]); + } +#endif /* not WIN32 */ + } + return result; +} + +char * +output_name_from_input_name (name) + char *name; +{ + return expand_filename (NULL, name); +} diff --git a/contrib/texinfo/makeinfo/files.h b/contrib/texinfo/makeinfo/files.h new file mode 100644 index 0000000..d96c444 --- /dev/null +++ b/contrib/texinfo/makeinfo/files.h @@ -0,0 +1,45 @@ +/* files.h -- declarations for files.c. + $Id: files.h,v 1.1 1998/10/24 21:37:25 karl Exp $ + + Copyright (C) 1998 Free Software Foundation, Inc. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + */ + +#ifndef FILES_H +#define FILES_H + +/* A stack of file information records. If a new file is read in with + "@input", we remember the old input file state on this stack. */ +typedef struct fstack +{ + struct fstack *next; + char *filename; + char *text; + int size; + int offset; + int line_number; +} FSTACK; +extern FSTACK *filestack; + +extern void pushfile (), popfile (); +extern void flush_file_stack (); +extern char *find_and_load (); +extern char *output_name_from_input_name (); +extern char *expand_filename (); +extern char *filename_part (); +extern char *pathname_part (); + +#endif /* !FILES_H */ diff --git a/contrib/texinfo/makeinfo/footnote.c b/contrib/texinfo/makeinfo/footnote.c new file mode 100644 index 0000000..c1a056d --- /dev/null +++ b/contrib/texinfo/makeinfo/footnote.c @@ -0,0 +1,359 @@ +/* footnote.c -- footnotes for Texinfo. + $Id: footnote.c,v 1.10 1999/09/20 12:20:52 karl Exp $ + + Copyright (C) 1998, 99 Free Software Foundation, Inc. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software Foundation, + Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ + +#include "system.h" +#include "footnote.h" +#include "macro.h" +#include "makeinfo.h" + +/* Nonzero means that the footnote style for this document was set on + the command line, which overrides any other settings. */ +int footnote_style_preset = 0; + +/* The current footnote number in this node. Each time a new node is + started this is reset to 1. */ +int current_footnote_number = 1; + +/* Nonzero means we automatically number footnotes with no specified marker. */ +int number_footnotes = 1; + +/* Nonzero means we are currently outputting footnotes. */ +int already_outputting_pending_notes = 0; + + +/* Footnotes can be handled in one of two ways: + + separate_node: + Make them look like followed references, with the reference + destinations in a makeinfo manufactured node or, + end_node: + Make them appear at the bottom of the node that they originally + appeared in. */ + +#define separate_node 0 +#define end_node 1 + +int footnote_style = end_node; +int first_footnote_this_node = 1; +int footnote_count = 0; + +/* Set the footnote style based on the style identifier in STRING. */ +int +set_footnote_style (string) + char *string; +{ + if (strcasecmp (string, "separate") == 0) + footnote_style = separate_node; + else if (strcasecmp (string, "end") == 0) + footnote_style = end_node; + else + return -1; + + return 0; +} + +void +cm_footnotestyle () +{ + char *arg; + + get_rest_of_line (1, &arg); + + /* If set on command line, do not change the footnote style. */ + if (!footnote_style_preset && set_footnote_style (arg) != 0) + line_error (_("Bad argument to %c%s"), COMMAND_PREFIX, command); + + free (arg); +} + +typedef struct fn +{ + struct fn *next; + char *marker; + char *note; + int number; +} FN; + +FN *pending_notes = NULL; + +/* A method for remembering footnotes. Note that this list gets output + at the end of the current node. */ +void +remember_note (marker, note) + char *marker, *note; +{ + FN *temp = xmalloc (sizeof (FN)); + + temp->marker = xstrdup (marker); + temp->note = xstrdup (note); + temp->next = pending_notes; + temp->number = current_footnote_number; + pending_notes = temp; + footnote_count++; +} + +/* How to get rid of existing footnotes. */ +static void +free_pending_notes () +{ + FN *temp; + + while ((temp = pending_notes)) + { + free (temp->marker); + free (temp->note); + pending_notes = pending_notes->next; + free (temp); + } + first_footnote_this_node = 1; + footnote_count = 0; + current_footnote_number = 1; /* for html */ +} + +/* What to do when you see a @footnote construct. */ + + /* Handle a "footnote". + footnote *{this is a footnote} + where "*" is the (optional) marker character for this note. */ +void +cm_footnote () +{ + char *marker; + char *note; + + get_until ("{", &marker); + canon_white (marker); + + if (macro_expansion_output_stream && !executing_string) + append_to_expansion_output (input_text_offset + 1); /* include the { */ + + /* Read the argument in braces. */ + if (curchar () != '{') + { + line_error (_("`%c%s' needs an argument `{...}', not just `%s'"), + COMMAND_PREFIX, command, marker); + free (marker); + return; + } + else + { + int len; + int braces = 1; + int loc = ++input_text_offset; + + while (braces) + { + if (loc == input_text_length) + { + line_error (_("No closing brace for footnote `%s'"), marker); + return; + } + + if (input_text[loc] == '{') + braces++; + else if (input_text[loc] == '}') + braces--; + else if (input_text[loc] == '\n') + line_number++; + + loc++; + } + + len = (loc - input_text_offset) - 1; + note = xmalloc (len + 1); + memcpy (note, &input_text[input_text_offset], len); + note[len] = 0; + input_text_offset = loc; + } + + /* Must write the macro-expanded argument to the macro expansion + output stream. This is like the case in index_add_arg. */ + if (macro_expansion_output_stream && !executing_string) + { + /* Calling me_execute_string on a lone } provokes an error, since + as far as the reader knows there is no matching {. We wrote + the { above in the call to append_to_expansion_output. */ + me_execute_string_keep_state (note, "}"); + } + + if (!current_node || !*current_node) + { + line_error (_("Footnote defined without parent node")); + free (marker); + free (note); + return; + } + + if (!*marker) + { + free (marker); + + if (number_footnotes) + { + marker = xmalloc (10); + sprintf (marker, "%d", current_footnote_number); + } + else + marker = xstrdup ("*"); + } + + remember_note (marker, note); + + /* fixme: html: footnote processing needs work; we currently ignore + the style requested; we could clash with a node name of the form + `fn-<n>', though that's unlikely. */ + if (html) + add_word_args ("<a rel=footnote href=\"#fn-%d\"><sup>%s</sup></a>", + current_footnote_number, marker); + else + /* Your method should at least insert MARKER. */ + switch (footnote_style) + { + case separate_node: + add_word_args ("(%s)", marker); + execute_string (" (*note %s-Footnote-%d::)", + current_node, current_footnote_number); + if (first_footnote_this_node) + { + char *temp_string, *expanded_ref; + + temp_string = xmalloc (strlen (current_node) + + strlen ("-Footnotes") + 1); + + strcpy (temp_string, current_node); + strcat (temp_string, "-Footnotes"); + expanded_ref = expansion (temp_string, 0); + remember_node_reference (expanded_ref, line_number, + followed_reference); + free (temp_string); + free (expanded_ref); + first_footnote_this_node = 0; + } + break; + + case end_node: + add_word_args ("(%s)", marker); + break; + + default: + break; + } + current_footnote_number++; + + free (marker); + free (note); +} + +/* Output the footnotes. We are at the end of the current node. */ +void +output_pending_notes () +{ + FN *footnote = pending_notes; + + if (!pending_notes) + return; + + if (html) + { /* The type= attribute is used just in case some weirdo browser + out there doesn't use numbers by default. Since we rely on the + browser to produce the footnote numbers, we need to make sure + they ARE indeed numbers. Pre-HTML4 browsers seem to not care. */ + add_word ("<hr><h4>"); + add_word (_("Footnotes")); + add_word ("</h4>\n<ol type=\"1\">\n"); + } + else + switch (footnote_style) + { + case separate_node: + { + char *old_current_node = current_node; + char *old_command = xstrdup (command); + + already_outputting_pending_notes++; + execute_string ("%cnode %s-Footnotes,,,%s\n", + COMMAND_PREFIX, current_node, current_node); + already_outputting_pending_notes--; + current_node = old_current_node; + free (command); + command = old_command; + } + break; + + case end_node: + close_paragraph (); + in_fixed_width_font++; + /* This string should be translated according to the + @documentlanguage, not the current LANG. We can't do that + yet, so leave it in English. */ + execute_string ("---------- Footnotes ----------\n\n"); + in_fixed_width_font--; + break; + } + + /* Handle the footnotes in reverse order. */ + { + FN **array = xmalloc ((footnote_count + 1) * sizeof (FN *)); + array[footnote_count] = NULL; + + while (--footnote_count > -1) + { + array[footnote_count] = footnote; + footnote = footnote->next; + } + + filling_enabled = 1; + indented_fill = 1; + + while ((footnote = array[++footnote_count])) + { + if (html) + { + /* Make the text of every footnote begin a separate paragraph. */ + add_word_args ("<li><a name=\"fn-%d\"></a>\n<p>", + footnote->number); + execute_string ("%s", footnote->note); + add_word ("</p>\n"); + } + else + { + char *old_current_node = current_node; + char *old_command = xstrdup (command); + + already_outputting_pending_notes++; + execute_string ("%canchor{%s-Footnote-%d}(%s) %s", + COMMAND_PREFIX, current_node, footnote->number, + footnote->marker, footnote->note); + already_outputting_pending_notes--; + current_node = old_current_node; + free (command); + command = old_command; + } + + close_paragraph (); + } + + if (html) + add_word ("</ol><hr>"); + close_paragraph (); + free (array); + } + + free_pending_notes (); +} diff --git a/contrib/texinfo/makeinfo/footnote.h b/contrib/texinfo/makeinfo/footnote.h new file mode 100644 index 0000000..c87a0aa --- /dev/null +++ b/contrib/texinfo/makeinfo/footnote.h @@ -0,0 +1,37 @@ +/* footnote.h -- declarations for footnote.c. + $Id: footnote.h,v 1.2 1998/10/26 22:16:15 karl Exp $ + + Copyright (C) 1998 Free Software Foundation, Inc. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + */ + +#ifndef FOOTNOTE_H +#define FOOTNOTE_H + +extern int footnote_style_preset; +extern int current_footnote_number; +extern int number_footnotes; +extern int already_outputting_pending_notes; + +/* The Texinfo @commands. */ +extern void cm_footnote (); +extern void cm_footnotestyle (); + +extern int set_footnote_style (); /* called for -s option */ + +extern void output_pending_notes (); /* called for output */ + +#endif /* !FOOTNOTE_H */ diff --git a/contrib/texinfo/makeinfo/html.c b/contrib/texinfo/makeinfo/html.c new file mode 100644 index 0000000..f2e53e5 --- /dev/null +++ b/contrib/texinfo/makeinfo/html.c @@ -0,0 +1,182 @@ +/* html.c -- html-related utilities. + $Id: html.c,v 1.5 1999/09/18 19:27:41 karl Exp $ + + Copyright (C) 1999 Free Software Foundation, Inc. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software Foundation, + Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ + +#include "system.h" +#include "cmds.h" +#include "html.h" +#include "lang.h" +#include "makeinfo.h" +#include "sectioning.h" + +/* See html.h. */ +int html_output_head_p = 0; + +void +html_output_head () +{ + char *html_title; + + if (html_output_head_p) + return; + html_output_head_p = 1; + + /* The <title> should not have markup. */ + html_title = title ? text_expansion (title) : _("Untitled"); + + add_word_args ("<html lang=\"%s\"><head>\n<title>%s</title>\n", + language_table[language_code].abbrev, html_title); + + add_word ("<meta http-equiv=\"Content-Type\" content=\"text/html"); + if (document_encoding) + add_word_args ("; charset=%s", document_encoding); + add_word ("\">\n"); + + add_word_args ("<meta name=description content=\"%s\">\n", html_title); + add_word_args ("<meta name=generator content=\"makeinfo %s\">\n", VERSION); + add_word ("<link href=\"http://texinfo.org/\" rel=generator-home>\n"); + add_word ("</head><body>\n\n"); +} + + +/* Escape HTML special characters in the string if necessary, + returning a pointer to a possibly newly-allocated one. */ +char * +escape_string (string) + char * string; +{ + int i=0, newlen=0; + char * newstring; + + do + { + /* Find how much to allocate. */ + switch (string[i]) + { + case '&': + newlen += 5; /* `&' */ + break; + case '<': + case '>': + newlen += 4; /* `<', `>' */ + break; + default: + newlen++; + } + i++; + } + while (string[i]); + + if (newlen == i) return string; /* Already OK. */ + + newstring = xmalloc (newlen + 2); + i = 0; + do + { + switch (string[i]) + { + case '&': + strcpy (newstring, "&"); + newstring += 5; + break; + case '<': + strcpy (newstring, "<"); + newstring += 4; + break; + case '>': + strcpy (newstring, ">"); + newstring += 4; + break; + default: + newstring[0] = string[i]; + newstring++; + } + } + while (string[i++]); + free (string); + return newstring - newlen -1; +} + +/* Open or close TAG according to START_OR_END. */ +void +insert_html_tag (start_or_end, tag) + int start_or_end; + char *tag; +{ + if (!paragraph_is_open && (start_or_end == START)) + { + /* Need to compensate for the <p> we are about to insert, or + else cm_xxx functions that call us will get wrong text + between START and END. */ + adjust_braces_following (output_paragraph_offset, 3); + add_word ("<p>"); + } + add_char ('<'); + if (start_or_end != START) + add_char ('/'); + add_word (tag); + add_char ('>'); +} + +/* Output an HTML <link> to the filename for NODE, including the + other string as extra attributes. */ +void +add_link (node, attributes) + char *node, *attributes; +{ + if (node) + { + add_word_args ("<link %s href=\"", attributes); + add_anchor_name (node, 1); + add_word ("\">\n"); + } +} + +/* Output NAME with characters escaped as appropriate for an anchor + name, i.e., escape URL special characters as %<n>. */ +void +add_escaped_anchor_name (name) + char *name; +{ + for (; *name; name++) + { + if (*name == '&') + add_word ("&"); + else if (! URL_SAFE_CHAR (*name)) + /* Cast so characters with the high bit set are treated as >128, + for example o-umlaut should be 246, not -10. */ + add_word_args ("%%%x", (unsigned char) *name); + else + add_char (*name); + } +} + +/* Insert the text for the name of a reference in an HTML anchor + appropriate for NODENAME. If HREF is nonzero, it will be + appropriate for a href= attribute, rather than name= i.e., including + the `#' if it's an internal reference. */ +void +add_anchor_name (nodename, href) + char *nodename; + int href; +{ + if (href) + add_char ('#'); + + add_escaped_anchor_name (nodename); +} diff --git a/contrib/texinfo/makeinfo/html.h b/contrib/texinfo/makeinfo/html.h new file mode 100644 index 0000000..2d68c77 --- /dev/null +++ b/contrib/texinfo/makeinfo/html.h @@ -0,0 +1,44 @@ +/* html.h -- declarations for html-related utilities. + $Id: html.h,v 1.1 1999/04/25 20:53:33 karl Exp $ + + Copyright (C) 1999 Free Software Foundation, Inc. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software Foundation, + Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ + +#ifndef HTML_H +#define HTML_H + +/* Nonzero if we have output the <head>. */ +extern int html_output_head_p; + +/* Perform the <head> output. */ +extern void html_output_head (); + +/* Escape &<>. */ +extern char *escape_string (/* char * */); + +/* Open or close TAG according to START_OR_END. */ +extern void insert_html_tag (/* int start_or_end, char *tag */); + +/* Output HTML <link> to NODE, plus extra ATTRIBUTES. */ +extern void add_link (/* char *node, char *attributes */); + +/* Escape URL-special characters as %xy. */ +extern void add_escaped_anchor_name (/* char *name */); + +/* See html.c. */ +extern void add_anchor_name (/* nodename, href */); + +#endif /* !HTML_H */ diff --git a/contrib/texinfo/makeinfo/index.c b/contrib/texinfo/makeinfo/index.c new file mode 100644 index 0000000..05466ce --- /dev/null +++ b/contrib/texinfo/makeinfo/index.c @@ -0,0 +1,823 @@ +/* index.c -- indexing for Texinfo. + $Id: index.c,v 1.21 1999/07/18 18:50:02 karl Exp $ + + Copyright (C) 1998, 99 Free Software Foundation, Inc. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software Foundation, + Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ + +#include "system.h" +#include "index.h" +#include "lang.h" +#include "macro.h" +#include "toc.h" + +/* An index element... */ +typedef struct index_elt +{ + struct index_elt *next; + char *entry; /* The index entry itself, after expansion. */ + char *entry_text; /* The original, non-expanded entry text. */ + char *node; /* The node from whence it came. */ + int code; /* Nonzero means add `@code{...}' when + printing this element. */ + int defining_line; /* Line number where this entry was written. */ + char *defining_file; /* Source file for defining_line. */ +} INDEX_ELT; + + +/* A list of short-names for each index. + There are two indices into the the_indices array. + * read_index is the index that points to the list of index + entries that we will find if we ask for the list of entries for + this name. + * write_index is the index that points to the list of index entries + that we will add new entries to. + + Initially, read_index and write_index are the same, but the + @syncodeindex and @synindex commands can change the list we add + entries to. + + For example, after the commands + @cindex foo + @defindex ii + @synindex cp ii + @cindex bar + + the cp index will contain the entry `foo', and the new ii + index will contain the entry `bar'. This is consistent with the + way texinfo.tex handles the same situation. + + In addition, for each index, it is remembered whether that index is + a code index or not. Code indices have @code{} inserted around the + first word when they are printed with printindex. */ +typedef struct +{ + char *name; + int read_index; /* index entries for `name' */ + int write_index; /* store index entries here, @synindex can change it */ + int code; +} INDEX_ALIST; + +INDEX_ALIST **name_index_alist = NULL; + +/* An array of pointers. Each one is for a different index. The + "synindex" command changes which array slot is pointed to by a + given "index". */ +INDEX_ELT **the_indices = NULL; + +/* The number of defined indices. */ +int defined_indices = 0; + +/* Stuff for defining commands on the fly. */ +COMMAND **user_command_array = NULL; +int user_command_array_len = 0; + +/* How to compare index entries for sorting. May be set to strcoll. */ +int (*index_compare_fn) () = strcasecmp; + +/* Find which element in the known list of indices has this name. + Returns -1 if NAME isn't found. */ +static int +find_index_offset (name) + char *name; +{ + int i; + for (i = 0; i < defined_indices; i++) + if (name_index_alist[i] && STREQ (name, name_index_alist[i]->name)) + return i; + return -1; +} + +/* Return a pointer to the entry of (name . index) for this name. + Return NULL if the index doesn't exist. */ +INDEX_ALIST * +find_index (name) + char *name; +{ + int offset = find_index_offset (name); + if (offset > -1) + return name_index_alist[offset]; + else + return NULL; +} + +/* User-defined commands, which happens only from user-defined indexes. + Used to initialize the builtin indices, too. */ +void +define_user_command (name, proc, needs_braces_p) + char *name; + COMMAND_FUNCTION *proc; + int needs_braces_p; +{ + int slot = user_command_array_len; + user_command_array_len++; + + if (!user_command_array) + user_command_array = xmalloc (1 * sizeof (COMMAND *)); + + user_command_array = xrealloc (user_command_array, + (1 + user_command_array_len) * sizeof (COMMAND *)); + + user_command_array[slot] = xmalloc (sizeof (COMMAND)); + user_command_array[slot]->name = xstrdup (name); + user_command_array[slot]->proc = proc; + user_command_array[slot]->argument_in_braces = needs_braces_p; +} + +/* Please release me, let me go... */ +static void +free_index (index) + INDEX_ELT *index; +{ + INDEX_ELT *temp; + + while ((temp = index)) + { + free (temp->entry); + free (temp->entry_text); + /* Do not free the node, because we already freed the tag table, + which freed all the node names. */ + /* free (temp->node); */ + index = index->next; + free (temp); + } +} + +/* Flush an index by name. This will delete the list of entries that + would be written by a @printindex command for this index. */ +static void +undefindex (name) + char *name; +{ + int i; + int which = find_index_offset (name); + + /* The index might have already been freed if this was the target of + an @synindex. */ + if (which < 0 || !name_index_alist[which]) + return; + + i = name_index_alist[which]->read_index; + + free_index (the_indices[i]); + the_indices[i] = NULL; + + free (name_index_alist[which]->name); + free (name_index_alist[which]); + name_index_alist[which] = NULL; +} + +/* Add the arguments to the current index command to the index NAME. + html fixxme generate specific html anchor */ +static void +index_add_arg (name) + char *name; +{ + int which; + char *index_entry; + INDEX_ALIST *tem; + + tem = find_index (name); + + which = tem ? tem->write_index : -1; + + if (macro_expansion_output_stream && !executing_string) + append_to_expansion_output (input_text_offset + 1); + + get_rest_of_line (0, &index_entry); + ignore_blank_line (); + + if (macro_expansion_output_stream && !executing_string) + { + char *index_line = xmalloc (strlen (index_entry) + 2); + sprintf (index_line, "%s\n", index_entry); + me_execute_string_keep_state (index_line, NULL); + free (index_line); + } + + if (which < 0) + { + line_error (_("Unknown index `%s'"), name); + free (index_entry); + } + else + { + INDEX_ELT *new = xmalloc (sizeof (INDEX_ELT)); + new->next = the_indices[which]; + new->entry_text = index_entry; + new->entry = NULL; + new->node = current_node ? current_node : xstrdup (""); + new->code = tem->code; + new->defining_line = line_number - 1; + /* We need to make a copy since input_filename may point to + something that goes away, for example, inside a macro. + (see the findexerr test). */ + new->defining_file = xstrdup (input_filename); + the_indices[which] = new; + } +} + +/* The function which user defined index commands call. */ +static void +gen_index () +{ + char *name = xstrdup (command); + if (strlen (name) >= strlen ("index")) + name[strlen (name) - strlen ("index")] = 0; + index_add_arg (name); + free (name); +} + +/* Define an index known as NAME. We assign the slot number. + If CODE is nonzero, make this a code index. */ +static void +defindex (name, code) + char *name; + int code; +{ + int i, slot; + + /* If it already exists, flush it. */ + undefindex (name); + + /* Try to find an empty slot. */ + slot = -1; + for (i = 0; i < defined_indices; i++) + if (!name_index_alist[i]) + { + slot = i; + break; + } + + if (slot < 0) + { /* No such luck. Make space for another index. */ + slot = defined_indices; + defined_indices++; + + name_index_alist = (INDEX_ALIST **) + xrealloc (name_index_alist, (1 + defined_indices) + * sizeof (INDEX_ALIST *)); + the_indices = (INDEX_ELT **) + xrealloc (the_indices, (1 + defined_indices) * sizeof (INDEX_ELT *)); + } + + /* We have a slot. Start assigning. */ + name_index_alist[slot] = xmalloc (sizeof (INDEX_ALIST)); + name_index_alist[slot]->name = xstrdup (name); + name_index_alist[slot]->read_index = slot; + name_index_alist[slot]->write_index = slot; + name_index_alist[slot]->code = code; + + the_indices[slot] = NULL; +} + +/* Define an index NAME, implicitly @code if CODE is nonzero. */ +static void +top_defindex (name, code) + char *name; + int code; +{ + char *temp; + + temp = xmalloc (1 + strlen (name) + strlen ("index")); + sprintf (temp, "%sindex", name); + define_user_command (temp, gen_index, 0); + defindex (name, code); + free (temp); +} + +/* Set up predefined indices. */ +void +init_indices () +{ + int i; + + /* Create the default data structures. */ + + /* Initialize data space. */ + if (!the_indices) + { + the_indices = xmalloc ((1 + defined_indices) * sizeof (INDEX_ELT *)); + the_indices[defined_indices] = NULL; + + name_index_alist = xmalloc ((1 + defined_indices) + * sizeof (INDEX_ALIST *)); + name_index_alist[defined_indices] = NULL; + } + + /* If there were existing indices, get rid of them now. */ + for (i = 0; i < defined_indices; i++) + { + undefindex (name_index_alist[i]->name); + if (name_index_alist[i]) + { /* Suppose we're called with two input files, and the first + does a @synindex pg cp. Then, when we get here to start + the second file, the "pg" element won't get freed by + undefindex (because it's pointing to "cp"). So free it + here; otherwise, when we try to define the pg index again + just below, it will still point to cp. */ + free (name_index_alist[i]->name); + free (name_index_alist[i]); + name_index_alist[i] = NULL; + } + } + + /* Add the default indices. */ + top_defindex ("cp", 0); /* cp is the only non-code index. */ + top_defindex ("fn", 1); + top_defindex ("ky", 1); + top_defindex ("pg", 1); + top_defindex ("tp", 1); + top_defindex ("vr", 1); +} + +/* Given an index name, return the offset in the_indices of this index, + or -1 if there is no such index. */ +int +translate_index (name) + char *name; +{ + INDEX_ALIST *which = find_index (name); + + if (which) + return which->read_index; + else + return -1; +} + +/* Return the index list which belongs to NAME. */ +INDEX_ELT * +index_list (name) + char *name; +{ + int which = translate_index (name); + if (which < 0) + return (INDEX_ELT *) -1; + else + return the_indices[which]; +} + +/* Define a new index command. Arg is name of index. */ +static void +gen_defindex (code) + int code; +{ + char *name; + get_rest_of_line (0, &name); + + if (find_index (name)) + { + line_error (_("Index `%s' already exists"), name); + } + else + { + char *temp = xmalloc (strlen (name) + sizeof ("index")); + sprintf (temp, "%sindex", name); + define_user_command (temp, gen_index, 0); + defindex (name, code); + free (temp); + } + + free (name); +} + +void +cm_defindex () +{ + gen_defindex (0); +} + +void +cm_defcodeindex () +{ + gen_defindex (1); +} + +/* Expects 2 args, on the same line. Both are index abbreviations. + Make the first one be a synonym for the second one, i.e. make the + first one have the same index as the second one. */ +void +cm_synindex () +{ + int source, target; + char *abbrev1, *abbrev2; + + skip_whitespace (); + get_until_in_line (0, " ", &abbrev1); + target = find_index_offset (abbrev1); + skip_whitespace (); + get_until_in_line (0, " ", &abbrev2); + source = find_index_offset (abbrev2); + if (source < 0 || target < 0) + { + line_error (_("Unknown index `%s' and/or `%s' in @synindex"), + abbrev1, abbrev2); + } + else + { + name_index_alist[target]->write_index + = name_index_alist[source]->write_index; + } + + free (abbrev1); + free (abbrev2); +} + +void +cm_pindex () /* Pinhead index. */ +{ + index_add_arg ("pg"); +} + +void +cm_vindex () /* Variable index. */ +{ + index_add_arg ("vr"); +} + +void +cm_kindex () /* Key index. */ +{ + index_add_arg ("ky"); +} + +void +cm_cindex () /* Concept index. */ +{ + index_add_arg ("cp"); +} + +void +cm_findex () /* Function index. */ +{ + index_add_arg ("fn"); +} + +void +cm_tindex () /* Data Type index. */ +{ + index_add_arg ("tp"); +} + +int +index_element_compare (element1, element2) + INDEX_ELT **element1, **element2; +{ + return index_compare_fn ((*element1)->entry, (*element2)->entry); +} + +/* Force all index entries to be unique. */ +void +make_index_entries_unique (array, count) + INDEX_ELT **array; + int count; +{ + int i, j; + INDEX_ELT **copy; + int counter = 1; + + copy = xmalloc ((1 + count) * sizeof (INDEX_ELT *)); + + for (i = 0, j = 0; i < count; i++) + { + if (i == (count - 1) + || array[i]->node != array[i + 1]->node + || !STREQ (array[i]->entry, array[i + 1]->entry)) + copy[j++] = array[i]; + else + { + free (array[i]->entry); + free (array[i]->entry_text); + free (array[i]); + } + } + copy[j] = NULL; + + /* Now COPY contains only unique entries. Duplicated entries in the + original array have been freed. Replace the current array with + the copy, fixing the NEXT pointers. */ + for (i = 0; copy[i]; i++) + { + copy[i]->next = copy[i + 1]; + + /* Fix entry names which are the same. They point to different nodes, + so we make the entry name unique. */ + if (copy[i+1] + && STREQ (copy[i]->entry, copy[i + 1]->entry) + && !html) + { + char *new_entry_name; + + new_entry_name = xmalloc (10 + strlen (copy[i]->entry)); + sprintf (new_entry_name, "%s <%d>", copy[i]->entry, counter); + free (copy[i]->entry); + copy[i]->entry = new_entry_name; + counter++; + } + else + counter = 1; + + array[i] = copy[i]; + } + array[i] = NULL; + + /* Free the storage used only by COPY. */ + free (copy); +} + +/* Sort the index passed in INDEX, returning an array of + pointers to elements. The array is terminated with a NULL + pointer. We call qsort because it's supposed to be fast. + I think this looks bad. */ +INDEX_ELT ** +sort_index (index) + INDEX_ELT *index; +{ + INDEX_ELT **array; + INDEX_ELT *temp = index; + int count = 0; + int save_line_number = line_number; + char *save_input_filename = input_filename; + int save_html = html; + + /* Pretend we are in non-HTML mode, for the purpose of getting the + expanded index entry that lacks any markup and other HTML escape + characters which could produce a wrong sort order. */ + /* fixme: html: this still causes some markup, such as non-ASCII + characters @AE{} etc., to sort incorrectly. */ + html = 0; + + while (temp) + { + count++; + temp = temp->next; + } + + /* We have the length. Make an array. */ + + array = xmalloc ((count + 1) * sizeof (INDEX_ELT *)); + count = 0; + temp = index; + + while (temp) + { + array[count++] = temp; + + /* Set line number and input filename to the source line for this + index entry, as this expansion finds any errors. */ + line_number = array[count - 1]->defining_line; + input_filename = array[count - 1]->defining_file; + + /* If this particular entry should be printed as a "code" index, + then expand it as @code{entry}, i.e. as in fixed-width font. */ + array[count-1]->entry = expansion (temp->entry_text, + array[count-1]->code); + + temp = temp->next; + } + array[count] = NULL; /* terminate the array. */ + line_number = save_line_number; + input_filename = save_input_filename; + html = save_html; + +#ifdef HAVE_STRCOLL + /* This is not perfect. We should set (then restore) the locale to the + documentlanguage, so strcoll operates according to the document's + locale, not the user's. For now, I'm just going to assume that + those few new documents which use @documentlanguage will be + processed in the appropriate locale. In any case, don't use + strcoll in the C (aka POSIX) locale, that is the ASCII ordering. */ + if (language_code != en) + { + char *lang_env = getenv ("LANG"); + if (lang_env && !STREQ (lang_env, "C") && !STREQ (lang_env, "POSIX")) + index_compare_fn = strcoll; + } +#endif /* HAVE_STRCOLL */ + + /* Sort the array. */ + qsort (array, count, sizeof (INDEX_ELT *), index_element_compare); + make_index_entries_unique (array, count); + return array; +} + +/* Nonzero means that we are in the middle of printing an index. */ +int printing_index = 0; + +/* Takes one arg, a short name of an index to print. + Outputs a menu of the sorted elements of the index. */ +void +cm_printindex () +{ + int item; + INDEX_ELT *index; + INDEX_ELT *last_index = 0; + INDEX_ELT **array; + char *index_name; + unsigned line_length; + char *line; + int saved_inhibit_paragraph_indentation = inhibit_paragraph_indentation; + int saved_filling_enabled = filling_enabled; + int saved_line_number = line_number; + char *saved_input_filename = input_filename; + + close_paragraph (); + get_rest_of_line (0, &index_name); + + index = index_list (index_name); + if (index == (INDEX_ELT *)-1) + { + line_error (_("Unknown index `%s' in @printindex"), index_name); + free (index_name); + return; + } + + /* Do this before sorting, so execute_string in index_element_compare + will give the same results as when we actually print. */ + printing_index = 1; + filling_enabled = 0; + inhibit_paragraph_indentation = 1; + array = sort_index (index); + + close_paragraph (); + if (html) + add_word ("<ul compact>"); + else if (!no_headers) + add_word ("* Menu:\n\n"); + + me_inhibit_expansion++; + + /* This will probably be enough. */ + line_length = 100; + line = xmalloc (line_length); + + for (item = 0; (index = array[item]); item++) + { + /* A pathological document might have an index entry outside of any + node. Don't crash; try using the section name instead. */ + char *index_node = index->node; + + line_number = index->defining_line; + input_filename = index->defining_file; + + if ((!index_node || !*index_node) && html) + index_node = toc_find_section_of_node (index_node); + + if (!index_node || !*index_node) + { + line_error (_("Entry for index `%s' outside of any node"), + index_name); + if (html || !no_headers) + index_node = _("(outside of any node)"); + } + + if (html) + /* fixme: html: we should use specific index anchors pointing + to the actual location of the indexed position (but then we + have to find something to wrap the anchor around). */ + { + if (last_index + && STREQ (last_index->entry_text, index->entry_text)) + add_word (", "); /* Don't repeat the previous entry. */ + else + { + /* In the HTML case, the expanded index entry is not + good for us, since it was expanded for non-HTML mode + inside sort_index. So we need to HTML-escape and + expand the original entry text here. */ + char *escaped_entry = xstrdup (index->entry_text); + char *expanded_entry; + + /* expansion() doesn't HTML-escape the argument, so need + to do it separately. */ + escaped_entry = escape_string (escaped_entry); + expanded_entry = expansion (escaped_entry, index->code); + add_word_args ("\n<li>%s: ", expanded_entry); + free (escaped_entry); + free (expanded_entry); + } + add_word ("<a href=\""); + if (index->node && *index->node) + { + /* Make sure any non-macros in the node name are expanded. */ + in_fixed_width_font++; + index_node = expansion (index_node, 0); + in_fixed_width_font--; + add_anchor_name (index_node, 1); + add_word_args ("\">%s</a>", index_node); + free (index_node); + } + else if (STREQ (index_node, _("(outside of any node)"))) + { + add_anchor_name (index_node, 1); + add_word_args ("\">%s</a>", index_node); + } + else + /* If we use the section instead of the (missing) node, then + index_node already includes all we need except the #. */ + add_word_args ("#%s</a>", index_node); + } + else + { + unsigned new_length = strlen (index->entry); + + if (new_length < 50) /* minimum length used below */ + new_length = 50; + new_length += strlen (index_node) + 7; /* * : .\n\0 */ + + if (new_length > line_length) + { + line_length = new_length; + line = xrealloc (line, line_length); + } + /* Print the entry, nicely formatted. We've already + expanded any commands in index->entry, including any + implicit @code. Thus, can't call execute_string, since + @@ has turned into @. */ + if (!no_headers) + { + sprintf (line, "* %-37s ", index->entry); + line[2 + strlen (index->entry)] = ':'; + insert_string (line); + /* Make sure any non-macros in the node name are expanded. */ + in_fixed_width_font++; + execute_string ("%s.\n", index_node); + in_fixed_width_font--; + } + else + { + /* With --no-headers, the @node lines are gone, so + there's little sense in referring to them in the + index. Instead, output the number or name of the + section that corresponds to that node. */ + char *section_name = toc_find_section_of_node (index_node); + + sprintf (line, "%-*s ", number_sections ? 50 : 1, index->entry); + line[strlen (index->entry)] = ':'; + insert_string (line); + if (section_name) + { + int idx = 0; + unsigned ref_len = strlen (section_name) + 30; + + if (ref_len > line_length) + { + line_length = ref_len; + line = xrealloc (line, line_length); + } + + if (number_sections) + { + while (section_name[idx] + && (isdigit (section_name[idx]) + || (idx && section_name[idx] == '.'))) + idx++; + } + if (idx) + sprintf (line, " See %.*s.\n", idx, section_name); + else + sprintf (line, "\n See ``%s''.\n", section_name); + insert_string (line); + } + else + { + insert_string (" "); /* force a blank */ + execute_string ("See node %s.\n", index_node); + } + } + } + + /* Prevent `output_paragraph' from growing to the size of the + whole index. */ + flush_output (); + last_index = index; + } + + free (line); + free (index_name); + + me_inhibit_expansion--; + + printing_index = 0; + free (array); + close_single_paragraph (); + filling_enabled = saved_filling_enabled; + inhibit_paragraph_indentation = saved_inhibit_paragraph_indentation; + input_filename = saved_input_filename; + line_number = saved_line_number; + + if (html) + add_word ("</ul>"); +} diff --git a/contrib/texinfo/makeinfo/index.h b/contrib/texinfo/makeinfo/index.h new file mode 100644 index 0000000..ed8583a --- /dev/null +++ b/contrib/texinfo/makeinfo/index.h @@ -0,0 +1,36 @@ +/* index.h -- declarations for index.c. + $Id: index.h,v 1.4 1999/04/19 18:12:17 karl Exp $ + + Copyright (C) 1998, 99 Free Software Foundation, Inc. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software Foundation, + Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ + +#ifndef INDEX_H +#define INDEX_H + +#include "makeinfo.h" +#include "cmds.h" + +/* User commands are only new indices. (Macros are handled separately.) */ +extern COMMAND **user_command_array; +extern int user_command_array_len; + +/* Initialize all indices. */ +extern void init_indices (); + +/* Function to compare index entries for sorting. */ +extern int (*index_compare_fn) (); + +#endif /* !INDEX_H */ diff --git a/contrib/texinfo/makeinfo/insertion.c b/contrib/texinfo/makeinfo/insertion.c new file mode 100644 index 0000000..11b9089 --- /dev/null +++ b/contrib/texinfo/makeinfo/insertion.c @@ -0,0 +1,1368 @@ +/* insertion.c -- insertions for Texinfo. + $Id: insertion.c,v 1.27 1999/07/06 23:12:53 karl Exp $ + + Copyright (C) 1998, 99 Free Software Foundation, Inc. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software Foundation, + Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ + +#include "system.h" +#include "cmds.h" +#include "defun.h" +#include "insertion.h" +#include "macro.h" +#include "makeinfo.h" + +/* Must match list in insertion.h. */ +static char *insertion_type_names[] = +{ + "cartouche", "defcv", "deffn", "defivar", "defmac", "defmethod", + "defop", "defopt", "defspec", "deftp", "deftypefn", "deftypefun", + "deftypeivar", "deftypemethod", "deftypeop", "deftypevar", + "deftypevr", "defun", "defvar", "defvr", "detailmenu", "direntry", + "display", "enumerate", "example", "flushleft", "flushright", + "format", "ftable", "group", "ifclear", "ifhtml", "ifinfo", + "ifnothtml", "ifnotinfo", "ifnottex", "ifset", "iftex", "itemize", + "lisp", "menu", "multitable", "quotation", "rawhtml", "rawtex", + "smalldisplay", "smallexample", "smallformat", "smalllisp", "table", + "tex", "vtable", "bad_type" +}; + +/* All nested environments. */ +INSERTION_ELT *insertion_stack = NULL; + +/* How deeply we're nested. */ +int insertion_level = 0; + +/* Whether to examine menu lines. */ +int in_menu = 0; + +/* How to examine menu lines. */ +int in_detailmenu = 0; + +/* Set to 1 if we've processed (commentary) text in a @menu that + wasn't part of a menu item. */ +int had_menu_commentary; + +/* Set to 1 if <p> is written in normal context. + Used for menu and itemize. */ +int in_paragraph = 0; + +static const char dl_tag[] = "<dl>\n"; + +void +init_insertion_stack () +{ + insertion_stack = NULL; +} + +/* Return the type of the current insertion. */ +static enum insertion_type +current_insertion_type () +{ + return insertion_level ? insertion_stack->insertion : bad_type; +} + +/* Return the string which is the function to wrap around items, or NULL + if we're not in an environment where @item is ok. */ +static char * +current_item_function () +{ + int done = 0; + INSERTION_ELT *elt = insertion_stack; + + /* Skip down through the stack until we find an insertion with an + itemize function defined, i.e., skip conditionals, @cartouche, etc. */ + while (!done && elt) + { + switch (elt->insertion) + { + /* This list should match the one in cm_item. */ + case ifclear: + case ifhtml: + case ifinfo: + case ifnothtml: + case ifnotinfo: + case ifnottex: + case ifset: + case iftex: + case rawhtml: + case rawtex: + case tex: + case cartouche: + elt = elt->next; + break; + + default: + done = 1; + } + } + + /* item_function usually gets assigned the empty string. */ + return done && (*elt->item_function) ? elt->item_function : NULL; +} + +/* Parse the item marker function off the input. If result is just "@", + change it to "@ ", since "@" by itself is not a command. This makes + "@ ", "@\t", and "@\n" all the same, but their default meanings are + the same anyway, and let's not worry about supporting redefining them. */ +char * +get_item_function () +{ + char *item_function; + get_rest_of_line (0, &item_function); + + /* If we hit the end of text in get_rest_of_line, backing up + input pointer will cause the last character of the last line + be pushed back onto the input, which is wrong. */ + if (input_text_offset < input_text_length) + backup_input_pointer (); + + if (STREQ (item_function, "@")) + { + free (item_function); + item_function = xstrdup ("@ "); + } + + return item_function; +} + + /* Push the state of the current insertion on the stack. */ +void +push_insertion (type, item_function) + enum insertion_type type; + char *item_function; +{ + INSERTION_ELT *new = xmalloc (sizeof (INSERTION_ELT)); + + new->item_function = item_function; + new->filling_enabled = filling_enabled; + new->indented_fill = indented_fill; + new->insertion = type; + new->line_number = line_number; + new->filename = xstrdup (input_filename); + new->inhibited = inhibit_paragraph_indentation; + new->in_fixed_width_font = in_fixed_width_font; + new->next = insertion_stack; + insertion_stack = new; + insertion_level++; +} + + /* Pop the value on top of the insertion stack into the + global variables. */ +void +pop_insertion () +{ + INSERTION_ELT *temp = insertion_stack; + + if (temp == NULL) + return; + + in_fixed_width_font = temp->in_fixed_width_font; + inhibit_paragraph_indentation = temp->inhibited; + filling_enabled = temp->filling_enabled; + indented_fill = temp->indented_fill; + free_and_clear (&(temp->item_function)); + free_and_clear (&(temp->filename)); + insertion_stack = insertion_stack->next; + free (temp); + insertion_level--; +} + + /* Return a pointer to the print name of this + enumerated type. */ +char * +insertion_type_pname (type) + enum insertion_type type; +{ + if ((int) type < (int) bad_type) + return insertion_type_names[(int) type]; + else + return _("Broken-Type in insertion_type_pname"); +} + +/* Return the insertion_type associated with NAME. + If the type is not one of the known ones, return BAD_TYPE. */ +enum insertion_type +find_type_from_name (name) + char *name; +{ + int index = 0; + while (index < (int) bad_type) + { + if (STREQ (name, insertion_type_names[index])) + return (enum insertion_type) index; + if (index == rawhtml && STREQ (name, "html")) + return rawhtml; + if (index == rawtex && STREQ (name, "tex")) + return rawtex; + index++; + } + return bad_type; +} + +int +defun_insertion (type) + enum insertion_type type; +{ + return 0 + || (type == defcv) + || (type == deffn) + || (type == defivar) + || (type == defmac) + || (type == defmethod) + || (type == defop) + || (type == defopt) + || (type == defspec) + || (type == deftp) + || (type == deftypefn) + || (type == deftypefun) + || (type == deftypeivar) + || (type == deftypemethod) + || (type == deftypeop) + || (type == deftypevar) + || (type == deftypevr) + || (type == defun) + || (type == defvar) + || (type == defvr) + ; +} + +/* MAX_NS is the maximum nesting level for enumerations. I picked 100 + which seemed reasonable. This doesn't control the number of items, + just the number of nested lists. */ +#define max_stack_depth 100 +#define ENUM_DIGITS 1 +#define ENUM_ALPHA 2 +typedef struct { + int enumtype; + int enumval; +} DIGIT_ALPHA; + +DIGIT_ALPHA enumstack[max_stack_depth]; +int enumstack_offset = 0; +int current_enumval = 1; +int current_enumtype = ENUM_DIGITS; +char *enumeration_arg = NULL; + +void +start_enumerating (at, type) + int at, type; +{ + if ((enumstack_offset + 1) == max_stack_depth) + { + line_error (_("Enumeration stack overflow")); + return; + } + enumstack[enumstack_offset].enumtype = current_enumtype; + enumstack[enumstack_offset].enumval = current_enumval; + enumstack_offset++; + current_enumval = at; + current_enumtype = type; +} + +void +stop_enumerating () +{ + --enumstack_offset; + if (enumstack_offset < 0) + enumstack_offset = 0; + + current_enumval = enumstack[enumstack_offset].enumval; + current_enumtype = enumstack[enumstack_offset].enumtype; +} + +/* Place a letter or digits into the output stream. */ +void +enumerate_item () +{ + char temp[10]; + + if (current_enumtype == ENUM_ALPHA) + { + if (current_enumval == ('z' + 1) || current_enumval == ('Z' + 1)) + { + current_enumval = ((current_enumval - 1) == 'z' ? 'a' : 'A'); + warning (_("lettering overflow, restarting at %c"), current_enumval); + } + sprintf (temp, "%c. ", current_enumval); + } + else + sprintf (temp, "%d. ", current_enumval); + + indent (output_column += (current_indent - strlen (temp))); + add_word (temp); + current_enumval++; +} + +static void +enum_html () +{ + char type; + int start; + + if (isdigit (*enumeration_arg)) + { + type = '1'; + start = atoi (enumeration_arg); + } + else if (isupper (*enumeration_arg)) + { + type = 'A'; + start = *enumeration_arg - 'A' + 1; + } + else + { + type = 'a'; + start = *enumeration_arg - 'a' + 1; + } + + add_word_args ("<ol type=%c start=%d>\n", type, start); +} + +/* Conditionally parse based on the current command name. */ +void +command_name_condition () +{ + char *discarder = xmalloc (8 + strlen (command)); + + sprintf (discarder, "\n%cend %s", COMMAND_PREFIX, command); + discard_until (discarder); + discard_until ("\n"); + + free (discarder); +} + +/* This is where the work for all the "insertion" style + commands is done. A huge switch statement handles the + various setups, and generic code is on both sides. */ +void +begin_insertion (type) + enum insertion_type type; +{ + int no_discard = 0; + + if (defun_insertion (type)) + { + push_insertion (type, xstrdup ("")); + no_discard++; + } + else + push_insertion (type, get_item_function ()); + + switch (type) + { + case menu: + if (!no_headers) + close_paragraph (); + + filling_enabled = no_indent = 0; + inhibit_paragraph_indentation = 1; + + if (html) + { + had_menu_commentary = 1; + } + else if (!no_headers) + add_word ("* Menu:\n"); + + in_menu++; + in_fixed_width_font++; + no_discard++; + break; + + case detailmenu: + if (!in_menu) + { + if (!no_headers) + close_paragraph (); + + filling_enabled = no_indent = 0; + inhibit_paragraph_indentation = 1; + + no_discard++; + } + + in_fixed_width_font++; + in_detailmenu++; + break; + + case direntry: + if (html) + command_name_condition (); + else + { + close_single_paragraph (); + filling_enabled = no_indent = 0; + inhibit_paragraph_indentation = 1; + insert_string ("START-INFO-DIR-ENTRY\n"); + } + break; + + case quotation: + /* @quotation does filling (@display doesn't). */ + if (html) + add_word ("<blockquote>\n"); + else + { + close_single_paragraph (); + last_char_was_newline = no_indent = 0; + indented_fill = filling_enabled = 1; + inhibit_paragraph_indentation = 1; + } + current_indent += default_indentation_increment; + break; + + case display: + case smalldisplay: + case example: + case smallexample: + case lisp: + case smalllisp: + /* Like @display but without indentation. */ + case smallformat: + case format: + close_single_paragraph (); + inhibit_paragraph_indentation = 1; + in_fixed_width_font++; + filling_enabled = 0; + last_char_was_newline = 0; + + if (html) + /* Kludge alert: if <pre> is followed by a newline, IE3 + renders an extra blank line before the pre-formatted block. + Other browsers seem to not mind one way or the other. */ + add_word ("<pre>"); + + if (type != format && type != smallformat) + current_indent += default_indentation_increment; + break; + + case multitable: + do_multitable (); + break; + + case table: + case ftable: + case vtable: + case itemize: + close_single_paragraph (); + current_indent += default_indentation_increment; + filling_enabled = indented_fill = 1; +#if defined (INDENT_PARAGRAPHS_IN_TABLE) + inhibit_paragraph_indentation = 0; +#else + inhibit_paragraph_indentation = 1; +#endif /* !INDENT_PARAGRAPHS_IN_TABLE */ + + /* Make things work for losers who forget the itemize syntax. */ + if (type == itemize) + { + if (!(*insertion_stack->item_function)) + { + free (insertion_stack->item_function); + insertion_stack->item_function = xstrdup ("@bullet"); + } + } + + if (!*insertion_stack->item_function) + { + line_error (_("%s requires an argument: the formatter for %citem"), + insertion_type_pname (type), COMMAND_PREFIX); + } + + if (html) + { + if (type == itemize) + { + add_word ("<ul>\n"); + in_paragraph = 0; + } + else + add_word (dl_tag); + } + break; + + case enumerate: + close_single_paragraph (); + no_indent = 0; +#if defined (INDENT_PARAGRAPHS_IN_TABLE) + inhibit_paragraph_indentation = 0; +#else + inhibit_paragraph_indentation = 1; +#endif /* !INDENT_PARAGRAPHS_IN_TABLE */ + + current_indent += default_indentation_increment; + filling_enabled = indented_fill = 1; + + if (html) + enum_html (); + + if (isdigit (*enumeration_arg)) + start_enumerating (atoi (enumeration_arg), ENUM_DIGITS); + else + start_enumerating (*enumeration_arg, ENUM_ALPHA); + break; + + /* @group does nothing special in makeinfo. */ + case group: + /* Only close the paragraph if we are not inside of an + @example-like environment. */ + if (!insertion_stack->next + || (insertion_stack->next->insertion != display + && insertion_stack->next->insertion != smalldisplay + && insertion_stack->next->insertion != example + && insertion_stack->next->insertion != smallexample + && insertion_stack->next->insertion != lisp + && insertion_stack->next->insertion != smalllisp + && insertion_stack->next->insertion != format + && insertion_stack->next->insertion != smallformat + && insertion_stack->next->insertion != flushleft + && insertion_stack->next->insertion != flushright)) + close_single_paragraph (); + break; + + /* Insertions that are no-ops in info, but do something in TeX. */ + case cartouche: + case ifclear: + case ifhtml: + case ifinfo: + case ifnothtml: + case ifnotinfo: + case ifnottex: + case ifset: + case iftex: + case rawtex: + if (in_menu) + no_discard++; + break; + + case rawhtml: + escape_html = 0; + break; + + case defcv: + case deffn: + case defivar: + case defmac: + case defmethod: + case defop: + case defopt: + case defspec: + case deftp: + case deftypefn: + case deftypefun: + case deftypeivar: + case deftypemethod: + case deftypeop: + case deftypevar: + case deftypevr: + case defun: + case defvar: + case defvr: + inhibit_paragraph_indentation = 1; + filling_enabled = indented_fill = 1; + current_indent += default_indentation_increment; + no_indent = 0; + break; + + case flushleft: + close_single_paragraph (); + inhibit_paragraph_indentation = 1; + filling_enabled = indented_fill = no_indent = 0; + break; + + case flushright: + close_single_paragraph (); + filling_enabled = indented_fill = no_indent = 0; + inhibit_paragraph_indentation = 1; + force_flush_right++; + break; + + default: + line_error ("begin_insertion internal error: type=%d", type); + + } + + if (!no_discard) + discard_until ("\n"); +} + +/* Try to end the insertion with the specified TYPE. With a value of + `bad_type', TYPE gets translated to match the value currently on top + of the stack. Otherwise, if TYPE doesn't match the top of the + insertion stack, give error. */ +void +end_insertion (type) + enum insertion_type type; +{ + enum insertion_type temp_type; + + if (!insertion_level) + return; + + temp_type = current_insertion_type (); + + if (type == bad_type) + type = temp_type; + + if (type != temp_type) + { + line_error + (_("`@end' expected `%s', but saw `%s'"), + insertion_type_pname (temp_type), insertion_type_pname (type)); + return; + } + + pop_insertion (); + + switch (type) + { + /* Insertions which have no effect on paragraph formatting. */ + case ifclear: + case ifhtml: + case ifinfo: + case ifnothtml: + case ifnotinfo: + case ifnottex: + case ifset: + case iftex: + case rawtex: + break; + + case rawhtml: + escape_html = 1; + break; + + case direntry: /* Eaten if html. */ + insert_string ("END-INFO-DIR-ENTRY\n\n"); + close_insertion_paragraph (); + break; + + case detailmenu: + in_detailmenu--; /* No longer hacking menus. */ + if (!in_menu) + { + if (!no_headers) + close_insertion_paragraph (); + } + break; + + case menu: + in_menu--; /* No longer hacking menus. */ + if (html) + add_word ("</ul>\n"); + else if (!no_headers) + close_insertion_paragraph (); + break; + + case multitable: + end_multitable (); + break; + + case enumerate: + stop_enumerating (); + close_insertion_paragraph (); + current_indent -= default_indentation_increment; + if (html) + add_word ("</ol>\n"); + break; + + case flushleft: + case group: + case cartouche: + close_insertion_paragraph (); + break; + + case format: + case smallformat: + case display: + case smalldisplay: + case example: + case smallexample: + case lisp: + case smalllisp: + case quotation: + /* @format and @smallformat are the only fixed_width insertion + without a change in indentation. */ + if (type != format && type != smallformat) + current_indent -= default_indentation_increment; + + if (html) + add_word (type == quotation ? "</blockquote>\n" : "</pre>\n"); + + /* The ending of one of these insertions always marks the + start of a new paragraph. */ + close_insertion_paragraph (); + break; + + case table: + case ftable: + case vtable: + current_indent -= default_indentation_increment; + if (html) + add_word ("</dl>\n"); + break; + + case itemize: + current_indent -= default_indentation_increment; + if (html) + add_word ("</ul>\n"); + close_insertion_paragraph (); + break; + + case flushright: + force_flush_right--; + close_insertion_paragraph (); + break; + + /* Handle the @defun insertions with this default clause. */ + default: + { + enum insertion_type base_type; + + if (type < defcv || type > defvr) + line_error ("end_insertion internal error: type=%d", type); + + base_type = get_base_type (type); + switch (base_type) + { + case deffn: + case defvr: + case deftp: + case deftypefn: + case deftypevr: + case defcv: + case defop: + case deftypemethod: + case deftypeop: + case deftypeivar: + if (html) + /* close the tables which has been opened in defun.c */ + add_word ("</TD></TR>\n</TABLE>\n"); + break; + } /* switch (base_type)... */ + + current_indent -= default_indentation_increment; + close_insertion_paragraph (); + } + break; + + } + + if (current_indent < 0) + line_error ("end_insertion internal error: current indent=%d", + current_indent); +} + +/* Insertions cannot cross certain boundaries, such as node beginnings. In + code that creates such boundaries, you should call `discard_insertions' + before doing anything else. It prints the errors for you, and cleans up + the insertion stack. + + With nonzero SPECIALS_OK argument, allows unmatched + @if... conditionals, otherwise not. This is because conditionals can + cross node boundaries. Always happens with the @top node, for example. */ +void +discard_insertions (specials_ok) + int specials_ok; +{ + int real_line_number = line_number; + while (insertion_stack) + { + if (specials_ok + && ((ifclear <= insertion_stack->insertion + && insertion_stack->insertion <= iftex) + || insertion_stack->insertion == rawhtml + || insertion_stack->insertion == rawtex)) + break; + else + { + char *offender = insertion_type_pname (insertion_stack->insertion); + char *current_filename = input_filename; + + input_filename = insertion_stack->filename; + line_number = insertion_stack->line_number; + line_error (_("No matching `%cend %s'"), COMMAND_PREFIX, offender); + input_filename = current_filename; + pop_insertion (); + } + } + line_number = real_line_number; +} + +/* Insertion (environment) commands. */ + +void +cm_quotation () +{ + begin_insertion (quotation); +} + +void +cm_example () +{ + begin_insertion (example); +} + +void +cm_smallexample () +{ + begin_insertion (smallexample); +} + +void +cm_lisp () +{ + begin_insertion (lisp); +} + +void +cm_smalllisp () +{ + begin_insertion (smalllisp); +} + +/* @cartouche/@end cartouche draws box with rounded corners in + TeX output. Right now, just a no-op insertion. */ +void +cm_cartouche () +{ + begin_insertion (cartouche); +} + +void +cm_format () +{ + begin_insertion (format); +} + +void +cm_smallformat () +{ + begin_insertion (smallformat); +} + +void +cm_display () +{ + begin_insertion (display); +} + +void +cm_smalldisplay () +{ + begin_insertion (smalldisplay); +} + +void +cm_direntry () +{ + if (no_headers || html) + command_name_condition (); + else + begin_insertion (direntry); +} + +void +cm_itemize () +{ + begin_insertion (itemize); +} + +/* Start an enumeration insertion of type TYPE. If the user supplied + no argument on the line, then use DEFAULT_STRING as the initial string. */ +static void +do_enumeration (type, default_string) + int type; + char *default_string; +{ + get_until_in_line (0, ".", &enumeration_arg); + canon_white (enumeration_arg); + + if (!*enumeration_arg) + { + free (enumeration_arg); + enumeration_arg = xstrdup (default_string); + } + + if (!isdigit (*enumeration_arg) && !isletter (*enumeration_arg)) + { + warning (_("%s requires letter or digit"), insertion_type_pname (type)); + + switch (type) + { + case enumerate: + default_string = "1"; + break; + } + enumeration_arg = xstrdup (default_string); + } + begin_insertion (type); +} + +void +cm_enumerate () +{ + do_enumeration (enumerate, "1"); +} + +void +cm_table () +{ + begin_insertion (table); +} + +void +cm_multitable () +{ + begin_insertion (multitable); /* @@ */ +} + +void +cm_ftable () +{ + begin_insertion (ftable); +} + +void +cm_vtable () +{ + begin_insertion (vtable); +} + +void +cm_group () +{ + begin_insertion (group); +} + +void +cm_ifinfo () +{ + if (process_info) + begin_insertion (ifinfo); + else + command_name_condition (); +} + +void +cm_ifnotinfo () +{ + if (!process_info) + begin_insertion (ifnotinfo); + else + command_name_condition (); +} + + +/* Insert raw HTML (no escaping of `<' etc.). */ +void +cm_html () +{ + if (process_html) + begin_insertion (rawhtml); + else + command_name_condition (); +} + +void +cm_ifhtml () +{ + if (process_html) + begin_insertion (ifhtml); + else + command_name_condition (); +} + +void +cm_ifnothtml () +{ + if (!process_html) + begin_insertion (ifnothtml); + else + command_name_condition (); +} + + +void +cm_tex () +{ + if (process_tex) + begin_insertion (rawtex); + else + command_name_condition (); +} + +void +cm_iftex () +{ + if (process_tex) + begin_insertion (iftex); + else + command_name_condition (); +} + +void +cm_ifnottex () +{ + if (!process_tex) + begin_insertion (ifnottex); + else + command_name_condition (); +} + +/* Begin an insertion where the lines are not filled or indented. */ +void +cm_flushleft () +{ + begin_insertion (flushleft); +} + +/* Begin an insertion where the lines are not filled, and each line is + forced to the right-hand side of the page. */ +void +cm_flushright () +{ + begin_insertion (flushright); +} + +void +cm_menu () +{ + if (current_node == NULL) + { + warning (_("@menu seen before first @node, creating `Top' node")); + warning (_("perhaps your @top node should be wrapped in @ifnottex rather than @ifinfo?")); + /* Include @top command so we can construct the implicit node tree. */ + execute_string ("@node top\n@top Top\n"); + } + begin_insertion (menu); +} + +void +cm_detailmenu () +{ + if (current_node == NULL) + { /* Problems anyway, @detailmenu should always be inside @menu. */ + warning (_("@detailmenu seen before first node, creating `Top' node")); + execute_string ("@node top\n@top Top\n"); + } + begin_insertion (detailmenu); +} + +/* End existing insertion block. */ +void +cm_end () +{ + char *temp; + enum insertion_type type; + + if (!insertion_level) + { + line_error (_("Unmatched `%c%s'"), COMMAND_PREFIX, command); + return; + } + + get_rest_of_line (0, &temp); + + if (temp[0] == 0) + line_error (_("`%c%s' needs something after it"), COMMAND_PREFIX, command); + + type = find_type_from_name (temp); + + if (type == bad_type) + { + line_error (_("Bad argument to `%s', `%s', using `%s'"), + command, temp, insertion_type_pname (current_insertion_type ())); + } + end_insertion (type); + free (temp); +} + +/* @itemx, @item. */ + +static int itemx_flag = 0; + +/* Return whether CMD takes a brace-delimited {arg}. */ +static int +command_needs_braces (cmd) + char *cmd; +{ + int i; + for (i = 0; command_table[i].name; i++) + { + if (STREQ (command_table[i].name, cmd)) + return command_table[i].argument_in_braces == BRACE_ARGS; + } + + return 0; /* macro or alias */ +} + + +void +cm_item () +{ + char *rest_of_line, *item_func; + + /* Can only hack "@item" while inside of an insertion. */ + if (insertion_level) + { + INSERTION_ELT *stack = insertion_stack; + int original_input_text_offset; + + skip_whitespace (); + original_input_text_offset = input_text_offset; + + get_rest_of_line (0, &rest_of_line); + item_func = current_item_function (); + + /* Do the right thing depending on which insertion function is active. */ + switch_top: + switch (stack->insertion) + { + case multitable: + multitable_item (); + /* Support text directly after the @item. */ + if (*rest_of_line) + { + line_number--; + input_text_offset = original_input_text_offset; + } + break; + + case ifclear: + case ifhtml: + case ifinfo: + case ifnothtml: + case ifnotinfo: + case ifnottex: + case ifset: + case iftex: + case rawhtml: + case rawtex: + case tex: + case cartouche: + stack = stack->next; + if (!stack) + goto no_insertion; + else + goto switch_top; + break; + + case menu: + case quotation: + case example: + case smallexample: + case lisp: + case smalllisp: + case format: + case smallformat: + case display: + case smalldisplay: + case group: + line_error (_("@%s not meaningful inside `@%s' block"), + command, + insertion_type_pname (current_insertion_type ())); + break; + + case itemize: + case enumerate: + if (itemx_flag) + { + line_error (_("@itemx not meaningful inside `%s' block"), + insertion_type_pname (current_insertion_type ())); + } + else + { + if (html) + { + if (in_paragraph) + { + add_word ("</p>"); + in_paragraph = 0; + } + add_word ("<li>"); + } + else + { + start_paragraph (); + kill_self_indent (-1); + filling_enabled = indented_fill = 1; + + if (current_item_function ()) + { + output_column = current_indent - 2; + indent (output_column); + + /* The item marker can be given with or without + braces -- @bullet and @bullet{} are both ok. + Or it might be something that doesn't take + braces at all, such as "o" or "#" or "@ ". + Thus, only supply braces if the item marker is + a command, they haven't supplied braces + themselves, and we know it needs them. */ + if (item_func && *item_func) + { + if (*item_func == COMMAND_PREFIX + && item_func[strlen (item_func) - 1] != '}' + && command_needs_braces (item_func + 1)) + execute_string ("%s{}", item_func); + else + execute_string ("%s", item_func); + } + insert (' '); + output_column++; + } + else + enumerate_item (); + + /* Special hack. This makes `close_paragraph' a no-op until + `start_paragraph' has been called. */ + must_start_paragraph = 1; + } + + /* Handle text directly after the @item. */ + if (*rest_of_line) + { + line_number--; + input_text_offset = original_input_text_offset; + } + } + break; + + case table: + case ftable: + case vtable: + if (html) + { + static int last_html_output_position = 0; + + /* If nothing has been output since the last <dd>, + remove the empty <dd> element. Some browsers render + an extra empty line for <dd><dt>, which makes @itemx + conversion look ugly. */ + if (last_html_output_position == output_position + && strncmp ((char *) output_paragraph, "<dd>", + output_paragraph_offset) == 0) + output_paragraph_offset = 0; + + /* Force the browser to render one blank line before + each new @item in a table. But don't do that unless + this is the first <dt> after the <dl>, or if we are + converting @itemx. + + Note that there are some browsers which ignore <br> + in this context, but I cannot find any way to force + them all render exactly one blank line. */ + if (!itemx_flag + && strncmp ((char *) output_paragraph + + output_paragraph_offset - sizeof (dl_tag) + 1, + dl_tag, sizeof (dl_tag) - 1) != 0) + add_word ("<br>"); + + add_word ("<dt>"); + if (item_func && *item_func) + execute_string ("%s{%s}", item_func, rest_of_line); + else + execute_string ("%s", rest_of_line); + + if (current_insertion_type () == ftable) + execute_string ("%cfindex %s\n", COMMAND_PREFIX, rest_of_line); + + if (current_insertion_type () == vtable) + execute_string ("%cvindex %s\n", COMMAND_PREFIX, rest_of_line); + /* Make sure output_position is updated, so we could + remember it. */ + close_single_paragraph (); + last_html_output_position = output_position; + add_word ("<dd>"); + } + else + { + /* We need this to determine if we have two @item's in a row + (see test just below). */ + static int last_item_output_position = 0; + + /* Get rid of extra characters. */ + kill_self_indent (-1); + + /* If we have one @item followed directly by another @item, + we need to insert a blank line. This is not true for + @itemx, though. */ + if (!itemx_flag && last_item_output_position == output_position) + insert ('\n'); + + /* `close_paragraph' almost does what we want. The problem + is when paragraph_is_open, and last_char_was_newline, and + the last newline has been turned into a space, because + filling_enabled. I handle it here. */ + if (last_char_was_newline && filling_enabled && + paragraph_is_open) + insert ('\n'); + close_paragraph (); + +#if defined (INDENT_PARAGRAPHS_IN_TABLE) + /* Indent on a new line, but back up one indentation level. */ + { + int save = inhibit_paragraph_indentation; + inhibit_paragraph_indentation = 1; + /* At this point, inserting any non-whitespace character will + force the existing indentation to be output. */ + add_char ('i'); + inhibit_paragraph_indentation = save; + } +#else /* !INDENT_PARAGRAPHS_IN_TABLE */ + add_char ('i'); +#endif /* !INDENT_PARAGRAPHS_IN_TABLE */ + + output_paragraph_offset--; + kill_self_indent (default_indentation_increment + 1); + + /* Add item's argument to the line. */ + filling_enabled = 0; + if (item_func && *item_func) + execute_string ("%s{%s}", item_func, rest_of_line); + else + execute_string ("%s", rest_of_line); + + if (current_insertion_type () == ftable) + execute_string ("%cfindex %s\n", COMMAND_PREFIX, rest_of_line); + else if (current_insertion_type () == vtable) + execute_string ("%cvindex %s\n", COMMAND_PREFIX, rest_of_line); + + /* Start a new line, and let start_paragraph () + do the indenting of it for you. */ + close_single_paragraph (); + indented_fill = filling_enabled = 1; + last_item_output_position = output_position; + } + } + free (rest_of_line); + } + else + { + no_insertion: + line_error (_("%c%s found outside of an insertion block"), + COMMAND_PREFIX, command); + } +} + +void +cm_itemx () +{ + itemx_flag++; + cm_item (); + itemx_flag--; +} diff --git a/contrib/texinfo/makeinfo/insertion.h b/contrib/texinfo/makeinfo/insertion.h new file mode 100644 index 0000000..6f4a24b --- /dev/null +++ b/contrib/texinfo/makeinfo/insertion.h @@ -0,0 +1,61 @@ +/* insertion.h -- declarations for insertion.c. + $Id: insertion.h,v 1.6 1999/07/06 23:12:58 karl Exp $ + + Copyright (C) 1998, 99 Free Software Foundation, Inc. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software Foundation, + Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ + +#ifndef INSERTION_H +#define INSERTION_H + +/* Must match list in insertion.c. */ +enum insertion_type +{ + cartouche, defcv, deffn, defivar, defmac, defmethod, defop, defopt, + defspec, deftp, deftypefn, deftypefun, deftypeivar, deftypemethod, + deftypeop, deftypevar, deftypevr, defun, defvar, defvr, detailmenu, + direntry, display, enumerate, example, flushleft, flushright, format, + ftable, group, ifclear, ifhtml, ifinfo, ifnothtml, ifnotinfo, + ifnottex, ifset, iftex, itemize, lisp, menu, multitable, quotation, + rawhtml, rawtex, smalldisplay, smallexample, smallformat, smalllisp, + table, tex, vtable, bad_type +}; + +typedef struct istack_elt +{ + struct istack_elt *next; + char *item_function; + char *filename; + int line_number; + int filling_enabled; + int indented_fill; + enum insertion_type insertion; + int inhibited; + int in_fixed_width_font; +} INSERTION_ELT; + + +extern int insertion_level; +extern INSERTION_ELT *insertion_stack; +extern int in_menu; +extern int in_detailmenu; +extern int had_menu_commentary; +extern int in_paragraph; + +extern void command_name_condition (); +extern void cm_ifnothtml (), cm_ifhtml(), cm_html (); +extern void cm_ifinfo (), cm_ifnotinfo (); +extern void cm_ifnottex (), cm_iftex (), cm_tex (); +#endif /* !INSERTION_H */ diff --git a/contrib/texinfo/makeinfo/lang.c b/contrib/texinfo/makeinfo/lang.c new file mode 100644 index 0000000..eeb9ef5 --- /dev/null +++ b/contrib/texinfo/makeinfo/lang.c @@ -0,0 +1,415 @@ +/* lang.c -- language depend behaviour (startpoint) + $Id: lang.c,v 1.11 1999/07/13 21:16:29 karl Exp $ + + Copyright (C) 1999 Free Software Foundation, Inc. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + + Written by Karl Heinz Marbaise <kama@hippo.fido.de>. */ + +#include "system.h" +#include "cmds.h" +#include "lang.h" +#include "makeinfo.h" + +/* Current document encoding. */ +char *document_encoding = NULL; + +/* Current language code; default is English. */ +language_code_type language_code = en; + +language_struct language_table[] = { + { aa, "aa", "Afar" }, + { ab, "ab", "Abkhazian" }, + { af, "af", "Afrikaans" }, + { am, "am", "Amharic" }, + { ar, "ar", "Arabic" }, + { as, "as", "Assamese" }, + { ay, "ay", "Aymara" }, + { az, "az", "Azerbaijani" }, + { ba, "ba", "Bashkir" }, + { be, "be", "Byelorussian" }, + { bg, "bg", "Bulgarian" }, + { bh, "bh", "Bihari" }, + { bi, "bi", "Bislama" }, + { bn, "bn", "Bengali; Bangla" }, + { bo, "bo", "Tibetan" }, + { br, "br", "Breton" }, + { ca, "ca", "Catalan" }, + { co, "co", "Corsican" }, + { cs, "cs", "Czech" }, + { cy, "cy", "Welsh" }, + { da, "da", "Danish" }, + { de, "de", "German" }, + { dz, "dz", "Bhutani" }, + { el, "el", "Greek" }, + { en, "en", "English" }, + { eo, "eo", "Esperanto" }, + { es, "es", "Spanish" }, + { et, "et", "Estonian" }, + { eu, "eu", "Basque" }, + { fa, "fa", "Persian" }, + { fi, "fi", "Finnish" }, + { fj, "fj", "Fiji" }, + { fo, "fo", "Faroese" }, + { fr, "fr", "French" }, + { fy, "fy", "Frisian" }, + { ga, "ga", "Irish" }, + { gd, "gd", "Scots Gaelic" }, + { gl, "gl", "Galician" }, + { gn, "gn", "Guarani" }, + { gu, "gu", "Gujarati" }, + { ha, "ha", "Hausa" }, + { he, "he", "Hebrew" } /* (formerly iw) */, + { hi, "hi", "Hindi" }, + { hr, "hr", "Croatian" }, + { hu, "hu", "Hungarian" }, + { hy, "hy", "Armenian" }, + { ia, "ia", "Interlingua" }, + { id, "id", "Indonesian" } /* (formerly in) */, + { ie, "ie", "Interlingue" }, + { ik, "ik", "Inupiak" }, + { is, "is", "Icelandic" }, + { it, "it", "Italian" }, + { iu, "iu", "Inuktitut" }, + { ja, "ja", "Japanese" }, + { jw, "jw", "Javanese" }, + { ka, "ka", "Georgian" }, + { kk, "kk", "Kazakh" }, + { kl, "kl", "Greenlandic" }, + { km, "km", "Cambodian" }, + { kn, "kn", "Kannada" }, + { ko, "ko", "Korean" }, + { ks, "ks", "Kashmiri" }, + { ku, "ku", "Kurdish" }, + { ky, "ky", "Kirghiz" }, + { la, "la", "Latin" }, + { ln, "ln", "Lingala" }, + { lo, "lo", "Laothian" }, + { lt, "lt", "Lithuanian" }, + { lv, "lv", "Latvian, Lettish" }, + { mg, "mg", "Malagasy" }, + { mi, "mi", "Maori" }, + { mk, "mk", "Macedonian" }, + { ml, "ml", "Malayalam" }, + { mn, "mn", "Mongolian" }, + { mo, "mo", "Moldavian" }, + { mr, "mr", "Marathi" }, + { ms, "ms", "Malay" }, + { mt, "mt", "Maltese" }, + { my, "my", "Burmese" }, + { na, "na", "Nauru" }, + { ne, "ne", "Nepali" }, + { nl, "nl", "Dutch" }, + { no, "no", "Norwegian" }, + { oc, "oc", "Occitan" }, + { om, "om", "(Afan) Oromo" }, + { or, "or", "Oriya" }, + { pa, "pa", "Punjabi" }, + { pl, "pl", "Polish" }, + { ps, "ps", "Pashto, Pushto" }, + { pt, "pt", "Portuguese" }, + { qu, "qu", "Quechua" }, + { rm, "rm", "Rhaeto-Romance" }, + { rn, "rn", "Kirundi" }, + { ro, "ro", "Romanian" }, + { ru, "ru", "Russian" }, + { rw, "rw", "Kinyarwanda" }, + { sa, "sa", "Sanskrit" }, + { sd, "sd", "Sindhi" }, + { sg, "sg", "Sangro" }, + { sh, "sh", "Serbo-Croatian" }, + { si, "si", "Sinhalese" }, + { sk, "sk", "Slovak" }, + { sl, "sl", "Slovenian" }, + { sm, "sm", "Samoan" }, + { sn, "sn", "Shona" }, + { so, "so", "Somali" }, + { sq, "sq", "Albanian" }, + { sr, "sr", "Serbian" }, + { ss, "ss", "Siswati" }, + { st, "st", "Sesotho" }, + { su, "su", "Sundanese" }, + { sv, "sv", "Swedish" }, + { sw, "sw", "Swahili" }, + { ta, "ta", "Tamil" }, + { te, "te", "Telugu" }, + { tg, "tg", "Tajik" }, + { th, "th", "Thai" }, + { ti, "ti", "Tigrinya" }, + { tk, "tk", "Turkmen" }, + { tl, "tl", "Tagalog" }, + { tn, "tn", "Setswana" }, + { to, "to", "Tonga" }, + { tr, "tr", "Turkish" }, + { ts, "ts", "Tsonga" }, + { tt, "tt", "Tatar" }, + { tw, "tw", "Twi" }, + { ug, "ug", "Uighur" }, + { uk, "uk", "Ukrainian" }, + { ur, "ur", "Urdu" }, + { uz, "uz", "Uzbek" }, + { vi, "vi", "Vietnamese" }, + { vo, "vo", "Volapuk" }, + { wo, "wo", "Wolof" }, + { xh, "xh", "Xhosa" }, + { yi, "yi", "Yiddish" } /* (formerly ji) */, + { yo, "yo", "Yoruba" }, + { za, "za", "Zhuang" }, + { zh, "zh", "Chinese" }, + { zu, "zu", "Zulu" }, + { last_language_code, NULL, NULL } +}; + +/* @documentlanguage. Maybe we'll do something useful with this in the + future. For now, we just recognize it. */ +void +cm_documentlanguage () +{ + language_code_type c; + char *lang_arg; + + /* Read the line with the language code on it. */ + get_rest_of_line (1, &lang_arg); + + /* Linear search is fine these days. */ + for (c = aa; c != last_language_code; c++) + { + if (strcmp (lang_arg, language_table[c].abbrev) == 0) + { /* Set current language code. */ + language_code = c; + break; + } + } + + /* If we didn't find this code, complain. */ + if (c == last_language_code) + warning (_("%s is not a valid ISO 639 language code"), lang_arg); + + free (lang_arg); +} + + + +/* @documentencoding. Set global. */ +void +cm_documentencoding () +{ + get_rest_of_line (1, &document_encoding); +} + + + +/* Accent commands that take explicit arguments and don't have any + special HTML support. */ + +void +cm_accent (arg) + int arg; +{ + if (arg == START) + { + /* Must come first to avoid ambiguity with overdot. */ + if (strcmp (command, "udotaccent") == 0) /* underdot */ + add_char ('.'); + } + else if (arg == END) + { + if (strcmp (command, "=") == 0) /* macron */ + add_word (html ? "¯" : "="); + else if (strcmp (command, "H") == 0) /* Hungarian umlaut */ + add_word ("''"); + else if (strcmp (command, "dotaccent") == 0) /* overdot */ + add_meta_char ('.'); + else if (strcmp (command, "ringaccent") == 0) /* ring */ + add_char ('*'); + else if (strcmp (command, "tieaccent") == 0) /* long tie */ + add_char ('['); + else if (strcmp (command, "u") == 0) /* breve */ + add_char ('('); + else if (strcmp (command, "ubaraccent") == 0) /* underbar */ + add_char ('_'); + else if (strcmp (command, "v") == 0) /* hacek/check */ + add_word (html ? "<" : "<"); + } +} + +/* Common routine for the accent characters that have support in HTML. + If the character being accented is in the HTML_SUPPORTED set, then + produce &CHTML_SOLO;, for example, Ä for an A-umlaut. If not in + HTML_SUPPORTED, just produce &HTML_SOLO;X for the best we can do with + at an X-umlaut. Finally, if not producing HTML, just use SINGLE, a + character such as " which is the best plain text representation we + can manage. If HTML_SOLO_STANDALONE is zero the given HTML_SOLO + does not exist as valid standalone character in HTML. */ + +static void +cm_accent_generic (arg, start, end, html_supported, single, + html_solo_standalone, html_solo) + int arg, start, end; + char *html_supported; + int single; + int html_solo_standalone; + char *html_solo; +{ + if (html) + { + static int valid_html_accent; + + if (arg == START) + { /* If HTML has good support for this character, use it. */ + if (strchr (html_supported, curchar ())) + { /* Yes; start with an ampersand. The character itself + will be added later in read_command (makeinfo.c). */ + add_char ('&'); + valid_html_accent = 1; + } + else + { /* No special HTML support, so produce standalone char. */ + valid_html_accent = 0; + if (html_solo_standalone) + { + add_char ('&'); + add_word (html_solo); + add_char (';'); + } + else + /* If the html_solo does not exist as standalone character + (namely ˆ ` ˜), then we use + the single character version instead. */ + add_char (single); + } + } + else if (arg == END) + { /* Only if we saw a valid_html_accent can we use the full + HTML accent (umlaut, grave ...). */ + if (valid_html_accent) + { + add_word (html_solo); + add_char (';'); + } + } + } + else if (arg == END) + { /* Not producing HTML, so just use the normal character. */ + add_char (single); + } +} + +void +cm_accent_umlaut (arg, start, end) + int arg, start, end; +{ + cm_accent_generic (arg, start, end, "aouAOUEeIiy", '"', 1, "uml"); +} + +void +cm_accent_acute (arg, start, end) + int arg, start, end; +{ + cm_accent_generic (arg, start, end, "AEIOUYaeiouy", '\'', 1, "acute"); +} + +void +cm_accent_cedilla (arg, start, end) + int arg, start, end; +{ + cm_accent_generic (arg, start, end, "Cc", ',', 1, "cedil"); +} + +void +cm_accent_hat (arg, start, end) + int arg, start, end; +{ + cm_accent_generic (arg, start, end, "AEIOUaeiou", '^', 0, "circ"); +} + +void +cm_accent_grave (arg, start, end) + int arg, start, end; +{ + cm_accent_generic (arg, start, end, "AEIOUaeiou", '`', 0, "grave"); +} + +void +cm_accent_tilde (arg, start, end) + int arg, start, end; +{ + cm_accent_generic (arg, start, end, "AOano", '~', 0, "tilde"); +} + + + +/* Non-English letters/characters that don't insert themselves. */ +void +cm_special_char (arg) +{ + if (arg == START) + { + if ((*command == 'L' || *command == 'l' + || *command == 'O' || *command == 'o') + && command[1] == 0) + { /* Lslash lslash Oslash oslash. + Lslash and lslash aren't supported in HTML. */ + if (html && (command[0] == 'O' || command[0] == 'o')) + add_word_args ("&%cslash;", command[0]); + else + add_word_args ("/%c", command[0]); + } + else if (strcmp (command, "exclamdown") == 0) + add_word (html ? "¡" : "!"); + else if (strcmp (command, "pounds") == 0) + add_word (html ? "£" : "#"); + else if (strcmp (command, "questiondown") == 0) + add_word (html ? "¿" : "?"); + else if (strcmp (command, "AE") == 0) + add_word (html ? "Æ" : command); + else if (strcmp (command, "ae") == 0) + add_word (html ? "æ" : command); + else if (strcmp (command, "OE") == 0) + add_word (html ? "Œ" : command); + else if (strcmp (command, "oe") == 0) + add_word (html ? "œ" : command); + else if (strcmp (command, "AA") == 0) + add_word (html ? "Å" : command); + else if (strcmp (command, "aa") == 0) + add_word (html ? "å" : command); + else if (strcmp (command, "ss") == 0) + add_word (html ? "ß" : command); + else + line_error ("cm_special_char internal error: command=@%s", command); + } +} + +/* Dotless i or j. */ +void +cm_dotless (arg, start, end) + int arg, start, end; +{ + if (arg == END) + { + if (output_paragraph[start] != 'i' && output_paragraph[start] != 'j') + /* This error message isn't perfect if the argument is multiple + characters, but it doesn't seem worth getting right. */ + line_error (_("%c%s expects `i' or `j' as argument, not `%c'"), + COMMAND_PREFIX, command, output_paragraph[start]); + + else if (end - start != 1) + line_error (_("%c%s expects a single character `i' or `j' as argument"), + COMMAND_PREFIX, command); + + /* We've already inserted the `i' or `j', so nothing to do. */ + } +} diff --git a/contrib/texinfo/makeinfo/lang.h b/contrib/texinfo/makeinfo/lang.h new file mode 100644 index 0000000..25bf0bd --- /dev/null +++ b/contrib/texinfo/makeinfo/lang.h @@ -0,0 +1,86 @@ +/* lang.h -- declarations for language codes etc. + $Id: lang.h,v 1.6 1999/03/22 20:07:34 karl Exp $ + + Copyright (C) 1999 Free Software Foundation, Inc. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + + Written by Karl Heinz Marbaise <kama@hippo.fido.de>. */ + +#ifndef LANG_H +#define LANG_H + +/* The langauge code which can be changed through @documentlanguage + * Actualy Info does not support this (may be in the future) ;-) + * Default for language code is en (english!) kama + * These code should ISO 639 two letter codes. + */ +typedef enum +{ + aa, ab, af, am, ar, as, ay, az, + ba, be, bg, bh, bi, bn, bo, br, + ca, co, cs, cy, + da, de, dz, + el, en, eo, es, et, eu, + fa, fi, fj, fo, fr, fy, + ga, gd, gl, gn, gu, + ha, he, hi, hr, hu, hy, + ia, id, ie, ik, is, it, iu, + ja, jw, + ka, kk, kl, km, kn, ko, ks, ku, ky, + la, ln, lo, lt, lv, + mg, mi, mk, ml, mn, mo, mr, ms, mt, my, + na, ne, nl, no, + oc, om, or, + pa, pl, ps, pt, + qu, + rm, rn, ro, ru, rw, + sa, sd, sg, sh, si, sk, sl, sm, sn, so, sq, sr, ss, st, su, sv, sw, + ta, te, tg, th, ti, tk, tl, tn, to, tr, ts, tt, tw, + ug, uk, ur, uz, + vi, vo, + wo, + xh, + yi, yo, + za, zh, zu, + last_language_code +} language_code_type; + +/* The current language code. */ +extern language_code_type language_code; + +/* Information about all valid languages. */ +typedef struct +{ + language_code_type lc; /* language code as enum type */ + char *abbrev; /* two letter language code */ + char *desc; /* full name for language code */ +} language_struct; +extern language_struct language_table[]; + +/* The encoding, or null if not set. */ +extern char *document_encoding; + + +/* The commands. */ +extern void cm_documentlanguage (), cm_documentencoding (); + +/* Accents, other non-English characters. */ +void cm_accent (), cm_special_char (), cm_dotless (); + +extern void cm_accent_umlaut (), cm_accent_acute (), cm_accent_cedilla (), + cm_accent_hat (), cm_accent_grave (), cm_accent_tilde (); + +#endif /* not LANG_H */ diff --git a/contrib/texinfo/makeinfo/macro.c b/contrib/texinfo/makeinfo/macro.c new file mode 100644 index 0000000..8c89da2 --- /dev/null +++ b/contrib/texinfo/makeinfo/macro.c @@ -0,0 +1,1114 @@ +/* macro.c -- user-defined macros for Texinfo. + $Id: macro.c,v 1.10 1999/08/17 21:06:35 karl Exp $ + + Copyright (C) 1998, 99 Free Software Foundation, Inc. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software Foundation, + Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ + +#include "system.h" +#include "cmds.h" +#include "macro.h" +#include "makeinfo.h" +#include "insertion.h" + +/* If non-NULL, this is an output stream to write the full macro expansion + of the input text to. The result is another texinfo file, but + missing @include, @infoinclude, @macro, and macro invocations. Instead, + all of the text is placed within the file. */ +FILE *macro_expansion_output_stream = NULL; + +/* Output file for -E. */ +char *macro_expansion_filename; + +/* Nonzero means a macro string is in execution, as opposed to a file. */ +int me_executing_string = 0; + +/* Nonzero means we want only to expand macros and + leave everything else intact. */ +int only_macro_expansion = 0; + +static ITEXT **itext_info = NULL; +static int itext_size = 0; + +/* Return the arglist on the current line. This can behave in two different + ways, depending on the variable BRACES_REQUIRED_FOR_MACRO_ARGS. */ +int braces_required_for_macro_args = 0; + +/* Array of macros and definitions. */ +MACRO_DEF **macro_list = NULL; + +int macro_list_len = 0; /* Number of elements. */ +int macro_list_size = 0; /* Number of slots in total. */ + +/* Return the length of the array in ARRAY. */ +int +array_len (array) + char **array; +{ + int i = 0; + + if (array) + for (i = 0; array[i]; i++); + + return i; +} + +void +free_array (array) + char **array; +{ + if (array) + { + int i; + for (i = 0; array[i]; i++) + free (array[i]); + + free (array); + } +} + +/* Return the macro definition of NAME or NULL if NAME is not defined. */ +MACRO_DEF * +find_macro (name) + char *name; +{ + int i; + MACRO_DEF *def; + + def = NULL; + for (i = 0; macro_list && (def = macro_list[i]); i++) + { + if ((!def->inhibited) && (strcmp (def->name, name) == 0)) + break; + } + return def; +} + +/* Add the macro NAME with ARGLIST and BODY to the list of defined macros. + SOURCE_FILE is the name of the file where this definition can be found, + and SOURCE_LINENO is the line number within that file. If a macro already + exists with NAME, then a warning is produced, and that previous + definition is overwritten. */ +void +add_macro (name, arglist, body, source_file, source_lineno, flags) + char *name; + char **arglist; + char *body; + char *source_file; + int source_lineno, flags; +{ + MACRO_DEF *def; + + def = find_macro (name); + + if (!def) + { + if (macro_list_len + 2 >= macro_list_size) + macro_list = xrealloc + (macro_list, ((macro_list_size += 10) * sizeof (MACRO_DEF *))); + + macro_list[macro_list_len] = xmalloc (sizeof (MACRO_DEF)); + macro_list[macro_list_len + 1] = NULL; + + def = macro_list[macro_list_len]; + macro_list_len += 1; + def->name = name; + } + else + { + char *temp_filename = input_filename; + int temp_line = line_number; + + warning (_("macro `%s' previously defined"), name); + + input_filename = def->source_file; + line_number = def->source_lineno; + warning (_("here is the previous definition of `%s'"), name); + + input_filename = temp_filename; + line_number = temp_line; + + if (def->arglist) + { + int i; + + for (i = 0; def->arglist[i]; i++) + free (def->arglist[i]); + + free (def->arglist); + } + free (def->source_file); + free (def->body); + } + + def->source_file = xstrdup (source_file); + def->source_lineno = source_lineno; + def->body = body; + def->arglist = arglist; + def->inhibited = 0; + def->flags = flags; +} + + +char ** +get_brace_args (quote_single) + int quote_single; +{ + char **arglist, *word; + int arglist_index, arglist_size; + int character, escape_seen, start; + int depth = 1; + + /* There is an arglist in braces here, so gather the args inside of it. */ + skip_whitespace_and_newlines (); + input_text_offset++; + arglist = NULL; + arglist_index = arglist_size = 0; + + get_arg: + skip_whitespace_and_newlines (); + start = input_text_offset; + escape_seen = 0; + + while ((character = curchar ())) + { + if (character == '\\') + { + input_text_offset += 2; + escape_seen = 1; + } + else if (character == '{') + { + depth++; + input_text_offset++; + } + else if ((character == ',' && !quote_single) || + ((character == '}') && depth == 1)) + { + int len = input_text_offset - start; + + if (len || (character != '}')) + { + word = xmalloc (1 + len); + memcpy (word, input_text + start, len); + word[len] = 0; + + /* Clean up escaped characters. */ + if (escape_seen) + { + int i; + for (i = 0; word[i]; i++) + if (word[i] == '\\') + memmove (word + i, word + i + 1, + 1 + strlen (word + i + 1)); + } + + if (arglist_index + 2 >= arglist_size) + arglist = xrealloc + (arglist, (arglist_size += 10) * sizeof (char *)); + + arglist[arglist_index++] = word; + arglist[arglist_index] = NULL; + } + + input_text_offset++; + if (character == '}') + break; + else + goto get_arg; + } + else if (character == '}') + { + depth--; + input_text_offset++; + } + else + { + input_text_offset++; + if (character == '\n') line_number++; + } + } + return arglist; +} + +char ** +get_macro_args (def) + MACRO_DEF *def; +{ + int i; + char *word; + + /* Quickly check to see if this macro has been invoked with any arguments. + If not, then don't skip any of the following whitespace. */ + for (i = input_text_offset; i < input_text_length; i++) + if (!cr_or_whitespace (input_text[i])) + break; + + if (input_text[i] != '{') + { + if (braces_required_for_macro_args) + { + return NULL; + } + else + { + /* Braces are not required to fill out the macro arguments. If + this macro takes one argument, it is considered to be the + remainder of the line, sans whitespace. */ + if (def->arglist && def->arglist[0] && !def->arglist[1]) + { + char **arglist; + + get_rest_of_line (0, &word); + if (input_text[input_text_offset - 1] == '\n') + { + input_text_offset--; + line_number--; + } + /* canon_white (word); */ + arglist = xmalloc (2 * sizeof (char *)); + arglist[0] = word; + arglist[1] = NULL; + return arglist; + } + else + { + /* The macro either took no arguments, or took more than + one argument. In that case, it must be invoked with + arguments surrounded by braces. */ + return NULL; + } + } + } + return get_brace_args (def->flags & ME_QUOTE_ARG); +} + +/* Substitute actual parameters for named parameters in body. + The named parameters which appear in BODY must by surrounded + reverse slashes, as in \foo\. */ +char * +apply (named, actuals, body) + char **named, **actuals, *body; +{ + int i; + int new_body_index, new_body_size; + char *new_body, *text; + int length_of_actuals; + + length_of_actuals = array_len (actuals); + new_body_size = strlen (body); + new_body = xmalloc (1 + new_body_size); + + /* Copy chars from BODY into NEW_BODY. */ + i = 0; + new_body_index = 0; + + while (body[i]) + { /* Anything but a \ is easy. */ + if (body[i] != '\\') + new_body[new_body_index++] = body[i++]; + else + { /* Snarf parameter name, check against named parameters. */ + char *param; + int param_start, which, len; + + param_start = ++i; + while (body[i] && body[i] != '\\') + i++; + + len = i - param_start; + param = xmalloc (1 + len); + memcpy (param, body + param_start, len); + param[len] = 0; + + if (body[i]) /* move past \ */ + i++; + + /* Now check against named parameters. */ + for (which = 0; named && named[which]; which++) + if (STREQ (named[which], param)) + break; + + if (named && named[which]) + { + text = which < length_of_actuals ? actuals[which] : NULL; + if (!text) + text = ""; + len = strlen (text); + } + else + { /* not a parameter, either it's \\ (if len==0) or an + error. In either case, restore one \ at least. */ + if (len) { + warning (_("\\ in macro expansion followed by `%s' instead of \\ or parameter name"), + param); + } + len++; + text = xmalloc (1 + len); + sprintf (text, "\\%s", param); + } + + if (strlen (param) + 2 < len) + { + new_body_size += len + 1; + new_body = xrealloc (new_body, new_body_size); + } + + free (param); + + strcpy (new_body + new_body_index, text); + new_body_index += len; + + if (!named || !named[which]) + free (text); + } + } + + new_body[new_body_index] = 0; + return new_body; +} + +/* Expand macro passed in DEF, a pointer to a MACRO_DEF, and + return its expansion as a string. */ +char * +expand_macro (def) + MACRO_DEF *def; +{ + char **arglist; + int num_args; + char *execution_string = NULL; + int start_line = line_number; + + /* Find out how many arguments this macro definition takes. */ + num_args = array_len (def->arglist); + + /* Gather the arguments present on the line if there are any. */ + arglist = get_macro_args (def); + + if (num_args < array_len (arglist)) + { + free_array (arglist); + line_error (_("Macro `%s' called on line %d with too many args"), + def->name, start_line); + return execution_string; + } + + if (def->body) + execution_string = apply (def->arglist, arglist, def->body); + + free_array (arglist); + return execution_string; +} + +/* Execute the macro passed in DEF, a pointer to a MACRO_DEF. */ +void +execute_macro (def) + MACRO_DEF *def; +{ + char *execution_string; + int start_line = line_number, end_line; + + if (macro_expansion_output_stream && !executing_string && !me_inhibit_expansion) + me_append_before_this_command (); + + execution_string = expand_macro (def); + if (!execution_string) + return; + + if (def->body) + { + /* Reset the line number to where the macro arguments began. + This makes line numbers reported in error messages correct in + case the macro arguments span several lines and the expanded + arguments invoke other commands. */ + end_line = line_number; + line_number = start_line; + + if (macro_expansion_output_stream && !executing_string && !me_inhibit_expansion) + { + remember_itext (input_text, input_text_offset); + me_execute_string (execution_string); + } + else + execute_string ("%s", execution_string); + + free (execution_string); + line_number = end_line; + } +} + + +/* Read and remember the definition of a macro. If RECURSIVE is set, + set the ME_RECURSE flag. MACTYPE is either "macro" or "rmacro", and + tells us what the matching @end should be. */ +static void +define_macro (mactype, recursive) + char *mactype; + int recursive; +{ + int i; + char *name, **arglist, *body, *line, *last_end; + int body_size, body_index; + int depth = 1; + int defining_line = line_number; + int flags = 0; + + arglist = NULL; + body = NULL; + body_size = 0; + body_index = 0; + + if (macro_expansion_output_stream && !executing_string) + me_append_before_this_command (); + + skip_whitespace (); + + /* Get the name of the macro. This is the set of characters which are + not whitespace and are not `{' immediately following the @macro. */ + { + int start = input_text_offset; + int len; + + for (i = start; + (i < input_text_length) && + (input_text[i] != '{') && + (!cr_or_whitespace (input_text[i])); + i++); + + len = i - start; + name = xmalloc (1 + len); + memcpy (name, input_text + start, len); + name[len] = 0; + input_text_offset = i; + } + + skip_whitespace (); + + /* It is not required that the definition of a macro includes an arglist. + If not, don't try to get the named parameters, just use a null list. */ + if (curchar () == '{') + { + int character; + int arglist_index = 0, arglist_size = 0; + int gathering_words = 1; + char *word = NULL; + + /* Read the words inside of the braces which determine the arglist. + These words will be replaced within the body of the macro at + execution time. */ + + input_text_offset++; + skip_whitespace_and_newlines (); + + while (gathering_words) + { + int len; + + for (i = input_text_offset; + (character = input_text[i]); + i++) + { + switch (character) + { + case '\n': + line_number++; + case ' ': + case '\t': + case ',': + case '}': + /* Found the end of the current arglist word. Save it. */ + len = i - input_text_offset; + word = xmalloc (1 + len); + memcpy (word, input_text + input_text_offset, len); + word[len] = 0; + input_text_offset = i; + + /* Advance to the comma or close-brace that signified + the end of the argument. */ + while ((character = curchar ()) + && character != ',' + && character != '}') + { + input_text_offset++; + if (character == '\n') + line_number++; + } + + /* Add the word to our list of words. */ + if (arglist_index + 2 >= arglist_size) + { + arglist_size += 10; + arglist = xrealloc (arglist, + arglist_size * sizeof (char *)); + } + + arglist[arglist_index++] = word; + arglist[arglist_index] = NULL; + break; + } + + if (character == '}') + { + input_text_offset++; + gathering_words = 0; + break; + } + + if (character == ',') + { + input_text_offset++; + skip_whitespace_and_newlines (); + i = input_text_offset - 1; + } + } + } + + /* If we have exactly one argument, do @quote-arg implicitly. Not + only does this match TeX's behavior (which can't feasibly be + changed), but it's a good idea. */ + if (arglist_index == 1) + flags |= ME_QUOTE_ARG; + } + + /* Read the text carefully until we find an "@end macro" which + matches this one. The text in between is the body of the macro. */ + skip_whitespace_and_newlines (); + + while (depth) + { + if ((input_text_offset + 9) > input_text_length) + { + int temp_line = line_number; + line_number = defining_line; + line_error (_("%cend macro not found"), COMMAND_PREFIX); + line_number = temp_line; + return; + } + + get_rest_of_line (0, &line); + + /* Handle commands only meaningful within a macro. */ + if ((*line == COMMAND_PREFIX) && (depth == 1) && + (strncmp (line + 1, "allow-recursion", 15) == 0) && + (line[16] == 0 || whitespace (line[16]))) + { + for (i = 16; whitespace (line[i]); i++); + strcpy (line, line + i); + flags |= ME_RECURSE; + if (!*line) + { + free (line); + continue; + } + } + + if ((*line == COMMAND_PREFIX) && (depth == 1) && + (strncmp (line + 1, "quote-arg", 9) == 0) && + (line[10] == 0 || whitespace (line[10]))) + { + for (i = 10; whitespace (line[i]); i++); + strcpy (line, line + i); + + if (arglist && arglist[0] && !arglist[1]) + { + flags |= ME_QUOTE_ARG; + if (!*line) + { + free (line); + continue; + } + } + else + line_error (_("@quote-arg only useful for single-argument macros")); + } + + if (*line == COMMAND_PREFIX + && (strncmp (line + 1, "macro ", 6) == 0 + || strncmp (line + 1, "rmacro ", 7) == 0)) + depth++; + + /* Incorrect implementation of nesting -- just check that the last + @end matches what we started with. Since nested macros don't + work in TeX anyway, this isn't worth the trouble to get right. */ + if (*line == COMMAND_PREFIX && strncmp (line + 1, "end macro", 9) == 0) + { + depth--; + last_end = "macro"; + } + if (*line == COMMAND_PREFIX && strncmp (line + 1, "end rmacro", 9) == 0) + { + depth--; + last_end = "rmacro"; + } + + if (depth) + { + if ((body_index + strlen (line) + 3) >= body_size) + body = xrealloc (body, body_size += 3 + strlen (line)); + strcpy (body + body_index, line); + body_index += strlen (line); + body[body_index++] = '\n'; + body[body_index] = 0; + } + free (line); + } + + /* Check that @end matched the macro command. */ + if (!STREQ (last_end, mactype)) + warning (_("mismatched @end %s with @%s"), last_end, mactype); + + /* If it was an empty macro like + @macro foo + @end macro + create an empty body. (Otherwise, the macro is not expanded.) */ + if (!body) + { + body = (char *)malloc(1); + *body = 0; + } + + /* We now have the name, the arglist, and the body. However, BODY + includes the final newline which preceded the `@end macro' text. + Delete it. */ + if (body && strlen (body)) + body[strlen (body) - 1] = 0; + + if (recursive) + flags |= ME_RECURSE; + + add_macro (name, arglist, body, input_filename, defining_line, flags); + + if (macro_expansion_output_stream && !executing_string) + remember_itext (input_text, input_text_offset); +} + +void +cm_macro () +{ + define_macro ("macro", 0); +} + +void +cm_rmacro () +{ + define_macro ("rmacro", 1); +} + +/* Delete the macro with name NAME. The macro is deleted from the list, + but it is also returned. If there was no macro defined, NULL is + returned. */ + +static MACRO_DEF * +delete_macro (name) + char *name; +{ + int i; + MACRO_DEF *def; + + def = NULL; + + for (i = 0; macro_list && (def = macro_list[i]); i++) + if (strcmp (def->name, name) == 0) + { + memmove (macro_list + i, macro_list + i + 1, + ((macro_list_len + 1) - i) * sizeof (MACRO_DEF *)); + macro_list_len--; + break; + } + return def; +} + +void +cm_unmacro () +{ + int i; + char *line, *name; + MACRO_DEF *def; + + if (macro_expansion_output_stream && !executing_string) + me_append_before_this_command (); + + get_rest_of_line (0, &line); + + for (i = 0; line[i] && !whitespace (line[i]); i++); + name = xmalloc (i + 1); + memcpy (name, line, i); + name[i] = 0; + + def = delete_macro (name); + + if (def) + { + free (def->source_file); + free (def->name); + free (def->body); + + if (def->arglist) + { + int i; + + for (i = 0; def->arglist[i]; i++) + free (def->arglist[i]); + + free (def->arglist); + } + + free (def); + } + + free (line); + free (name); + + if (macro_expansion_output_stream && !executing_string) + remember_itext (input_text, input_text_offset); +} + +/* How to output sections of the input file verbatim. */ + +/* Set the value of POINTER's offset to OFFSET. */ +ITEXT * +remember_itext (pointer, offset) + char *pointer; + int offset; +{ + int i; + ITEXT *itext = NULL; + + /* If we have no info, initialize a blank list. */ + if (!itext_info) + { + itext_info = xmalloc ((itext_size = 10) * sizeof (ITEXT *)); + for (i = 0; i < itext_size; i++) + itext_info[i] = NULL; + } + + /* If the pointer is already present in the list, then set the offset. */ + for (i = 0; i < itext_size; i++) + if ((itext_info[i]) && + (itext_info[i]->pointer == pointer)) + { + itext = itext_info[i]; + itext_info[i]->offset = offset; + break; + } + + if (i == itext_size) + { + /* Find a blank slot (or create a new one), and remember the + pointer and offset. */ + for (i = 0; i < itext_size; i++) + if (itext_info[i] == NULL) + break; + + /* If not found, then add some slots. */ + if (i == itext_size) + { + int j; + + itext_info = xrealloc + (itext_info, (itext_size += 10) * sizeof (ITEXT *)); + + for (j = i; j < itext_size; j++) + itext_info[j] = NULL; + } + + /* Now add the pointer and the offset. */ + itext_info[i] = xmalloc (sizeof (ITEXT)); + itext_info[i]->pointer = pointer; + itext_info[i]->offset = offset; + itext = itext_info[i]; + } + return itext; +} + +/* Forget the input text associated with POINTER. */ +void +forget_itext (pointer) + char *pointer; +{ + int i; + + for (i = 0; i < itext_size; i++) + if (itext_info[i] && (itext_info[i]->pointer == pointer)) + { + free (itext_info[i]); + itext_info[i] = NULL; + break; + } +} + +/* Append the text which appeared in input_text from the last offset to + the character just before the command that we are currently executing. */ +void +me_append_before_this_command () +{ + int i; + + for (i = input_text_offset; i && (input_text[i] != COMMAND_PREFIX); i--) + ; + maybe_write_itext (input_text, i); +} + +/* Similar to execute_string, but only takes a single string argument, + and remembers the input text location, etc. */ +void +me_execute_string (execution_string) + char *execution_string; +{ + int saved_escape_html = escape_html; + int saved_in_paragraph = in_paragraph; + escape_html = me_executing_string == 0; + in_paragraph = 0; + + pushfile (); + input_text_offset = 0; + /* The following xstrdup is so we can relocate input_text at will. */ + input_text = xstrdup (execution_string); + input_filename = xstrdup (input_filename); + input_text_length = strlen (execution_string); + + remember_itext (input_text, 0); + + me_executing_string++; + reader_loop (); + free (input_text); + free (input_filename); + popfile (); + me_executing_string--; + + in_paragraph = saved_in_paragraph; + escape_html = saved_escape_html; +} + +/* A wrapper around me_execute_string which saves and restores + variables important for output generation. This is called + when we need to produce macro-expanded output for input which + leaves no traces in the Info output. */ +void +me_execute_string_keep_state (execution_string, append_string) + char *execution_string, *append_string; +{ + int op_orig, opcol_orig, popen_orig; + int fill_orig, newline_orig, indent_orig, meta_pos_orig; + + remember_itext (input_text, input_text_offset); + op_orig = output_paragraph_offset; + meta_pos_orig = meta_char_pos; + opcol_orig = output_column; + popen_orig = paragraph_is_open; + fill_orig = filling_enabled; + newline_orig = last_char_was_newline; + filling_enabled = 0; + indent_orig = no_indent; + no_indent = 1; + me_execute_string (execution_string); + if (append_string) + write_region_to_macro_output (append_string, 0, strlen (append_string)); + output_paragraph_offset = op_orig; + meta_char_pos = meta_pos_orig; + output_column = opcol_orig; + paragraph_is_open = popen_orig; + filling_enabled = fill_orig; + last_char_was_newline = newline_orig; + no_indent = indent_orig; +} + +/* Append the text which appears in input_text from the last offset to + the current OFFSET. */ +void +append_to_expansion_output (offset) + int offset; +{ + int i; + ITEXT *itext = NULL; + + for (i = 0; i < itext_size; i++) + if (itext_info[i] && itext_info[i]->pointer == input_text) + { + itext = itext_info[i]; + break; + } + + if (!itext) + return; + + if (offset > itext->offset) + { + write_region_to_macro_output (input_text, itext->offset, offset); + remember_itext (input_text, offset); + } +} + +/* Only write this input text iff it appears in our itext list. */ +void +maybe_write_itext (pointer, offset) + char *pointer; + int offset; +{ + int i; + ITEXT *itext = NULL; + + for (i = 0; i < itext_size; i++) + if (itext_info[i] && (itext_info[i]->pointer == pointer)) + { + itext = itext_info[i]; + break; + } + + if (itext && (itext->offset < offset)) + { + write_region_to_macro_output (itext->pointer, itext->offset, offset); + remember_itext (pointer, offset); + } +} + +void +write_region_to_macro_output (string, start, end) + char *string; + int start, end; +{ + if (macro_expansion_output_stream) + fwrite (string + start, 1, end - start, macro_expansion_output_stream); +} + +/* Aliases. */ + +typedef struct alias_struct +{ + char *alias; + char *mapto; + struct alias_struct *next; +} alias_type; + +static alias_type *aliases; + +/* @alias */ +void +cm_alias () +{ + alias_type *a = xmalloc (sizeof (alias_type)); + + skip_whitespace (); + get_until_in_line (1, "=", &(a->alias)); + discard_until ("="); + skip_whitespace (); + get_until_in_line (0, " ", &(a->mapto)); + + a->next = aliases; + aliases = a; +} + +/* Perform an alias expansion. Called from read_command. */ +char * +alias_expand (tok) + char *tok; +{ + alias_type *findit = aliases; + + while (findit) + if (strcmp (findit->alias, tok) == 0) + { + free (tok); + return alias_expand (xstrdup (findit->mapto)); + } + else + findit = findit->next; + + return tok; +} + +/* definfoenclose implementation. */ + +/* This structure is used to track enclosure macros. When an enclosure + macro is recognized, a pointer to the enclosure block corresponding + to its name is saved in the brace element for its argument. */ +typedef struct enclose_struct +{ + char *enclose; + char *before; + char *after; + struct enclose_struct *next; +} enclosure_type; + +static enclosure_type *enclosures; + +typedef struct enclosure_stack_struct +{ + enclosure_type *current; + struct enclosure_stack_struct *next; +} enclosure_stack_type; + +static enclosure_stack_type *enclosure_stack; + +/* @definfoenclose */ +void +cm_definfoenclose () +{ + enclosure_type *e = xmalloc (sizeof (enclosure_type)); + + skip_whitespace (); + get_until_in_line (1, ",", &(e->enclose)); + discard_until (","); + get_until_in_line (0, ",", &(e->before)); + discard_until (","); + get_until_in_line (0, "\n", &(e->after)); + + e->next = enclosures; + enclosures = e; +} + +/* If TOK is an enclosure command, push it on the enclosure stack and + return 1. Else return 0. */ + +int +enclosure_command (tok) + char *tok; +{ + enclosure_type *findit = enclosures; + + while (findit) + if (strcmp (findit->enclose, tok) == 0) + { + enclosure_stack_type *new = xmalloc (sizeof (enclosure_stack_type)); + new->current = findit; + new->next = enclosure_stack; + enclosure_stack = new; + + return 1; + } + else + findit = findit->next; + + return 0; +} + +/* actually perform the enclosure expansion */ +void +enclosure_expand (arg, start, end) + int arg, start, end; +{ + if (arg == START) + add_word (enclosure_stack->current->before); + else + { + enclosure_stack_type *temp; + + add_word (enclosure_stack->current->after); + + temp = enclosure_stack; + enclosure_stack = enclosure_stack->next; + free (temp); + } +} diff --git a/contrib/texinfo/makeinfo/macro.h b/contrib/texinfo/makeinfo/macro.h new file mode 100644 index 0000000..a64c613 --- /dev/null +++ b/contrib/texinfo/makeinfo/macro.h @@ -0,0 +1,71 @@ +/* macro.h -- declarations for macro.c. + $Id: macro.h,v 1.5 1999/07/15 00:00:46 karl Exp $ + + Copyright (C) 1998, 99 Free Software Foundation, Inc. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + */ + +#ifndef MACRO_H +#define MACRO_H + +extern FILE *macro_expansion_output_stream; +extern char *macro_expansion_filename; +extern int me_executing_string; +extern int only_macro_expansion; + +/* Here is a structure used to remember input text strings and offsets + within them. */ +typedef struct { + char *pointer; /* Pointer to the input text. */ + int offset; /* Offset of the last character output. */ +} ITEXT; + +/* Macro definitions for user-defined commands. */ +typedef struct { + char *name; /* Name of the macro. */ + char **arglist; /* Args to replace when executing. */ + char *body; /* Macro body. */ + char *source_file; /* File where this macro is defined. */ + int source_lineno; /* Line number within FILENAME. */ + int inhibited; /* Nonzero means make find_macro () fail. */ + int flags; /* ME_RECURSE, ME_QUOTE_ARG, etc. */ +} MACRO_DEF; + +/* flags for MACRO_DEF */ +#define ME_RECURSE 0x01 +#define ME_QUOTE_ARG 0x02 + +extern void execute_macro (); +extern MACRO_DEF *find_macro (); +extern char *expand_macro (); + +extern ITEXT *remember_itext (); +extern void forget_itext (); +extern void maybe_write_itext (); +extern void write_region_to_macro_output (); +extern void append_to_expansion_output (); +extern void me_append_before_this_command (); +extern void me_execute_string (); + +extern char *alias_expand (); +extern int enclosure_command (); +extern void enclosure_expand (); + +/* The @commands. */ +extern void cm_macro (), cm_rmacro (), cm_unmacro (); +extern void cm_alias (), cm_definfoenclose (); + +#endif /* not MACRO_H */ diff --git a/contrib/texinfo/makeinfo/makeinfo.h b/contrib/texinfo/makeinfo/makeinfo.h index 205a3bd..caff188 100644 --- a/contrib/texinfo/makeinfo/makeinfo.h +++ b/contrib/texinfo/makeinfo/makeinfo.h @@ -1,7 +1,7 @@ -/* makeinfo.h -- Declarations for Makeinfo. - $Id: makeinfo.h,v 1.3 1997/07/15 18:28:38 karl Exp $ +/* makeinfo.h -- declarations for Makeinfo. + $Id: makeinfo.h,v 1.25 1999/09/18 18:09:22 karl Exp $ - Copyright (C) 1996, 97 Free Software Foundation, Inc. + Copyright (C) 1996, 97, 98, 99 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -19,68 +19,44 @@ Written by Brian Fox (bfox@ai.mit.edu). */ -/* Why, oh why, did I ever listen to rms when he said: - "Don't make lots of small files, just make one big one!" I've - regretted it ever since with this program, and with readline. - bfox@ai.mit.edu Thu Jul 11 07:54:32 1996 */ - -#if !defined (MAKEINFO_H) +#ifndef MAKEINFO_H #define MAKEINFO_H -#if defined (COMPILING_MAKEINFO) -# define DECLARE(type, var, init) type var = init +#ifdef COMPILING_MAKEINFO +# define DECLARE(type,var,init) type var = init #else -# define DECLARE(type, var, init) extern type var +# define DECLARE(type,var,init) extern type var #endif -enum insertion_type -{ - cartouche, defcv, deffn, defivar, defmac, defmethod, - defop, defopt, defspec, deftp, deftypefn, deftypefun, - deftypemethod, deftypevar, deftypevr, defun, defvar, - defvr, detailmenu, direntry, display, enumerate, example, - flushleft, flushright, format, ftable, group, ifclear, - ifinfo, ifnothtml, ifnottex, ifset, itemize, lisp, menu, - multitable, quotation, smallexample, smalllisp, table, vtable, - bad_type -}; +/* Hardcoded per GNU standards, not dependent on argv[0]. */ +DECLARE (char *, progname, "makeinfo"); -DECLARE (int, insertion_level, 0); - -#if defined (COMPILING_MAKEINFO) -char *insertion_type_names[] = +enum reftype { - "cartouche", "defcv", "deffn", "defivar", "defmac", "defmethod", - "defop", "defopt", "defspec", "deftp", "deftypefn", "deftypefun", - "deftypemethod", "deftypevar", "deftypevr", "defun", "defvar", - "defvr", "detailmenu", "direntry", "display", "enumerate", "example", - "flushleft", "flushright", "format", "ftable", "group", "ifclear", - "ifinfo", "ifnothtml", "ifnottex", "ifset", "itemize", "lisp", "menu", - "multitable", "quotation", "smallexample", "smalllisp", "table", "vtable", - "bad_type" + menu_reference, followed_reference }; -#endif -typedef struct istack_elt -{ - struct istack_elt *next; - char *item_function; - char *filename; - int line_number; - int filling_enabled; - int indented_fill; - enum insertion_type insertion; - int inhibited; - int in_fixed_width_font; -} INSERTION_ELT; - -DECLARE (INSERTION_ELT *, insertion_stack, (INSERTION_ELT *)NULL); +extern char *get_xref_token (); + +/* Nonzero means a string is in execution, as opposed to a file. */ +DECLARE (int, executing_string, 0); + +/* Nonzero means to inhibit writing macro expansions to the output + stream, because it has already been written. */ +DECLARE (int, me_inhibit_expansion, 0); +extern char *expansion (), *text_expansion (); + /* Current output stream. */ -DECLARE (FILE *, output_stream, (FILE *)NULL); +DECLARE (FILE *, output_stream, NULL); + +DECLARE (char *, pretty_output_filename, NULL); + +/* Current output file name. */ +DECLARE (char *, current_output_filename, NULL); /* Output paragraph buffer. */ -DECLARE (unsigned char *, output_paragraph, (unsigned char *)NULL); +DECLARE (unsigned char *, output_paragraph, NULL); /* Offset into OUTPUT_PARAGRAPH. */ DECLARE (int, output_paragraph_offset, 0); @@ -88,46 +64,132 @@ DECLARE (int, output_paragraph_offset, 0); /* The output paragraph "cursor" horizontal position. */ DECLARE (int, output_column, 0); -/* Non-zero means output_paragraph contains text. */ +/* Position in the output file. */ +DECLARE (int, output_position, 0); + +/* The offset into OUTPUT_PARAGRAPH where we have a meta character + produced by a markup such as @code or @dfn. */ +DECLARE (int, meta_char_pos, -1); + +/* Nonzero means output_paragraph contains text. */ DECLARE (int, paragraph_is_open, 0); +/* Nonzero means that `start_paragraph' MUST be called before we pay + any attention to `close_paragraph' calls. */ +DECLARE (int, must_start_paragraph, 0); + +/* Nonzero means that we have seen "@top" once already. */ +DECLARE (int, top_node_seen, 0); + +/* Nonzero means that we have seen a non-"@top" node already. */ +DECLARE (int, non_top_node_seen, 0); + +/* Nonzero indicates that indentation is temporarily turned off. */ +DECLARE (int, no_indent, 1); + +/* Nonzero indicates that filling a line also indents the new line. */ +DECLARE (int, indented_fill, 0); + +/* Nonzero means forcing output text to be flushright. */ +DECLARE (int, force_flush_right, 0); + /* The amount of indentation to apply at the start of each line. */ DECLARE (int, current_indent, 0); -/* nonzero if we are currently processing a multitable command */ -DECLARE (int, multitable_active, 0); - /* The column at which long lines are broken. */ DECLARE (int, fill_column, 72); +/* Nonzero means that words are not to be split, even in long lines. This + gets changed for cm_w (). */ +DECLARE (int, non_splitting_words, 0); + +/* Amount by which @example indentation increases/decreases. */ +DECLARE (int, default_indentation_increment, 5); + +/* Nonzero means that we are currently hacking the insides of an + insertion which would use a fixed width font. */ +DECLARE (int, in_fixed_width_font, 0); + +/* Nonzero if we are currently processing a multitable command */ +DECLARE (int, multitable_active, 0); + +/* Nonzero means that we're generating HTML. */ +DECLARE (int, html, 0); + +/* Nonzero means escape characters in HTML output. */ +DECLARE (int, escape_html, 1); +extern char *escape_string (); /* do HTML escapes */ + +/* Nonzero means that the use of paragraph_start_indent is inhibited. + @example uses this to line up the left columns of the example text. + A negative value for this variable is incremented each time it is used. + @noindent uses this to inhibit indentation for a single paragraph. */ +DECLARE (int, inhibit_paragraph_indentation, 0); + +/* Nonzero indicates that filling will take place on long lines. */ +DECLARE (int, filling_enabled, 1); + +/* The current node's node name. */ +DECLARE (char *, current_node, NULL); + +/* Command name in the process of being hacked. */ +DECLARE (char *, command, NULL); + +/* Nonzero if the last character inserted has the syntax class of NEWLINE. */ +DECLARE (int, last_char_was_newline, 1); + /* The current input file state. */ DECLARE (char *, input_filename, (char *)NULL); DECLARE (char *, input_text, (char *)NULL); -DECLARE (int, size_of_input_text, 0); +DECLARE (int, input_text_length, 0); DECLARE (int, input_text_offset, 0); DECLARE (int, line_number, 0); - #define curchar() input_text[input_text_offset] -/* **************************************************************** */ -/* */ -/* Global Defines */ -/* */ -/* **************************************************************** */ - -/* Error levels */ -#define NO_ERROR 0 -#define SYNTAX 2 -#define FATAL 4 - + +/* A colon separated list of directories to search for files included + with @include. This can be controlled with the `-I' option to makeinfo. */ +DECLARE (char *, include_files_path, NULL); + +/* The filename of the current input file. This is never freed. */ +DECLARE (char *, node_filename, NULL); + +/* Nonzero means do not output "Node: Foo" for node separations, that + is, generate plain text. (--no-headers) */ +DECLARE (int, no_headers, 0); + +/* Nonzero means that we process @html and @rawhtml even when not + generating HTML. (--ifhtml) */ +DECLARE (int, process_html, 0); + +/* Nonzero means that we process @ifinfo even when generating HTML. + (--ifinfo) */ +DECLARE (int, process_info, 1); + +/* Nonzero means that we process @tex and @iftex. (--iftex) */ +DECLARE (int, process_tex, 0); + +/* Maximum number of references to a single node before complaining. + (--reference-limit) */ +DECLARE (int, reference_warning_limit, 1000); + +/* Default is to check node references. (--no-validate) */ +DECLARE (int, validating, 1); + +/* Nonzero means print information about what is going on. (--verbose) */ +DECLARE (int, verbose_mode, 0); + +/* Nonzero means prefix each @chapter, ... with a number like 1. (--number-sections) */ +DECLARE (int, number_sections, 0); + +/* Nonzero means expand node names and references while validating. + This will avoid errors when the Texinfo document uses features + like @@ and @value inconsistently in node names, but will slow + the program by about 80%. You HAVE been warned. */ +DECLARE (int, expensive_validation, 0); + /* C's standard macros don't check to make sure that the characters being changed are within range. So I have to check explicitly. */ -/* GNU Library doesn't have toupper(). Until GNU gets this fixed, I will - have to do it. */ -#ifndef toupper -#define toupper(c) ((c) - 32) -#endif - #define coerce_to_upper(c) ((islower(c) ? toupper(c) : (c))) #define coerce_to_lower(c) ((isupper(c) ? tolower(c) : (c))) @@ -138,9 +200,9 @@ DECLARE (int, line_number, 0); #define META(c) ((c) | (meta_character_bit)) #define UNMETA(c) ((c) & (~meta_character_bit)) -#define whitespace(c) (((c) == '\t') || ((c) == ' ')) -#define sentence_ender(c) ((c) == '.' || (c) == '?' || (c) == '!') -#define cr_or_whitespace(c) (((c) == '\t') || ((c) == ' ') || ((c) == '\n')) +#define whitespace(c) ((c) == '\t' || (c) == ' ') +#define sentence_ender(c) ((c) == '.' || (c) == '?' || (c) == '!') +#define cr_or_whitespace(c) (whitespace(c) || (c) == '\r' || (c) == '\n') #ifndef isletter #define isletter(c) (((c) >= 'A' && (c) <= 'Z') || ((c) >= 'a' && (c) <= 'z')) @@ -158,33 +220,30 @@ DECLARE (int, line_number, 0); #define digit_value(c) ((c) - '0') #endif -#define member(c, s) (strchr (s, c) != NULL) +#define HTML_SAFE "$-_.+!*'()" +#define URL_SAFE_CHAR(ch) (isalnum (ch) || strchr (HTML_SAFE, ch)) #define COMMAND_PREFIX '@' /* Stuff for splitting large files. */ #define SPLIT_SIZE_THRESHOLD 70000 /* What's good enough for Stallman... */ #define DEFAULT_SPLIT_SIZE 50000 /* Is probably good enough for me. */ - DECLARE (int, splitting, 1); /* Defaults to true for now. */ -typedef void COMMAND_FUNCTION (); /* So I can say COMMAND_FUNCTION *foo; */ - -#define command_char(c) ((!whitespace(c)) && \ - ((c) != '\n') && \ - ((c) != '{') && \ - ((c) != '}') && \ - ((c) != '=')) +#define command_char(c) (!cr_or_whitespace(c) \ + && (c) != '{' \ + && (c) != '}' \ + && (c) != '=') #define skip_whitespace() \ - while ((input_text_offset != size_of_input_text) && \ + while ((input_text_offset != input_text_length) && \ whitespace (curchar())) \ input_text_offset++ #define skip_whitespace_and_newlines() \ do { \ - while ((input_text_offset != size_of_input_text) && \ - (whitespace (curchar ()) || (curchar () == '\n'))) \ + while (input_text_offset != input_text_length \ + && cr_or_whitespace (curchar ())) \ { \ if (curchar () == '\n') \ line_number++; \ @@ -192,4 +251,10 @@ typedef void COMMAND_FUNCTION (); /* So I can say COMMAND_FUNCTION *foo; */ } \ } while (0) -#endif /* !MAKEINFO_H */ +/* Return nonzero if STRING is the text at input_text + input_text_offset, + else zero. */ +#define looking_at(string) \ + (strncmp (input_text + input_text_offset, string, strlen (string)) == 0) + + +#endif /* not MAKEINFO_H */ diff --git a/contrib/texinfo/makeinfo/multi.c b/contrib/texinfo/makeinfo/multi.c index 99c380d..b41bb47 100644 --- a/contrib/texinfo/makeinfo/multi.c +++ b/contrib/texinfo/makeinfo/multi.c @@ -1,7 +1,7 @@ /* multi.c -- multitable stuff for makeinfo. - $Id: multi.c,v 1.9 1997/07/24 22:01:00 karl Exp $ + $Id: multi.c,v 1.18 1999/08/17 21:06:56 karl Exp $ - Copyright (C) 1996, 97 Free Software Foundation, Inc. + Copyright (C) 1996, 97, 98, 99 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -18,6 +18,7 @@ Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ #include "system.h" +#include "insertion.h" #include "makeinfo.h" #define MAXCOLS 100 /* remove this limit later @@ */ @@ -51,6 +52,7 @@ struct env { unsigned char *output_paragraph; int output_paragraph_offset; + int meta_char_pos; int output_column; int paragraph_is_open; int current_indent; @@ -66,20 +68,33 @@ static int last_column; /* flags indicating whether horizontal and vertical separators need to be drawn, separating rows and columns in the current multitable. */ static int hsep, vsep; + +/* whether this is the first row. */ +static int first_row; + +static void output_multitable_row (); -/* Output a row. Have to keep `output_position' up-to-date for each - character we output, or the tags table will be off, leading to - chopped-off output files and undefined nodes (because they're in the - wrong file, etc.). Perhaps it would be better to accumulate this - value somewhere and add it once at the end of the table, or return it - as the value, but this seems simplest. */ +/* Output a row. Calls insert, but also flushes the buffered output + when we see a newline, since in multitable every line is a separate + paragraph. */ static void out_char (ch) int ch; { - extern int output_position; - putc (ch, output_stream); - output_position++; + if (html) + add_char (ch); + else + { + int env = select_output_environment (0); + insert (ch); + if (ch == '\n') + { + uninhibit_output_flushing (); + flush_output (); + inhibit_output_flushing (); + } + select_output_environment (env); + } } @@ -88,6 +103,12 @@ draw_horizontal_separator () { int i, j, s; + if (html) + { + add_word ("<hr>"); + return; + } + for (s = 0; s < envs[0].current_indent; s++) out_char (' '); if (vsep) @@ -101,34 +122,48 @@ draw_horizontal_separator () out_char ('\n'); } + +/* multitable strategy: + for each item { + for each column in an item { + initialize a new paragraph + do ordinary formatting into the new paragraph + save the paragraph away + repeat if there are more paragraphs in the column + } + dump out the saved paragraphs and free the storage + } + + For HTML we construct a simple HTML 3.2 table with <br>s inserted + to help non-tables browsers. `@item' inserts a <tr> and `@tab' + inserts <td>; we also try to close <tr>. The only real + alternative is to rely on the info formatting engine and present + preformatted text. */ + void do_multitable () { int ncolumns; - /* - * multitable strategy: - * for each item { - * for each column in an item { - * initialize a new paragraph - * do ordinary formatting into the new paragraph - * save the paragraph away - * repeat if there are more paragraphs in the column - * } - * dump out the saved paragraphs and free the storage - * } - */ - if (multitable_active) { line_error ("Multitables cannot be nested"); return; } + close_single_paragraph (); + /* scan the current item function to get the field widths and number of columns, and set up the output environment list accordingly. */ ncolumns = setup_multitable_parameters (); + first_row = 1; + + /* <p> for non-tables browsers. @multitable implicitly ends the + current paragraph, so this is ok. */ + if (html) + add_word ("<p><table>"); + if (hsep) draw_horizontal_separator (); @@ -141,6 +176,53 @@ do_multitable () ++multitable_active; } +/* Called to handle a {...} template on the @multitable line. + We're at the { and our first job is to find the matching }; as a side + effect, we change *PARAMS to point to after it. Our other job is to + expand the template text and return the width of that string. */ +static unsigned +find_template_width (params) + char **params; +{ + char *template, *xtemplate; + unsigned len; + char *start = *params; + int brace_level = 0; + + /* The first character should be a {. */ + if (!params || !*params || **params != '{') + { + line_error ("find_template width internal error: passed %s", + params ? *params : "null"); + return 0; + } + + do + { + if (**params == '{' && (*params)[-1] != '@') + brace_level++; + else if (**params == '}' && (*params)[-1] != '@') + brace_level--; + else if (**params == 0) + { + line_error (_("Missing } in @multitable template")); + return 0; + } + (*params)++; + } + while (brace_level > 0); + + template = substring (start + 1, *params - 1); /* omit braces */ + xtemplate = expansion (template, 0); + len = strlen (xtemplate); + + free (template); + free (xtemplate); + + return len; +} + + /* Read the parameters for a multitable from the current command line, save the parameters away, and return the number of columns. */ @@ -150,7 +232,7 @@ setup_multitable_parameters () char *params = insertion_stack->item_function; int nchars; float columnfrac; - char command[200]; /* naughty, should be no fixed limits */ + char command[200]; /* xx no fixed limits */ int i = 1; /* We implement @hsep and @vsep even though TeX doesn't. @@ -176,12 +258,12 @@ setup_multitable_parameters () for ( ; i <= MAXCOLS; i++) { if (sscanf (params, "%f", &columnfrac) < 1) goto done; - /* Unfortunately, can't use %n since some m68k-hp-bsd libc + /* Unfortunately, can't use %n since m68k-hp-bsd libc (at least) doesn't support it. So skip whitespace (preceding the number) and then non-whitespace (the number). */ while (*params && (*params == ' ' || *params == '\t')) params++; - /* Hmm, but what what @columnfractions 3foo. Well, I suppose + /* Hmm, but what about @columnfractions 3foo. Well, I suppose it's invalid input anyway. */ while (*params && *params != ' ' && *params != '\t' && *params != '\n' && *params != '@') @@ -192,15 +274,11 @@ setup_multitable_parameters () } } else if (*params == '{') { - char *start = params; - while ((*params != '}' || params[-1] == '@') && *params) { - params++; - } + unsigned template_width = find_template_width (¶ms); + /* This gives us two spaces between columns. Seems reasonable. - Really should expand the text, though, so a template of - `@code{foo}' has a width of five, not ten. Also have to match - braces, then. How to take into account current_indent here? */ - setup_output_environment (i++, params++ - start); + How to take into account current_indent here? */ + setup_output_environment (i++, template_width + 2); } else { warning (_("ignoring stray text `%s' after @multitable"), params); @@ -252,6 +330,7 @@ select_output_environment (n) /* stash current env info from global vars into the old environment */ e->output_paragraph = output_paragraph; e->output_paragraph_offset = output_paragraph_offset; + e->meta_char_pos = meta_char_pos; e->output_column = output_column; e->paragraph_is_open = paragraph_is_open; e->current_indent = current_indent; @@ -262,6 +341,7 @@ select_output_environment (n) e = &envs[current_env_no]; output_paragraph = e->output_paragraph; output_paragraph_offset = e->output_paragraph_offset; + meta_char_pos = e->meta_char_pos; output_column = e->output_column; paragraph_is_open = e->paragraph_is_open; current_indent = e->current_indent; @@ -281,8 +361,6 @@ nselect_next_environment () } -static void output_multitable_row (); - /* do anything needed at the beginning of processing a multitable column. */ void @@ -300,10 +378,20 @@ int multitable_item () { if (!multitable_active) { - /* impossible, I think. */ - error (_("multitable item not in active multitable")); - exit (1); + line_error ("multitable_item internal error: no active multitable"); + xexit (1); } + + if (html) + { + if (!first_row) + add_word ("<br></tr>"); /* <br> for non-tables browsers. */ + add_word ("<tr align=\"left\"><td>"); + first_row = 0; + return; + } + first_row = 0; + if (current_env_no > 0) { output_multitable_row (); } @@ -311,7 +399,7 @@ multitable_item () select_output_environment (1); if (!output_paragraph) { line_error (_("Cannot select column #%d in multitable"), current_env_no); - exit (FATAL); + exit (1); } init_column (); @@ -322,11 +410,11 @@ multitable_item () static void output_multitable_row () { - int i, j, s, remaining; - /* offset in the output paragraph of the next char needing to be output for that column. */ int offset[MAXCOLS]; + int i, j, s, remaining; + int had_newline = 0; for (i = 0; i <= last_column; i++) offset[i] = 0; @@ -340,9 +428,12 @@ output_multitable_row () /* remove trailing whitespace from each column */ for (i = 1; i <= last_column; i++) { - while (cr_or_whitespace (CHAR_AT (envs[i].output_paragraph_offset - 1))) { - envs[i].output_paragraph_offset--; - } + if (envs[i].output_paragraph_offset) + while (cr_or_whitespace (CHAR_AT (envs[i].output_paragraph_offset - 1))) + envs[i].output_paragraph_offset--; + + if (i == current_env_no) + output_paragraph_offset = envs[i].output_paragraph_offset; } /* read the current line from each column, outputting them all @@ -367,7 +458,7 @@ output_multitable_row () out_char ('|'); for (i = 1; i <= last_column; i++) { - for (s = 0; i < envs[i].current_indent; s++) + for (s = 0; s < envs[i].current_indent; s++) out_char (' '); for (j = 0; CHAR_ADDR (j) < envs[i].output_paragraph_offset; j++) { if (CHAR_AT (j) == '\n') @@ -375,13 +466,22 @@ output_multitable_row () out_char (CHAR_AT (j)); } offset[i] += j + 1; /* skip last text plus skip the newline */ - for (; j <= envs[i].fill_column; j++) - out_char (' '); + + /* Do not output trailing blanks if we're in the last column and + there will be no trailing |. */ + if (i < last_column && !vsep) + for (; j <= envs[i].fill_column; j++) + out_char (' '); if (vsep) out_char ('|'); /* draw column separator */ } out_char ('\n'); /* end of line */ + had_newline = 1; } + + /* If completely blank item, get blank line despite no other output. */ + if (!had_newline) + out_char ('\n'); /* end of line */ if (hsep) draw_horizontal_separator (); @@ -403,7 +503,11 @@ cm_tab () if (!multitable_active) error (_("ignoring @tab outside of multitable")); - nselect_next_environment (); + if (html) + add_word ("<td>"); + else + nselect_next_environment (); + init_column (); } @@ -412,17 +516,19 @@ cm_tab () void end_multitable () { - output_multitable_row (); + if (!html) + output_multitable_row (); /* Multitables cannot be nested. Otherwise, we'd have to save the previous output environment number on a stack somewhere, and then restore to that environment. */ select_output_environment (0); - close_paragraph (); - insert ('\n'); /* we swallow newlines, so insert one of our own */ - multitable_active = 0; uninhibit_output_flushing (); + close_insertion_paragraph (); + + if (html) + add_word ("<br></tr></table>\n"); #if 0 printf (_("** Multicolumn output from last row:\n")); diff --git a/contrib/texinfo/makeinfo/node.c b/contrib/texinfo/makeinfo/node.c new file mode 100644 index 0000000..8dbbd42 --- /dev/null +++ b/contrib/texinfo/makeinfo/node.c @@ -0,0 +1,1568 @@ +/* node.c -- nodes for Texinfo. + $Id: node.c,v 1.23 1999/09/20 12:31:21 karl Exp $ + + Copyright (C) 1998, 99 Free Software Foundation, Inc. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software Foundation, + Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ + +#include "system.h" +#include "cmds.h" +#include "files.h" +#include "footnote.h" +#include "macro.h" +#include "makeinfo.h" +#include "node.h" +#include "sectioning.h" +#include "insertion.h" + + +/* See comments in node.h. */ +NODE_REF *node_references = NULL; +NODE_REF *node_node_references = NULL; +TAG_ENTRY *tag_table = NULL; +int node_number = -1; +int current_section = 0; +int outstanding_node = 0; + +/* Adding nodes, and making tags. */ + +/* Start a new tag table. */ +void +init_tag_table () +{ + while (tag_table) + { + TAG_ENTRY *temp = tag_table; + free (temp->node); + free (temp->prev); + free (temp->next); + free (temp->up); + tag_table = tag_table->next_ent; + free (temp); + } +} + +/* Write out the contents of the existing tag table. + INDIRECT_P says how to format the output (it depends on whether the + table is direct or indirect). */ +static void +write_tag_table_internal (indirect_p) + int indirect_p; +{ + TAG_ENTRY *node; + int old_indent = no_indent; + + no_indent = 1; + filling_enabled = 0; + must_start_paragraph = 0; + close_paragraph (); + + if (!indirect_p) + { + no_indent = 1; + insert ('\n'); + } + + add_word_args ("\037\nTag Table:\n%s", indirect_p ? "(Indirect)\n" : ""); + + /* Do not collapse -- to -, etc., in node names. */ + in_fixed_width_font++; + + for (node = tag_table; node; node = node->next_ent) + { + if (node->flags & TAG_FLAG_ANCHOR) + { /* This reference is to an anchor. */ + execute_string ("Ref: %s", node->node); + } + else + { /* This reference is to a node. */ + execute_string ("Node: %s", node->node); + } + add_word_args ("\177%d\n", node->position); + } + + add_word ("\037\nEnd Tag Table\n"); + + /* Do not collapse -- to -, etc., in node names. */ + in_fixed_width_font--; + + flush_output (); + no_indent = old_indent; +} + +void +write_tag_table () +{ + write_tag_table_internal (0); /* Not indirect. */ +} + +void +write_tag_table_indirect () +{ + write_tag_table_internal (1); +} + +/* Convert "top" and friends into "Top". */ +static void +normalize_node_name (string) + char *string; +{ + if (strcasecmp (string, "Top") == 0) + strcpy (string, "Top"); +} + +char * +get_node_token (expand) + int expand; +{ + char *string; + + get_until_in_line (expand, ",", &string); + + if (curchar () == ',') + input_text_offset++; + + fix_whitespace (string); + + /* Force all versions of "top" to be "Top". */ + normalize_node_name (string); + + return string; +} + +/* Expand any macros and other directives in a node name, and + return the expanded name as an malloc'ed string. */ +char * +expand_node_name (node) + char *node; +{ + char *result = node; + + if (node) + { + /* Don't expand --, `` etc., in case somebody will want + to print the result. */ + in_fixed_width_font++; + result = expansion (node, 0); + in_fixed_width_font--; + fix_whitespace (result); + normalize_node_name (result); + } + return result; +} + +/* Look up NAME in the tag table, and return the associated + tag_entry. If the node is not in the table return NULL. */ +TAG_ENTRY * +find_node (name) + char *name; +{ + TAG_ENTRY *tag = tag_table; + char *expanded_name; + char n1 = name[0]; + + while (tag) + { + if (tag->node[0] == n1 && strcmp (tag->node, name) == 0) + return tag; + tag = tag->next_ent; + } + + if (!expensive_validation) + return NULL; + + /* Try harder. Maybe TAG_TABLE has the expanded NAME, or maybe NAME + is expanded while TAG_TABLE has its unexpanded form. This may + slow down the search, but if they want this feature, let them + pay! If they want it fast, they should write every node name + consistently (either always expanded or always unexpaned). */ + expanded_name = expand_node_name (name); + for (tag = tag_table; tag; tag = tag->next_ent) + { + if (STREQ (tag->node, expanded_name)) + break; + /* If the tag name doesn't have the command prefix, there's no + chance it could expand into anything but itself. */ + if (strchr (tag->node, COMMAND_PREFIX)) + { + char *expanded_node = expand_node_name (tag->node); + + if (STREQ (expanded_node, expanded_name)) + { + free (expanded_node); + break; + } + free (expanded_node); + } + } + free (expanded_name); + return tag; +} + +/* Similarly for next etc. references in a @node command, where we + don't care about most of the entries. */ +static void +remember_node_node_reference (node) + char *node; +{ + NODE_REF *temp = xmalloc (sizeof (NODE_REF)); + int number; + + if (!node) return; + temp->next = node_node_references; + temp->node = xstrdup (node); + temp->type = followed_reference; + number = number_of_node (node); + if (number) + temp->number = number; /* Already assigned. */ + else + { + node_number++; + temp->number = node_number; + } + node_node_references = temp; +} + +/* Remember NODE and associates. */ +void +remember_node (node, prev, next, up, position, line_no, flags) + char *node, *prev, *next, *up; + int position, line_no, flags; +{ + /* Check for existence of this tag already. */ + if (validating) + { + TAG_ENTRY *tag = find_node (node); + if (tag) + { + line_error (_("Node `%s' previously defined at line %d"), + node, tag->line_no); + return; + } + } + + if (!(flags & TAG_FLAG_ANCHOR)) + { + /* Make this the current node. */ + current_node = node; + } + + /* Add it to the list. */ + { + int number = number_of_node (node); + + TAG_ENTRY *new = xmalloc (sizeof (TAG_ENTRY)); + new->node = node; + new->prev = prev; + new->next = next; + new->up = up; + new->position = position; + new->line_no = line_no; + new->filename = node_filename; + new->touched = 0; + new->flags = flags; + if (number) + new->number = number; /* Already assigned. */ + else + { + node_number++; + new->number = node_number; + } + new->next_ent = tag_table; + tag_table = new; + } + + if (html) + { /* Note the references to the next etc. nodes too. */ + remember_node_node_reference (next); + remember_node_node_reference (prev); + remember_node_node_reference (up); + } +} + +/* Remember this node name for later validation use. This is used to + remember menu references while reading the input file. After the + output file has been written, if validation is on, then we use the + contents of `node_references' as a list of nodes to validate. */ +void +remember_node_reference (node, line, type) + char *node; + int line; + enum reftype type; +{ + NODE_REF *temp = xmalloc (sizeof (NODE_REF)); + int number = number_of_node (node); + + temp->next = node_references; + temp->node = xstrdup (node); + temp->line_no = line; + temp->section = current_section; + temp->type = type; + temp->containing_node = xstrdup (current_node ? current_node : ""); + temp->filename = node_filename; + if (number) + temp->number = number; /* Already assigned. */ + else + { + node_number++; + temp->number = node_number; + } + + node_references = temp; +} + +static void +isolate_nodename (nodename) + char *nodename; +{ + int i, c; + int paren_seen, paren; + + if (!nodename) + return; + + canon_white (nodename); + paren_seen = paren = i = 0; + + if (*nodename == '.' || !*nodename) + { + *nodename = 0; + return; + } + + if (*nodename == '(') + { + paren++; + paren_seen++; + i++; + } + + for (; (c = nodename[i]); i++) + { + if (paren) + { + if (c == '(') + paren++; + else if (c == ')') + paren--; + + continue; + } + + /* If the character following the close paren is a space, then this + node has no more characters associated with it. */ + if (c == '\t' || + c == '\n' || + c == ',' || + ((paren_seen && nodename[i - 1] == ')') && + (c == ' ' || c == '.')) || + (c == '.' && + ((!nodename[i + 1] || + (cr_or_whitespace (nodename[i + 1])) || + (nodename[i + 1] == ')'))))) + break; + } + nodename[i] = 0; +} + +/* This function gets called at the start of every line while inside a + menu. It checks to see if the line starts with "* ", and if so and + REMEMBER_REF is nonzero, remembers the node reference as type + REF_TYPE that this menu refers to. input_text_offset is at the \n + just before the menu line. If REMEMBER_REF is zero, REF_TYPE is unused. */ +#define MENU_STARTER "* " +char * +glean_node_from_menu (remember_ref, ref_type) + int remember_ref; + enum reftype ref_type; +{ + int i, orig_offset = input_text_offset; + char *nodename; + char *line, *expanded_line; + char *old_input = input_text; + size_t old_size = input_text_length; + + if (strncmp (&input_text[input_text_offset + 1], + MENU_STARTER, + strlen (MENU_STARTER)) != 0) + return NULL; + else + input_text_offset += strlen (MENU_STARTER) + 1; + + /* The menu entry might include macro calls, so we need to expand them. */ + get_until ("\n", &line); + only_macro_expansion++; /* only expand macros in menu entries */ + expanded_line = expansion (line, 0); + only_macro_expansion--; + free (line); + input_text = expanded_line; + input_text_offset = 0; + input_text_length = strlen (expanded_line); + + get_until_in_line (0, ":", &nodename); + if (curchar () == ':') + input_text_offset++; + + if (curchar () != ':') + { + free (nodename); + get_until_in_line (0, "\n", &nodename); + isolate_nodename (nodename); + } + + input_text = old_input; + input_text_offset = orig_offset; + input_text_length = old_size; + free (expanded_line); + fix_whitespace (nodename); + normalize_node_name (nodename); + i = strlen (nodename); + if (i && nodename[i - 1] == ':') + nodename[i - 1] = 0; + + if (remember_ref) + remember_node_reference (nodename, line_number, ref_type); + + return nodename; +} + +/* Set the name of the current output file. */ +void +set_current_output_filename (fname) + const char *fname; +{ + if (current_output_filename) + free (current_output_filename); + current_output_filename = xstrdup (fname); +} + +/* The order is: nodename, nextnode, prevnode, upnode. + If all of the NEXT, PREV, and UP fields are empty, they are defaulted. + You must follow a node command which has those fields defaulted + with a sectioning command (e.g. @chapter) giving the "level" of that node. + It is an error not to do so. + The defaults come from the menu in this node's parent. */ +void +cm_node () +{ + char *node, *prev, *next, *up; + int new_node_pos, defaulting, this_section; + int no_warn = 0; + + if (strcmp (command, "nwnode") == 0) + no_warn = TAG_FLAG_NO_WARN; + + /* Get rid of unmatched brace arguments from previous commands. */ + discard_braces (); + + /* There also might be insertions left lying around that haven't been + ended yet. Do that also. */ + discard_insertions (1); + + if (!html && !already_outputting_pending_notes) + { + close_paragraph (); + output_pending_notes (); + } + + if (html && splitting && top_node_seen) + { + /* End the current split output file. */ + close_paragraph (); + output_pending_notes (); + start_paragraph (); + /* Fixme: html: need a navigation bar here. */ + add_word ("</body></html>\n"); + close_paragraph (); + fclose (output_stream); + output_stream = NULL; + } + + filling_enabled = indented_fill = 0; + new_node_pos = output_position; + if (!html || (html && splitting)) + current_footnote_number = 1; + + if (macro_expansion_output_stream && !executing_string) + append_to_expansion_output (input_text_offset + 1); + + /* Do not collapse -- to -, etc., in node names. */ + in_fixed_width_font++; + + /* While expanding the @node line, leave any non-macros + intact, so that the macro-expanded output includes them. */ + only_macro_expansion++; + node = get_node_token (1); + only_macro_expansion--; + next = get_node_token (0); + prev = get_node_token (0); + up = get_node_token (0); + + if (verbose_mode) + printf (_("Formatting node %s...\n"), node); + + if (macro_expansion_output_stream && !executing_string) + remember_itext (input_text, input_text_offset); + + no_indent = 1; + if (!no_headers && !html) + { + add_word_args ("\037\nFile: %s, Node: ", pretty_output_filename); + + if (macro_expansion_output_stream && !executing_string) + me_execute_string (node); + else + execute_string ("%s", node); + filling_enabled = indented_fill = 0; + } + + /* Check for defaulting of this node's next, prev, and up fields. */ + defaulting = (*next == 0 && *prev == 0 && *up == 0); + + this_section = what_section (input_text + input_text_offset); + + /* If we are defaulting, then look at the immediately following + sectioning command (error if none) to determine the node's + level. Find the node that contains the menu mentioning this node + that is one level up (error if not found). That node is the "Up" + of this node. Default the "Next" and "Prev" from the menu. */ + if (defaulting) + { + NODE_REF *last_ref = NULL; + NODE_REF *ref = node_references; + + if (this_section < 0 && !STREQ (node, "Top")) + { + char *polite_section_name = "top"; + int i; + + for (i = 0; section_alist[i].name; i++) + if (section_alist[i].level == current_section + 1) + { + polite_section_name = section_alist[i].name; + break; + } + + line_error + (_("Node `%s' requires a sectioning command (e.g. %c%s)"), + node, COMMAND_PREFIX, polite_section_name); + } + else + { + if (strcmp (node, "Top") == 0) + { + /* Default the NEXT pointer to be the first menu item in + this node, if there is a menu in this node. We have to + try very hard to find the menu, as it may be obscured + by execution_strings which are on the filestack. For + every member of the filestack which has a FILENAME + member which is identical to the current INPUT_FILENAME, + search forward from that offset. */ + int saved_input_text_offset = input_text_offset; + int saved_input_text_length = input_text_length; + char *saved_input_text = input_text; + FSTACK *next_file = filestack; + + int orig_offset, orig_size; + + /* No matter what, make this file point back at `(dir)'. */ + free (up); + up = xstrdup ("(dir)"); /* html fixxme */ + + while (1) + { + orig_offset = input_text_offset; + orig_size = + search_forward (node_search_string, orig_offset); + + if (orig_size < 0) + orig_size = input_text_length; + + input_text_offset = search_forward ("\n@menu", orig_offset); + if (input_text_offset > -1 + && cr_or_whitespace (input_text[input_text_offset + 6])) + { + char *nodename_from_menu = NULL; + + input_text_offset = + search_forward ("\n* ", input_text_offset); + + if (input_text_offset != -1) + nodename_from_menu = glean_node_from_menu (0, 0); + + if (nodename_from_menu) + { + free (next); + next = nodename_from_menu; + break; + } + } + + /* We got here, so it hasn't been found yet. Try + the next file on the filestack if there is one. */ + if (next_file + && FILENAME_CMP (next_file->filename, input_filename) + == 0) + { + input_text = next_file->text; + input_text_offset = next_file->offset; + input_text_length = next_file->size; + next_file = next_file->next; + } + else + { /* No more input files to check. */ + break; + } + } + + input_text = saved_input_text; + input_text_offset = saved_input_text_offset; + input_text_length = saved_input_text_length; + } + } + + /* Fix the level of the menu references in the Top node, iff it + was declared with @top, and no subsequent reference was found. */ + if (top_node_seen && !non_top_node_seen) + { + /* Then this is the first non-@top node seen. */ + int level; + + level = set_top_section_level (this_section - 1); + non_top_node_seen = 1; + + while (ref) + { + if (ref->section == level) + ref->section = this_section - 1; + ref = ref->next; + } + + ref = node_references; + } + + while (ref) + { + if (ref->section == (this_section - 1) + && ref->type == menu_reference + && strcmp (ref->node, node) == 0) + { + char *containing_node = ref->containing_node; + + free (up); + up = xstrdup (containing_node); + + if (last_ref + && last_ref->type == menu_reference + && strcmp (last_ref->containing_node, containing_node) == 0) + { + free (next); + next = xstrdup (last_ref->node); + } + + while (ref->section == this_section - 1 + && ref->next + && ref->next->type != menu_reference) + ref = ref->next; + + if (ref->next && ref->type == menu_reference + && strcmp (ref->next->containing_node, containing_node) == 0) + { + free (prev); + prev = xstrdup (ref->next->node); + } + else if (!ref->next + && strcasecmp (ref->containing_node, "Top") == 0) + { + free (prev); + prev = xstrdup (ref->containing_node); + } + break; + } + last_ref = ref; + ref = ref->next; + } + } + + /* Insert the correct args if we are expanding macros, and the node's + pointers weren't defaulted. */ + if (macro_expansion_output_stream && !executing_string && !defaulting) + { + char *temp; + int op_orig = output_paragraph_offset; + int meta_pos_orig = meta_char_pos; + int extra = html ? strlen (node) : 0; + + temp = xmalloc (7 + extra + strlen (next) + strlen (prev) + strlen (up)); + sprintf (temp, "%s, %s, %s, %s", html ? node : "", next, prev, up); + me_execute_string (temp); + free (temp); + + output_paragraph_offset = op_orig; + meta_char_pos = meta_pos_orig; + } + + if (!*node) + { + line_error (_("No node name specified for `%c%s' command"), + COMMAND_PREFIX, command); + free (node); + free (next); next = NULL; + free (prev); prev= NULL; + free (up); up = NULL; + node_number++; /* else it doesn't get bumped */ + } + else + { + if (!*next) { free (next); next = NULL; } + if (!*prev) { free (prev); prev = NULL; } + if (!*up) { free (up); up = NULL; } + remember_node (node, prev, next, up, new_node_pos, line_number, no_warn); + outstanding_node = 1; + } + + if (html) + { + char *tem; + + if (splitting) + { /* this code not operational, we do not currently split html */ + char filename[20]; + + sprintf (filename, "node%d.html", number_of_node (node)); + output_stream = fopen (filename, "w"); + if (output_stream == NULL) + { + fs_error (filename); + xexit (1); + } + set_current_output_filename (filename); + /* FIXME: when this code is operational, we will need to + expand node, next, prev, and up before output. */ + add_word_args ("<html><head><title>%s</title>", node); + if (next) add_link (next, "rel=next"); + if (prev) add_link (prev, "rel=previous"); + if (up) add_link (up, "rel=up"); + add_word ("</head>\n<body>\n"); + } + + if (!splitting && no_headers) + { /* cross refs need a name="#anchor" even if we're not writing headers*/ + add_word ("<a name=\""); + tem = expand_node_name (node); + add_anchor_name (tem, 0); + add_word ("\"></a>"); + free (tem); + } + + if (splitting || !no_headers) + { /* Navigation bar. The <p> avoids the links area running + on with old Lynxen. */ + add_word_args ("<p>%s\n", splitting ? "" : "<hr>"); + add_word_args ("%s<a name=\"", _("Node:")); + tem = expand_node_name (node); + add_anchor_name (tem, 0); + add_word_args ("\">%s</a>", tem); + free (tem); + + if (next) + { + add_word (",\n"); + add_word (_("Next:")); + add_word ("<a rel=next href=\""); + tem = expansion (next, 0); + add_anchor_name (tem, 1); + add_word_args ("\">%s</a>", tem); + free (tem); + } + if (prev) + { + add_word (",\n"); + add_word (_("Previous:")); + add_word ("<a rel=previous href=\""); + tem = expansion (prev, 0); + add_anchor_name (tem, 1); + add_word_args ("\">%s</a>", tem); + free (tem); + } + if (up) + { + add_word (",\n"); + add_word (_("Up:")); + add_word ("<a rel=up href=\""); + tem = expansion (up, 0); + add_anchor_name (tem, 1); + add_word_args ("\">%s</a>", tem); + free (tem); + } + /* html fixxme: we want a `top' or `contents' link here. */ + + add_word_args ("\n%s<br>\n", splitting ? "<hr>" : ""); + } + } + + else if (!no_headers) + { + if (macro_expansion_output_stream) + me_inhibit_expansion++; + + /* These strings are not translatable. */ + if (next) + { + execute_string (", Next: %s", next); + filling_enabled = indented_fill = 0; + } + if (prev) + { + execute_string (", Prev: %s", prev); + filling_enabled = indented_fill = 0; + } + if (up) + { + execute_string (", Up: %s", up); + filling_enabled = indented_fill = 0; + } + if (macro_expansion_output_stream) + me_inhibit_expansion--; + } + + close_paragraph (); + no_indent = 0; + + /* Change the section only if there was a sectioning command. */ + if (this_section >= 0) + current_section = this_section; + + if (current_node && STREQ (current_node, "Top")) + top_node_seen = 1; + + filling_enabled = 1; + in_fixed_width_font--; +} + +/* Cross-reference target at an arbitrary spot. */ +void +cm_anchor (arg) + int arg; +{ + char *anchor; + + if (arg == END) + return; + + /* Parse the anchor text. */ + anchor = get_xref_token (1); + + /* In HTML mode, need to actually produce some output. */ + if (html) + { + /* If this anchor is at the beginning of a new paragraph, make + sure a new paragraph is indeed started. */ + if (!paragraph_is_open) + { + start_paragraph (); + if (!in_fixed_width_font || in_menu || in_detailmenu) + { + insert_string ("<p>"); + in_paragraph = 1; + } + } + add_word ("<a name=\""); + add_anchor_name (anchor, 0); + add_word ("\"></a>"); + } + + /* Save it in the tag table. */ + remember_node (anchor, NULL, NULL, NULL, output_position + output_column, + line_number, TAG_FLAG_ANCHOR); +} + +/* Find NODE in REF_LIST. */ +static NODE_REF * +find_node_reference (node, ref_list) + char *node; + NODE_REF *ref_list; +{ + NODE_REF *orig_ref_list = ref_list; + char *expanded_node; + + while (ref_list) + { + if (strcmp (node, ref_list->node) == 0) + break; + ref_list = ref_list->next; + } + + if (ref_list || !expensive_validation) + return ref_list; + + /* Maybe NODE is not expanded yet. This may be SLOW. */ + expanded_node = expand_node_name (node); + for (ref_list = orig_ref_list; ref_list; ref_list = ref_list->next) + { + if (STREQ (expanded_node, ref_list->node)) + break; + if (strchr (ref_list->node, COMMAND_PREFIX)) + { + char *expanded_ref = expand_node_name (ref_list->node); + + if (STREQ (expanded_node, expanded_ref)) + { + free (expanded_ref); + break; + } + free (expanded_ref); + } + } + free (expanded_node); + return ref_list; +} + +void +free_node_references () +{ + NODE_REF *list, *temp; + + list = node_references; + + while (list) + { + temp = list; + free (list->node); + free (list->containing_node); + list = list->next; + free (temp); + } + node_references = NULL; +} + +void +free_node_node_references () +{ + NODE_REF *list, *temp; + + list = node_references; + + while (list) + { + temp = list; + free (list->node); + list = list->next; + free (temp); + } + node_node_references = NULL; +} + +/* Return the number assigned to a named node in either the tag_table + or node_references list or zero if no number has been assigned. */ +int +number_of_node (node) + char *node; +{ + NODE_REF *temp_ref; + TAG_ENTRY *temp_node = find_node (node); + + if (temp_node) + return temp_node->number; + else if ((temp_ref = find_node_reference (node, node_references))) + return temp_ref->number; + else if ((temp_ref = find_node_reference (node, node_node_references))) + return temp_ref->number; + else + return 0; +} + +/* validation */ + +/* Return 1 if TAG (at LINE) correctly validated, or 0 if not. + LABEL is the (translated) description of the type of reference -- + Menu, Cross, Next, etc. */ + +static int +validate (tag, line, label) + char *tag; + int line; + char *label; +{ + TAG_ENTRY *result; + + /* If there isn't a tag to verify, or if the tag is in another file, + then it must be okay. */ + if (!tag || !*tag || *tag == '(') + return 1; + + /* Otherwise, the tag must exist. */ + result = find_node (tag); + + if (!result) + { + line_number = line; + line_error (_("%s reference to nonexistent node `%s'"), label, tag); + return 0; + } + result->touched++; + return 1; +} + +/* The strings here are followed in the message by `reference to...' in + the `validate' routine. They are only used in messages, thus are + translated. */ +static char * +reftype_type_string (type) + enum reftype type; +{ + switch (type) + { + case menu_reference: + return _("Menu"); + case followed_reference: + return _("Cross"); + default: + return "Internal-bad-reference-type"; + } +} + +static void +validate_other_references (ref_list) + NODE_REF *ref_list; +{ + char *old_input_filename = input_filename; + + while (ref_list) + { + input_filename = ref_list->filename; + validate (ref_list->node, ref_list->line_no, + reftype_type_string (ref_list->type)); + ref_list = ref_list->next; + } + input_filename = old_input_filename; +} + +/* Validation of an info file. + Scan through the list of tag entries touching the Prev, Next, and Up + elements of each. It is an error not to be able to touch one of them, + except in the case of external node references, such as "(DIR)". + + If the Prev is different from the Up, + then the Prev node must have a Next pointing at this node. + + Every node except Top must have an Up. + The Up node must contain some sort of reference, other than a Next, + to this node. + + If the Next is different from the Next of the Up, + then the Next node must have a Prev pointing at this node. */ +void +validate_file (tag_table) + TAG_ENTRY *tag_table; +{ + char *old_input_filename = input_filename; + TAG_ENTRY *tags = tag_table; + + while (tags) + { + TAG_ENTRY *temp_tag; + char *tem1, *tem2; + + input_filename = tags->filename; + line_number = tags->line_no; + + /* If this is a "no warn" node, don't validate it in any way. */ + if (tags->flags & TAG_FLAG_NO_WARN) + { + tags = tags->next_ent; + continue; + } + + /* If this node has a Next, then make sure that the Next exists. */ + if (tags->next) + { + validate (tags->next, tags->line_no, _("Next")); + + /* If the Next node exists, and there is no Up, then make sure + that the Prev of the Next points back. But do nothing if + we aren't supposed to issue warnings about this node. */ + temp_tag = find_node (tags->next); + if (temp_tag && !(temp_tag->flags & TAG_FLAG_NO_WARN)) + { + char *prev = temp_tag->prev; + int you_lose = !prev || !STREQ (prev, tags->node); + + if (you_lose && expensive_validation) + { + tem1 = expand_node_name (prev); + tem2 = expand_node_name (tags->node); + + if (STREQ (tem1, tem2)) + you_lose = 0; + free (tem1); + free (tem2); + } + if (you_lose) + { + line_error (_("Next field of node `%s' not pointed to"), + tags->node); + line_number = temp_tag->line_no; + input_filename = temp_tag->filename; + line_error (_("This node (%s) has the bad Prev"), + temp_tag->node); + input_filename = tags->filename; + line_number = tags->line_no; + temp_tag->flags |= TAG_FLAG_PREV_ERROR; + } + } + } + + /* Validate the Prev field if there is one, and we haven't already + complained about it in some way. You don't have to have a Prev + field at this stage. */ + if (!(tags->flags & TAG_FLAG_PREV_ERROR) && tags->prev) + { + int valid_p = validate (tags->prev, tags->line_no, _("Prev")); + + if (!valid_p) + tags->flags |= TAG_FLAG_PREV_ERROR; + else + { /* If the Prev field is not the same as the Up field, + then the node pointed to by the Prev field must have + a Next field which points to this node. */ + int prev_equals_up = !tags->up || STREQ (tags->prev, tags->up); + + if (!prev_equals_up && expensive_validation) + { + tem1 = expand_node_name (tags->prev); + tem2 = expand_node_name (tags->up); + prev_equals_up = STREQ (tem1, tem2); + free (tem1); + free (tem2); + } + if (!prev_equals_up) + { + temp_tag = find_node (tags->prev); + + /* If we aren't supposed to issue warnings about the + target node, do nothing. */ + if (!temp_tag || (temp_tag->flags & TAG_FLAG_NO_WARN)) + /* Do nothing. */ ; + else + { + int you_lose = !temp_tag->next + || !STREQ (temp_tag->next, tags->node); + + if (temp_tag->next && you_lose && expensive_validation) + { + tem1 = expand_node_name (temp_tag->next); + tem2 = expand_node_name (tags->node); + if (STREQ (tem1, tem2)) + you_lose = 0; + free (tem1); + free (tem2); + } + if (you_lose) + { + line_error + (_("Prev field of node `%s' not pointed to"), + tags->node); + line_number = temp_tag->line_no; + input_filename = temp_tag->filename; + line_error (_("This node (%s) has the bad Next"), + temp_tag->node); + input_filename = tags->filename; + line_number = tags->line_no; + temp_tag->flags |= TAG_FLAG_NEXT_ERROR; + } + } + } + } + } + + if (!tags->up + && !(tags->flags & TAG_FLAG_ANCHOR) + && strcasecmp (tags->node, "Top") != 0) + line_error (_("`%s' has no Up field"), tags->node); + else if (tags->up) + { + int valid_p = validate (tags->up, tags->line_no, _("Up")); + + /* If node X has Up: Y, then warn if Y fails to have a menu item + or note pointing at X, if Y isn't of the form "(Y)". */ + if (valid_p && *tags->up != '(') + { + NODE_REF *nref; + NODE_REF *tref = NULL; + NODE_REF *list = node_references; + + for (;;) + { + nref = find_node_reference (tags->node, list); + if (!nref) + break; + + if (strcmp (nref->containing_node, tags->up) == 0) + { + if (nref->type != menu_reference) + { + tref = nref; + list = nref->next; + } + else + break; + } + list = nref->next; + } + + if (!nref) + { + if (!tref && expensive_validation) + { + /* Sigh... This might be AWFULLY slow, but if + they want this feature, they'll have to pay! + We do all the loop again expanding each + containing_node reference as we go. */ + char *tags_up = expand_node_name (tags->up); + char *tem; + + list = node_references; + + for (;;) + { + nref = find_node_reference (tags->node, list); + if (!nref) + break; + tem = expand_node_name (nref->containing_node); + if (STREQ (tem, tags_up)) + { + if (nref->type != menu_reference) + tref = nref; + else + { + free (tem); + break; + } + } + free (tem); + list = nref->next; + } + } + if (!nref && !tref) + { + temp_tag = find_node (tags->up); + line_number = temp_tag->line_no; + input_filename = temp_tag->filename; + line_error ( + _("Node `%s' lacks menu item for `%s' despite being its Up target"), + tags->up, tags->node); + line_number = tags->line_no; + input_filename = tags->filename; + } + } + } + } + tags = tags->next_ent; + } + + validate_other_references (node_references); + /* We have told the user about the references which didn't exist. + Now tell him about the nodes which aren't referenced. */ + + for (tags = tag_table; tags; tags = tags->next_ent) + { + /* If this node is a "no warn" node, do nothing. */ + if (tags->flags & TAG_FLAG_NO_WARN) + { + tags = tags->next_ent; + continue; + } + + /* Special hack. If the node in question appears to have + been referenced more than REFERENCE_WARNING_LIMIT times, + give a warning. */ + if (tags->touched > reference_warning_limit) + { + input_filename = tags->filename; + line_number = tags->line_no; + warning (_("node `%s' has been referenced %d times"), + tags->node, tags->touched); + } + + if (tags->touched == 0) + { + input_filename = tags->filename; + line_number = tags->line_no; + + /* Notice that the node "Top" is special, and doesn't have to + be referenced. Anchors don't have to be referenced + either, you might define them for another document. */ + if (strcasecmp (tags->node, "Top") != 0 + && !(tags->flags & TAG_FLAG_ANCHOR)) + warning (_("unreferenced node `%s'"), tags->node); + } + } + input_filename = old_input_filename; +} + + +/* Splitting */ + +/* Return true if the tag entry pointed to by TAGS is the last node. + This means only anchors follow. */ + +static int +last_node_p (tags) + TAG_ENTRY *tags; +{ + int last = 1; + while (tags->next_ent) { + tags = tags->next_ent; + if (tags->flags & TAG_FLAG_ANCHOR) + ; + else + { + last = 0; + break; + } + } + + return last; +} + + +/* Split large output files into a series of smaller files. Each file + is pointed to in the tag table, which then gets written out as the + original file. The new files have the same name as the original file + with a "-num" attached. SIZE is the largest number of bytes to allow + in any single split file. */ +void +split_file (filename, size) + char *filename; + int size; +{ + char *root_filename, *root_pathname; + char *the_file, *filename_part (); + struct stat fileinfo; + long file_size; + char *the_header; + int header_size; + int dos_file_names = 0; /* if nonzero, don't exceed 8+3 limits */ + + /* Can only do this to files with tag tables. */ + if (!tag_table) + return; + + if (size == 0) + size = DEFAULT_SPLIT_SIZE; + + if ((stat (filename, &fileinfo) != 0) || + (((long) fileinfo.st_size) < SPLIT_SIZE_THRESHOLD)) + return; + file_size = (long) fileinfo.st_size; + + the_file = find_and_load (filename); + if (!the_file) + return; + + root_filename = filename_part (filename); + root_pathname = pathname_part (filename); + + /* Do we need to generate names of subfiles which don't exceed 8+3 limits? */ + dos_file_names = !HAVE_LONG_FILENAMES (root_pathname ? root_pathname : "."); + + if (!root_pathname) + root_pathname = xstrdup (""); + + /* Start splitting the file. Walk along the tag table + outputting sections of the file. When we have written + all of the nodes in the tag table, make the top-level + pointer file, which contains indirect pointers and + tags for the nodes. */ + { + int which_file = 1; + TAG_ENTRY *tags = tag_table; + char *indirect_info = NULL; + + /* Remember the `header' of this file. The first tag in the file is + the bottom of the header; the top of the file is the start. */ + the_header = xmalloc (1 + (header_size = tags->position)); + memcpy (the_header, the_file, header_size); + + while (tags) + { + int file_top, file_bot, limit; + + /* Have to include the Control-_. */ + file_top = file_bot = tags->position; + limit = file_top + size; + + /* If the rest of this file is only one node, then + that is the entire subfile. */ + if (last_node_p (tags)) + { + int i = tags->position + 1; + char last_char = the_file[i]; + + while (i < file_size) + { + if ((the_file[i] == '\037') && + ((last_char == '\n') || + (last_char == '\014'))) + break; + else + last_char = the_file[i]; + i++; + } + file_bot = i; + tags = tags->next_ent; + goto write_region; + } + + /* Otherwise, find the largest number of nodes that can fit in + this subfile. */ + for (; tags; tags = tags->next_ent) + { + if (last_node_p (tags)) + { + /* This entry is the last node. Search forward for the end + of this node, and that is the end of this file. */ + int i = tags->position + 1; + char last_char = the_file[i]; + + while (i < file_size) + { + if ((the_file[i] == '\037') && + ((last_char == '\n') || + (last_char == '\014'))) + break; + else + last_char = the_file[i]; + i++; + } + file_bot = i; + + if (file_bot < limit) + { + tags = tags->next_ent; + goto write_region; + } + else + { + /* Here we want to write out everything before the last + node, and then write the last node out in a file + by itself. */ + file_bot = tags->position; + goto write_region; + } + } + + /* Write region only if this was a node, not an anchor. */ + if (tags->next_ent->position > limit + && !(tags->flags & TAG_FLAG_ANCHOR)) + { + if (tags->position == file_top) + tags = tags->next_ent; + + file_bot = tags->position; + + write_region: + { + int fd; + char *split_filename, *split_basename; + unsigned root_len = strlen (root_filename); + + split_filename = xmalloc (10 + strlen (root_pathname) + + root_len); + split_basename = xmalloc (10 + root_len); + sprintf (split_basename, "%s-%d", root_filename, which_file); + if (dos_file_names) + { + char *dot = strchr (split_basename, '.'); + unsigned base_len = strlen (split_basename); + + if (dot) + { /* Make foobar.i1, .., foobar.i99, foobar.100, ... */ + dot[1] = 'i'; + memmove (which_file <= 99 ? dot + 2 : dot + 1, + split_basename + root_len + 1, + strlen (split_basename + root_len + 1) + 1); + } + else if (base_len > 8) + { + /* Make foobar-1, .., fooba-10, .., foob-100, ... */ + unsigned numlen = base_len - root_len; + + memmove (split_basename + 8 - numlen, + split_basename + root_len, numlen + 1); + } + } + sprintf (split_filename, "%s%s", root_pathname, + split_basename); + + fd = open (split_filename, O_WRONLY|O_TRUNC|O_CREAT, 0666); + if (fd < 0 + || write (fd, the_header, header_size) != header_size + || write (fd, the_file + file_top, file_bot - file_top) + != (file_bot - file_top) + || (close (fd)) < 0) + { + perror (split_filename); + if (fd != -1) + close (fd); + xexit (1); + } + + if (!indirect_info) + { + indirect_info = the_file + file_top; + sprintf (indirect_info, "\037\nIndirect:\n"); + indirect_info += strlen (indirect_info); + } + + sprintf (indirect_info, "%s: %d\n", + split_basename, file_top); + + free (split_basename); + free (split_filename); + indirect_info += strlen (indirect_info); + which_file++; + break; + } + } + } + } + + /* We have sucessfully created the subfiles. Now write out the + original again. We must use `output_stream', or + write_tag_table_indirect () won't know where to place the output. */ + output_stream = fopen (filename, "w"); + if (!output_stream) + { + perror (filename); + xexit (1); + } + + { + int distance = indirect_info - the_file; + fwrite (the_file, 1, distance, output_stream); + + /* Inhibit newlines. */ + paragraph_is_open = 0; + + write_tag_table_indirect (); + fclose (output_stream); + free (the_header); + free (the_file); + return; + } + } +} diff --git a/contrib/texinfo/makeinfo/node.h b/contrib/texinfo/makeinfo/node.h new file mode 100644 index 0000000..e2fc883 --- /dev/null +++ b/contrib/texinfo/makeinfo/node.h @@ -0,0 +1,111 @@ +/* node.h -- declarations for Node. + $Id: node.h,v 1.5 1999/07/11 16:50:19 karl Exp $ + + Copyright (C) 1996, 97, 98, 99 Free Software Foundation, Inc. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + + Written by Brian Fox (bfox@ai.mit.edu). */ + +#ifndef NODE_H +#define NODE_H + +/* The various references that we know about. */ +/* What we remember for each node. */ +typedef struct tentry +{ + struct tentry *next_ent; + char *node; /* Name of this node. */ + char *prev; /* Name of "Prev:" for this node. */ + char *next; /* Name of "Next:" for this node. */ + char *up; /* Name of "Up:" for this node. */ + int position; /* Output file position of this node. */ + int line_no; /* Defining line in source file. */ + char *filename; /* The file that this node was found in. */ + int touched; /* Nonzero means this node has been referenced. */ + int flags; + int number; /* Number for this node, relevant for HTML + splitting -- from use+define order, not just + define. */ +} TAG_ENTRY; + +/* If node-a has a "Next" for node-b, but node-b has no "Prev" for node-a, + we turn on this flag bit in node-b's tag entry. This means that when + it is time to validate node-b, we don't report an additional error + if there was no "Prev" field. */ +#define TAG_FLAG_PREV_ERROR 1 +#define TAG_FLAG_NEXT_ERROR 2 +#define TAG_FLAG_UP_ERROR 4 +#define TAG_FLAG_NO_WARN 8 +#define TAG_FLAG_IS_TOP 16 +#define TAG_FLAG_ANCHOR 32 + +/* Menu reference, *note reference, and validation hacking. */ + +/* A structure to remember references with. A reference to a node is + either an entry in a menu, or a cross-reference made with [px]ref. */ +typedef struct node_ref +{ + struct node_ref *next; + char *node; /* Name of node referred to. */ + char *containing_node; /* Name of node containing this reference. */ + int line_no; /* Line number where the reference occurs. */ + int section; /* Section level where the reference occurs. */ + char *filename; /* Name of file where the reference occurs. */ + enum reftype type; /* Type of reference, either menu or note. */ + int number; /* Number for this node, relevant for + HTML splitting -- from use+define + order, not just define. */ +} NODE_REF; + +/* The linked list of such structures. */ +extern NODE_REF *node_references; + +/* A similar list for references occuring in @node next + and similar references, needed for HTML. */ +extern NODE_REF *node_node_references; + +/* List of all nodes. */ +extern TAG_ENTRY *tag_table; + +/* Counter for setting node_ref.number; zero is Top. */ +extern int node_number; + +/* The current node's section level. */ +extern int current_section; + +/* Nonzero when the next sectioning command should generate an anchor + corresponding to the current node in HTML mode. */ +extern int outstanding_node; + +extern TAG_ENTRY *find_node (); + +/* A search string which is used to find a line defining a node. */ +DECLARE (char *, node_search_string, "\n@node "); + +/* Extract node name from a menu item. */ +extern char *glean_node_from_menu (); + +/* Remember a node for later validation. */ +extern void remember_node_reference (); + +/* Remember the name of the current output file. */ +extern void set_current_output_filename (); + +/* Expand macros and commands in the node name and canonicalize + whitespace in the resulting expansion. */ +extern char *expand_node_name (); + +#endif /* NODE_H */ diff --git a/contrib/texinfo/makeinfo/sectioning.c b/contrib/texinfo/makeinfo/sectioning.c new file mode 100644 index 0000000..b06785b --- /dev/null +++ b/contrib/texinfo/makeinfo/sectioning.c @@ -0,0 +1,691 @@ +/* sectioning.c -- all related stuff @chapter, @section... @contents + $Id: sectioning.c,v 1.12 1999/08/17 21:06:50 karl Exp $ + + Copyright (C) 1999 Free Software Foundation, Inc. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + + Written by Karl Heinz Marbaise <kama@hippo.fido.de>. */ + +#include "system.h" +#include "cmds.h" +#include "macro.h" +#include "makeinfo.h" +#include "node.h" +#include "toc.h" +#include "sectioning.h" + +/* See comment in sectioning.h. */ +section_alist_type section_alist[] = { + { "unnumberedsubsubsec", 5, ENUM_SECT_NO, TOC_YES }, + { "unnumberedsubsec", 4, ENUM_SECT_NO, TOC_YES }, + { "unnumberedsec", 3, ENUM_SECT_NO, TOC_YES }, + { "unnumbered", 2, ENUM_SECT_NO, TOC_YES }, + + { "appendixsubsubsec", 5, ENUM_SECT_APP, TOC_YES }, /* numbered like A.X.X.X */ + { "appendixsubsec", 4, ENUM_SECT_APP, TOC_YES }, + { "appendixsec", 3, ENUM_SECT_APP, TOC_YES }, + { "appendixsection", 3, ENUM_SECT_APP, TOC_YES }, + { "appendix", 2, ENUM_SECT_APP, TOC_YES }, + + { "subsubsec", 5, ENUM_SECT_YES, TOC_YES }, + { "subsubsection", 5, ENUM_SECT_YES, TOC_YES }, + { "subsection", 4, ENUM_SECT_YES, TOC_YES }, + { "section", 3, ENUM_SECT_YES, TOC_YES }, + { "chapter", 2, ENUM_SECT_YES, TOC_YES }, + + { "subsubheading", 5, ENUM_SECT_NO, TOC_NO }, + { "subheading", 4, ENUM_SECT_NO, TOC_NO }, + { "heading", 3, ENUM_SECT_NO, TOC_NO }, + { "chapheading", 2, ENUM_SECT_NO, TOC_NO }, + { "majorheading", 2, ENUM_SECT_NO, TOC_NO }, + + { "top", 1, ENUM_SECT_NO, TOC_YES }, + { NULL, 0, 0, 0 } +}; + +/* The argument of @settitle, used for HTML. */ +char *title = NULL; + + +#define APPENDIX_MAGIC 1024 +#define UNNUMBERED_MAGIC 2048 + +/* Number memory for every level @chapter, @section, + @subsection, @subsubsection. */ +static int numbers [] = { 0, 0, 0, 0 }; + +/* enum_marker == APPENDIX_MAGIC then we are counting appendencies + enum_marker == UNNUMBERED_MAGIC then we are within unnumbered area. + Handling situations like this: + @unnumbered .. + @section ... */ +static int enum_marker = 0; + +/* Organized by level commands. That is, "*" == chapter, "=" == section. */ +static char *scoring_characters = "*=-."; + +/* Amount to offset the name of sectioning commands to levels by. */ +static int section_alist_offset = 0; + + +/* num == ENUM_SECT_NO means unnumbered (should never call this) + num == ENUM_SECT_YES means numbered + num == ENUM_SECT_APP means numbered like A.1 and so on */ +char * +get_sectioning_number (level, num) + int level; + int num; +{ + static char s[100]; /* should ever be enough for 99.99.99.99 + Appendix A.1 */ + + char *p; + int i; + + s[0] = 0; + + /* create enumeration in front of chapter, section, subsection and so on. */ + for (i = 0; i < level; i++) + { + p = s + strlen (s); + if ((i == 0) && (enum_marker == APPENDIX_MAGIC)) + sprintf (p, "%c.", numbers[i] + 64); /* Should be changed to + be more portable */ + else + sprintf (p, "%d.", numbers[i]); + } + + /* the last number is never followed by a dot */ + p = s + strlen (s); + if ((num == ENUM_SECT_APP) + && (i == 0) + && (enum_marker == APPENDIX_MAGIC)) + sprintf (p, _("Appendix %c "), numbers[i] + 64); + else + sprintf (p, "%d ", numbers[i]); + + return s; +} + + +/* Set the level of @top to LEVEL. Return the old level of @top. */ +int +set_top_section_level (level) + int level; +{ + int i, result = -1; + + for (i = 0; section_alist[i].name; i++) + if (strcmp (section_alist[i].name, "top") == 0) + { + result = section_alist[i].level; + section_alist[i].level = level; + break; + } + return result; +} + + +/* return the index of the given sectioning command in section_alist */ +int +search_sectioning (text) + char *text; +{ + int i; + char *t; + + /* ignore the optional command prefix */ + if (text[0] == COMMAND_PREFIX) + text++; + + for (i = 0; (t = section_alist[i].name); i++) + { + if (strcmp (t, text) == 0) + { + return i; + } + } + return -1; +} + +/* Return an integer which identifies the type section present in TEXT. */ +int +what_section (text) + char *text; +{ + int index, j; + char *temp; + int return_val; + + find_section_command: + for (j = 0; text[j] && cr_or_whitespace (text[j]); j++); + if (text[j] != COMMAND_PREFIX) + return -1; + + text = text + j + 1; + + /* We skip @c, @comment, and @?index commands. */ + if ((strncmp (text, "comment", strlen ("comment")) == 0) || + (text[0] == 'c' && cr_or_whitespace (text[1])) || + (strcmp (text + 1, "index") == 0)) + { + while (*text++ != '\n'); + goto find_section_command; + } + + /* Handle italicized sectioning commands. */ + if (*text == 'i') + text++; + + for (j = 0; text[j] && !cr_or_whitespace (text[j]); j++); + + temp = xmalloc (1 + j); + strncpy (temp, text, j); + temp[j] = 0; + + index = search_sectioning (temp); + free (temp); + if (index >= 0) + { + return_val = section_alist[index].level + section_alist_offset; + if (return_val < 0) + return_val = 0; + else if (return_val > 5) + return_val = 5; + return return_val; + } + return -1; +} + + +void +sectioning_underscore (cmd) + char *cmd; +{ + char character; + char *temp; + int level; + + temp = xmalloc (2 + strlen (cmd)); + temp[0] = COMMAND_PREFIX; + strcpy (&temp[1], cmd); + level = what_section (temp); + free (temp); + level -= 2; + + if (level < 0) + level = 0; + + if (html) + sectioning_html (level, cmd); + else + { + character = scoring_characters[level]; + insert_and_underscore (level, character, cmd); + } +} + +/* insert_and_underscore and sectioning_html are the + only functions which call this. + I have created this, because it was exactly the same + code in both functions. */ +static char * +handle_enum_increment (level, index) + int level; + int index; +{ + /* special for unnumbered */ + if (number_sections && section_alist[index].num == ENUM_SECT_NO) + { + if (level == 0 + && enum_marker != UNNUMBERED_MAGIC) + enum_marker = UNNUMBERED_MAGIC; + } + /* enumerate only things which are allowed */ + if (number_sections && section_alist[index].num) + { + /* reset the marker if we get into enumerated areas */ + if (section_alist[index].num == ENUM_SECT_YES + && level == 0 + && enum_marker == UNNUMBERED_MAGIC) + enum_marker = 0; + /* This is special for appendix; if we got the first + time an appendix command then we are entering appendix. + Thats the point we have to start countint with A, B and so on. */ + if (section_alist[index].num == ENUM_SECT_APP + && level == 0 + && enum_marker != APPENDIX_MAGIC) + { + enum_marker = APPENDIX_MAGIC; + numbers [0] = 0; /* this means we start with Appendix A */ + } + + /* only increment counters if we are not in unnumbered + area. This handles situations like this: + @unnumbered .... This sets enum_marker to UNNUMBERED_MAGIC + @section .... */ + if (enum_marker != UNNUMBERED_MAGIC) + { + int i; + + /* reset all counters which are one level deeper */ + for (i = level; i < 3; i++) + numbers [i + 1] = 0; + + numbers[level]++; + return xstrdup + (get_sectioning_number (level, section_alist[index].num)); + } + } /* if (number_sections)... */ + + return xstrdup (""); +} + + +/* Insert the text following input_text_offset up to the end of the line + in a new, separate paragraph. Directly underneath it, insert a + line of WITH_CHAR, the same length of the inserted text. */ +void +insert_and_underscore (level, with_char, cmd) + int level; + int with_char; + char *cmd; +{ + int i, len; + int index; + int old_no_indent; + unsigned char *starting_pos, *ending_pos; + char *temp; + + close_paragraph (); + filling_enabled = indented_fill = 0; + old_no_indent = no_indent; + no_indent = 1; + + if (macro_expansion_output_stream && !executing_string) + append_to_expansion_output (input_text_offset + 1); + + get_rest_of_line (0, &temp); + starting_pos = output_paragraph + output_paragraph_offset; + + index = search_sectioning (cmd); + if (index < 0) + { + /* should never happen, but a poor guy, named Murphy ... */ + warning (_("Internal error (search_sectioning) \"%s\"!"), cmd); + return; + } + + /* This is a bit tricky: we must produce "X.Y SECTION-NAME" in the + Info output and in TOC, but only SECTION-NAME in the macro-expanded + output. */ + + /* Step 1: produce "X.Y" and add it to Info output. */ + add_word (handle_enum_increment (level, index)); + + /* Step 2: add "SECTION-NAME" to both Info and macro-expanded output. */ + if (macro_expansion_output_stream && !executing_string) + { + char *temp1 = xmalloc (2 + strlen (temp)); + sprintf (temp1, "%s\n", temp); + remember_itext (input_text, input_text_offset); + me_execute_string (temp1); + free (temp1); + } + else + execute_string ("%s\n", temp); + + /* Step 3: pluck "X.Y SECTION-NAME" from the output buffer and + insert it into the TOC. */ + ending_pos = output_paragraph + output_paragraph_offset; + if (section_alist[index].toc == TOC_YES) + toc_add_entry (substring (starting_pos, ending_pos - 1), + level, current_node, NULL); + + free (temp); + + len = (ending_pos - starting_pos) - 1; + for (i = 0; i < len; i++) + add_char (with_char); + insert ('\n'); + close_paragraph (); + filling_enabled = 1; + no_indent = old_no_indent; +} + +/* Insert the text following input_text_offset up to the end of the + line as an HTML heading element of the appropriate `level' and + tagged as an anchor for the current node.. */ +void +sectioning_html (level, cmd) + int level; + char *cmd; +{ + static int toc_ref_count = 0; + int index; + int old_no_indent; + unsigned char *starting_pos, *ending_pos; + char *temp, *toc_anchor = NULL; + + close_paragraph (); + filling_enabled = indented_fill = 0; + old_no_indent = no_indent; + no_indent = 1; + + add_word_args ("<h%d>", level + 1); /* level 0 is <h1> */ + + /* If we are outside of any node, produce an anchor that + the TOC could refer to. */ + if (!current_node || !*current_node) + { + starting_pos = output_paragraph + output_paragraph_offset; + add_word_args ("<a name=\"TOC%d\">", toc_ref_count++); + toc_anchor = substring (starting_pos + 9, + output_paragraph + output_paragraph_offset); + } + starting_pos = output_paragraph + output_paragraph_offset; + + if (macro_expansion_output_stream && !executing_string) + append_to_expansion_output (input_text_offset + 1); + + get_rest_of_line (0, &temp); + + index = search_sectioning (cmd); + if (index < 0) + { + /* should never happen, but a poor guy, named Murphy ... */ + warning (_("Internal error (search_sectioning) \"%s\"!"), cmd); + return; + } + + /* Produce "X.Y" and add it to HTML output. */ + add_word (handle_enum_increment (level, index)); + + /* add the section name to both HTML and macro-expanded output. */ + if (macro_expansion_output_stream && !executing_string) + { + remember_itext (input_text, input_text_offset); + me_execute_string (temp); + write_region_to_macro_output ("\n", 0, 1); + } + else + execute_string ("%s", temp); + + ending_pos = output_paragraph + output_paragraph_offset; + + /* Pluck ``X.Y SECTION-NAME'' from the output buffer and insert it + into the TOC. */ + if (section_alist[index].toc == TOC_YES) + toc_add_entry (substring (starting_pos, ending_pos), + level, current_node, toc_anchor); + + free (temp); + + if (outstanding_node) + outstanding_node = 0; + + add_word_args ("</h%d>", level+1); + close_paragraph(); + filling_enabled = 1; + no_indent = old_no_indent; +} + + +/* Shift the meaning of @section to @chapter. */ +void +cm_raisesections () +{ + discard_until ("\n"); + section_alist_offset--; +} + +/* Shift the meaning of @chapter to @section. */ +void +cm_lowersections () +{ + discard_until ("\n"); + section_alist_offset++; +} + +/* The command still works, but prints a warning message in addition. */ +void +cm_ideprecated (arg, start, end) + int arg, start, end; +{ + warning (_("%c%s is obsolete; use %c%s instead"), + COMMAND_PREFIX, command, COMMAND_PREFIX, command + 1); + sectioning_underscore (command + 1); +} + + +/* Treat this just like @unnumbered. The only difference is + in node defaulting. */ +void +cm_top () +{ + /* It is an error to have more than one @top. */ + if (top_node_seen && strcmp (current_node, "Top") != 0) + { + TAG_ENTRY *tag = tag_table; + + line_error (_("Node with %ctop as a section already exists"), + COMMAND_PREFIX); + + while (tag) + { + if (tag->flags & TAG_FLAG_IS_TOP) + { + int old_line_number = line_number; + char *old_input_filename = input_filename; + + line_number = tag->line_no; + input_filename = tag->filename; + line_error (_("Here is the %ctop node"), COMMAND_PREFIX); + input_filename = old_input_filename; + line_number = old_line_number; + return; + } + tag = tag->next_ent; + } + } + else + { + TAG_ENTRY *top_node = find_node ("Top"); + top_node_seen = 1; + + /* It is an error to use @top before you have used @node. */ + if (!tag_table) + { + char *top_name; + + get_rest_of_line (0, &top_name); + line_error (_("%ctop used before %cnode, defaulting to %s"), + COMMAND_PREFIX, COMMAND_PREFIX, top_name); + execute_string ("@node Top, , (dir), (dir)\n@top %s\n", top_name); + free (top_name); + return; + } + else if (html && splitting) + { + char *next = top_node ? top_node->next : NULL; + + add_word ("<p>"); + if (next) + { + add_word (_("Next:")); + add_word ("<a rel=next href=\""); + add_anchor_name (next, 1); + add_word ("\">"); + execute_string (next); + add_word ("</a>\n"); + } + } + + cm_unnumbered (); + + /* The most recently defined node is the top node. */ + tag_table->flags |= TAG_FLAG_IS_TOP; + + /* Now set the logical hierarchical level of the Top node. */ + { + int orig_offset = input_text_offset; + + input_text_offset = search_forward (node_search_string, orig_offset); + + if (input_text_offset > 0) + { + int this_section; + + /* We have encountered a non-top node, so mark that one exists. */ + non_top_node_seen = 1; + + /* Move to the end of this line, and find out what the + sectioning command is here. */ + while (input_text[input_text_offset] != '\n') + input_text_offset++; + + if (input_text_offset < input_text_length) + input_text_offset++; + + this_section = what_section (input_text + input_text_offset); + + /* If we found a sectioning command, then give the top section + a level of this section - 1. */ + if (this_section != -1) + set_top_section_level (this_section - 1); + } + input_text_offset = orig_offset; + } + } +} + +/* The remainder of the text on this line is a chapter heading. */ +void +cm_chapter () +{ + sectioning_underscore ("chapter"); +} + +/* The remainder of the text on this line is a section heading. */ +void +cm_section () +{ + sectioning_underscore ("section"); +} + +/* The remainder of the text on this line is a subsection heading. */ +void +cm_subsection () +{ + sectioning_underscore ("subsection"); +} + +/* The remainder of the text on this line is a subsubsection heading. */ +void +cm_subsubsection () +{ + sectioning_underscore ("subsubsection"); +} + +/* The remainder of the text on this line is an unnumbered heading. */ +void +cm_unnumbered () +{ + sectioning_underscore ("unnumbered"); +} + +/* The remainder of the text on this line is an unnumbered section heading. */ +void +cm_unnumberedsec () +{ + sectioning_underscore ("unnumberedsec"); +} + +/* The remainder of the text on this line is an unnumbered + subsection heading. */ +void +cm_unnumberedsubsec () +{ + sectioning_underscore ("unnumberedsubsec"); +} + +/* The remainder of the text on this line is an unnumbered + subsubsection heading. */ +void +cm_unnumberedsubsubsec () +{ + sectioning_underscore ("unnumberedsubsubsec"); +} + +/* The remainder of the text on this line is an appendix heading. */ +void +cm_appendix () +{ + sectioning_underscore ("appendix"); +} + +/* The remainder of the text on this line is an appendix section heading. */ +void +cm_appendixsec () +{ + sectioning_underscore ("appendixsec"); +} + +/* The remainder of the text on this line is an appendix subsection heading. */ +void +cm_appendixsubsec () +{ + sectioning_underscore ("appendixsubsec"); +} + +/* The remainder of the text on this line is an appendix + subsubsection heading. */ +void +cm_appendixsubsubsec () +{ + sectioning_underscore ("appendixsubsubsec"); +} + +/* Compatibility functions substitute for chapter, section, etc. */ +void +cm_majorheading () +{ + sectioning_underscore ("majorheading"); +} + +void +cm_chapheading () +{ + sectioning_underscore ("chapheading"); +} + +void +cm_heading () +{ + sectioning_underscore ("heading"); +} + +void +cm_subheading () +{ + sectioning_underscore ("subheading"); +} + +void +cm_subsubheading () +{ + sectioning_underscore ("subsubheading"); +} diff --git a/contrib/texinfo/makeinfo/sectioning.h b/contrib/texinfo/makeinfo/sectioning.h new file mode 100644 index 0000000..75243f0 --- /dev/null +++ b/contrib/texinfo/makeinfo/sectioning.h @@ -0,0 +1,80 @@ +/* sectioning.h -- all related stuff @chapter, @section... @contents + $Id: sectioning.h,v 1.2 1999/03/09 22:48:15 karl Exp $ + + Copyright (C) 1999 Free Software Foundation, Inc. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + + Written by Karl Heinz Marbaise <kama@hippo.fido.de>. */ + +#ifndef SECTIONING_H +#define SECTIONING_H + +/* Sectioning. */ +extern void + cm_chapter (), cm_unnumbered (), cm_appendix (), cm_top (), + cm_section (), cm_unnumberedsec (), cm_appendixsec (), + cm_subsection (), cm_unnumberedsubsec (), cm_appendixsubsec (), + cm_subsubsection (), cm_unnumberedsubsubsec (), cm_appendixsubsubsec (), + cm_heading (), cm_chapheading (), cm_subheading (), cm_subsubheading (), + cm_majorheading (), cm_raisesections (), cm_lowersections (), + + cm_ideprecated (); + +extern void + sectioning_underscore (), insert_and_underscore (); + +extern int what_section (); + + + +/* is needed in node.c */ +extern int set_top_section_level (); + +extern void sectioning_html (); +extern int what_section (); + +/* The argument of @settitle, used for HTML. */ +extern char *title; + + +/* Here is a structure which associates sectioning commands with + an integer that reflects the depth of the current section. */ +typedef struct +{ + char *name; + int level; /* I can't replace the levels with defines + because it is changed during run */ + int num; /* ENUM_SECT_NO means no enumeration... + ENUM_SECT_YES means enumerated version + ENUM_SECT_APP appendix (Character enumerated + at first position */ + int toc; /* TOC_NO means do not enter in toc; + TOC_YES means enter it in toc */ +} section_alist_type; + +extern section_alist_type section_alist[]; + +/* enumerate sections */ +#define ENUM_SECT_NO 0 +#define ENUM_SECT_YES 1 +#define ENUM_SECT_APP 2 + +/* make entries into toc no/yes */ +#define TOC_NO 0 +#define TOC_YES 1 + + +#endif /* not SECTIONING_H */ diff --git a/contrib/texinfo/makeinfo/toc.c b/contrib/texinfo/makeinfo/toc.c new file mode 100644 index 0000000..41c5ffb --- /dev/null +++ b/contrib/texinfo/makeinfo/toc.c @@ -0,0 +1,476 @@ +/* toc.c -- table of contents handling. + $Id: toc.c,v 1.14 1999/08/09 20:28:18 karl Exp $ + + Copyright (C) 1999 Free Software Foundation, Inc. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + + Written by Karl Heinz Marbaise <kama@hippo.fido.de>. */ + +#include "system.h" +#include "makeinfo.h" +#include "cmds.h" +#include "files.h" +#include "macro.h" +#include "node.h" +#include "lang.h" +#include "makeinfo.h" +#include "sectioning.h" +#include "toc.h" + + + + +/* array of toc entries */ +static TOC_ENTRY_ELT **toc_entry_alist = NULL; + +/* toc_counter start from 0 ... n for every @chapter, @section ... */ +static int toc_counter = 0; + +/* the file where we found the @contents directive */ +char *contents_filename; + +/* the file where we found the @shortcontents directive */ +char *shortcontents_filename; + +static const char contents_placebo[] = "\n...Table of Contents...\n"; +static const char shortcontents_placebo[] = "\n...Short Contents...\n"; +static const char lots_of_stars[] = +"***************************************************************************"; + + +/* Routine to add an entry to the table of contents */ +int +toc_add_entry (tocname, level, node_name, anchor) + char *tocname; + int level; + char *node_name; + char *anchor; +{ + char *tocname_and_node, *expanded_node, *s, *d; + + if (!node_name) + node_name = ""; + + /* I assume that xrealloc behaves like xmalloc if toc_entry_alist is + NULL */ + toc_entry_alist = xrealloc (toc_entry_alist, + (toc_counter + 1) * sizeof (TOC_ENTRY_ELT *)); + + toc_entry_alist[toc_counter] = xmalloc (sizeof (TOC_ENTRY_ELT)); + + if (html) + { + /* We need to insert the expanded node name into the TOC, so + that when we eventually output the TOC, its <A REF= link will + point to the <A NAME= tag created by cm_node in the navigation + bar. We cannot expand the containing_node member, for the + reasons explained in the WARNING below. We also cannot wait + with the node name expansion until the TOC is actually output, + since by that time the macro definitions may have been changed. + So instead we store in the tocname member the expanded node + name and the TOC name concatenated together (with the necessary + HTML markup), since that's how they are output. */ + if (!anchor) + s = expanded_node = expand_node_name (node_name); + else + expanded_node = anchor; + /* Sigh... Need to HTML-escape the expanded node name like + add_anchor_name does, except that we are not writing this to + the output, so can't use add_anchor_name... */ + /* The factor 5 in the next allocation is because the maximum + expansion of HTML-escaping is for the & character, which is + output as "&". 2 is for "> that separates node from tocname. */ + d = tocname_and_node = (char *)xmalloc (2 + 5 * strlen (expanded_node) + + strlen (tocname) + 1); + if (!anchor) + { + for (; *s; s++) + { + if (*s == '&') + { + strcpy (d, "&"); + d += 5; + } + else if (! URL_SAFE_CHAR (*s)) + { + sprintf (d, "%%%x", (unsigned char) *s); + /* do this manually since sprintf returns char * on + SunOS 4 and other old systems. */ + while (*d) + d++; + } + else + *d++ = *s; + } + strcpy (d, "\">"); + } + else + /* Section outside any node, they provided explicit anchor. */ + strcpy (d, anchor); + strcat (d, tocname); + free (tocname); /* it was malloc'ed by substring() */ + free (expanded_node); + toc_entry_alist[toc_counter]->name = tocname_and_node; + } + else + toc_entry_alist[toc_counter]->name = tocname; + /* WARNING! The node name saved in containing_node member must + be the node name with _only_ macros expanded (the macros in + the node name are expanded by cm_node when it grabs the name + from the @node directive). Non-macros, like @value, @@ and + other @-commands must NOT be expanded in containing_node, + because toc_find_section_of_node looks up the node name where + they are also unexpanded. You *have* been warned! */ + toc_entry_alist[toc_counter]->containing_node = xstrdup (node_name); + toc_entry_alist[toc_counter]->level = level; + toc_entry_alist[toc_counter]->number = toc_counter; + + /* have to be done at least */ + return toc_counter++; +} + +/* Return the name of a chapter/section/subsection etc. that + corresponds to the node NODE. If the node isn't found, + return NULL. + + WARNING! This function relies on NODE being unexpanded + except for macros (i.e., @value, @@, and other non-macros + should NOT be expanded), because the containing_node member + stores unexpanded node names. + + Note that this function returns the first section whose + containing node is NODE. Thus, they will lose if they use + more than a single chapter structioning command in a node, + or if they have a node without any structuring commands. */ +char * +toc_find_section_of_node (node) + char *node; +{ + int i; + + if (!node) + node = ""; + for (i = 0; i < toc_counter; i++) + if (STREQ (node, toc_entry_alist[i]->containing_node)) + return toc_entry_alist[i]->name; + + return NULL; +} + +/* free up memory used by toc entries */ +void +toc_free () +{ + int i; + + if (toc_counter) + { + for (i = 0; i < toc_counter; i++) + { + free (toc_entry_alist[i]->name); + free (toc_entry_alist[i]->containing_node); + free (toc_entry_alist[i]); + } + + free (toc_entry_alist); + toc_entry_alist = NULL; /* to be sure ;-) */ + toc_counter = 0; /* to be absolutley sure ;-) */ + } +} + + +/* print table of contents in HTML, may be we can produce a standalone + HTML file? */ +static void +contents_update_html (fp) + FILE *fp; +{ + int i; + int k; + int last_level; + + /* does exist any toc? */ + if (!toc_counter) + /* no, so return to sender ;-) */ + return; + + flush_output (); /* in case we are writing stdout */ + + fprintf (fp, "\n<h1>%s</h1>\n<ul>\n", _("Table of Contents")); + + last_level = toc_entry_alist[0]->level; + + for (i = 0; i < toc_counter; i++) + { + if (toc_entry_alist[i]->level > last_level) + { + /* unusual, but it is possible + @chapter ... + @subsubsection ... ? */ + for (k = 0; k < (toc_entry_alist[i]->level-last_level); k++) + fputs ("<ul>\n", fp); + } + else if (toc_entry_alist[i]->level < last_level) + { + /* @subsubsection ... + @chapter ... this IS usual.*/ + for (k = 0; k < (last_level-toc_entry_alist[i]->level); k++) + fputs ("</ul>\n", fp); + } + + fprintf (fp, "<li><a href=\"#%s</a>\n", toc_entry_alist[i]->name); + + last_level = toc_entry_alist[i]->level; + } + + /* Go back to start level. */ + if (toc_entry_alist[0]->level < last_level) + for (k = 0; k < (last_level-toc_entry_alist[0]->level); k++) + fputs ("</ul>\n", fp); + + fputs ("</ul>\n\n", fp); +} + +/* print table of contents in ASCII (--no-headers) + May be we should create a new command line switch --ascii ? */ +static void +contents_update_info (fp) + FILE *fp; +{ + int i; + int k; + + if (!toc_counter) + return; + + flush_output (); /* in case we are writing stdout */ + + fprintf (fp, "%s\n%.*s\n\n", _("Table of Contents"), + (int) strlen (_("Table of Contents")), lots_of_stars); + + for (i = 0; i < toc_counter; i++) + { + if (toc_entry_alist[i]->level == 0) + fputs ("\n", fp); + + /* indention with two spaces per level, should this + changed? */ + for (k = 0; k < toc_entry_alist[i]->level; k++) + fputs (" ", fp); + + fprintf (fp, "%s\n", toc_entry_alist[i]->name); + } + fputs ("\n\n", fp); +} + +/* shortcontents in HTML; Should this produce a standalone file? */ +static void +shortcontents_update_html (fp) + FILE *fp; +{ + int i; + + /* does exist any toc? */ + if (!toc_counter) + return; + + flush_output (); /* in case we are writing stdout */ + + fprintf (fp, "\n<h1>%s</h1>\n<ul>\n", _("Short Contents")); + + for (i = 0; i < toc_counter; i++) + { + if ((toc_entry_alist[i])->level == 0) + { + fputs ("<li>", fp); + fprintf (fp, "<a href=\"#%s\n", toc_entry_alist[i]->name); + } + } + + fputs ("</ul>\n\n", fp); +} + +/* short contents in ASCII (--no-headers). + May be we should create a new command line switch --ascii ? */ +static void +shortcontents_update_info (fp) + FILE *fp; +{ + int i; + + if (!toc_counter) + return; + + flush_output (); /* in case we are writing stdout */ + + fprintf (fp, "%s\n%.*s\n\n", _("Short Contents"), + (int) strlen (_("Short Contents")), lots_of_stars); + + for (i = 0; i < toc_counter; i++) + { + if ((toc_entry_alist[i])->level == 0) + fprintf (fp, "%s\n", toc_entry_alist[i]->name); + } + fputs ("\n\n", fp); +} + + +static FILE *toc_fp; +static char *toc_buf; + +static int +rewrite_top (fname, placebo) + const char *fname, *placebo; +{ + int idx; + + toc_buf = find_and_load (fname); + + if (!toc_buf) + { + /* Can't rewrite standard output. No point in complaining. */ + if (!STREQ (fname, "-")) + fs_error (fname); + return -1; + } + + idx = search_forward (placebo, 0); + + if (idx < 0) + { + error (_("%s: TOC should be here, but it was not found"), fname); + return -1; + } + + toc_fp = fopen (fname, "w"); + if (!toc_fp) + { + fs_error (fname); + return -1; + } + + if (fwrite (toc_buf, 1, idx, toc_fp) != idx) + { + fs_error (fname); + return -1; + } + + return idx + strlen (placebo); +} + +static void +contents_update () +{ + int cont_idx = rewrite_top (contents_filename, contents_placebo); + + if (cont_idx < 0) + return; + + if (html) + contents_update_html (toc_fp); + else + contents_update_info (toc_fp); + + if (fwrite (toc_buf + cont_idx, 1, input_text_length - cont_idx, toc_fp) + != input_text_length - cont_idx + || fclose (toc_fp) != 0) + fs_error (contents_filename); +} + +static void +shortcontents_update () +{ + int cont_idx = rewrite_top (shortcontents_filename, shortcontents_placebo); + + if (cont_idx < 0) + return; + + if (html) + shortcontents_update_html (toc_fp); + else + shortcontents_update_info (toc_fp); + + if (fwrite (toc_buf + cont_idx, 1, input_text_length - cont_idx - 1, toc_fp) + != input_text_length - cont_idx - 1 + || fclose (toc_fp) != 0) + fs_error (shortcontents_filename); +} + +void +toc_update () +{ + if (!html && !no_headers) + return; + + if (contents_filename) + contents_update (); + if (shortcontents_filename) + shortcontents_update (); +} + +void +cm_contents (arg) + int arg; +{ + if ((html || no_headers) && arg == START) + { + if (contents_filename) + { + free (contents_filename); + contents_filename = NULL; + } + + if (contents_filename && STREQ (contents_filename, "-")) + { + if (html) + contents_update_html (stdout); + else + contents_update_info (stdout); + } + else + { + contents_filename = xstrdup (current_output_filename); + insert_string (contents_placebo); /* just mark it, for now */ + } + } +} + +void +cm_shortcontents (arg) + int arg; +{ + if ((html || no_headers) && arg == START) + { + if (shortcontents_filename) + { + free (shortcontents_filename); + shortcontents_filename = NULL; + } + + if (shortcontents_filename && STREQ (shortcontents_filename, "-")) + { + if (html) + shortcontents_update_html (stdout); + else + shortcontents_update_info (stdout); + } + else + { + shortcontents_filename = xstrdup (current_output_filename); + insert_string (shortcontents_placebo); /* just mark it, for now */ + } + } +} diff --git a/contrib/texinfo/makeinfo/toc.h b/contrib/texinfo/makeinfo/toc.h new file mode 100644 index 0000000..a37faf7 --- /dev/null +++ b/contrib/texinfo/makeinfo/toc.h @@ -0,0 +1,49 @@ +/* toc.h -- table of contents handling. + $Id: toc.h,v 1.4 1999/04/25 19:49:22 karl Exp $ + + Copyright (C) 1999 Free Software Foundation, Inc. + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + + Written by Karl Heinz Marbaise <kama@hippo.fido.de>. */ + +#ifndef TOC_H +#define TOC_H + +/* the file where we found the @contents directive */ +extern char *contents_filename; + +/* the file where we found the @shortcontents directive */ +extern char *shortcontents_filename; + +/* Structure to hold one entry for the toc. */ +typedef struct toc_entry_elt { + char *name; + char *containing_node; /* Name of node containing this section. */ + int number; /* counting number from 0...n independent from + chapter/section can be used for anchors or + references to it. */ + int level; /* level: chapter, section, subsection... */ +} TOC_ENTRY_ELT; + +/* all routines which have relationship with TOC should start with + toc_ (this is a kind of name-space) */ +extern int toc_add_entry (); /* return the number for the toc-entry */ +extern void toc_free (); +extern char *toc_find_section_of_node (); + +extern void cm_contents (), cm_shortcontents (); + +#endif /* not TOC_H */ diff --git a/contrib/texinfo/util/README b/contrib/texinfo/util/README index 5385522..20d7bda 100644 --- a/contrib/texinfo/util/README +++ b/contrib/texinfo/util/README @@ -2,3 +2,9 @@ Assorted Texinfo-related programs and scripts. texindex, texi2dvi, and install-info get installed. The other items here are for your amusement and/or hacking pleasure. + +You may also be interested in a2ps, an ASCII->PostScript program which +has a Texinfo style option. Available from +http://www.inf.enst.fr/~demaille/a2ps/ and +ftp://ftp.enst.fr/pub/unix/a2ps/. + diff --git a/contrib/texinfo/util/texindex.c b/contrib/texinfo/util/texindex.c index 7ae607c..cd4bd0f 100644 --- a/contrib/texinfo/util/texindex.c +++ b/contrib/texinfo/util/texindex.c @@ -1,7 +1,7 @@ -/* Prepare TeX index dribble output into an actual index. - $Id: texindex.c,v 1.22 1998/02/22 23:00:09 karl Exp $ +/* Process TeX index dribble output into an actual index. + $Id: texindex.c,v 1.34 1999/08/06 17:03:14 karl Exp $ - Copyright (C) 1987, 91, 92, 96, 97, 98 Free Software Foundation, Inc. + Copyright (C) 1987, 91, 92, 96, 97, 98, 99 Free Software Foundation, Inc. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -20,6 +20,8 @@ #include "system.h" #include <getopt.h> +static char *program_name = "texindex"; + #if defined (emacs) # include "../src/config.h" /* Some s/os.h files redefine these. */ @@ -34,19 +36,8 @@ #define memset(ptr, ignore, count) bzero (ptr, count) #endif - char *mktemp (); -#if defined (VMS) -# include <file.h> -# define TI_NO_ERROR ((1 << 28) | 1) -# define TI_FATAL_ERROR ((1 << 28) | 4) -# define unlink delete -#else /* !VMS */ -# define TI_NO_ERROR 0 -# define TI_FATAL_ERROR 1 -#endif /* !VMS */ - #if !defined (SEEK_SET) # define SEEK_SET 0 # define SEEK_CUR 1 @@ -124,11 +115,7 @@ char *text_base; /* Nonzero means do not delete tempfiles -- for debugging. */ int keep_tempfiles; -/* The name this program was run with. */ -char *program_name; - /* Forward declarations of functions in this file. */ - void decode_command (); void sort_in_core (); void sort_offline (); @@ -149,9 +136,7 @@ void fatal (); void error (); void *xmalloc (), *xrealloc (); char *concat (); -char *maketempname (); void flush_tempfiles (); -char *tempcopy (); #define MAX_IN_CORE_SORT 500000 @@ -165,12 +150,6 @@ main (argc, argv) tempcount = 0; last_deleted_tempcount = 0; - program_name = strrchr (argv[0], '/'); - if (program_name != (char *)NULL) - program_name++; - else - program_name = argv[0]; - #ifdef HAVE_SETLOCALE /* Set locale via LC_ALL. */ setlocale (LC_ALL, ""); @@ -208,14 +187,26 @@ main (argc, argv) for (i = 0; i < num_infiles; i++) { int desc; - long ptr; + off_t ptr; char *outfile; + struct stat instat; desc = open (infiles[i], O_RDONLY, 0); if (desc < 0) pfatal_with_name (infiles[i]); + + if (stat (infiles[i], &instat)) + pfatal_with_name (infiles[i]); + if (S_ISDIR (instat.st_mode)) + { +#ifdef EISDIR + errno = EISDIR; +#endif + pfatal_with_name (infiles[i]); + } + lseek (desc, (off_t) 0, SEEK_END); - ptr = (long) lseek (desc, (off_t) 0, SEEK_CUR); + ptr = (off_t) lseek (desc, (off_t) 0, SEEK_CUR); close (desc); @@ -233,8 +224,8 @@ main (argc, argv) } flush_tempfiles (tempcount); - exit (TI_NO_ERROR); - + xexit (0); + return 0; /* Avoid bogus warnings. */ } @@ -249,6 +240,8 @@ typedef struct } TEXINDEX_OPTION; TEXINDEX_OPTION texindex_options[] = { + { "--help", "-h", (int *)NULL, 0, (char *)NULL, + N_("display this help and exit") }, { "--keep", "-k", &keep_tempfiles, 1, (char *)NULL, N_("keep temporary files around after processing") }, { "--no-keep", 0, &keep_tempfiles, 0, (char *)NULL, @@ -257,8 +250,6 @@ TEXINDEX_OPTION texindex_options[] = { N_("send output to FILE") }, { "--version", (char *)NULL, (int *)NULL, 0, (char *)NULL, N_("display version information and exit") }, - { "--help", "-h", (int *)NULL, 0, (char *)NULL, - N_("display this help and exit") }, { (char *)NULL, (char *)NULL, (int *)NULL, 0, (char *)NULL } }; @@ -272,11 +263,15 @@ usage (result_value) fprintf (f, _("Usage: %s [OPTION]... FILE...\n"), program_name); fprintf (f, _("Generate a sorted index for each TeX output FILE.\n")); /* Avoid trigraph nonsense. */ - fprintf (f, _("Usually FILE... is `foo.??\' for a document `foo.texi'.\n")); + fprintf (f, +_("Usually FILE... is specified as `foo.%c%c\' for a document `foo.texi'.\n"), + '?', '?'); /* avoid trigraph in cat-id-tbl.c */ fprintf (f, _("\nOptions:\n")); for (i = 0; texindex_options[i].long_name; i++) { + putc (' ', f); + if (texindex_options[i].short_name) fprintf (f, "%s, ", texindex_options[i].short_name); @@ -287,9 +282,12 @@ usage (result_value) fprintf (f, "\t%s\n", _(texindex_options[i].doc_string)); } - puts (_("\nEmail bug reports to bug-texinfo@gnu.org.")); + fputs (_("\n\ +Email bug reports to bug-texinfo@gnu.org,\n\ +general questions and discussion to help-texinfo@gnu.org.\n\ +"), f); - exit (result_value); + xexit (result_value); } /* Decode the command line arguments to set the parameter variables @@ -307,15 +305,14 @@ decode_command (argc, argv) /* Store default values into parameter variables. */ tempdir = getenv ("TMPDIR"); -#ifdef VMS if (tempdir == NULL) - tempdir = "sys$scratch:"; -#else + tempdir = getenv ("TEMP"); + if (tempdir == NULL) + tempdir = getenv ("TMP"); if (tempdir == NULL) - tempdir = "/tmp/"; + tempdir = DEFAULT_TMPDIR; else tempdir = concat (tempdir, "/", ""); -#endif keep_tempfiles = 0; @@ -335,12 +332,13 @@ decode_command (argc, argv) if (strcmp (arg, "--version") == 0) { printf ("texindex (GNU %s) %s\n", PACKAGE, VERSION); - printf (_("Copyright (C) %s Free Software Foundation, Inc.\n\ + puts (""); + printf (_("Copyright (C) %s Free Software Foundation, Inc.\n\ There is NO warranty. You may redistribute this software\n\ under the terms of the GNU General Public License.\n\ For more information about these matters, see the files named COPYING.\n"), - "1998"); - exit (0); + "1999"); + xexit (0); } else if ((strcmp (arg, "--keep") == 0) || (strcmp (arg, "-k") == 0)) @@ -383,12 +381,12 @@ For more information about these matters, see the files named COPYING.\n"), /* Return a name for a temporary file. */ -char * +static char * maketempname (count) int count; { char tempsuffix[10]; - sprintf (tempsuffix, "%d", count); + sprintf (tempsuffix, ".%d", count); return concat (tempdir, tempbase, tempsuffix); } @@ -404,36 +402,6 @@ flush_tempfiles (to_count) unlink (maketempname (++last_deleted_tempcount)); } -/* Copy the input file open on IDESC into a temporary file - and return the temporary file name. */ - -#define BUFSIZE 1024 - -char * -tempcopy (idesc) - int idesc; -{ - char *outfile = maketempname (++tempcount); - int odesc; - char buffer[BUFSIZE]; - - odesc = open (outfile, O_WRONLY | O_CREAT, 0666); - - if (odesc < 0) - pfatal_with_name (outfile); - - while (1) - { - int nread = read (idesc, buffer, BUFSIZE); - write (odesc, buffer, nread); - if (!nread) - break; - } - - close (odesc); - - return outfile; -} /* Compare LINE1 and LINE2 according to the specified set of keyfields. */ @@ -894,7 +862,7 @@ void sort_offline (infile, nfiles, total, outfile) char *infile; int nfiles; - long total; + off_t total; char *outfile; { /* More than enough. */ @@ -993,7 +961,7 @@ fail: void sort_in_core (infile, total, outfile) char *infile; - long total; + off_t total; char *outfile; { char **nextline; @@ -1251,7 +1219,7 @@ indexify (line, ostream) pagenumber = find_braced_pos (line, 1, 0, 0); pagelength = find_braced_end (pagenumber) - pagenumber; if (pagelength == 0) - abort (); + fatal (_("No page number in %s"), line); primary = find_braced_pos (line, 2, 0, 0); primarylength = find_braced_end (primary) - primary; @@ -1627,7 +1595,7 @@ fatal (format, arg) char *format, *arg; { error (format, arg); - exit (TI_FATAL_ERROR); + xexit (1); } /* Print error message. FORMAT is printf control string, ARG is arg for it. */ @@ -1661,7 +1629,7 @@ pfatal_with_name (name) s = strerror (errno); printf ("%s: ", program_name); printf (_("%s; for file `%s'.\n"), s, name); - exit (TI_FATAL_ERROR); + xexit (1); } /* Return a newly-allocated string whose contents concatenate those of @@ -1682,21 +1650,6 @@ concat (s1, s2, s3) return result; } -#if !defined (HAVE_STRERROR) -extern char *sys_errlist[]; -extern int sys_nerr; - -char * -strerror (num) - int num; -{ - if (num >= sys_nerr) - return (""); - else - return (sys_errlist[num]); -} -#endif /* !HAVE_STRERROR */ - #if !defined (HAVE_STRCHR) char * strrchr (string, character) @@ -1712,50 +1665,3 @@ strrchr (string, character) return ((char *)NULL); } #endif /* HAVE_STRCHR */ - -void -memory_error (callers_name, bytes_wanted) - char *callers_name; - int bytes_wanted; -{ - char printable_string[80]; - - sprintf (printable_string, - _("Virtual memory exhausted in %s ()! Needed %d bytes."), - callers_name, bytes_wanted); - - error (printable_string); - abort (); -} - -/* Just like malloc, but kills the program in case of fatal error. */ -void * -xmalloc (nbytes) - int nbytes; -{ - void *temp = (void *) malloc (nbytes); - - if (nbytes && temp == (void *)NULL) - memory_error ("xmalloc", nbytes); - - return (temp); -} - -/* Like realloc (), but barfs if there isn't enough memory. */ -void * -xrealloc (pointer, nbytes) - void *pointer; - int nbytes; -{ - void *temp; - - if (!pointer) - temp = (void *)xmalloc (nbytes); - else - temp = (void *)realloc (pointer, nbytes); - - if (nbytes && !temp) - memory_error ("xrealloc", nbytes); - - return (temp); -} |
