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

[Peter Wang <tjaden@xxxxxxxxxx>]

On 2005-09-10, Matthew Leverton <meffer@xxxxxxxxxx> wrote:
> I envision scenarios such as: a newbie on a.cc posts a problem
> regarding blit(). A veteran helps him out by linking to the manual and
> explaining something. Someone (perhaps the same person) then takes it
> upon himself to click on the linked blit() function and then click
> "edit" and make a clarification or update to the description. Trusted
> editors then get notified that there is a pending change. Assuming
> it's accepted, it instantly updates the manual and all downloadable
> versions of it - without having to wait a few months (or years) for
> the next Allegro release. That would *never* happen with an offline
> makedoc format. Once people start doing that and seeing themselves get
> credited with doc updates, they may just very will start proactively
> writing documentation.

Matthew, I like your idea and I'm sure you'll do a great job with it.
So I'm keen to coordinate between the two approaches.

This is my idea of how it could work.  For every entry, you would
provide two views on your site: the official wording (which is
read-only) and then the unofficial (editable) version.  The official
version would be regularly reimported, either from Allegro releases or
directly from CVS.

Some trusted people would be given the authority to check if the
modified version was acceptable, and if so it would be "copied over" to
become the official version.  If it is rejected there would usually be a
good reason (i.e. something outright wrong), in which case either it
could be modified further until the problems are fixed, or the modified
version could just be discarded.

For now, the "copying over" to the official version would actually
involve generating a diff to be committed manually to CVS, which your
site would then reimport later.  This is the most inconvenient part, but
it should be okay.  (We might also be able to set it up so a.cc can
commit directly, if there are no conflicts.)

If you do an import and an official entry has diverged from an
unofficial entry, then the unofficial entry could be updated or
discarded, by regular users.

Now, this depends on there being a common syntax between both versions
of the docs, and being able to export from the online version reliably
such that a diff will work.  I think we'd be happy with whatever syntax
you use, so long as there is enough information there for the offline
outputs.  Ideally one file format could serve both purposes, though your
site would only present a fragment of that to be editted at any one time.

What do you think?  Or did I restate what you had in mind already?

Peter