Re: DOCBOOK: generating a reference manual from source code

[Stefan Seefeld <seefeld at sympatico dot ca>]

Norman Walsh wrote:
> 
> / Stefan Seefeld <seefeld@sympatico.ca> was heard to say:
> | However, in case of docbook I'm missing a couple of entities (or is it just
> | the documentation that lacks...?): typedefs, modules, enums for example
> | are missing.
> 
> DocBook is intended for software documentation, not necessarily a
> complete representation of all the abstract syntax elements of a
> particular language.

ok, may be not all, and not individually. But it appears a bit inconsistent
(not self-contained) that there are entities to represent functions and entities
for classes, but none for 'other' types. Wouldn't it make sense to provide a
'type' entity with similar 'meta data' such as 'typesynopsis' etc. ?

> I'm not sure exactly what you're generating, but I suggest that a good
> working solution is to use a role attribute to distinguish between the
> cases on some more general element.

ok, take this as an example:

IDL:

module Input
{
  typedef unsigned long Device;
  struct Toggle
  {
    enum type {press, hold, release} actuation;
    unsigned long number;
  };
  typedef Vertex        Position;
  typedef double        Value;
  enum Discriminator { telltale, key, button, positional, valuation};
  union Payload switch (Discriminator)
  {
  case telltale: Bitset state;
  case key: Toggle kselection;
  case button: Toggle bselection;
  case positional: Position location;
  case valuation: Value val;
  };
  struct Item
  {
    Device dev;
    Payload attr;
  };
  typedef sequence<Item> Event;
  interface Filter
  {
    boolean handle(in Event e);
  };
};

which is from an IDL file of a project that I'm working on. I'd like to generate
a reference manual from that, in various formats. I have written a tool (synopsis)
that can read the above, and translate it into an abstract syntax tree, where I
have nodes for 'module', 'class', 'typedef', 'variable', 'method', and all the others.
Only class, variable, and method can be easily documented in docbook (with some
associated text), for the others I'd have to improvise. While I can see the special
interest into class and method, I would expect that there was at least one general
entity set for types (which I could annotate with a 'role' attribute to encode the
specific name of the declaration or type, depending on the language, such as 'typedef',
'enum', etc.).
If 'class' was a special form of 'type', it would be possible to generate a full index
of all declared types, whether they are structured or primitive. But just classes don't
really help me at all. I want to document an API, not just a set of classes I define.
(Does anybody know about other projects that (want to) use docbook for automatic manual
generation from inlined documentation ?)

For html documentation I generate the output directly with an html formatter
(see http://www2.berlin-consortium.org/manuals/Warsaw/ as an example), but for
hardcopies (postscript, pdf) I have yet to find a way.
By the way, what do people use to generate postscript and pdf from docbook xml ?
What (free) tools exist that can deal with the FO output ?

Best regards,
		Stefan

------------------------------------------------------------------
To unsubscribe from this elist send a message with the single word
"unsubscribe" in the body to: docbook-request@lists.oasis-open.org