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

[Elias Pschernig <elias@xxxxxxxxxx>]

On Sat, 2005-09-10 at 00:50 -0500, Matthew Leverton wrote:

> 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 sounds great, it's just what I had in mind when working on a new
makedoc in C (which is now superceded by Peter's Haskell one).

> 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.

Documentation being tied down to a release isn't a problem I think. In
fact, it makes it easier to have only the docs for what you need.
Version information of course should have been in the docs from the
beginning.

> 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.

I think the online interface should get a little feature to send a patch
to [AD]. So everytime someone makes a change, or maybe once per week,
the system compares the online version to CVS, then makes a patch
against ._tx. Of course, that requires to keep the source as ._tx (hence
it's important to design a new format right now), or alternatively
back-convert to ._tx (in which case XML sources would make it easier of
course).

> 
> 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.

Yes, really the only problem I see is that a web-browser is currently
not as accessible as a text editor. There are two things I find most
important:

- Easy editing for developers (at least for me personally, it means an
offline text editor, and a wiki-like text format)

- Easy editing for users (wiki-like web-interface)

Now, ideally, I think both could use the same ._tx source format (not
the current of course), just one edits it in a text-editor, the other in
the web-interface. It also would make the patch sending trivial
(everything is ._tx).

> 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. ;)

Good luck :) A lot of people have spent many hours on it already - all
of Grzegorz's work on the original makedoc, Tomasu's perl makedoc (which
is what was actually used for the docs in the allegro bot I think),
Tomasu+my C makedoc, and now the new Haskell makedoc.

And yet, we still have to deal with the current hackish ._tx format
whenever we want to modify documentation :/

-- 
Elias Pschernig