ADoc

Extract Autodocs from source code

Edition 0.9beta for Version 0.17

August 9, 2024

Copyright © 1995 by Tobias Ferber, All Rights Reserved.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the author.

Overview & Legal stuff

Controling ADOC

What you should be aware of

Appendix

GNU GENERAL PUBLIC LICENSE

@input 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.

1 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 title, a line with only — and at least two — capital letters. Some common section titles 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 section Style Guide, for further details.

2 Options

ADOC will read 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.

2.1 Options controling input and output

--stdin

This switch behaves like a filename for the standard input stream. Like that you can 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.

2.2 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).

2.3 Options for Autodoc and Texinfo output

--flip-slashes

This option converts ‘\*’ to ‘/*’ and ‘*\’ to ‘*/’. This allows C comments in the autodocs without nesting comments in the source code.

--tabs-to-spaces

Tabs in the input are turned into spaces with a default tab size of 8.

--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’).

--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 one of the chatacters in the type string in columns 5 or 6.

-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.

2.4 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:

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

Hack:

If you are absolutely sure that there are no tabs in your autodoc comments, then you can use ‘-t0’, which will lead to a better performance of the texinfo generator since tab expansion is not performed.

--project

--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, 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.

--itemize-references

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

--no-groups

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.

-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.

2.5 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.

--version

Author and version information will be printed.

2.6 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.

3 Style Guide

This section is under development.

3.1 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.

3.2 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.

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

4 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
• - Text in front of the first section title is ignored (or is this a feature?)
• - 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().

Index

The index is under development.

Table of Contents

About This Document

This document was generated on August 9, 2024 using texi2html 5.0.

The buttons in the navigation panels have the following meaning:

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

• 1. Section One
  • 1.1 Subsection One-One
    • ...
  • 1.2 Subsection One-Two
    • 1.2.1 Subsubsection One-Two-One
    • 1.2.2 Subsubsection One-Two-Two
    • 1.2.3 Subsubsection One-Two-Three     <== Current Position
    • 1.2.4 Subsubsection One-Two-Four
  • 1.3 Subsection One-Three
    • ...
  • 1.4 Subsection One-Four

This document was generated on August 9, 2024 using texi2html 5.0.