[AD] Re: [AL] allegro DTD

[Elias Pschernig <elias@xxxxxxxxxx>]

Oh, I sent this to the wrong list. But luckily you read this one as
well :)

On Sun, 2004-11-28 at 12:14 +0100, Stepan Roh wrote:
> 
> On Sat, 27 Nov 2004, Elias Pschernig wrote:
> 
> > I have some question about that allegro.dtd in the makedoc CVS module,
> > in case who designed it is reading this list:
> >
> > - Isn't there something more readable than DTD which could be used to
> > describe the XML? :)
> 
> XML Schema: http://w3.org/XML/Schema

Ah, doesn't look much more readable after a quick glance. Anyway, this
was rather rhetorical.. I just felt DTD it is hard to read by humans
when trying to figure out how the XML should look (in the end I just
scanned for !ELEMENT tags and wrote them all down).

> > - How do I put in functions who have the same description? E.g:
> > "@@extern int @os_version;
> > @@extern int @os_revision;
> > @xref os_type, os_multitasking
> >   The major and minor version of the Operating System currently running."
> 
> Your example does not have functions, but variables which is a different 
> XML element. To answer your question: you won't. Each function needs 
> separate element with unique id (for xrefs). You would have to introduce 
> some function-group holding functions and move description (and 
> return-value?) into that.
> 

I see. Shouldn't be a big problem to just require every
function/variable to have its own documentation.

> > - If point 1 above isn't resolved, the following will need to be added
> > to the DTD at some point I think: retval section, example section,
> > example reference
> >
> > - header/footer/front-page: They seem too output-format specific. I'd
> > like the XML to contain the contents, and nothing else. So probably
> > should remove them at some point I think.
> 
> What's the replacement?

The output plugins. The HTML plugin can decide to put some sort of
Prev/Up/Next buttons, PDF will have maybe the current section as header
and the page number as footer, the man plugin will make it look like a
man page, and so on. The XML itself will contain the documentation only.
This gives maybe up a bit of flexibility, but I think it makes sense.

One of the things making the current makedoc so complicated is that it
has to deal with all the output specifics while reading in the ._tx file
(instead of leaving it to the output generators). And I don't see how
the docs have any advantage from it.

> 
> > - what is the block-quote element? It is there, without comments..
> 
> Some elements are derived from DocBook: 
> http://www.docbook.org/tdg/en/html/docbook.html. This one is 'blockquote':
> 
> Block quotations are set off from the main text, as opposed to occurring 
> inline.
> 

Ah. My ._tx->.xml converter will have no use of it right now I think,
but could later add something to ._tx which translates to it, since it
looks like it could be useful.

-- 
Elias Pschernig