[Libclc-developers] Re: Suggested documentation format

[Jan E. <je...@li...>]

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

Hm if this is going to be in the C files itself, may using
some sig like POD format does

/* =pod

=head1 NAME

lolz...

etc...

=cut */

>@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'?

(3)

Hm, after wrting this short reply I realize that one could really USE
pod, it's already written and can be embedded (I guess)
into any language that supports multi-line comments (or POD
directly).


- Jan Engelhardt