     Warning: The ADOC project and this documentation are far from complete!
              Please report bugs and direct comments to

                       Tobias Ferber, <ferber@rpk.mach.uni-karlsruhe.de>

This document describes ADOC version 1.01, which extracts Autodocs or Texinfo from source code.

Copyright © 1995 by Tobias Ferber,  All Rights Reserved.

GNU GENERAL PUBLIC LICENSE
**************************

gpl.texinfo

Contributors
************

  * Tobias Ferber, <ukjg@rz.uni-karlsruhe.de> wrote ADOC and this documentation.

  * Harald Kunze, <kunze@rpk.mach.uni-karlsruhe.de> contributed most of the ideas and forced the project to come into life.

Introduction
************

The ADOC scanner creates Autodocs or Texinfo source from source code. It is an enhanced version of Bill Koesters Autodoc program as of 21-Aug-89 which is part of C=ommodore's Native Developer Kit (NDK).

ADOC scans the input files for a special kind of comments: the autodoc comments.  Autodoc comments start at the begining of a line with a string of the form

     ?***??* lib/fun ...

The ? stands for characters which are ignored, they must however be ``black'', i.e. they must not be tabs or spaces.  The * ist ment literally, so in these places there must be an asterisk.  lib/fun is the identifier which specifies the library and the name of the function described in the following comment.  lib and fun consist of upper- and/or lower case letters, decimal digits, a dash - and/or the underscore _.  The rest of the line is ignored.

E.g.: A standard C language autodoc comment begins like this:

     /****** mylib/myfun **************************

The following lines make up the function description, a sequence of one or more sections.  A section begins with the section heading, a line with only --- and at least two --- capital letters.  Some common section headings are

     NAME, SYNOPSIS, FUNCTION, INPUTS, RESULT, ...

Each line in the function description must be prefixed with a black character followed by at least one white space or the end of the line. An autodoc comment ends with a line beginning with a black character followed by at least two asterisks *.  An example template comment can be found at the end of this document. See Style Guide, for further details.

Options
*******

ADOC reads the command line from left to right and collects filenames and options before it starts processing your input. The filenames are queued and processed in the same order as they appear in the command line.  The list-file option @ is replaced by the contents of the list file read in top-down order. If no input files are specified ADOC will read from the standard input stream.

Options for the Autodoc output
==============================

--autodoc
     ADOC creates an autodoc file. (This is the default)

--no-form-feeds
     Usually the functions in ADOCs autodoc output are seperated by form feeds (^L). With this switch ADOC omits them. (This switch is a no-op in --texinfo mode).

--table-of-contents
     A table of contents is written to the output followed by the autodoc functions. Functions and toc-entries are always in the same order, so --preserve-order also affects the table of contents. (This switch is a no-op in --texinfo mode).

--preserve-order
     With this option ADOC does not sort the functions before writing the autodoc output. (This switch is ignored in --texinfo mode).

Options for Autodoc and Texinfo output
======================================

--stdin
     This switch behaves like a filename for the standard input stream. Using it does not only force reading from stdin but you can also specify the files to read before and after the standard input.

--output-file FILENAME
     This option allows you to specify a filename for ADOC's output. If this option is ommited ADOC will write to the standard output stream.

--error-file FILENAME
     Like --output-file this option allows you to redirect ADOC's output. The difference between the two is that this option redirects warnings and error messages from stderr into the file FILENAME.

--flip-slashes
     This option converts \* to /* and *\ to */. This allows C language comments in the autodocs without nesting comments in the source code.

     The name of the option might give you the idea of a general conversion of backslashes into slashes. This is however incorrect. The character on the left or right of the \ must be an asterisk (*). Please note that *\* is transformed into */*.

--tabs-to-spaces
     Tabs in the input are turned into spaces with a default tab size of 8. This is the default in --texinfo mode.

--tabsize NUMBER
     The tab size is changed to NUMBER.  (default is --tabsize 8). This option implies --tabs-to-spaces.

--line-length NUMBER
     Function headers in the autodoc output will be NUMBER columns wide.  (default is --line-length 80). (This option has no influence on ADOC's Texinfo output).

--internal
     ADOC will only read comments with an i in column 5 or 6. (same as --yank-type "i").

--yank-type TYPE
     ADOC will only read comments which have in column 5 or 6 one of the chatacters in the TYPE string.

--indented-comments
     The autodoc comments normally have to start at column 1, i.e.: they must not be indented.  This option allows indented comments, but it does not check whether or not the indentation of all comment lines is equal or not.

     Additionally, if the indentation is not a multiple of ADOC's tab size, the conversion of TAB characters into spaces might lead to wrong results. This is due to the fact that ADOC does not remember the columnar position of each body text line but silently assumes that they all start at a tab stop column.

     In general it is not recommended to make use of TABs in indented comments. If you really insist on them you can pipe these files through expand and ADOC's output through unexpand:

          $ cat *.c | expand -t8 | adoc -I | unexpand -t8 -a > adoc.out

--reindent-bodytext NUMBER
     This option changes the indentation of lines in the body text of all functions to NUMBER spaces.  If NUMBER is 0 then the current indentation is removed which is default in --texinfo mode.

     In order to remove the current indentation ADOC cuts a columnar block beginning at column 1 from the function body. The width of this block is the maximum width without hurting any text.

     There is one more thing to mention:  This option automatically converts all TAB characters into the apropriate number of spaces.  You want this because the new indentation might destroy your textual layout otherwise. The conversion is performed before the removal of the indentation.

     If you want to change the body text indentation via --reindent-bodytext but insist on having TAB characters instead of spaces then you have to pipe the ADOC output through unexpand:

          $ adoc -I *.c | unexpand -t8 -a > adoc.out

--preserve-indentation
     This option avoids reindentation of the body text (e.g.: in --texinfo mode where --reindent-bodytext 0 is ADOC's default).

--sort-entries
     This option forces sorting of the functions which is default in both --autodoc and --texinfo mode.

-MMACRO VALUE
     Defines a value VALUE for a macro MACRO which is expanded when writing the body text of a function.  (e.g.: the above mentioned conversions of for --flip-slashes and --texinfo are implemented in this manner).

     Note that there must not be a space between -M and the name (i.e. the source string) of the macro.

-U MACRO
     Undefines a macro MACRO no matter whether MACRO had been defined with -D or -M or not at all.

Options for Texinfo output
==========================

--texinfo
     Write texinfo source instead of autodocs.  This switch implies --tabs-to-spaces. --preserve-order and --no-form-feeds are ignored.  The functions in the texinfo output are always sorted, tabs are always expanded and there will be no form feeds.

     Some conversions will be performed on your autodoc body text, especially:

          @  ->  @@
          {  ->  @{
          }  ->  @}

--project
--revision
--edition
--copyright
--author
     ADOC's texinfo header reserves these four macros.  Their value defaults to their name.  --project is not only used on the title page but also as the name for the .info or .guide file.

     These options actually define the macros PROJECT, EDTITION, REVISION, COPYRIGHT and AUTHOR as if they had been defined via -D.

--no-references
     In --texinfo mode, ADOC tries to find matching nodes for the identifiers in the SEE ALSO section.  You can however force ADOC to write this section as it is by giving this switch.

     Best results can be obtained by writing one reference per line in the same lib/fun format as in the header line of the referenced function.  ADOC will however try to prepend the current functions library name to the identifiers and removes parens, commata, white spaces and newline characters in order to find the referenced lib/fun header.

--parse-references
     This option prints one "See ..." sentence containing all references from the SEE ALSO section.  No itemization is used.

     The name of this option might insinuate the necessity of passing it together with other options which need to analyze the SEE ALSO section.  This is however incorrect.  The name of this option is somehow an archaic requilict from those times where ADOC learned to look closer at it's input. It could also be called --make-one-sentence-of-references or something similar.

--itemize-references
     ADOC puts the parsed references as an @item into an @itemize environment.  (This is default in --texinfo mode).

     Parsing the references is done automatically, even if you guess that you need the --parse-references option.  This not a good guess. Perhaps you should better look at the above description of this option.

--no-grouping
     ADOC will not make use of texinfo's grouping feature. (This is the default).

--group-sections
     The section body (following the title keyword) will be grouped into a @group ... @end group environment in order to prevent TeX from breaking the page inside a section.   The current implementation of texinfo does not allow placing the section keyword into the @group as well:

          ! @group invalid in context where filling is enabled.

--body-environment STRING
     This option allows you to specify the texinfo environment into which the section body text will be placed.  The internal default is --body-environment smallexample and so each section body is placed into an environment of the form

          @smallexample
            <body text>
          @end smallexample

     If --group-sections is specified, then this @group is placed into the given environment like this:

          @smallexample
          @group
            <body text>
          @end group
          @end smallexample

     Please note that this environment is not used within parsed references in the SEE ALSO section.

--texi-funtable
     This switch tells the texinfo code generator to place a function into a @table environment with each section keyword as a @b{}old @item.  This might however look ugly and lead to an immense amount of overfull \hbox{}es because TeX will then indent the following body text twice (for the @item and for the @example) and so ADOC's default is to write a section keyword like an ordinary, indented, @b{}old paragraph.

--form-feeds
     With this option a page break is forced by inserting a @page command in front of each function description.  An exception is the first function of a library which always begins on the same page as the library @chapter.

--texi-header-file FILENAME
     ADOC comes up with a minimal header and titlepage when writing texinfo output.  This option allows you to replace ADOC's internal header with the contents of FILENAME.

     Note that a macro expansion of macros defined via -D will be performed on the contents of FILENAME.

--no-texi-header
     This option forces ADOC to ommit writing a texinfo header and a title page.  Texinfo output begins with the (Top) @menu.

--no-texi-index
     No function index and no table of contents is used in the texinfo file.

-DMACRO VALUE
     Defines a value VALUE for a macro MACRO which is expanded when writing the texinfo header.  These definitions are not performed on the body text of a function description like those defined via -M.

     Note that there must not be a space between -D and the name of the macro.

Miscellaneous Options
=====================

--no-output
--dry-run
     ADOC only reads your input (and eventually prints warnings). No output will be written.

--silent
     ADOC will behave more briefly with this option.

--help
     A list of options and a short description will be printed to the standard output stream.

     If your terminal is limited to 80 columns then you can use

     -h0
          To print only the usage:... line

     -h1
          To print only the ``short'' options (those with one dash -).

     -h2
          To print only the ``long'' options (those with two dashes --).

--version
     Author and version information will be printed.

Influencing ADOC's pedanticness
===============================

--no-warnings
     ADOC will not print any warnings.

--check-keywords
     ADOC will complain about section title keywords which are not in the example below.

--check-presence
     ADOC will complain if one of the keywords in the example below is missing in a function description.

--pedantic
     ADOC will complain about almost everything.

Style Guide
***********

This chapter is under development.

How ADOC reads your input
=========================

ADOC scanns your input for autodoc comments. These comments begin on the leftmost column in a new line which most likely looks like one of those:

/****** mylib/myfun ******
     This is the beginning of a standard C or Rexx Language autodoc comment for the function myfun in the library or module mylib.

;****** mylib/myfun ******
******* mylib/myfun ******
     Most assemblers use a semicolon (;) or an asterisk (*) to begin a remark.

#****** mylib/myfun ******
     This type is known in Makefiles and shell scripts.

%****** mylib/myfun ******
     For autodoc comments in TeX or METAFONT we need the percent sign (%).

When ADOC encounters the beginning of an autodoc comment it starts collecting section headings and body text lines and saves them for later use in the code generator.

The lines inside autodoc comments must be prefixed by a black character. This character is made invisible in the output.  To be more precise: ADOC removes the black character in column 1 if the following character is a TAB or a newline character but it replaces it by a space if the following character is a space character.

Each line which contains entirely capitalized letters is assumed to be a section heading unless it contains only one single upper case character.

The indentation of section headings and body text lines does not matter. You should however use an indentation of 3 spaces for a section heading and 7 spaces for body text lines. Note that ADOC allows you to adjust the indentation for the output via the --reindent-bodytext option.

Example comment
===============

Here is a sample ``correct'' autodoc comment taken from the autodoc.style which is part of Commodore's Native Developer Kit (NDK):

     /****** financial.library/StealMoney ***************************************
     *
     *  NAME
     *     StealMoney -- Steal money from the Federal Reserve Bank. (V77)
     *
     *  SYNOPSIS
     *     error = StealMoney( userName,amount,destAccount,falseTrail )
     *     D0,Z                D0       D1.W    A0         [A1]
     *
     *     BYTE StealMoney
     *          ( STRPTR,UWORD,struct AccountSpec *,struct falseTrail *);
     *
     *  FUNCTION
     *     Transfer money from the Federal Reserve Bank into the specified
     *     interest-earning checking account.  No records of the transaction
     *     will be retained.
     *
     *  INPUTS
     *     userName      - name to make the transaction under.
     *                     Popular favorites include "Ronald Reagan"
     *                     and "Mohamar Quadaffi".
     *     amount        - Number of dollars to transfer (in thousands).
     *     destAccount   - A filled-in AccountSpec structure detailing the
     *                     destination account (see financial/accounts.h).
     *                     If NULL, a second Great Depression will be triggered.
     *     falseTrail    - If the DA_FALSETRAIL bit is set in the destAccount,
     *                     a falseTrail structure must be provided.
     *
     *  RESULT
     *     error - zero for success, else an error code is returned (see
     *             financial/errors.h).  The Z condition code is guaranteed.
     *
     *  EXAMPLE
     *     Federal regulations prohibit a demonstration of this function.
     *
     *  NOTES
     *     Do not run on Tuesdays!
     *
     *  BUGS
     *     Before V88, this function would occasionally print the address and
     *     home phone number of the caller on local police 976 terminals.
     *     We are confident that this problem has been resolved.
     *
     *  SEE ALSO
     *     CreateAccountSpec(),security.device/SCMD_DESTROY_EVIDENCE,
     *     financial/misc.h
     *
     ****************************************************************************
     *
     *  Private notes:
     *     A4=stringbean
     *     A3=dogbreath
     *  Must preserve A1 for taxshelter.library
     */

There are three spaces from the * to the start of each HEADING. There is one tab after the * before the start of the body text. No other tabs are used.

Note that ADOC also allows the use of spaces to indent body text lines. You can even mix tabs and spaces!  (We recommend to avoid TAB characters.)

General style notes
===================

  * It is critical that changes be noted in a sane manner.

  * When referring to a function, the standard format is FunctionName().

  * Capitalization should be correct.  Here are some guidelines:

      1. Trademarks, must be capitalized.

      2. Names of ``things'' are as defined. For example, OpenWindow(), and ``a Window structure''. ``fiddles with your window'' does not refer to the structure, and should not be capitalized.

  * Lines terminate at column 79, so the autodocs are readable from within an 80 column window.

For further guidelines refer to autodoc.style --- Commodore's autodoc style guide which is part of the Native Developer Kit (NDK).

Bugs
****

  - Most of ADOC's ``short'' options are compatible with Bill Koester's Autodoc Program.  -C, -s, -a, -F, -r and -w are ignored for compatibility.

  - This documentation is far from being complete

  - Most of the options are not tested

  - The -M option actually does not affect the SEE ALSO section in texinfo source if parsing is enabled.  This might change in the future when using funexpand().

  - TeX will not break a page inside of indented paragraphs in @example or @smallexample blocks.  The result might look ugly. Here is a hacky workaround for this problem:

          adoc --texinfo | sed "s/^ / /" > outfile.texi

Index
*****

The index is under development.