Re: [avr-libc-dev] Re: New layout for documentation

[Joerg Wunsch]

As Christopher X. Candreva wrote:

> While not optimal, the previous tree was probably the ONLY
> side-navigation I've ever liked on a web site.  I found it very easy
> to use for online reference.  The new page, so far, I do not find
> easy to jump around and use for reference.

I'm open for any suggestions...

It's not I didn't love the previous side menu to some degree -- we
wouldn't have used it at all in the first place otherwise.  However,
over time, the following things became apparent:

. If we handed out someone the URL e.g. for the FAQ page, there has
  been no direct way for him to obtain a back link to the
  documentation main page from there (unless that person was
  intelligent enough to edit the URL in his browser).  This always
  left one with the problem: give out the URL of the FAQ, or rather
  the URL of the main doc entry, and then describe how to get to the
  FAQ from there?

. The small size of the side menu did not allow for very descriptive
  section names.  In particular, the name of the corresponding header
  file had been omitted, so you'd need some guessing to actually
  notice that "General utilities" (taken from the C standard btw.) was
  just a verbal description of what is contained in <stdlib.h>.

. The contents of the side menu was entirely dictated by doxygen.
  You've notice the ironic comment about the prominent link to div_t
  and ldiv_t disappearing ;-), doxygen's idea about the relative
  importance of something (like structs in that case) often differred
  quite a bit from our perception.

So it has always been burning at the backburner to eventually change
that.  Now it occurred to me that the methods to change it actually
have been there all the time: doxygen allows for header and footer
files that are being included in each page (and for a style sheet that
it refers to).  So I rather decided to put links into the header.
However, when combining this with the side menu, the result looks
really disappointing, as the side menu still sits aside from
everything, and the header is only attached to the actual page itself.
Sorry, but that simply looked too terrible to me to stay.

> I'm not sure what is needed, but I would have looked into improving
> the side tree bar rather than remove it.

It's basically not customizable, alas, unless you're going to
hand-edit (or rather Makefile-edit) the result, but that makes you
fragile to each and every new doxygen release.  Been there, done that.
In a previous version, we've been `tuning' the menu that way, and I'd
rather not have *that* back in.  It's been a nightmare to maintain.

> > btw, is it possible to modify list configuration so the Reply-to
> > pointed the list instead of sender?

> Now your looking for a religous war. :-)

;-)  Thus I'd rather not continue that myself.

As Wojtek Kaniewski wrote:

> >>it looks more like mid-'90s homepage, than a user manual of a
> >>project that's being used by thousands of programmers all over the
> >>world.

> >Can you explain in more detail?

> It's hard to explain a subjective impression, but user manuals
> usually don't come with yellow backgrounds.

Well, I'm not religous about that.  I thought that adding a bit of
colour actually makes the HTML pages more pleasant, and well, the old
gray background looked really boring to me after all the time, and I
personally don't really love bright white backgrounds either.  But if
a majority of people tells me that white is the smallest common
denominator, I'll simply change it that way.  The current light yellow
has been chosen to fit to the project's "home" page at:

http://www.nongnu.org/avr-libc/

(from where you can proceed to the online documentation).

Of course, the printable version doesn't have background colors
either.

If you'd love to see some more gimmicks in, like a few more little
pictures in the link area on top, well, I'm not adverse to that, but
crafting images takes quite some time, and I did want to finish that
up within a weekend, so to be able to continue adding actual features
to the software right now again.  The photo of the AVRs on top,
including color correction, background transparency etc. already took
me about 30 minutes or more -- with a total of maybe 5 hours I could
spend into this entire `facelift' project, that's already quite a lot.

However, I don't like to see something completely overloaded with
color and gimmicks like avrfreaks.net.  Small is beautiful, but boring
isn't quite nice either.  Sure, that's opinions, and it's always easy
to debate about personal opinions...  I'm open for any suggestions,
and even more open for anyone who wants to contribute.  If you
volunteer to make the DocBook/XML conversion of the docs right next
week, well, be warned you'll probably get CVS commit privs faster than
you can look, once there is some prove you're taking that serious. ;-)

> I wasn't aware that Doxygen doesn't doesn't let control how HTML
> files are generated.

Only the headers and footers are completely under user control, the
generated HTML itself mostly isn't.  (The generated LaTeX isn't
either, and if you look into the Makefiles, you'll notice a big deal
of tweaking we are doing to the LaTeX to make it fit better our
needs.)

-- 
cheers, J"org               .-.-.   --... ...--   -.. .  DL8DTL

http://www.sax.de/~joerg/                        NIC: JW11-RIPE
Never trust an operating system you don't have sources for. ;-)