Re: Using texi2html for the documentation

[Reinhold Kainhofer]

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

Here's a further update of the open issues with texi2html for lilypond's 
documentation:

Am Donnerstag, 20. März 2008 schrieb Reinhold Kainhofer:
> > - 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.

That's now implemented in texi2html.

> I already wonder whether lastest texi2html version interprets -D "VAR
> VALUE" makeinfo option, which is needed for big page docs, and is also
> useful for automatic version number.  It's doable to get the version

All we need is the actual text ;-)

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

Implemented. Now, we can simply use a @translationof macro in each section to 
give the original section title (to be used for the filename). E.g.:
@node Translated chapter title
@chapter Translated chapter title
@translationof Spacing issues
will create a file and anchor from "Spacing issues", but display the 
translated chapter title.
In the init file I'll then simply ignore the whole macro, so for texi2html we 
wouldn't even need it defined at all, but of course, for all other output 
programs, we need it.

The problem that I see in general are cross references (they are a problem 
even with multiple nodes in one file... How do we get the correct file name 
for a cross-reference, if it cannot be deduced from the node title at 
all????). How should be define the @r* macros to work 

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

The language passed to texi2html as --lang=$(ISOLANG) is now added to the 
extension as .$(ISOLANG).html.

> -) "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)

Not fixed yet.

> -) 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]...[...>>]).

That's now possible, but I have not yet implemented it, since I heard some 
opposition...

> I already wonder whether lastest texi2html version interprets -D "VAR
> VALUE" makeinfo option, which is needed for big page docs, and is also
> useful for automatic version number.

That's still open.

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)

iD8DBQFH7sshTqjEwhXvPN0RAn02AJ9dklnGuA/UPRWvjsY94nodW90HaQCgzHqz
Dvma5co/BgDdgstDoQrplgg=
=otoL
-----END PGP SIGNATURE-----