Positional cues or not

[Marcin 'Qrczak' Kowalczyk]

Tue, 13 Feb 2001 05:58:49 -0500 (EST), Jan Skibinski <jans@numeric-quest.com> pisze:

> 	Should the documention standard respect the module
> 	authors' wishes and provide at least some sort of support
> 	for 'categories'? I think, it should.

I agree. Sections of a module could be separated by "lots of dashes"
with a section title together with them (either on the same line or
on the next).

We can allow a tool to distinguish chapters/sections/subsections by
decreasing numbers of dashes. Don't define which number corresponds
to which level - just anything above a threshold (e.g. >= 8) marks
a part, and different lengths can mark different levels (if the tool
supports different levels).

Let's say that comments marked by "--" are ignored by the documentation
tool, unless it's a pretty printer of the whole source. Comments marked
by "---" are basic descriptions of entities: each comment refers to an
entity if it's adjacent to it, or is a standalone comment if it doesn't.
Comments marked by eight dashes or more are section headers. (Or four?)

These rules (after precise definitions of the details) are enough to
have a concrete tool which produces a summary of a module (extracting
type signatures etc. from the source), formatted in any format
(HTML, LaTeX, text). Anything more specific will be compatible with
this simple view: we can add keywords for more precise control,
but comments with keywords can be emitted as is by a simple tool.

Keywords don't require special punctuation. They can be spelled
in ALL CAPS so that pure English text is not taken as a keyword
by mistake. For example EXPORTED (so that we can distinguish what
should go into the interface documentation and what should go only
to browsable internals), and custom keywords to be specified with
an invocation of a sophisticated doc tool to have project-specific
subsetting of the documentation.

A remaining thing is hyperlinks to different entities or modules (or
fully qualified entities). It's easy to have SEE as a keyword, but
we also want to mark an identifier used as a part of a sentence, e.g.

  To clarify, @doesDirectoryExist@ returns True if a file system object
  exist, and it's a directory. @doesFileExist@ returns True if the file
  system object exist, but it's not a directory (i.e., for every other
  file system object that is not a directory.)

(this is a real quotation - I don't suggest to use @ in particular).

The same concept can be uniformly applied to quoted chunks of code.
In this case a tool can make hyperlinks to names it recognizes if
it wishes.

Let me stop at this point, and clarify one detail about basic
recognition of kinds of comments. For a block of comment lines the
form of the first line matters, so it can be equivalently written

  ---- Overview of the foo process
  ----
  ---- Blah blah blah
  ---- blah blah blah

or

  ---- Overview of the foo process
  --
  -- Blah blah blah
  -- blah blah blah

-- 
 __("<  Marcin Kowalczyk * qrczak@knm.org.pl http://qrczak.ids.net.pl/
 \__/
  ^^                      SYGNATURA ZASTĘPCZA
QRCZAK