Re: makedoc syntax (was Re: [AD] Screen destruction documentation update)

[Matthew Leverton <meffer@xxxxxxxxxx>]

On 9/9/05, Peter Wang <tjaden@xxxxxxxxxx> wrote:
> > On 2005-09-09, Elias Pschernig <elias@xxxxxxxxxx> wrote:
> > > Can we get rid of any ` at least for the new makedoc?
> 
> I think the textual parts of new makedoc documents should be strict XML,
> with no "enhancements".  You'd have to write <code>blah</code> or
> <tt>blah</tt> instead of `blah'.  We also would drop non-standard stuff
> like "&gt" without the semicolon, the automatic interpretation of "&" as
> "&amp;", missing closing tags, etc.
> 
Personally, I think unless we would switch to a completely non-hacky
procedure that easily allows multiple people to edit and submit
changes to documentation without having to be an expert in XML or
XHTML that there's not a whole lot of reason to make any drastic
changes to the makedoc.

I recently wrote a ._tx => XML converter in PHP that used a very
minimal approach. Ie, I didn't try to "correct" a lot of stuff, and I
left most things as is.

Example: <ref name="allegro_init" syntax="void allegro_init()">

I know there were other XML converters that were already built, but
they were way too wordy for what I wanted to do (slap it in the
database). I'm just using it as an intermediate step for now, but
please don't make me rewrite it... :'(

I'm working on an online tool that resembles a Wiki, but is more
structured. Ie, you can edit pages on the fly, but it knows something
about function lists, related examples, etc. I fully plan on using it
to replace a.cc's online Allegro manual, which means the official docs
would be forked upon launch and not kept in sync.

It's my belief that the Allegro documentation (if not installation
related) shouldn't be bundled with Allegro, but just able to be
downloaded at anytime. This means documentation wouldn't be tied down
to a particular release of Allegro. (Instead, each individual function
will be marked with version information - which is useful anyway.)
People on Windows generally prefer to download a pre-built binary  +
CHM. However, under Linux I think it's quite acceptable (and expected)
to provide man/info pages with a source library.

The data from my online manual will be downloadable as XML, so it
could be converted into any other format (man, HTML, CHM, ._tx, etc),
which could be used as the official docs. I know it's a plan with much
controversy, so I'm not going to even try to convince Allegro
developers to adopt it, nor based from past conversations do I really
expect that they will.

However, I'm sure that in the long run it will help attract more
documentation writers, especially because it will be highly visible
and also serve as an organized online repository for other
documentation, such as add-on libraries,  tutorials, and references.

Of course the release date of the system isn't even close yet, so if
something much better than the current makedoc is developed sooner,
I'll all for it. Don't worry, it won't stop me from finishing my
online documentation tool anyway. ;)

--
Matthew Leverton