doc/ref/texinfo.texi

1 @c -*-texinfo-*-
4 @c See the file guile.texi for copying conditions.
7 @c a clash in the HTML output between texinfo.html (from the "texinfo"
14 * texinfo::              Parse texinfo files or fragments into @code{stexi}, a scheme representation
15 * texinfo docbook::      Transform a subset of docbook into @code{stexi}
16 * texinfo html::         Transform @code{stexi} into HTML
17 * texinfo indexing::     Extract an index from a piece of @code{stexi}
18 * texinfo string-utils::  String utility functions used by the texinfo processor
19 * texinfo plain-text::   Render @code{stexi} as plain text
20 * texinfo serialize::    Render @code{stexi} as texinfo
21 * texinfo reflection::   Enable texinfo across Guile's help system
24 @node texinfo
25 @subsection (texinfo)
28 This module parses texinfo into SXML. TeX will always be the processor
29 of choice for print output, of course. However, although @code{makeinfo}
30 works well for info, its output in other formats is not very
32 aims to provide an extensible framework for texinfo processing that
33 integrates texinfo into the constellation of SXML processing tools.
36 Consider the following texinfo fragment:
46 the content. However, texinfo allows for @@-commands within the
48 texinfo ``attributes'' are PCDATA. XML attributes, on the other hand,
49 are CDATA. For this reason, ``attributes'' of texinfo @@-commands are
54 function to replace the `%' with `texinfo-arguments'.
57 @anchor{texinfo call-with-file-and-dir}@defun call-with-file-and-dir filename proc
61 @var{filename})}. This is useful for parsing documents that can include
66 @anchor{texinfo texi-command-specs}@defvar texi-command-specs
69 @anchor{texinfo texi-command-depth}@defun texi-command-depth command max-depth
70 Given the texinfo command @var{command}, return its nesting level, or
71 @code{#f} if it nests too deep for @var{max-depth}.
85 @anchor{texinfo texi-fragment->stexi}@defun texi-fragment->stexi string-or-port
86 Parse the texinfo commands in @var{string-or-port}, and return the
92 @anchor{texinfo texi->stexi}@defun texi->stexi port
93 Read a full texinfo document from @var{port} and return the parsed stexi
99 @anchor{texinfo stexi->sxml}@defun stexi->sxml tree
101 the @code{%} element that keeps the texinfo arguments with an element
102 for each argument.
104 FIXME: right now it just changes % to @code{texinfo-arguments} -- that
109 @node texinfo docbook
110 @subsection (texinfo docbook)
113 This module exports procedures for transforming a limited subset of the
116 so that external modules can parse specific subsets of docbook, for
120 @anchor{texinfo docbook *sdocbook->stexi-rules*}@defvar *sdocbook->stexi-rules*
123 @anchor{texinfo docbook *sdocbook-block-commands*}@defvar *sdocbook-block-commands*
126 @anchor{texinfo docbook sdocbook-flatten}@defun sdocbook-flatten sdocbook
135 On the contrary, texinfo is a flat format, in which sections are marked
156 @xref{texinfo docbook replace-titles,,replace-titles}, and @ref{texinfo
160 @xref{SXPath}, for the definition of a nodeset.
164 @anchor{texinfo docbook filter-empty-elements}@defun filter-empty-elements sdocbook
170 @anchor{texinfo docbook replace-titles}@defun replace-titles sdocbook-fragment
173 texinfo sectioning command. Most useful after having run
185 @node texinfo html
186 @subsection (texinfo html)
195 @dfn{ref-resolver}.  @xref{texinfo html
199 @anchor{texinfo html add-ref-resolver!}@defun add-ref-resolver! proc
210 @anchor{texinfo html stexi->shtml}@defun stexi->shtml tree
212 ref-resolvers. See the module commentary for more details.
216 @anchor{texinfo html urlify}@defun urlify str
219 @node texinfo indexing
220 @subsection (texinfo indexing)
222 @c texinfo formatting
229 @anchor{texinfo indexing stexi-extract-index}@defun stexi-extract-index tree manual-name kind
231 @var{kind}. @var{kind} can be one of the predefined texinfo indices
234 or @code{all}. @code{auto} will scan the stext for a @code{(printindex)}
243 @node texinfo string-utils
244 @subsection (texinfo string-utils)
246 Module @samp{(texinfo string-utils)} provides various string-related
247 functions useful to Guile's texinfo support.
250 @anchor{texinfo string-utils escape-special-chars}@defun escape-special-chars str special-chars esc…
252 by the given @var{escape-char}.
259  (escape-special-chars "***(Example String)***"
264 ;; also can escape a singe char...
265  (escape-special-chars "richardt@@vzavenue.net"
273 @anchor{texinfo string-utils transform-string}@defun transform-string str match? replace [start] [e…
275 replacement on each character for which matches are found.
279 character as input, and should return @samp{#t} for matches.
290 Note that the replacement for the matched characters does not need to be
292 @samp{string-map}, and what makes it useful for applications such as
311 @anchor{texinfo string-utils expand-tabs}@defun expand-tabs str [tab-size]
323 @anchor{texinfo string-utils center-string}@defun center-string str [width] [chr] [rchr]
345 @anchor{texinfo string-utils left-justify-string}@defun left-justify-string str [width] [chr]
353 @anchor{texinfo string-utils right-justify-string}@defun right-justify-string str [width] [chr]
361 @anchor{texinfo string-utils collapse-repeated-chars}@defun collapse-repeated-chars str [chr] [num]
363 collapsed down to at most @var{num} instances. The default value for
364 @var{chr} is @samp{#\space}, and the default value for @var{num} is 1.
377 @anchor{texinfo string-utils make-text-wrapper}@defun make-text-wrapper [#:line-width] [#:expand-ta…
426 @anchor{texinfo string-utils fill-string}@defun fill-string str . kwargs
434 @anchor{texinfo string-utils string->wrapped-lines}@defun string->wrapped-lines str . kwargs
443 @node texinfo plain-text
444 @subsection (texinfo plain-text)
450 @anchor{texinfo plain-text stexi->plain-text}@defun stexi->plain-text tree
457 line for the purposes of line wrapping in the @code{stexi->plain-text}
461 @node texinfo serialize
462 @subsection (texinfo serialize)
464 Serialization of @code{stexi} to plain texinfo.
467 @anchor{texinfo serialize stexi->texi}@defun stexi->texi tree
468 Serialize the stexi @var{tree} into plain texinfo.
472 @node texinfo reflection
473 @subsection (texinfo reflection)
475 Routines to generare @code{stexi} documentation for objects and modules.
481 @anchor{texinfo reflection module-stexi-documentation}@defun module-stexi-documentation sym-name [%…
482 Return documentation for the module named @var{sym-name}. The
484 (@pxref{texinfo,texinfo}).
488 @anchor{texinfo reflection script-stexi-documentation}@defun script-stexi-documentation scriptpath
489 Return documentation for given script. The documentation will be taken
491 format (@pxref{texinfo,texinfo}).
495 @anchor{texinfo reflection object-stexi-documentation}@defun object-stexi-documentation _ [_] [#:fo…
498 @anchor{texinfo reflection package-stexi-standard-copying}@defun package-stexi-standard-copying nam…
499 Create a standard texinfo @code{copying} section.
506 @anchor{texinfo reflection package-stexi-standard-titlepage}@defun package-stexi-standard-titlepage…
527 @anchor{texinfo reflection package-stexi-generic-menu}@defun package-stexi-generic-menu name entries
534 @anchor{texinfo reflection package-stexi-standard-menu}@defun package-stexi-standard-menu name modu…
535 Create a standard top node and menu, suitable for processing by
540 @anchor{texinfo reflection package-stexi-extended-menu}@defun package-stexi-extended-menu name modu…
541 Create an "extended" menu, like the standard menu but with a section for
546 @anchor{texinfo reflection package-stexi-standard-prologue}@defun package-stexi-standard-prologue n…
547 Create a standard prologue, suitable for later serialization to texinfo
550 Returns a list of stexinfo forms suitable for passing to
551 @code{package-stexi-documentation} as the prologue. @xref{texinfo
552 reflection package-stexi-documentation}, @ref{texinfo reflection
554 @ref{texinfo reflection
556 @ref{texinfo reflection
561 @anchor{texinfo reflection package-stexi-documentation}@defun package-stexi-documentation modules n…
562 Create stexi documentation for a @dfn{package}, where a package is a set
567 @var{name} and a texinfo filename of @var{filename}.
571 documentation, respectively. @xref{texinfo reflection
572 package-stexi-standard-prologue}, to create a conventional GNU texinfo
582 @anchor{texinfo reflection package-stexi-documentation-for-include}@defun package-stexi-documentati…
583 Create stexi documentation for a @dfn{package}, where a package is a set
590 a menu and the module documentations instead of producing a full texinfo