| Re: [AD] Makedoc patch (was: 4.0.x branch) |
[ Thread Index |
Date Index
| More lists.liballeg.org/allegro-developers Archives
]
On Thu, 21 Feb 2002, Peter Wang wrote:
> On 2002-02-21, Stepan Roh <stepan@xxxxxxxxxx> wrote:
> > > > Why? Generating pretty documentation at the time of compiling
seems like> > > > bad idea to me anyway. Only maintainers generating WIPs
and CVS users
> > > > (which should be experienced users anyway) will be forced to
install
> > > > necessary tools.
> > >
> > > So why are we still doing it?
> >
> > Who knows? Because noone wants to change it?
>
> There are lots of useful formats around, but no-one uses all of them.
> Putting everything in the main package increases the download size,
> splitting documentation into separate packages is annoying (for
> users). Downloading extra stuff to generate docs is annoying too.
Why are the users forced to download entire (big) sources to be able to
use Allegro library in its own projects? They should be able to download
compiled library and generated documentation. Package with library sources
will stay on its size, because external documentation will just move to
source files.
On Wed, 20 Feb 2002, Bob wrote:
> 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 :)
Oh, Jesus! You actually read next sentence, right? :-)
> > 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).
Brand new? DocBook was created in 1991 and is standardized by OASIS. It is
since used in many projects. Its XML version is of course not as old
because XML was standardized in 1998, but is used in many projects too.
SGML and XML versions are not that different, only SGML uses DSSSS and XML
uses XSL for output generation.
> [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 :)
But you have to write those programs. You can't use existing ones. Say,
for example, that I want to generate PDF. How will you do it? With
DocBook, someone already wrote such styles, but I wonder if you will write
program which will be able to output nice FOP sources.
> [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.
Les flexible? You mean noone can write improper documentation like in the
past, right?
And honestly, I don't know Doxygen much, but I know Javadoc very well.
> [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.
OK, here is a snippet from Linux 2.4.14
Documentation/DocBook/parportbook.tmpl. It is SGML version, but XML is
very similar. It is the answer to all the paragraphs above. Any questions?
<funcsynopsis>
<funcsynopsisinfo>
#include <parport.h>
</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>parport_find_device</function></funcdef>
<paramdef>const char *<parameter>mfg</parameter></paramdef>
<paramdef>const char *<parameter>mdl</parameter></paramdef>
<paramdef>int <parameter>from</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>parport_find_class</function></funcdef>
<paramdef>parport_device_class <parameter>cls</parameter></paramdef>
<paramdef>int <parameter>from</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
These functions take a device number (in addition to some other
things), and return another device number. They walk through the
list of detected devices until they find one that matches the
requirements, and then return that device number (or
<constant>-1</constant> if there are no more such devices). They
start their search at the device after the one in the list with
the number given (at <parameter>from</parameter>+1, in other
words).
</para>
> > 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.
Sure.
> > 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.
New one required this tag, older ones don't. But they worked.
> 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.
I have to say again: why reinventing the wheel. DocBook's set of tags
proved to be good, so where's the problem?
Here are fundamental questions we should ask ourselves:
1. Does Allegro need replacement for _tx? (I think so)
2. Should it be based on XML or on some proprietary format? (I think XML
or SGML)
3. If it should be XML/SGML should it use some standard DTD or brand new
one? (I think standard DocBook should be used)
4. Should the API documentation be generated from library sources or
written separately? (I think it should be generated from sources - then it
will be consistent)
5. Should the documentation be shipped generated or will everyone have to
generate it itself? (I think it should be shipped generated)
6. If it will be shipped generated should it be in package with sources or
compiled library, in separate package (all output formats together) or in
separate packages (one package per output format)? (I think it should be
shipped in one package per output format)
Have a nice day.
Stepan Roh