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

[Matthew Leverton <meffer@xxxxxxxxxx>]

Peter W wrote:
> 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.
>...
> What do you think?  Or did I restate what you had in mind already?
> 
Honestly I think trying to use such a procedure to keep them in sync
would be highly impractical in a real usage scenario. You could have
10 minor changes applied to documentation, and then someone make a
major offline change that gets imported first to the Allegro ._tx
source. Now you have 10 minor patches that might fail, or in reverse
order - the major one will. The only way I'd really consider trying
such a thing is if the online usage of the Allegro manual got very
little use (in the form of editting).

Personally, I think it's a lot of headache to endure just because
there's a handful of people who would prefer to use the offline
makedoc approach. (Right now, obviously they are the only ones to
write the documentation - and they do a good job getting the
essentials documented. I'm not trying to imply that they aren't.) I'm
assuming that after an online system goes live and people get
comfortable with it, then it will start getting used a lot. The higher
the online usage gets, the less sense it makes that it be the
secondary version.

So really, I'm just banking on my belief that it will be so easy to
use that the only people that won't initially be comfortable with it
are those that have spent a lot of time writing ._tx files in the
past. If things stay disjointed forever, then I think it will be
easier for a.cc editors to monitor [AD] for patches and manually copy
them over to the online docs on a as needed basis, then to write some
sort of auto import system. Because, really once a stub entry is
created the details can easily be filled in by anyone. In the event
that the Allegro team finds it challenging to keep up with changes
made to the online docs, then they should just allow the online docs
to become official. (Who really wants to sit around and document
anyway?)

The short of it is that I'd rather come up with a way to make offline
editing usable than to try to maintain the online docs as some sort of
secondary version that must be kept in sync. From my perspective, the
most practical approach is to export the online docs to XML (when a
new version of Allegro is released) and have it converted to the
appropriate formats. Perhaps this means it is converted back to ._tx
(ugh) for use with makedoc - I really wouldn't care at all, as it
wouldn't affect the online manual.

After the system is live, I think usage will dictate how things go.
Right now all we can do is speculate on what it might look like. If
either extreme scenarios happen (it gets used a lot or not at all),
then it will be obvious which should become the master. If usage is
somewhere in the middle, then some sort of compromise would have to be
reached. (If the online version doesn't prove to be popular, I'd
actually be more inclined to just disable editing for it completely.
My online "wiki" editor could then just be used for side articles,
tutorials, etc.)

I know that people tend to doubt that radical changes will work out,
but I think if given a fair chance it will be for the better. I
typically don't mention things when they are as early in the
design/development process as my online docs are, but I didn't want
others to go to the same length that I am and end up with two
completely incompatible systems...

--
Matthew Leverton