You are looking at historical revision 16548 of this page. It may differ significantly from its current revision.

• egg

chicken-doc-admin

chicken-doc-admin is a tool for generating and maintaining Chicken documentation for the chicken-doc egg.

Overview

chicken-doc-admin provides facilities to create and modify a Chicken documentation repository for chicken-doc. It includes a command-line tool to convert egg documentation and manual pages from the Chicken wiki for use with chicken-doc. It also provides an API for repository manipulation.

The typical mode of using chicken-doc-admin is to check out a copy of the wiki using Subversion, then run the chicken-doc-admin command against the copy's egg and man directories. Repeat when the wiki is updated.

Quick start

The default repository location is in the Chicken install tree and may not be writable by your user. If so, either use sudo or set an alternate writable location with:

$ export CHICKEN_DOC_REPOSITORY=/path/to/some/writable/directory

Now download and process the wiki documentation:

$ svn co --username anonymous --password "" \
     http://galinha.ucpel.tche.br/svn/chicken-eggs/wiki
$ chicken-doc-admin -i
$ chicken-doc-admin -m wiki/man/4
$ chicken-doc-admin -e wiki/eggref/4

Command-line

$ chicken-doc-admin COMMAND

  -l           list repository information

Print some information about the repository, such as its location and version.

  -i           initialize repository non-destructively

Initialize the repository in the current default location or as overridden by CHICKEN_DOC_REPOSITORY. The directory will be created if it does not exist. This command must be run before any documentation can be processed. You should usually initialize an empty directory; initializing a populated directory won't delete anything, and may confuse us.

  -e dir       process svnwiki egg directory DIR

Process a copy of svnwiki egg directory DIR (usually /path/to/wiki/eggref/4), adding each egg documentation page to a node at toplevel and the identifiers contained in the page to that node's children. Egg names are displayed as they are processed. Currently, the node name is that of the file basename, so file eggref/4/9p becomes node 9p.

  -m dir       process svnwiki manual directory DIR

Process a copy of svnwiki Chicken manual directory DIR (usually /path/to/wiki/man/4). Adds unit documentation to nodes at toplevel (Unit posix -> posix) and Chicken core documentation to nodes under toplevel node chicken (Parameters -> chicken parameters).

chicken-doc-admin internally maps each manual page to a node path, based on its filename.

  -E file      process svnwiki egg file FILE

Process an individual svnwiki egg file FILE as in -e. The node name is that of the file basename, so file eggref/4/9p becomes node 9p. This file may reside anywhere, not just inside an svnwiki checkout.

  -M file      process svnwiki man file FILE

Process an individual svnwiki manual page FILE as in -m. The node name is determined by an internal map of filenames to node paths. You can not currently override the destination node path from the command line.

  -r           regenerate indices

Regenerate documentation indices; at the moment, this is just one index, the node -> path search map. This is automatically done after -e and -m, but must be done by hand after -E, -M and -d as it is fairly expensive.

  -d path      delete node path recursively

Delete node path PATH and everything under it. Useful for removing, for example, an entire egg from the repository.

WARNING: If you do not provide a path, the root path () is used, which will delete the contents of the entire repository. Fortunately, you can usually just regenerate it.

Repository

The repository layout produced by chicken-doc-admin's automatic egg and man parser is detailed in the documentation for the chicken-doc egg.

To recap, documentation for each egg and unit is placed in a toplevel node named after that egg or unit, with procedure, macro, etc. identifiers for that unit as the node's children. Chicken core man pages not corresponding to a particular unit are placed individually under the "chicken" toplevel node; for example, Non-standard macros and special forms resides under the path (chicken macros).

As with chicken-doc, you can override the repository location by setting an environment variable:

export CHICKEN_DOC_REPOSITORY=/path/to/repository

This is useful for testing and also if the default location, which is located in (chicken-home), is not writable by you. You can verify the current repository location with chicken-doc-admin -l.

Low-level repository structure

This structure is subject to change.

|-- .chicken-doc-repo    Repository magic file; contains repository info
|-- id.idx               Alist mapping node identifiers to paths
|-- lock                 Lock file to prevent write conflicts
|-- root/                Documentation root node ()
    |-- 9p/              Documentation node (9p)
        |- ,text         (9p) text description (full egg doc)
        |- ,meta         (9p) metadata alist (signature "9p egg", type 'egg)
        |- file-open/    Documentation node (9p file-open)
           |- ,text      (9p file-open) identifier text description
           |- ,meta      (9p file-open) metadata (signature "(file-open ...)",
                                                  type 'procedure)

Certain characters are %-escaped in filenames, such as / and period.

Proper wiki documentation

This section is a work in progress.

The short and skinny

• Use svnwiki type tags (procedure, macro) around all identifiers to be documented. See Chicken-specific wiki syntax.
• Place related tagged identifiers on consecutive, non-blank lines; the text description below is then used for all of them.
• Ensure all identifier signatures can be read with a call to (read). Don't use characters such as | (pipe).
• Ensure open and close tags for bold, italic, links, code and identifiers are located on the same line.

svnwiki identifier type tags

Each identifier is assigned a type (such as 'procedure, 'macro) corresponding to svnwiki tags "procedure", "macro" etc. It is also assigned a signature which is taken verbatim from the svnwiki tag content. Finally, the identifier name also comes from the signature; the signature is parsed using (read), and the result may be a symbol (for example, a constant), or a list --- typically, a procedure or macro signature, in which case the first element of the list is used. With rare exception, as when the signature contains an illegal character such as | (pipe), this strategy works well.

The currently recognized svnwiki tags are:

(define +identifier-tags+
  (list "procedure" "macro" "read" "parameter"
        "record" "string" "class" "method" "constant"))

Identifier descriptions

When creating an identifier description, the parser takes all text from after the occurrence of the identifier tag up until the next section marker, or the next identifier tag. This follows the informal standard for Chicken documentation on the wiki, and is a natural way to separate descriptions logically. Some points to note:

• The description stops even if the section marker denotes a nested section. This works well in general, although there are a few eggs which do contain important identifier info in nested sections. To get this information, you have to read the full documentation, or rearrange the structure.
• If several identifier signatures occur on consecutive lines, without any blank lines between them, they are considered part of a "group" of identifiers. The following text description then applies to every identifier in the group. Again, this corresponds to common practice on the wiki.
• If you look up one identifier in a group, they will all appear, along with the single text description.

Parser limitations

The svnwiki parser in this egg is unsophisticated and requires several concessions to its quirks, which are hopefully not too onerous. Ideally, these will be fixed.

• Open and close tags should appear on the same line. This applies to bold, italic, links, type tags, and so on.
• Tables will only be readable if each "tr" row is on a single line. Even so, they are not particularly readable.
• Paragraphs are not reflowed.

However, the parser does perform several transformations to make the output more readable.

API

To be documented.

Bugs

The repository takes up a lot of space, the parser is pretty silly and the index is slow. On the plus side, it doesn't have any external dependencies.

Author

Jim Ursetto

Version history

0.1.1

Initial release

License

BSD