Re: [AD] xfixicon documentation

[Elias Pschernig <elias@xxxxxxxxxx>]

On Wed, 2004-07-28 at 09:19 +0100, Grzegorz Adam Hankiewicz wrote:
> 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.
> 

I'm thinking about things like CHM or devhelp mostly - they are a bit
awkward to use right now, if compared to other CHM or devhelp docs. HTML
wouldn't change much, just the TOC wouldn't be a flat list, but have a
depth of 2. PS wouldn't change much. In PDF, instead of a huge list of
sections, there would be a few chapters, one of which would be "API
reference". info/man probably wouldn't change at all and ignore the new
@chapter (or similiar) command, but I don't use those 2 much so not
sure.

> > - Utility programs
> >   - grabber.txt
> >   - dat
> >   - and so on
> 
> The docs could integrate those external files better.
> 

Yep. That was exactly the reason that made me think about this. I
wondered where to include them, and it would mean, the current TOC would
get even longer and even more hard to navigate in. For things like
info/man - you would be able to type "man grabber" or "man dat", so
again, they could ignore the new @chapter command.

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

I think not. It is something that really is missing from the docs - e.g.
someone who uses Allegro for the first time, and for some reason is
confused by demo.c, would have a use for it. This is another topic
though.. it definitely shouldn't be appended to the current TOC which is
just a collection of ungrouped sections.

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

Well, having a hierarchical TOC instead of a flat is enough design -
most other docs I have installed here have a deeper hierarchy than
Allegro, even though they are much smaller.

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

Well, as I said.. even HTML or PDF would profit from it.

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

Yes, that wouldn't change at all. The actual contents, when read from
front to back, shouldn't get modified by this. Just the TOC.

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

I see no difference between looking at the PDF or the CHM docs here. It
would be nice in both to have the section "Mouse routines" under "API
Reference", and not just in the flat top hierarchy along with all the
many sections of the docs (especially if we add things like utility
programs, making even more entries there).

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

I like the idea of monolothic docs. Instead of having to hunt for docs,
I just have one place to find everything. But, I must admit, I have no
idea how much work it would be to add this to makedoc :)

-- 
Elias Pschernig