Re: Source Text Tools

["Eric W. Nikitin" <enikitin@apk.net>]

Michael van Acken <mvacken@t-online.de> wrote:
> I started on a set of modules which could be extended into a number of
> utilities working on the textual representation of modules.  

Will these be used exclusively for source code manipulation?  Or could these
also be extended for programatic uses such as "object serialization" or
reflection (sorta like Java Bean info)?

> Especially a tool to extract a commented interface definition from a
> module is sorely missed.  Someone should implement such a beast.  In
> the meantime I want to start a discussion how "doc comments" should
> look like.  I have some points I would like to see addressed:
> 
> o To which declaration is a doc comment attached?  For procedures this
> is simple, the comment is placed after the header but in front of the
> first local declaration.  How is this handled for the other kinds of
> declarations? 

To keep things consistent, I'd think all doc comments should be handled this
way: the comment is placed after a declaration.

> o Are free floating comments, i.e., comments not attached to a
> declaration, permitted and how are they dealt with?

I can see where free floating comments would be desirable.  To make these
automatic (rather than having to mark the end of a previous attached comment
-- like using `@end deftp' in texinfo), would the tool have to look for 
`END ProcName;', and so forth? 

> o Should there be special commands available to refer to other
> declarations from within a comment?  E.g. a procedure doc comment
> could refer to its parameter `foo' as @oparam{foo}, and to a type
> `Bar' as @otype{Bar}.  This kind of reference tags allow consistency
> checks (does the referenced declaration exist? is it of the correct
> kind?) and permit to insert hyper-links when translating to HTML.

Hmm... I'm not sure about this one.  I think I'd have to see an example of
how you think these kinds of commands should be used.  Are these specialized
@ref commands?

> o Should there be additional formatting commands?  The simplest
> command would be an empty line to signal a paragraph, @samp{...} to
> mark example code, and commands like @table / @enumerate / @itemize to
> implement tables.  This way more flexible targets like Texinfo or HTML
> can do better formatting.  Of course the set of additional format
> commands should be small but powerful.  I'm sure Eric will have a
> suggestion for a suitable set of commands.

The texinfo commands that I use the most and find the most useful (besides
the structuring commands like @node, @chapter, @menu, etc.) are mainly for
formatting and cross referencing.  Here is a list and short description of
each: 

Font and style commands:

   @cite   -- name of a book (with no cross reference link available)
   @code   -- syntactic tokens
   @dfn    -- introductory or defining use of a technical term
   @emph   -- emphasis; produces *italics* in printout
   @kbd    -- input to be typed by users
   @minus  -- generate a minus sign (or `---' for an em-dash)
   @samp   -- literal example or sequence of characters
   @strong -- stronger emphasis than @emph; produces *bold* in printout
   @var    -- metasyntactic variables (e.g., formal procedure parameters)


Lists and tables:

   @enumerate -- enumerated lists, using numbers or letters
   @itemize   -- itemized lists with and without bullets
   @table     -- two-column tables with highlighting

   @item      -- used with the above lists and tables for each entry
   @asis      -- used with @table for entries without added highlighting
   @bullet    -- used with @itemize


Paragraph formatting:

   @example   -- example that is not part of the running text (fixed font)
      (and @smallexample, which uses a smaller font in `smallbook' format)
   @format    -- example in the current font that does not narrow the margins
   @quotation -- excerpt from another (real or hypothetical) printed work
   @noindent  -- prevents paragraph indentation


Cross reference:

   @url   -- indicate a uniform resource locator (URL)
   @uref  -- reference to a uniform resource locator (URL)
   @ref   -- cross reference

   @pref  -- variation on @ref
   @xref  -- variation on @ref


Any other suggestions?  Can any of these be omitted?  Can some of these be
done automatically?

> o Should formatting for a given display width be implemented?  Doc
> comments have to be reformatted for a convenient line width.  Having
> some comments formatted for a width of 132, while others prefer 72,
> just won't do.

How do texinfo, texi2html, and the other programs do this?  I think I'd
prefer the various tools allowing display width to be set by the user,
rather than having an @ command embedded in the doc comment itself.


Tim Teulings <tim@edge.ping.de> wrote:
[About special formatting commands]
> The problem with this aproch is, that you end implementing all keyword
> html or latex has. Tables and list will soon per to be nice stuff
> implemented. You can restrict yourself to a *very* limited set of
> options or drop the idea of makeing your own language and use an
> existing one. for autodoc I planed to yuse SGML together with the
> SGML-Tools. This will allow you a huge number of formatting stuff while
> beeing able to generate a huge number of document types without doing
> it all for yourself.

Do you mean you'd allow embedded SGML?  (Which Document Type Definition
(DTD) would you use?  XML and XSL?)

-- 
___________________________________________________________________________
           Eric Nikitin              |   When thou wakest, let love forbid
    _Into the Realm of Oberon:       |   Sleep his seat on thy eyelid:
 an Introduction to Programming and  |   So awake when I am gone;
 the Oberon-2 Programming Language_  |   For I must now to Oberon.
       ISBN:  0-387-98279-5          |       
     http://www.springer-ny.com      |       -- A Midsummer Night's Dream
___________________________________________________________________________