\input texinfo  @c -*-texinfo-*-
@comment %**start of header
@setfilename adoc.guide
@settitle ADOC -- Extract Autodocs from source code
@paragraphindent 0
@iftex
@afourpaper
@headings double
@c @smallbook
@finalout
@setchapternewpage odd
@end iftex
@comment %**end of header

@c generate only one master index for the rest
@synindex fn cp
@synindex vr cp
@synindex ky cp
@synindex pg cp
@synindex tp cp

@set RCSID $VER: $Id$
@set VERSION 0.17
@set EDITION 0.9beta

@ifinfo
@node Top
@c    node-name,  next,  previous,  up
@top
This document describes @code{ADOC} version @value{VERSION}, which
extracts Autodocs or Texinfo from source code.

@noindent Copyright @copyright{} 1995 by Tobias Ferber,  All Rights Reserved.
@end ifinfo

@ignore
@iftex
@shorttitlepage ADOC
@end iftex
@end ignore

@titlepage
@title ADoc
@subtitle Extract Autodocs from source code
@subtitle Edition @value{EDITION} for Version @value{VERSION}
@subtitle @today
@author Tobias Ferber

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1995 by Tobias Ferber,  All Rights Reserved.
@sp 2
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.
@end titlepage

@comment %**end of `header.texi'


@menu

Overview & Legal stuff

* Copying::           Your rights
* Contributors::      People who have contributed to @code{ADOC}
* Introduction::      The name of the game

Controling @code{ADOC}

* Options::           Running @code{ADOC}
* Style Guide::       How to write autodocs

What you should be aware of

* Bugs::              Known problems

Appendix

* Index::             Contents and Overview
@end menu

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@node Copying
@unnumbered GNU GENERAL PUBLIC LICENSE
@input gpl.texinfo

@node Contributors
@unnumbered Contributors
@cindex Contributors
@cindex Author

@itemize @bullet
@item
Tobias Ferber, @code{<ukjg@@rz.uni-karlsruhe.de>} 
wrote @code{ADOC} and this documentation.

@item
Harald Kunze, @code{<kunze@@rpk.mach.uni-karlsruhe.de>}
contributed most of the ideas and forced the project to come into life.
@end itemize

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@node Introduction
@chapter Introduction
@cindex Autodocs
@cindex Autodoc comments

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

@code{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

@example
?***??* lib/fun @dots{}
@end example

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

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

@example
/****** mylib/myfun **************************
@end example


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

@example
NAME, SYNOPSIS, FUNCTION, INPUTS, RESULT, @dots{}
@end example

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 @samp{*}.  An example template comment
can be found at the end of this document.
@xref{Style Guide}, for further details.

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@node Options
@chapter Options
@cindex Options
@cindex Command line
@cindex Switchs

@code{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 @samp{@@} is replaced
by the contents of the list file read in top-down order. If no input
files are specified @code{ADOC} will read from the standard input stream.

@menu
* IO Options::            controling @code{ADOC}'s input and output
* Autodoc Options::       @code{Autodoc} output only
* Output Options::        both @code{Autodoc} and @code{Texinfo} output
* Texinfo Options::       @code{Texinfo} output only
* Warning Options::       influencing @code{ADOC}'s pedanticness
* Miscellaneous Options:: everything else
@end menu

@c %--------------------------------------------------------------------------

@node IO Options
@section Options controling input and output

@table @code

@item --stdin
@pindex --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.

@item --output-file @var{filename}
@pindex --output-file
This option allows you to specify a filename for @code{ADOC}'s
output.  If this option is ommited @code{ADOC} will write to
the standard output stream.

@item --error-file @var{filename}
@pindex --error-file
Like @samp{--output-file} this option allows you to redirect
@code{ADOC}'s output.  The difference between the two is that
this option redirects warnings and error messages from
stderr into the file @var{filename}.

@end table

@c %--------------------------------------------------------------------------

@node Autodoc Options
@section Options for the @code{Autodoc} output

@table @code

@item --autodoc
@pindex --autodoc
@code{ADOC} creates an autodoc file (This is the default)

@item --no-form-feeds
@pindex --no-form-feeds
Usually the functions in @code{ADOC}s autodoc output are seperated
by form feeds @kbd{^L}.  With this switch @code{ADOC} omits them.
(This switch is a no-op in @samp{--texinfo} mode).

@item --table-of-contents
@pindex --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 @samp{--preserve-order} also
affects the table of contents.
(This switch is a no-op in @samp{--texinfo} mode).

@item --preserve-order
@pindex --preserve-order
With this option @code{ADOC} does not sort the functions before
writing the autodoc output.
(This switch is ignored in @samp{--texinfo} mode).

@end table

@c %--------------------------------------------------------------------------

@node Output Options
@section Options for @code{Autodoc} and @code{Texinfo} output

@table @code

@item --flip-slashes
@pindex --flip-slashes
This option converts @samp{\*} to @samp{/*} and @samp{*\} to @samp{*/}.
This allows C comments in the autodocs without nesting
comments in the source code.

@item --tabs-to-spaces
@pindex --tabs-to-spaces
Tabs in the input are turned into spaces with a default tab size of 8.

@item --tabsize @var{number}
@pindex --tabsize
The tab size is changed to @var{number}.  (default is @samp{--tabsize 8}).
This option implies @samp{--tabs-to-spaces}.

@item --line-length @var{number}
@pindex --line-length
Function headers in the autodoc output will be @var{number}
columns wide.  (default is @samp{--line-length 80}).

@item --internal
@pindex --internal
@code{ADOC} will only read comments with an @samp{i} in column 5 or 6.
(same as @samp{--yank-type "i"}).

@item --yank-type @var{type}
@pindex --yank-type
@code{ADOC} will only read comments which have one of the chatacters
in the @var{type} string in columns 5 or 6.

@item -M@var{macro} @var{value}
@pindex -M
Defines a value @var{value} for a macro @var{macro} which is expanded
when writing the body text of a function.  (e.g.:@: the above
mentioned conversions of for @samp{--flip-slashes} and @samp{--texinfo}
are implemented in this manner).

Note that there must @strong{not} be a space between @samp{-M} and the
name (i.e.@: the source string) of the macro.

@item -U @var{macro}
@pindex -U
Undefines a macro @var{macro} no matter whether @var{macro} had been
defined with @samp{-D} or @samp{-M} or not at all.

@end table

@c %--------------------------------------------------------------------------

@node Texinfo Options
@section Options for @code{Texinfo} output

@table @code

@item --texinfo
@pindex --texinfo
Write texinfo source instead of autodocs.  This switch implies
@samp{--tabs-to-spaces}. @samp{--preserve-order} and @samp{--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:

@example
@@  ->  @@@@
@{  ->  @@@{
@}  ->  @@@}
@end example

Hack:

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


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

These options actually define the macros
@code{PROJECT}, @code{EDTITION}, @code{COPYRIGHT} and @code{AUTHOR}
as if they had been defined via @samp{-D}.  

@item --no-references
@pindex --no-references
In @samp{--texinfo} mode, @code{ADOC} tries to find matching nodes for
the identifiers in the @code{SEE ALSO} section.  You can however
force @code{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 @samp{lib/fun} format as in the header line of
the referenced function.  @code{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 @samp{lib/fun} header.

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

@item --no-groups
@pindex --no-groups
@code{ADOC} will not make use of texinfo's grouping feature.
(This is the default).

@item --group-sections
@pindex --group-sections
The section body (following the title keyword) will be grouped
into a @code{@@group} @dots{} @code{@@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 @code{@@group} as well:

@example
! @@group invalid in context where filling is enabled.
@end example

@item --body-environment @var{string}
@pindex --body-environment
This option allows you to specify the texinfo environment into
which the section body text will be placed.  The internal
default is @samp{--body-environment smallexample} and so each
section body is placed into an environment of the form

@example
@@smallexample
  <body text>
@@end smallexample
@end example

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

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

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

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

@item --form-feeds
@pindex --form-feeds
With this option a page break is forced by inserting a @code{@@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 @code{@@chapter}.

@item --texi-header-file @var{filename}
@pindex --texi-header-file
@code{ADOC} comes up with a minimal header and titlepage when writing
texinfo output.  This option allows you to replace @code{ADOC}'s
internal header with the contents of @var{filename}.

Note that a macro expansion of macros defined via @samp{-D} will be
performed on the contents of @var{filename}.

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

@item -D@var{macro} @var{value}
@pindex -D
Defines a value @var{value} for a macro @var{macro} which is expanded
when writing the texinfo header.  These definitions are @strong{not}
performed on the body text of a function description like
those defined via @samp{-M}.

Note that there must @strong{not} be a space between @samp{-D} and the
name of the macro.

@end table

@c %--------------------------------------------------------------------------

@node Miscellaneous Options
@section Miscellaneous Options

@table @code

@item --no-output
@itemx --dry-run
@pindex --no-output
@pindex --dry-run
@code{ADOC} only reads your input (and eventually prints warnings).
No output will be written.

@item --silent
@pindex --silent
@code{ADOC} will behave more briefly with this option.

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

@item --version
@pindex --version
Author and version information will be printed.

@end table

@c %--------------------------------------------------------------------------

@node Warning Options
@section Influencing @code{ADOC}'s pedanticness

@table @code

@item --no-warnings
@pindex --no-warnings
@code{ADOC} will not print @strong{any} warnings.

@item --check-keywords
@pindex --check-keywords
@code{ADOC} will complain about section title keywords which are not
in the example below.

@item --check-presence
@pindex --check-presence
@code{ADOC} will complain if one of the keywords in the example below
is missing in a function description.

@item --pedantic
@pindex --pedantic
@code{ADOC} will complain about almost everything.

@end table

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@node Style Guide
@chapter Style Guide
@cindex Style Guide
@cindex Example
@cindex Template comment

This section is under development.

@section General style notes
@itemize @bullet
@item
It is critical that changes be noted in a sane manner.

@item
When referring to a function, the standard format is @code{FunctionName()}.

@item
Capitalization should be correct.  Here are some guidelines:

@enumerate
@item
Trademarks, @strong{must} be capitalized.

@item
Names of ``things'' are as defined.  
For example, @code{OpenWindow()}, and ``a @code{Window} structure''.  
``fiddles with your window'' does not refer to the structure, and should not be capitalized.
@end enumerate

@item
Lines terminate at column 79, so the autodocs are readable from within an 80 column window.
@end itemize

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

@page
@smallexample
/****** 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
*/
@end smallexample

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

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

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@node Bugs
@chapter Bugs
@cindex Problems
@cindex Bugs
@cindex Compatibility

@itemize @minus
@item
Most of @code{ADOC}'s ``short'' options are compatible with Bill Koester's
@code{Autodoc} Program.  @samp{-C}, @samp{-s}, @samp{-a}, @samp{-F}, @samp{-r} and @samp{-w} are
ignored for compatibility.

@item
This documentation is far from being complete

@item
Most of the options are not tested

@item
Text in front of the first section title is ignored
(or is this a feature?)

@item
The @samp{-M} option actually does not affect the @code{SEE ALSO} section in
texinfo source if parsing is enabled.  This might change in the
future when using @code{funexpand()}.
@end itemize

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@node Index
@unnumbered Index
The index is under development.
@printindex cp

@page
@contents
@bye