OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Subject: Re: DOCBOOK: generating a reference manual from source code

/ Stefan Seefeld <seefeld@sympatico.ca> was heard to say:
| 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. ?

Yes, it is a bit inconsistent.

Here are some suggestions:

| module Input

This looks like a ClassSynopsis (role="idl", probably).

| {
|   typedef unsigned long Device;

DocBook is lacking a tag for type definitions. Perhaps
FieldSynopsis with a role attribute?

|   struct Toggle
|   {
|     enum type {press, hold, release} actuation;
|     unsigned long number;
|   };

The best I can suggest is a MethodSynopsis (which is ugly tag abuse)
with a role attribute.

|   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);
|   };
| };

Yuck. We're clearly unable to represent all of an IDL Synopsis.

Can you enumerate all of the elements that would have to be added to
describe an "IDLSynopsis" to the level of detail that a ClassSynopsis
works for Java/C++/etc.?

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

Yes, that would seem like a reasonable compromise, except that I'm not
sure how to handle the struct and union types without more hierarchical

| (Does anybody know about other projects that (want to) use docbook for automatic manual
| generation from inlined documentation ?)

This is definitely an interesting and "in-scope" problem.

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

PassiveTeX[1] and FOP[2] are free.

                                        Be seeing you,

[1] http://users.ox.ac.uk/~rahtz/passivetex/
[2] http://xml.apache.org/fop/
Norman Walsh <ndw@nwalsh.com>      | One of the great misfortunes of
http://www.oasis-open.org/docbook/ | mankind is that even his good
Chair, DocBook Technical Committee | qualities are sometimes useless to
                                   | him, and that the art of employing
                                   | and well directing them is often
                                   | the latest fruit of his
                                   | experience.--Chamfort

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Powered by eList eXpress LLC