Re: Using texi2html for the documentation

[John Mandereau]

Le samedi 15 mars 2008 à 23:01 +0100, Reinhold Kainhofer a écrit :
> Hi all,
> After all the month-long whining that no perl developer with ~10 hours at 
> hand 
> could be found for using texi2html for the docs generation, I though that it 
> couldn't possibly be that hard and I was crazy enough to try it out. -- Well, 
> it wasn't hard (thanks also to Graham's enthusiasm and administrative help)!

> The current status of the conversion (which was aimed at looking like the old 
> docs) can be found at:
>         http://kainhofer.com/~lilypond/texi2html-out-traditional/
> 
> Could you please have a look at it and tell me about things that should / 
> need 
> to be fixed before this can be used for the "official" docs creation.

Our HTML docs, especially translations, are heavily hacked before taking
final shape.  We *must* switch to texi2html in a branch other than
master in order to fix nitpicks in docs formatting, including translated
docs.  We should also check that texi2html provides enough translated
strings in Spanish, French and German.

Texi2html output generally looks good, but it misses some makeinfo
features:

- 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

<a rel="next" accesskey="n" 
href="Musical-notation.html#Musical-notation">Musical notation</a>

<a accesskey="1" href="Musical-notation.html#Musical-notation">Musical 
notation</a>


- 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][?]

1.1.4 Note heads

Maybe titles could be printed in small font (10pt) so that the line is
not too long.


> And then I played around a little with the flexibility that texi2html brings 
> and my current results can be found at:
>         http://kainhofer.com/~lilypond/texi2html-out/
> (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).

> As you can see, there is a lot that texi2html can do (you have basically full 
> control over the html page generation), so all that is missing is some good 
> screen design. As this is not my strength, the current output really sucks as 
> far as a good look (Headers, colors, frames, fonts, layout, text/position of 
> the navigation links) is concerned. So, who would be willing to do the 
> graphical design of the docs page, which I can then implement in HTML/CSS?

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:

- colors used for titles and links could be the same as colors used on
lilypond.org, for better consistency.  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.

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


> Also, are there any features that you would like to see in the documentation 
> (not editorial, but technical stuff!)?

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

@node Übung
@chapter Übung
@translationof Tutorial

texi2html would use @nodetranslation for HTML file names and anchors,
and @node for printing it text.

I have no Perl skills, but I guess this is not so hard to achieve. I
would start this as defining @translationof macro in macros.itexi as

@macro translationof{TEXT}
@clear translationof
@set translationof \TEXT\
@end macro

Then, the customized formatting routines would read
@value{translationof}. Of course, texi2pdf for PDF output would
completely and silently ignore this stuff.

How does this sound?

Cheers,
John