[AD] Documentation upgrade patch

[Grzegorz Adam Hankiewicz <gradha@xxxxxxxxxx>]

Hi.

Here's a patch to upgrade the Allegro documentation. The story is not very
long, and I didn't comment anywhere the reason of the new changes (ala
makedoc.c :-) so this is it:

Some time ago I started playing with LaTeX and postscript generated
documentation. texi2dvi generates files ready for print, and I tried it
with allegro.texi. To my surprise, it gave a few erros, and all cross
references where undefined and looked ugly.

After some trial and error, I thought I had found a bug or restriction, so
I emailed the texinfo mantainers. But as Eli Zaretskii pointed out,
allegro.texi was a little bit broken. Although it worked for makeinfo, it
didn't work correctly for texi2dvi. Things which were wrong: 

- Cross references. The only way to get them is to have sections inside
  chapters. That's pretty simple to add, and the info output is not very
  different from the old one: you have one line more describing the
  section you are in, which is the same as the function/variable
  description you are reading. Probably most people won't see the
  difference at first glance. The fine thing is that with sections, cross
  references get generated correctly, as well as an automatic index at the
  end of the documentation.

- The previous effect eliminates the need of a generated index chapter, so
  I have put it inside @ifinfo/@end ifinfo, because info still needs it.

- dvi pages get printed only after a titlepage, so I added this command.
  But info ignores it, so I patched makedoc to generate twice the text
  inside @titlepage and @!titlepage, one time for texi2dvi and another
  time for info. The way it works is like a simple goto like sentence in
  C: first it detects the beginning of the titlepage; once it's finished,
  it repeats the process setting a variable to avoid looping forever.

- I added the "@setchapternew off" command. It reduces final documentation
  output in around 40 pages, so it's worth it.

After this, the dvi output is pretty beautifull (IMHO) and useful. There's
still a problem: for those sections which use preformatted text (like the
joystick section), the dvi output puts some square black boxes after those
lines which are too long for the page width. We could use the @finalout
texi command to prevent this from happening, but those boxes are really
there to point out a problem: we should reformat the text. 

However I have not done it. Should I? dvi is not really a primary output
of the documentation but it should be dealt with sooner of later... It
would mean reformatting such texts to say 65 or 70 columns instead of 77
as they are now. If nobody objects to it, I will post soon another patch
which corrects those long lines, and possibly an optional make command to
get directly the .dvi file.

 Grzegorz Adam Hankiewicz   gradha@xxxxxxxxxx - http://gradha.infierno.org
 Other web pages:  http://glub.ehu.es/  -  http://welcome.to/gogosoftware/

Attachment: allegro_documentation_patch.gz
Description: Binary data