Re: [AD] xfixicon documentation

[Grzegorz Adam Hankiewicz <gradha@xxxxxxxxxx>]

On 2004-07-21, Elias Pschernig <elias@xxxxxxxxxx> wrote:
> Maybe we should put all the build/*.txt into the main
> documentation.

In the HTML version they are externally linked from the external
readme.html. You need some *magic* to index a second layer of
external documents from another one and get the external links
working correctly.

> - Utility programs
>   - grabber.txt
>   - dat
>   - and so on

The docs could integrate those external files better.

> - Tutorial

Aren't you trying to swallow too many things at once?

> Grzegorz, do you think this would be possible? It would require
> something like  a new "chapter" command or something similiar.

You can't design a feature with a single sentence and two times
the word something in it. I don't know exactly what you want,
will need to be more precise.

Note that documentation is not exactly hierarchical. In first place,
some chapters have an introduction containing important information
which new users might skip and have problems with. It already
tends to happen with the info/html version. A hierarchical TOC
would be more of a cosmetic feature, so maybe it should go inside
a @html/@!html block.

I think there's a pattern in new people prefering to read everything
from front to back, and those who already did it and find it
bothersome to skip again through several chapters to find the
function they know is somewhere around but not exactly where.

For completeness we have been adding lots of external files to the
HTML version and that doesn't fit into any hierarchy. While popular,
other formats are left in disadvantage because they can't do such
tricks.  Maybe this negative effect can be solved with placeholders
that tell the user to look more carefully in the allegro directory
for the missing file.

For book like formats like PDF you would need a "swallow external
file" command, as you wouldn't expect the user to go and print
another .PDF file for a few pages. The placeholder would be a joke.

Looks like the documentation is drifting as well towards a monolithic
solution. Therefore, in Allegro 5 we will have a single file per
function/variable description. Wait, we already have man pages,
that's not right...