13.44 guile-tools twerp2texi

See Doc Insertion, for discussion.

Usage: twerp2texi -I INDEX [...] [-d DEPS] [-o OUTFILE] TWERP

Process TWERP (a Texi With Eval-Requiring Predelictions file) and
write the result to OUTFILE, typically named w/ .texi extension, or
stdout if "-o OUTFILE" is not specified.  Processing requires one or
more index files prepared by "guile-tools make-twerp2texi-index";
it is an error to omit "-I INDEX".

* Options

  At this time there is only one additional option: "-d DEPS" means
  write to the file DEPS a makefile fragment suitable for "include
  DEPS".  This fragment is typically named w/ extension .Ptexi to
  indicate the prerequisites (aka dependencies) of OUTFILE determined
  during twerp2texi operation (and not before!).  Note that DEPS only
  lists source files w/ no mention of .doc files.  Dependency
  tracking requires you to prepare the Makefile in a special way; see
  "guile-tools prep-Ptexi" for more info.

  NOTE: It is an error to use `-d DEPS' without `-o OUTFILE'.

* Twerp Processing

  A .twerp file is mostly texinfo, w/ a some directives thrown in.
  At this time, the entire directive must be on one line.  This
  restriction will probably be lifted in the future.

  In its simplest form a directive names a single symbol:

     @twerpdoc (SYMBOL)

  This is replaced by the header

     @deffn {Scheme Procedure} SYMBOL SIG ...

  followed by text associated with SYMBOL from the appropriate .doc
  file.  The text is inserted verbatim.  SIG is also taken from the
  .doc file.

  The list following the "@twerpdoc" directive can name additional
  symbols or sublists beginning w/ `C'.  These inherit the SIG and
  are formatted appropriately[1], depending on whether the language
  is Scheme (default) or C.  For example, the directive:

     @twerpdoc (acons (C scm_acons))

  results in the header:

     @deffn {Scheme Procedure} acons key value alist
     @deffnx {C Function} scm_acons (key, value, alist)

  Scheme syntax and macros macros are likewise handled with
  @twerpsyntaxdoc and @twerpmacdoc, respectively.  For example:

     @twerpmacdoc (begin-thread)

  produces header:

     @deffn {Scheme Macro} begin-thread first . rest

  followed by the snarfed documentation.  C macros are handled
  similarly, using @twerpcmacdoc (note the "c").  For example:

     @twerpcmacdoc (GH_USE_MODULE)

  produces header:

     @deffn {C Macro} GH_USE_MODULE (cvar, fullname)

  If the macro does not have an arglist, that part is omitted.

  [1] Style issues like what is "appropriate" are not yet finalized.
      There is much room for generalization here.

  For doc and macdoc, the "Scheme " (in "Scheme Procedure" and
  "Scheme Macro", respectively) can be omitted by specifying the
  command-line option `--scheme-implied'.

  To include commentary from a module, use a "commentary directive"
  followed by a sexp of the form: (STYLE MODULE-NAME).  STYLE specifies
  STYLE specifies how to handle the raw text of the commentary, and
  MODULE-NAME specifies which module to consult.  For example:

     @twerpcommentary (example (ice-9 documentation))

  Currently the following styles are supported, corresponding to the
  same-named texinfo commands for enclosing blocks of text:

     verbatim, quotation, example, smallexample,
     display, smalldisplay, format, smallformat

  For example (literally), the `example' style results in something
  like the following to be generated:

     @example
     COMMENTARY TEXT
     @end example

  Additionally, the built-in `include' style inserts COMMENTARY TEXT
  directly, flush-left, without any "@" tags.  All styles except for
  `verbatim' and `include' also perform "@"-escaping for at-sign,
  left-curly-brace and right-curly-brace ("@", "{" and "}", respectively)
  to prevent texinfo misinterpretation.  You can inhibit this processing
  with the name pure-STYLE, for example `pure-example'.  NOTE: There is
  no `pure-include' style, since that combination is redundant.

  You can specify a particular path to use for module searching
  with a setsearchpath directive, which takes a sexp: (DIR DIR...).
  For example:

     @twerpsetsearchpath ("..")

  This sets the search path to simply the parent directory.  This
  path is actually used as a prefix; if the search fails for the
  specified path, the normal `%load-path' is then searched.
  Each DIR may also be a symbol (e.g., `top_srcdir'); in that case,
  the value of the specified environment variable (if non-#f) is used.

* Errors

  The indexes are read first.  If there is an error during this
  process, the output file is not opened.  After index reading, any
  kind of error results in the output file being deleted (if not to
  stdout).

* More Twerp Processing

  All directives beginning w/ "@twerp" are reserved for future use.


TODO: Handle multi-line directives.
      Clean up error handling.
      Make `keep-going-on-missing-tag?' optional.