Re: Gnome Developer's documentation.

[Mark Galassi <rosalia cygnus com>]

Hmm: I started writing a long answer thinking that you were asking
about how to format code and comments in a <programlisting>.  Then I
actually read your text!

So at the end of this note I have a little blurb on printouts of
source code, but first I will actually try to answer your question.

    Gary> I was wondering (Mark?) whether sgml (or XML or somesuch) is
    Gary> flexible enough that one could write a DTD so that the sgml
    Gary> parser would scan the annotated C (or whatever) source files
    Gary> directly and effectively ignore the non-documentation bits
    Gary> while formatting the documentation directly from tags in
    Gary> source comments?

Whereas I think it is possible to choose your delimiters in SGML, I
don't think you can mix tags delimiters: if you are using < and >,
then you cannot start using /* and */ as delimiters (which wouldn't
really be right anyway -- you would want /* to be equivalent to
<begin-C-comment> or something).

If C comments and source happened to (by some lucky chance) behave in
an SGML-ically correct manner, then I would look into that
possibility.  Unfortunately C comments do not balance, and neither do
Lisp and C++ comments, which use a newline as end-of-comment.

So pre-processing the source is probably the only way.  That's OK
because you usually have Makefiles anyway.

    Gary> If this worked directly, it would be cool because the same
    Gary> file would serve as source for the code compiler and the
    Gary> documentation compiler.

[I can't find it in the GNU standards right now] It is discouraged to
try to write documentation from comments.  This is because very good
documentation should be written with care for the whole context, and
not just by extracting pasting pieces of information together.

/\/\/\/\

[this is the blurb in answer to the question you did not ask!]

I think there is a nice way of formatting source code: DocBook has a
"role" attribute (remember: attributes are those little things that
modify an element, like in HTML's <a href="..."> -- href is an
attribute of <a>).

For every tag, you can assign it a role if you think that the tag is a
bit too generic.

So my recommendation is that you use:

<programlisting role="C">
  C program text here
</programlisting>

and the same for lisp, perl, Python and other program listings.

Then in the *output rendering* you would acknowledge the tags and do
your thing.

[This last paragraph denotes a slightly bad attitude for now: I say
"leave it to the output rendering", but eventually someone will have
to implement that in the DSSSL context.  I have not yet researched the
issue, but I will later on for the purposes of Cygnus documentation.]