| Re: [AD] Makedoc patch (was: 4.0.x branch) |
[ Thread Index |
Date Index
| More lists.liballeg.org/allegro-developers Archives
]
Stepan Roh wrote:
[snip]
By "non-standard XML-based documentation" I meant "XML-based, but using
non-standard tags".
Which comes back to the same thing: there are no standard tags in XML :)
And standard in this context means "widely used and
adopted documentation structure".
If something is brand new. how can it be both widely used and adopted? :) I
don't see much of XML used in documentation (at least, no one seems to
advertise it).
[snip]
By "binary output format generators" I meant "output generators which are
distributed as binary files (programs)". I will try to be more clear this
time :-)
Yes, which is why the source is supplied :)
[snip]
This clearly indicates bad documentation layout. See Javadoc's or
Doxygen's standard doclets how it should look like.
Yes, I know those - that's how AllegroGL and FBlend are documented. I have
proposed including all docs in the sources, but that's less flexible than
having the docs manually written. Doxygen also can't generate .txt nor
standard HTML, which are big minuses.
[snip
Using DocBook could solve this too.
See Peter's post on why this is a bad idea in general. I would like to keep
the tags *really* simple - adapted to Allegro even. This way, the
documentation is split up logically (functions, descriptions of modules,
macros, etc)
[snip]
Yes, that's true, today's Allegro documentation is just an API (with
exceptions to FAQ (direct support in DocBook :-) ), contributors, aHack
and maybe others). But maybe someone will write nice guides (remember
Vivace?) in the future and in that case you will have to add more tags, so
why not to move to something bigger today?
The thing is, DocBook isn't big enough in some respects (APIs can't easily
be documented), and too big in others. I beleive that DocBook is not well
suited for the task.
And for example documentation in Linux kernel is also API-based and is
written in DocBook SGML.
Do you have a URL? I can't seem to get my hands on it.
I think that Javadoc or Doxygen could be very useful here (of course
documentation will have to go into sources). You can also generate DocBook
from this.
Now this i more interesting. Doxygen could then be used to generate the XML
files, which are then converted to other output formats.
I hope so, but makedoc from Allegro 4.1.x said to me something like
'@document_title missing' and gave up when I tried to generate
documentation for 4.0.x and 5.x. Are you sure this won't happen in the
future?
Well, that error was there because makedoc *required* this tag to be
present, so it could give a title to the HTML files. As for it not happening
the future, I can't give any guarentees; but with a good set of tags, this
is not likely to happen.
It is a good amount of work: will
someone do the same for Allegro's special XML-based documentation format?
If you fear the size of DocBook, the Simple DocBook with less tags is
available and it is also possible to define our own subset of tags.
--
- Robert J Ohannessian
"Microsoft code is probably O(n^20)" (my CS prof)
http://pages.infinit.net/voidstar/