Re: [AD] Proposal to change Allegro's doc directory structure

[Grzegorz Adam Hankiewicz <gradha@xxxxxxxxxx>]

> > >A good question would be if these docs/build files should be generated
> > >from ._tx files. It could be an option if the manual could integrate
> > >them like the changes or thanks files, but I see no way to do this
> > >(at least for all format options).
> > 
> > But that requires building makedoc...
> 
> You are right, the docs/build files must exist in the archive, but we
> can still make them be generated from ._tx files. This is how authors,
> thanks, and changes are handled already.

That was exactly my idea, sorry for not clearing it very much. Certainly
it's not a good idea having to generate the instructions in order to
read them :)

> I think it might be a good idea to generate docs/build/*, because then
> we can generate .html versions as well and put them on the web page.

Yes, documentation integration is a nice bonus. When I said above that
I saw no clear way to integrate those files, I was meaning about all
possible output formats. At the moment only the html version can easily
include external files which aren't part of the original ._tx file,
and that's a pity because you cannot have all documentation centralized
and accesible from a single point (which OTOH may be horrible for
non-hyperlinked versions like .txt or .rtf).

> I think your proposal is nice, but one (small) part does not convince me:
> If I want to look at the doc for something, the first name I try is
> <name of lib>.txt, or .doc (well, before word, that were the standard
> for text format documentation on DOS).
> Especially as this file can be installed among other docs, so it must
> bear a distinctive name (eg /usr/info/manual.txt isn't very distinctive...)

This happens because of that 8+3 restriction, all packaged files
should be in this format. Now, since later everything will be handled
through a makefile which _will_ be platform dependant, you can leave
build/format/manual.ext like that, and let 'final output' be renamed,
leading to something like this under DOS:

  c:\djgpp\info\allegro.info
  c:\allegro\docs\txt\manual.txt
  c:\allegro\docs\html\manual.htm
  etc

...and the following under Linux:

  ~/allegro-?/docs/info/manual.info
  ~/allegro-?/docs/manual.ps
  etc
  /usr/local/info/allegro-manual.info

The rationale is that anything under allegro/* is related to allegro, so
manual.txt has a clear meaning (there). Outside of the allegro directory
the name can be modified to use the advantage of long filenames under
OSes which support them, DOS can keep the old name.

PS: I forgot to say that it may be worth to also restructure the makefiles,
    like putting them under something like makefiles/platform.

-- 
 Grzegorz Adam Hankiewicz   gradha@xxxxxxxxxx   http://gradha.infierno.org/