Re: [AD] Integrating docs/build in HTML

[ Thread Index | Date Index | More lists.liballeg.org/allegro-developers Archives ]


On 2003-09-12, Eric Botcazou <ebotcazou@xxxxxxxxxx> wrote:
> > This patch integrates docs/build/*txt in the HTML version of
> > the documentation.
> 
> This is a good idea,

Commited then.

> but what about going one step farther and pre-generating the
> HTML version of the build docs (as well as the readme file) in
> the distribution? We could put readme.txt and readme.html in the
> top-level directory, linking respectively to docs/txt/build and
> docs/html/build and eliminating docs/build.

I dislike this because the pregenerated version would be incomplete
without the full HTML manual. It's all too interconnected, people
could start reporting broken readme.txt links when they are just
exploring it and it could get annoying to tell them that we know the
main manual is not there and you actually have to build Allegro once.

Another version of the documentation brings more bloat to an already
bloated download.  People trying to read HTML documentation before
installing are likely to read it from the allegro website before
doing anything at all, which was the main motivation behind the
patch. Currently we tell them to get Allegro, unpack it and read
a file inside, which seems a rude beginning to get a few KB of text.

Finally, moving docs/build to docs/txt/build could annoy more
people already used to the structure, without making it easier
for new users, whose main problem seems to be reading enough of
readme.txt to know where to look for installation instructions.

BTW, is there really somebody using the .txt version of the
documentation for serious reading? I've always thought of it as a
'just-in-case' backup plan, when you are stranded in a corner of
the world, without internet acces, friends, somehow with a computer
and electricity but without the courage to open those strange ._tx
files. A very weird situation.




Mail converted by MHonArc 2.6.19+ http://listengine.tuxfamily.org/