[Libclc-developers] Suggested documentation format

[Hallvard B F. <h.b...@us...>]

Here is a suggestion for a file format for documentation.
Contributors should write this, though maybe the documentation
manager(s) will clean the file up a little, and it will be used to
generate the other formats. If accepted, I'll write a Perl program to
process it.  The overall documentation structure reflects Unix man
pages, as in <http://libclc.sourceforge.net/documentation-policy.txt>.
I've also added an initial NAME section.  (Bertrand, are you there?:-)

Comments welcome.


An example first, since that's shorter than the format description.
(CVS replaces $Id$ below with info about the file.)

@comment $Id$
@comment Copyright 2003 Hallvard B. Furuseth <h.b...@us...>

NAME

clc_strblurg, clc_strglarp - fromp a string

SYNOPSIS

#include <clc_string.h>
char *clc_strblurg(char *src);
char *clc_strglarp(char *src);

Link with: clc library

DESCRIPTION

These functions modify their arguments by fromping the string src.
@break
clc_strblurg() blurgifies the string first.
@break
clc_strglarp() glarps the string afterwards.

RETURN VALUES

The functions return src, or NULL at failure.

ERROR CODES

CLC_ENOFROMP
The string could not be fromped.
The resulting contents of src is undefined.

CLC_ENOGLARP
The string could not be glarped.
src will contain the fromped but unglarped string.

EXAMPLE

    /* Print a blurgified string using @manpage{printf} */
    void printfromp(const char *str)
    {
        char *tmp = clc_strdup(str);
        if (tmp && clc_strblurg(tmp))
            printf("Glarp: %s\n", tmp);
        free(tmp);
    }


Format description:

- A document consists of a series of paragraphs separated by blank
  lines.  Whitespace at the end of lines are ignored.

- Normal paragraphs are plain text to be filled and justified.

- Lines starting with '@' <word> <whitespace> are single-line commands:
    @comment <text>...      -- a comment-line, not written.
                               Retained as a comment in some output
                               filetypes, at the start of the paragraph.
			       A comment may not contain '--' (because
			       that mucks up HTML comments).
    @section <name>         -- start a section (NAME, SYNOPSIS, etc).
    @subsection <name>      -- start a subsection.
    @break/@br              -- force a line break.
    @list ... @item <name> ... @end list -- list of items.  Each item
                            can be followed by paragraphs describing it.
    @fixed/@pre/@preformatted ... @end fixed/pre/preformatted
                            -- print fixed font, and don't fill.
    @indent ... @end indent -- indent (but still fill/justify) contents.
    @manpage <name> or <name>(section) -- explicit reference to manpage.
  One may also write @manpage{...} or @fixed{...} in the middle of text.
  @fixed{} text should be short: it will not be broken with line breaks.
  Or should it be, at spaces?  I'm not sure.

- Various error checks are done: For example, all @items in the
  ERRORS section are checked to be CLC_E*, ERANGE or EDOM.

- The special cases below let us avoid most of the above commands.
  Or are some of these too complex so it's simpler to always use
  commands?

- Indented paragraphs are not filled or justified, and they are printed
  in a fixed-width font.  4 spaces of indentation are removed, or less
  if the whole paragraph is not indented that much.
  Thus, example code can be written just as it is by indenting it.

- The paragraphs in the SYNOPSIS section are not filled or justified,
  since they contain C code.

- A paragraph which consists of one line of uppercase words is taken
  to be a section header, e.g. NAME, DESCRIPTION, SEE ALSO and so on.

- In the ERRORS section, if the first line of a paragraph is simply
  one all-uppercase word (which may have digits and underscores), it
  is considered to be an @item line.  Also, if ERRORS has @items but
  not @list, the whole ERRORS section from the first @item and onwards
  is wrapped in @list ... @end list.

- In the SEE ALSO section, single comma-separated words are translated
  to manpage references if they either start with "clc_" or are ISO C
  (1989) function names.  If they are neither, they produce a warning.

Other details:

- Preformatted lines should be 58 or fewer characters long, or less
  still if they are inside already-indented text (@indent or @list).
  [Or should this be less still for the sake of HTML pages?]

- Don't indent with TABs, use SPACEs.  Some contributors will be using
  tab-width 4, others will be using 8, so TABs for indentation would
  cause havoc.

- Please start each sentence on a new line.  Troff notices this and
  puts extra space after such sentences ending with '.', '!' or '?'.
  I'll make a word starting with an uppercase letter except CLC_E* and
  E*, which follows a letter, a ',', '!' or '?', and a space, to also
  be taken to start a sentence.

- Picky people can write opening single quotes as "`", not "'", like
  troff and nroff want.  We can't do that with quotes that should be
  the C quoted char "'", so a program can't convert "'"s to "`"s.

- 8-bit characters are taken to be latin-1 characters.


Questions:

- Nroff and troff retain multiple spaces typed into a paragraph,
  though troff's space is thinner than most other characters.  Should
  we retain this feature, or transform multiple spaces to single ones
  in filled paragraphs like HTML does?

- If a line in an otherwise unindented paragraph starts with
  whitespace, nroff and troff retains that whitespace at the beginning
  of a new line.  However, they still break the line if it gets too
  long or fill it from the next line if too short.  I'm not sure what
  to do about this feature.  We could retain it, but my suggestion is
  to report such paragraphs as an error -- probably there should be a
  blank line between the indented and the unindented part.  OK?

- There are two basic dashes: minus and hyphen.  Hyphen may be
  shorter.  I suggest all minuses are treated as minus, except that it
  is a hyphen if there is a letter or digit on each side.  Thus, one
  should write 'size - strlen(foo)', not 'size-strlen(foo)'.  OK?

- Should manpage references in text, html and PostScript formats use
  the Unix format 'strcmp(3)', or just 'strcmp'?

-- 
Hallvard