2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 2013 Free Software Foundation, Inc.
4 @c See the file guile.texi for copying conditions.
6 @c Note: Don't use "Texinfo" as the node name here because this leads to
7 @c a clash in the HTML output between texinfo.html (from the "texinfo"
8 @c node) and Texinfo.html on case-insensitive file systems such as
10 @node Texinfo Processing
11 @section Texinfo Processing
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
26 @subsubsection Overview
27 @subheading Texinfo processing in scheme
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
31 customizable, and the program is not extensible as a whole. This module
32 aims to provide an extensible framework for texinfo processing that
33 integrates texinfo into the constellation of SXML processing tools.
35 @subheading Notes on the SXML vocabulary
36 Consider the following texinfo fragment:
39 @@deffn Primitive set-car! pair value
44 Logically, the category (Primitive), name (set-car!), and arguments
45 (pair value) are ``attributes'' of the deffn, with the description as
46 the content. However, texinfo allows for @@-commands within the
47 arguments to an environment, like @code{@@deffn}, which means that
48 texinfo ``attributes'' are PCDATA. XML attributes, on the other hand,
49 are CDATA. For this reason, ``attributes'' of texinfo @@-commands are
50 called ``arguments'', and are grouped under the special element, `%'.
52 Because `%' is not a valid NCName, stexinfo is a superset of SXML. In
53 the interests of interoperability, this module provides a conversion
54 function to replace the `%' with `texinfo-arguments'.
57 @anchor{texinfo call-with-file-and-dir}@defun call-with-file-and-dir filename proc
58 Call the one-argument procedure @var{proc} with an input port that reads
59 from @var{filename}. During the dynamic extent of @var{proc}'s
60 execution, the current directory will be @code{(dirname
61 @var{filename})}. This is useful for parsing documents that can include
62 files by relative path name.
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}.
76 (texi-command-depth 'chapter 4) @result{} 1
77 (texi-command-depth 'top 4) @result{} 0
78 (texi-command-depth 'subsection 4) @result{} 3
79 (texi-command-depth 'appendixsubsec 4) @result{} 3
80 (texi-command-depth 'subsection 2) @result{} #f
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
87 resultant stexi tree. The head of the tree will be the special command,
92 @anchor{texinfo texi->stexi}@defun texi->stexi port
93 Read a full texinfo document from @var{port} and return the parsed stexi
94 tree. The parsing will start at the @code{@@settitle} and end at
99 @anchor{texinfo stexi->sxml}@defun stexi->sxml tree
100 Transform the stexi tree @var{tree} into sxml. This involves replacing
101 the @code{%} element that keeps the texinfo arguments with an element
104 FIXME: right now it just changes % to @code{texinfo-arguments} -- that
105 doesn't hang with the idea of making a dtd at some point
109 @node texinfo docbook
110 @subsection (texinfo docbook)
111 @subsubsection Overview
113 This module exports procedures for transforming a limited subset of the
114 SXML representation of docbook into stexi. It is not complete by any
115 means. The intention is to gather a number of routines and stylesheets
116 so that external modules can parse specific subsets of docbook, for
117 example that set generated by certain tools.
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
127 "Flatten" a fragment of sdocbook so that block elements do not nest
130 Docbook is a nested format, where e.g. a @code{refsect2} normally
131 appears inside a @code{refsect1}. Logical divisions in the document are
132 represented via the tree topology; a @code{refsect2} element
133 @emph{contains} all of the elements in its section.
135 On the contrary, texinfo is a flat format, in which sections are marked
136 off by standalone section headers like @code{@@subsection}, and block
137 elements do not nest inside each other.
139 This function takes a nested sdocbook fragment @var{sdocbook} and
140 flattens all of the sections, such that e.g.
143 (refsect1 (refsect2 (para "Hello")))
149 ((refsect1) (refsect2) (para "Hello"))
152 Oftentimes (always?) sectioning elements have @code{<title>} as their
153 first element child; users interested in processing the @code{refsect*}
154 elements into proper sectioning elements like @code{chapter} might be
155 interested in @code{replace-titles} and @code{filter-empty-elements}.
156 @xref{texinfo docbook replace-titles,,replace-titles}, and @ref{texinfo
157 docbook filter-empty-elements,,filter-empty-elements}.
159 Returns a nodeset; that is to say, an untagged list of stexi elements.
160 @xref{SXPath}, for the definition of a nodeset.
164 @anchor{texinfo docbook filter-empty-elements}@defun filter-empty-elements sdocbook
165 Filters out empty elements in an sdocbook nodeset. Mostly useful after
166 running @code{sdocbook-flatten}.
170 @anchor{texinfo docbook replace-titles}@defun replace-titles sdocbook-fragment
171 Iterate over the sdocbook nodeset @var{sdocbook-fragment}, transforming
172 contiguous @code{refsect} and @code{title} elements into the appropriate
173 texinfo sectioning command. Most useful after having run
174 @code{sdocbook-flatten}.
179 (replace-titles '((refsect1) (title "Foo") (para "Bar.")))
180 @result{} '((chapter "Foo") (para "Bar."))
186 @subsection (texinfo html)
187 @subsubsection Overview
188 This module implements transformation from @code{stexi} to HTML. Note
189 that the output of @code{stexi->shtml} is actually SXML with the HTML
190 vocabulary. This means that the output can be further processed, and
191 that it must eventually be serialized by @code{sxml->xml}.
192 @xref{Reading and Writing XML}.
194 References (i.e., the @code{@@ref} family of commands) are resolved by a
195 @dfn{ref-resolver}. @xref{texinfo html
196 add-ref-resolver!,add-ref-resolver!}.
199 @anchor{texinfo html add-ref-resolver!}@defun add-ref-resolver! proc
200 Add @var{proc} to the head of the list of ref-resolvers. @var{proc} will
201 be expected to take the name of a node and the name of a manual and
202 return the URL of the referent, or @code{#f} to pass control to the next
203 ref-resolver in the list.
205 The default ref-resolver will return the concatenation of the manual
206 name, @code{#}, and the node name.
210 @anchor{texinfo html stexi->shtml}@defun stexi->shtml tree
211 Transform the stexi @var{tree} into shtml, resolving references via
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)
221 @subsubsection Overview
222 @c texinfo formatting
223 Given a piece of stexi, return an index of a specified variety.
225 Note that currently, @code{stexi-extract-index} doesn't differentiate
226 between different kinds of index entries. That's a bug ;)
229 @anchor{texinfo indexing stexi-extract-index}@defun stexi-extract-index tree manual-name kind
230 Given an stexi tree @var{tree}, index all of the entries of type
231 @var{kind}. @var{kind} can be one of the predefined texinfo indices
232 (@code{concept}, @code{variable}, @code{function}, @code{key},
233 @code{program}, @code{type}) or one of the special symbols @code{auto}
234 or @code{all}. @code{auto} will scan the stext for a @code{(printindex)}
235 statement, and @code{all} will generate an index from all entries,
238 The returned index is a list of pairs, the @sc{car} of which is the
239 entry (a string) and the @sc{cdr} of which is a node name (a string).
243 @node texinfo string-utils
244 @subsection (texinfo string-utils)
245 @subsubsection Overview
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 escape-char
251 Returns a copy of @var{str} with all given special characters preceded
252 by the given @var{escape-char}.
254 @var{special-chars} can either be a single character, or a string
255 consisting of all the special characters.
258 ;; make a string regexp-safe...
259 (escape-special-chars "***(Example String)***"
262 => "\\*\\*\\*\\(Example String\\)\\*\\*\\*"
264 ;; also can escape a singe char...
265 (escape-special-chars "richardt@@vzavenue.net"
268 => "richardt@@@@vzavenue.net"
273 @anchor{texinfo string-utils transform-string}@defun transform-string str match? replace [start] [end]
274 Uses @var{match?} against each character in @var{str}, and performs a
275 replacement on each character for which matches are found.
277 @var{match?} may either be a function, a character, a string, or
278 @code{#t}. If @var{match?} is a function, then it takes a single
279 character as input, and should return @samp{#t} for matches.
280 @var{match?} is a character, it is compared to each string character
281 using @code{char=?}. If @var{match?} is a string, then any character in
282 that string will be considered a match. @code{#t} will cause every
283 character to be a match.
285 If @var{replace} is a function, it is called with the matched character
286 as an argument, and the returned value is sent to the output string via
287 @samp{display}. If @var{replace} is anything else, it is sent through
288 the output string via @samp{display}.
290 Note that te replacement for the matched characters does not need to be
291 a single character. That is what differentiates this function from
292 @samp{string-map}, and what makes it useful for applications such as
293 converting @samp{#\&} to @samp{"&"} in web page text. Some other
294 functions in this module are just wrappers around common uses of
295 @samp{transform-string}. Transformations not possible with this function
296 should probably be done with regular expressions.
298 If @var{start} and @var{end} are given, they control which portion of
299 the string undergoes transformation. The entire input string is still
300 output, though. So, if @var{start} is @samp{5}, then the first five
301 characters of @var{str} will still appear in the returned string.
304 ; these two are equivalent...
305 (transform-string str #\space #\-) ; change all spaces to -'s
306 (transform-string str (lambda (c) (char=? #\space c)) #\-)
311 @anchor{texinfo string-utils expand-tabs}@defun expand-tabs str [tab-size]
312 Returns a copy of @var{str} with all tabs expanded to spaces.
313 @var{tab-size} defaults to 8.
315 Assuming tab size of 8, this is equivalent to:
318 (transform-string str #\tab " ")
323 @anchor{texinfo string-utils center-string}@defun center-string str [width] [chr] [rchr]
324 Returns a copy of @var{str} centered in a field of @var{width}
325 characters. Any needed padding is done by character @var{chr}, which
326 defaults to @samp{#\space}. If @var{rchr} is provided, then the padding
327 to the right will use it instead. See the examples below. left and
328 @var{rchr} on the right. The default @var{width} is 80. The default
329 @var{chr} and @var{rchr} is @samp{#\space}. The string is never
333 (center-string "Richard Todd" 24)
336 (center-string " Richard Todd " 24 #\=)
337 => "===== Richard Todd ====="
339 (center-string " Richard Todd " 24 #\< #\>)
340 => "<<<<< Richard Todd >>>>>"
345 @anchor{texinfo string-utils left-justify-string}@defun left-justify-string str [width] [chr]
346 @code{left-justify-string str [width chr]}. Returns a copy of @var{str}
347 padded with @var{chr} such that it is left justified in a field of
348 @var{width} characters. The default @var{width} is 80. Unlike
349 @samp{string-pad} from srfi-13, the string is never truncated.
353 @anchor{texinfo string-utils right-justify-string}@defun right-justify-string str [width] [chr]
354 Returns a copy of @var{str} padded with @var{chr} such that it is right
355 justified in a field of @var{width} characters. The default @var{width}
356 is 80. The default @var{chr} is @samp{#\space}. Unlike @samp{string-pad}
357 from srfi-13, the string is never truncated.
361 @anchor{texinfo string-utils collapse-repeated-chars}@defun collapse-repeated-chars str [chr] [num]
362 Returns a copy of @var{str} with all repeated instances of @var{chr}
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.
367 (collapse-repeated-chars "H e l l o")
369 (collapse-repeated-chars "H--e--l--l--o" #\-)
371 (collapse-repeated-chars "H-e--l---l----o" #\- 2)
377 @anchor{texinfo string-utils make-text-wrapper}@defun make-text-wrapper [#:line-width] [#:expand-tabs?] [#:tab-width] [#:collapse-whitespace?] [#:subsequent-indent] [#:initial-indent] [#:break-long-words?]
378 Returns a procedure that will split a string into lines according to the
383 This is the target length used when deciding where to wrap lines.
387 Boolean describing whether tabs in the input should be expanded. Default
391 If tabs are expanded, this will be the number of spaces to which they
392 expand. Default is 8.
394 @item #:collapse-whitespace?
395 Boolean describing whether the whitespace inside the existing text
396 should be removed or not. Default is #t.
398 If text is already well-formatted, and is just being wrapped to fit in a
399 different width, then set this to @samp{#f}. This way, many common text
400 conventions (such as two spaces between sentences) can be preserved if
401 in the original text. If the input text spacing cannot be trusted, then
402 leave this setting at the default, and all repeated whitespace will be
403 collapsed down to a single space.
405 @item #:initial-indent
406 Defines a string that will be put in front of the first line of wrapped
407 text. Default is the empty string, ``''.
409 @item #:subsequent-indent
410 Defines a string that will be put in front of all lines of wrapped text,
411 except the first one. Default is the empty string, ``''.
413 @item #:break-long-words?
414 If a single word is too big to fit on a line, this setting tells the
415 wrapper what to do. Defaults to #t, which will break up long words. When
416 set to #f, the line will be allowed, even though it is longer than the
417 defined @code{#:line-width}.
421 The return value is a procedure of one argument, the input string, which
422 returns a list of strings, where each element of the list is one line.
426 @anchor{texinfo string-utils fill-string}@defun fill-string str . kwargs
427 Wraps the text given in string @var{str} according to the parameters
428 provided in @var{kwargs}, or the default setting if they are not given.
429 Returns a single string with the wrapped text. Valid keyword arguments
430 are discussed in @code{make-text-wrapper}.
434 @anchor{texinfo string-utils string->wrapped-lines}@defun string->wrapped-lines str . kwargs
435 @code{string->wrapped-lines str keywds ...}. Wraps the text given in
436 string @var{str} according to the parameters provided in @var{keywds},
437 or the default setting if they are not given. Returns a list of strings
438 representing the formatted lines. Valid keyword arguments are discussed
439 in @code{make-text-wrapper}.
443 @node texinfo plain-text
444 @subsection (texinfo plain-text)
445 @subsubsection Overview
446 Transformation from stexi to plain-text. Strives to re-create the output
447 from @code{info}; comes pretty damn close.
450 @anchor{texinfo plain-text stexi->plain-text}@defun stexi->plain-text tree
451 Transform @var{tree} into plain text. Returns a string.
455 @node texinfo serialize
456 @subsection (texinfo serialize)
457 @subsubsection Overview
458 Serialization of @code{stexi} to plain texinfo.
461 @anchor{texinfo serialize stexi->texi}@defun stexi->texi tree
462 Serialize the stexi @var{tree} into plain texinfo.
466 @node texinfo reflection
467 @subsection (texinfo reflection)
468 @subsubsection Overview
469 Routines to generare @code{stexi} documentation for objects and modules.
471 Note that in this context, an @dfn{object} is just a value associated
472 with a location. It has nothing to do with GOOPS.
475 @anchor{texinfo reflection module-stexi-documentation}@defun module-stexi-documentation sym-name [%docs-resolver] [#:docs-resolver]
476 Return documentation for the module named @var{sym-name}. The
477 documentation will be formatted as @code{stexi}
478 (@pxref{texinfo,texinfo}).
482 @anchor{texinfo reflection script-stexi-documentation}@defun script-stexi-documentation scriptpath
483 Return documentation for given script. The documentation will be taken
484 from the script's commentary, and will be returned in the @code{stexi}
485 format (@pxref{texinfo,texinfo}).
489 @anchor{texinfo reflection object-stexi-documentation}@defun object-stexi-documentation _ [_] [#:force]
492 @anchor{texinfo reflection package-stexi-standard-copying}@defun package-stexi-standard-copying name version updated years copyright-holder permissions
493 Create a standard texinfo @code{copying} section.
495 @var{years} is a list of years (as integers) in which the modules being
496 documented were released. All other arguments are strings.
500 @anchor{texinfo reflection package-stexi-standard-titlepage}@defun package-stexi-standard-titlepage name version updated authors
501 Create a standard GNU title page.
503 @var{authors} is a list of @code{(@var{name} . @var{email})} pairs. All
504 other arguments are strings.
506 Here is an example of the usage of this procedure:
509 (package-stexi-standard-titlepage
513 '(("Alyssa P Hacker" . "alyssa@@example.com"))
515 "Free Software Foundation, Inc."
516 "Standard GPL permissions blurb goes here")
521 @anchor{texinfo reflection package-stexi-generic-menu}@defun package-stexi-generic-menu name entries
522 Create a menu from a generic alist of entries, the car of which should
523 be the node name, and the cdr the description. As an exception, an entry
524 of @code{#f} will produce a separator.
528 @anchor{texinfo reflection package-stexi-standard-menu}@defun package-stexi-standard-menu name modules module-descriptions extra-entries
529 Create a standard top node and menu, suitable for processing by
534 @anchor{texinfo reflection package-stexi-extended-menu}@defun package-stexi-extended-menu name module-pairs script-pairs extra-entries
535 Create an "extended" menu, like the standard menu but with a section for
540 @anchor{texinfo reflection package-stexi-standard-prologue}@defun package-stexi-standard-prologue name filename category description copying titlepage menu
541 Create a standard prologue, suitable for later serialization to texinfo
542 and .info creation with makeinfo.
544 Returns a list of stexinfo forms suitable for passing to
545 @code{package-stexi-documentation} as the prologue. @xref{texinfo
546 reflection package-stexi-documentation}, @ref{texinfo reflection
547 package-stexi-standard-titlepage,package-stexi-standard-titlepage},
548 @ref{texinfo reflection
549 package-stexi-standard-copying,package-stexi-standard-copying}, and
550 @ref{texinfo reflection
551 package-stexi-standard-menu,package-stexi-standard-menu}.
555 @anchor{texinfo reflection package-stexi-documentation}@defun package-stexi-documentation modules name filename prologue epilogue [#:module-stexi-documentation-args] [#:scripts]
556 Create stexi documentation for a @dfn{package}, where a package is a set
557 of modules that is released together.
559 @var{modules} is expected to be a list of module names, where a module
560 name is a list of symbols. The stexi that is returned will be titled
561 @var{name} and a texinfo filename of @var{filename}.
563 @var{prologue} and @var{epilogue} are lists of stexi forms that will be
564 spliced into the output document before and after the generated modules
565 documentation, respectively. @xref{texinfo reflection
566 package-stexi-standard-prologue}, to create a conventional GNU texinfo
569 @var{module-stexi-documentation-args} is an optional argument that, if
570 given, will be added to the argument list when
571 @code{module-texi-documentation} is called. For example, it might be
572 useful to define a @code{#:docs-resolver} argument.
576 @anchor{texinfo reflection package-stexi-documentation-for-include}@defun package-stexi-documentation-for-include modules module-descriptions [#:module-stexi-documentation-args]
577 Create stexi documentation for a @dfn{package}, where a package is a set
578 of modules that is released together.
580 @var{modules} is expected to be a list of module names, where a module
581 name is a list of symbols. Returns an stexinfo fragment.
583 Unlike @code{package-stexi-documentation}, this function simply produces
584 a menu and the module documentations instead of producing a full texinfo
585 document. This can be useful if you write part of your manual by hand,
586 and just use @code{@@include} to pull in the automatically generated
589 @var{module-stexi-documentation-args} is an optional argument that, if
590 given, will be added to the argument list when
591 @code{module-texi-documentation} is called. For example, it might be
592 useful to define a @code{#:docs-resolver} argument.