Re: Using texi2html for the documentation

[Reinhold Kainhofer]

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

Here is an update about the current situation with texi2html for the docs 
building. The current version is at:


Am Sonntag, 16. März 2008 schrieb Graham Percival:
> Lists are destroyed.  Look at:
> http://kainhofer.com/~lilypond/texi2html-out-traditional/Writing-pitches.ht
>ml#Relative-octave-entry

Fixed by Patrice Dumas (who is simply amazing: Ask him about a problem and an 
hour later you'll either have an explanation how to do it, or if it's a bug, 
he will have fixed it already).

> > (Don't worry about the long toc on the left, I simply haven't yet
> > found a way to show only two levels plus the full path to the current
> > page).
>
> 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.

I've implemented it now so that two levels are shown by default, plus the full 
path to the current page (with their siblings, so it behaves just like in a 
file browser). Example:
http://kainhofer.com/~lilypond/texi2html-out/Percent-repeats.html

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

Also, the current page (and its ancestors) are printed in bold and italic 
(style is completely up to the design, so we can change that easily in 
the .css file) in the toc on the left.

> > 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".  If we keep "See also" sections as they
> are, i.e. with references grouped by external manual name, we should
> even have two different external ref commands for HTML ouptut, one with
> the name of the manual, and one without it.

I put this up for discussion: Currently we have the links already split by 
external refs (i.e. one line for Music Glossary links, one or IR links, one 
for Snippet links). As long as it stays like this, I don't think we should 
show the target external manual name again, since it is already printed at 
the begining of the line...

> - 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, the HTML code looks like

Patrice will take a look at implementing access keys in the next few days.


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

Implemented.


> I'd like to improve the process of translated docs HTML output.
> The problem is, node names and section titles should of course be
> translated in the ouptut, but we want HTML page names and anchors use
> the node names in English even in translated docs, for the sake of easy
> per-page switching and working cross-references even if the destination
> page is not translated (thus redirecting to the corrseponding page in
> English).

Currently that's not possible, because for determining the file name, we have 
only the section name, number and ID available, but not the contents of the 
section. There is also no chance to set some property in a macro, because 
that will only be expanded later on. However, Patrice seems to have an idea 
to move macro evaluation to an earlier place and make this possible.

Looking at the texi file:
Do we really still need the @node before each section/chapter with texi2html, 
since splitting is then based on sections anyway? Currently, this causes two 
identical <a name="section_id"> anchors into the page...


> At the moment, I have no real opinion on all the CSS stuff,
> except to agree with you that it's somewhat subjective.  However, I'm
> sure we have a few CSS geeks on the -user, not to mention Valentin...

Actually, we don't need any CSS geeks (I know CSS well enough to implement 
anything we might need, even up to automatically expanding sub-menus on 
mouse-over, implemented entierly in CSS, see e.g. 
http://www.jung-wien.at/designtest.php, which I find annoying..). What we 
need is some good graphical designer, who makes a screen design (e.g. as 
image, PDF, PhotoShop, etc.) for all the design elements that the docs (and 
the main lilypond.org page) contain.

> I'm just glad to see that these opportunities are offered now; I think
> a community needs to be motivated by visible (superficial) spectacular
> initiatives, more than *really* important (but invisible to them)
> program code etc. In other words, IMO you have to make it sexy to
> motivate people.

That's exactly the reason, why I'm pointing at improving the appearance of the 
web page ;-) Our documentation is really great, the application itself, too, 
only the start page looks a bit bare compared to what gems are hidden behind 
it...



About translations: texi2html has full translation support, I've sent Patrice 
the updated German strings, he wrote the French ones, so we might only miss 
some Spanish strings...  I have not yet looked at adding the language to the 
file name (i.e. use .de.html as extension for the German docs).
About the automatic language selection: I think inside the manual, we should 
generate links to the full file names (i.e. pointing to Rhythms.html, 
Rhythms.de.html, Rhythms.fr.html) and not leave out the extension (i.e. 
pointing to Rhythms). My reason is that if you leave out the extension, 
automatic language selection will be applied to each and every page. Since my 
Browser defaults to German, I will always get the German docs. Now, if I want 
to see the English one, I click on the alternative translation and get the 
English files. However, all links on that page are again without the 
extension, so clicking on them, I'll again end up with the German version...
So, for me this automatic language selection is really annoying!

For the index page, I think it's a good idea to have automatic language 
selection, but from the on, all links should point to the files for the same 
language as the current page.

BTW, is the automatic language selection (i.e. creating links without .html 
extension and adding the "Alternative languages" link on the bottom) 
implemented directly in makeinfo, or does lilypond's build system some more 
magic to get this?




Further issues that are still open (for most of them, I have already sent a 
mail to Patrice, and he is aware of them and might even implement a fix 
shortly):

- -) "Short" TOC for the start/contents/about page. Currently, I can only put 
the full TOC there, while I want to show only the first two levels (like on 
any other page)

- -) For pages with multiple subsections shown on the same file, I want the 
navigation panel between the subsections to show only the [<..] [Up...] 
[...>] buttons, but not the chapter navigation ones (i.e. [<<] [Contents]
[Top]...[...>>]). 


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)

iD8DBQFH4qztTqjEwhXvPN0RAiULAKCkvjY+nhPoahmGakQ9sG6xfNhRlQCgiXNy
NrhDuXOpLMgHAA+uuqwI6y0=
=KUWR
-----END PGP SIGNATURE-----