Re: Using texi2html for the documentation

[Reinhold Kainhofer]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Am Sonntag, 16. März 2008 schrieb John Mandereau:
> Le samedi 15 mars 2008 à 16:23 -0700, Graham Percival a écrit :
> > The third "paragraph" (the indented bit) should have a number of
> > bullet points.  Well, not /necessarly/ bullet points -- I'll leave
> > this up to you -- but it should be clear that it's a list of
> > points.
>
> It's clear in the HTML code, it's only a problem of setting the <ul>
> class or style attribute properly to display bullets or something else.

Yes, for some strange reason the list is created with class "toc" (which in 
the CSS is defined to not have any list bullets)... I've sent a mail to the 
texi2html developers whether this is a bug in texi2html.

> > Some people might wonder about the "(music-glossary)double sharp"
> > links, but I actually prefer them this way -- it makes it clear
> > where it's going.  One tiny nitpick: could we have a space between
> > the ) and the next character?
> > - if this is difficult, forget about it; there's much more
> >   important things to fuss about.
>
> After quickly looking at texi2html docs, it should be possible to get
> any desired output by redefining the output function, e.g.
> "Music Glossary, double sharp", which is much prettier than
> "(music-glossary)double sharp".  

Yes, I suppose that should be possible. But if anything I'd prefer "double 
sharp (Music Glossary)".
Anyway, I now found the way to remove the (lilypond-internals) etc. 
altogether. Already fixed online

> > I'm not certain we only want two levels... the ideal would be if
> > users could click to expand/contract each tree.  Perhaps two
> > levels would be good by default, but I'd like it if people could
> > expand them to see three or four levels.
>
> That's ceratinly doable, but AFAIK this involves a bit of Javascript.

Yes. However, the problem I have with the full TOC present in the HTML file is 
the size of it. In particular, it currently adds a whopping 41 kB (!!!!!) to 
each and every html file... If we add JS to open/close section, we'll need to 
add a name to each <ul>, plus the onClick code plus the JS code, so the size 
will in the worst case double. Is an 80kB overhead per page really 
acceptable? For the single-page version, that would be fine, but I don't 
think it is for the small-pages version.

What I have in mind is something like the following: Show only the first two 
levels (i.e. 1. and 1.1, 1.2 etc) plus the path to the current page.
If you are on page "1.2.3.3 Unmetered music", the TOC would then display:

1. Musical notation 
   1.1 Pitches 
   1.2 Rhythms 
      1.2.1 Writing rhythms 
      1.2.2 Writing rests 
      1.2.3 Displaying rhythms 
         1.2.3.1 Time signature
         1.2.3.2 Upbeats
         1.2.3.3 Unmetered music (in bold or whatever)
         1.2.3.4 Polymetric notation
         1.2.3.5 Automatic note splitting
      1.2.4 Beams 
      1.2.5 Bars 
      1.2.6 Special rhythmic concerns 
   1.3 Expressive marks 
   1.4 Repeats 
   1.5 Simultaneous notes 
   1.6 Staff notation 
   1.7 Editorial annotations 
   1.8 Text 
2. Specialist notation 
   2.1 Vocal music
   2.2 Chords 
   2.3 Piano music 
   2.4 Percussion 
   2.5 Guitar 
   2.6 Orchestral strings 
   2.7 Bagpipes 
   2.8 Ancient notation 
3. Input syntax 
   3.1 Input files 
   3.2 Common syntax issues TODO name? 
   3.3 Other stuffs TODO move? 
4. Non-musical notation 
   4.1 Titles and headers 
   4.2 MIDI output 
   4.3 other midi
...

This still provides a quick raw navigation through the whole contents and also 
makes it also easy to go to "near" pages.

> This would be also very cool if the node currently displayed was
> highlighted in the TOC.

Of course. Currenly, however, I'm only using the TOC lines generated for 
the "Contents" page. texi2html keeps two TOC lists, one for the "Overview" 
(containing only the top-level sections) and the full contents (containing 
every section). I'll need to find an easy way to generate a custom TOC, 
anyway...


> - navigating the pages with the keyboard (Alt-U for up, Alt-P for
> previous, Alt-1 for first menu entry and so on); this should be easy to
> add this in texi2html, 

yes, we'd just need to hook into the function that creates the quick 
navigation links. the section titles "problem" is connected with this and can 
also be solved by this. 
As this also depends on the screen design, I have not yet touched this.



> - the navigation bar at top and bottom of each page is very handy, but
> it misses section titles; it'd be very cool if texi2html could print the
> titles too, something like
>
> [< Ambitus][Special note heads >] [<< Musical notation][Up][Specialist
> notation >>] [Top][Contents][Index][?]

In particular, I don't like the default order 
[<][>]  [<<][UP][>>]   [Top]  [Contents]  [Index]  [ ? ]

How about using two lines with left/center/right-aligned  links? Something 
like:
[<< Musical ...]   [Top][Contents][Index][?]   [Specialist ...... >>]
[< Ambitus]                     [Up]                    [Special note heads >]

(And I like the idea to print them in a smaller font)


> I like the general design of your experiment, but the formatting style
> is very different from current docs, I have some concerns about fonts
> and colors. Of course, layout and formatting style are a matter of
> taste, so it might not be easy to find a consensus, but here are some
> suggestions anyway:

That's why I said that my attempts (some are based on Valentin's CSS) are crap 
and asked for a complete screen design to implement....

> - colors used for titles and links could be the same as colors used on
> lilypond.org, for better consistency. 

Which brings me again to the point that the mail page could really use some 
design overhaul to make it more appealing and look well-designed...

> Besides this, the background 
> color of the TOC ("goose shit green" as a litteral translation from
> French) is too dark, and the red dotted box around contents of the page
> looks strange.

hehe, yes the color is the TOC is just there to make it clearly distinct from 
the contents. I never meant the color to be usable in real life.  And the 
dotted box is only there for me to check proper placement and extents of the 
CSS div box.

> - I don't mind about using sans-serif fonts for titles, but I don't
> like, well I'm even strongly opposed to sans-serif fonts for running
> text.

Ah, was hard-coded in the css, sorry.
To be honest, I find a sans font much easier to read on screen than a serif 
font. For printed text, a serif font is definitely better, because the serifs 
help the eye progressing through the line. On screen, however, the eye 
already has to work hard to keep focussed, so the additional "clutter" that 
the serifs bring don't really help.
Anyway, I like sans, you like serif, so the obvious solution is to simply 
remove the font-family altogether and use the browser defaults... I've 
already changed this in the CSS. Better?

> Currently, this is achieved with a complex hack: node names and section
> titles in translated docs are not translated in the Texinfo source, e.g.
>
> @node Tutorial
> @chapter Tutorial
>
> but they are translated in HTML ouptut by a Python script
> (buildscripts/html-gettext.py) which reads translations with gettext,
> using compiled POs from Documentation/po.  It would be very cool for
> translators if we could get rid of this ugly hack thanks to texi2html,
> with Texinfo input looking like

Ouch, this really sucks currently. I suppose it should be possible to find a 
way in texi2html to avoid such a hack and use translated section names 
directly in the sources. I'm already using a function to create proper file 
and anchor names, so I only need to extract the proper english section name 
for them.
I don't know if your @translation approach is really that simple to implement, 
though... It would definitely be easier if the english version would also be 
directly in the @chapter. Do we really still need the @node with texi2html, 
since splitting is then based on sections anyway?
Hmm, thinking of it, such an encoding will probably break texi2pdf :(

Cheers,
Reinhold
- -- 
- ------------------------------------------------------------------
Reinhold Kainhofer, Vienna University of Technology, Austria
email: address@hidden, http://reinhold.kainhofer.com/
 * Financial and Actuarial Mathematics, TU Wien, http://www.fam.tuwien.ac.at/
 * K Desktop Environment, http://www.kde.org, KOrganizer maintainer
 * Chorvereinigung "Jung-Wien", http://www.jung-wien.at/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)

iD8DBQFH3YsHTqjEwhXvPN0RAq2gAKCH5qcaAgY57KOxoO55N8+RQpXWXQCeL6Of
PDUo4uLcAkH3p+/1R2hPC8A=
=Ioik
-----END PGP SIGNATURE-----