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

[Grzegorz Adam Hankiewicz <gradha@xxxxxxxxxx>]

Hi.

Here's a proposal to change Allegro's doc directory structure. The
actual version has the problem that it may be confusing for somebody
new to find the apropiate file from those many laying around. Also,
it's nicer to have it separated by formats.

At http://www.terra.es/personal7/gradha/newallegrodocs.zip
(20Kb) you have a sample. There's a copy at
http://leo.worldonline.es/jerzegor/newallegrodocs.zip, but this one is
slow even for me!  The contents of the file are basically the following:

newallegrodocs/
newallegrodocs/src
newallegrodocs/src/ahack._tx
newallegrodocs/src/changes._tx
newallegrodocs/src/const._tx
newallegrodocs/src/faq._tx
newallegrodocs/src/help._tx
newallegrodocs/src/thanks._tx
newallegrodocs/src/makedoc.c
newallegrodocs/src/manual._tx
newallegrodocs/man
newallegrodocs/txt
newallegrodocs/html
newallegrodocs/info
newallegrodocs/rtf
newallegrodocs/texi
newallegrodocs/build
newallegrodocs/Makefile

You can probably imagine what each directory is for. The provided makefile
works under linux, should work for djgpp too except the info part, but I'm
not sure. Ignore it, I used it just for testing. Now, the funny part is
the build subdirectory. This is where I would like to put those readme.*
files which are now at the root directory.

Some of the reasons are that gui-like people aren't able to click on a
readme file and open it properly due to extension associations, and most
platform extensions are not so obvious for newbies. Also, the big number
of readme files may fool people. My proposal is to move those readme.*
to docs/build/platform.txt, like build/djgpp.txt, build/unix.djgpp,
etc. Then, put a single short readme.txt file at the root, saying that
since Allegro is multiplatform you have to go to docs/build/ directory
and choose the apropiate platform you use in order to read the
build/installation instructions.

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

Files like AUTHORS, CHANGES, etc can be generated through makefile,
copying from the docs/txt/ directory.  Of course such files should be
pregenerated and packaged with releases. Finally, I changed allegro._tx
to manual._tx, much more explicit. The best would be allegro-manual._tx,
but I guess we still keep that 8+3 fileformat limit.

Comments?

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