Re: [AD] Docs and set_gfx_mode

[Elias Pschernig <elias@xxxxxxxxxx>]

On Fri, 2004-09-24 at 19:06 +1000, aj wrote:
> docs suggestions:
> 
> 1.  bottom of the  /docs/html/readme.html       "A general introduction to 
> Allegro"  there is no  'Back to Contents' link at the bottom of the page, 
> like all the other pages.
> it would be nice to have the "back to contents" link at the top of  all  pages.
> 

Seems to be a bug in makedoc. I'll try look at it some time since I'm
somewhat familiar with the makedoc code again right now.. unless
Grzegorz does it first :)

> 
> 2.  when i use the links at the top of a page to find a function, the 
> browser jumps to the link, but if its at the bottom of the page, my target 
> link does not appear at the top of the browser window, so it feels like i 
> have gone to the wrong place, i then need to read all the other targets on 
> the page to find which one i clicked on..  solution:  place a lot of blank 
> lines at the bottom of the HTML pages, so lcicked links always appear at 
> the top of browsers.
> 

That's a problem of your browser though.. not sure we should work around
browser bugs. Blank lines at the bottom of every page might cause other
problems..

What we could do is, make a separate HTML page for every topic, as some
other HTML documentations do. But that would be a rather big change,
given that makedoc is more or less unmaintainable (don't ask me how long
it took me to make the simple change of adding a @chapter command), and
I'm not sure I'd like that.. often you actually want to read about other
commands available in a chapter. The real solution would be, replace
makedoc by another system which can output the docs in different
formats, like the gnu.org documentations. They let you choose between
all the docs in one document, one html page per chapter, or one html
page per node. Or maybe if we create the .html pages out of the .texi
that actually would work with allegro already..

-- 
Elias Pschernig