Chapter 2. Tool documentation

Table of Contents
2.1. extract-doc: Scheme comments to SXML
2.2. sxml2xml: pseudo-SXML to XML text

This section describes each tool installed as part of docscm in the docscm-config --tooldir directory.

2.1. extract-doc: Scheme comments to SXML

extract-doc filename...

Extracts documentation from Scheme files and writes out SXML DocBook entries to stdout. SRFI-10 external representations of comment blocks are used as an intermediate processing step.

2.1.1. Internal datatypes and procedures

record: (make-comment-block command lines code)

Holds a comment-block between parsing and output.

procedure: (->string x)

Convert an arbitrary scheme object to a string.

procedure: (split-paragraphs lines)

Splits a list of strings into a list of paragraphs, representing each paragraph as a list of strings. Empty (zero-length) strings are interpreted as paragraph separators in the input list.

procedure: (gen-body-text doc lines)

Emits a block of comment text to the output SXML document, after splitting it into paragraphs using split-paragraphs and formatting it appropriately.

procedure: (newsym)

A version of gensym that generates (reasonably) unique symbols not only within an instance of the scheme system, but also between runs, by incorporating the current time in the symbol.

procedure: (gen-variable-def doc lines varname initlist)

Formats a block of documentation for a variable as DocBook markup.

procedure: (gen-function-def doc lines fnname arglist)

Formats a block of documentation for a function as DocBook markup.

procedure: (gen-macro-def doc lines macroname arglist)

Formats a block of documentation for a macro as DocBook markup.

procedure: (gen-sxml doc lines)

Appends raw SXML text directly to the output SXML document. Used by the @sxml docscm command.

procedure: (dig-for-lambda-value body)

Recurses into an expression, trying (via a fairly sloppy algorithm) to figure out if it returns a procedure or not.

procedure: (gen-block cblk doc)

Processes a single docscm comment block.

procedure: (gen-doc filename items)

Returns an SXML fragment of documentation for file filename, generated from the comment-blocks in items.

procedure: (extract-doc filename)

Extracts documentation from the file passed in as an argument. filename is the file to parse. The function returns a quasiquoted SXML DocBook expression.