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

[Peter Wang <tjaden@xxxxxxxxxx>]

On 2005-09-11, Matthew Leverton <meffer@xxxxxxxxxx> wrote:
> 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).

That's fine.  Even if the process is not formalised as I described
above, I expect there to be liberal copying between the two sources so
it would still help to have as much common syntax as possible.

For the makedocers: let's wait until Matthew's system is live, then just
adopt whatever syntax he chooses for the makedoc format as well.  We're
not in a hurry.

> 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 am only really uncomfortable with having the code and docs live in two
different places, and using different version control systems.  If your
system could check [approved] changes into the CVS tree automatically
(and let's say we banned modifications to the docs outside of your site)
then I would have no qualms at all.

Peter