Re: Issue 1000 in lilypond: communicate with upstream texi2html project

[lilypond]

Updates:
        Cc: address@hidden

Comment #9 on issue 1000 by address@hidden: communicate with  
upstream texi2html project
http://code.google.com/p/lilypond/issues/detail?id=1000

Hi Patrice,
Thanks for you offer, which I gladly accept (I was the main "offender" of  
our init script three years ago).

It's actually not that easy to send you our texi files, since most are  
generated by lilypond-book from .tely files (texinfo with lilypond  
snippets, which are turned into images by lilypond-book), and some are even  
auto-generated by our buildsystem (like the whole internals reference).
So, it's probably easiest for you to chec out all of lilypond, build  
lilypond and then the documentation (see out contributor's guide for  
detailled information,  
http://lilypond.org/doc/v2.15/Documentation/contributor/ ):
-) git clone git://git.sv.gnu.org/lilypond.git
-) ./autogen.sh; ./configure
-) make
-) make doc


The texi2html init script is Documentation/lilypond-texi2html.init, and the  
texinfo sources can be found in the Documentation subdir (the .texi files  
created by lilypond-book from the .tely files during make doc can be found  
in the out-www/ subdirs...).

A few words about the largest chunks of our script:
1) We print out a TOC in a <div> on the left side, which is created from  
the texi2html node list, not from the menu structure.
2) The snippets include several files multiple times (in different  
sections), so many nodes are duplicate, and -- what's worse -- we don't  
want any menus there (which just waste space and clutter the page). So, we  
get thousands of warnings (when you run "make doc") about nodes not being  
in a menu etc.
3) The parts about the map files (*.xref-map) are about our own splitting  
(we don't want every node in a separate file, but only each numbered  
section should start a new file) and about translated node names:
We wanted to translate node names in translated documentation (because the  
file names should be translated), too. Unfortunately, for xrefs between  
unrelated manuals, we need to know more (file name where the translated  
node can be found, which cannot be deduced from the node name because we  
only split at numbered sections). The build system then extracts all those  
node names and the corresponding file names and stores them in .xref-map  
files (in out-ww/xref-maps/ ).
For translated docs so we added @translationof (see any of the translated  
manuals in Documentation/{cs,de,es,fr,hu,it,ja,nl,zh}/ ), which specifies  
the original untranslated node name, which will be used for the xrefs.
4) We use our own navigation bars between the nodes. Their structure is  
defined in several arrays.
5) All those AJAX_SEARCH conditionals are about optionally adding an AJAX  
search fields (which does a server-side searche of all entries in the  
texinfo index files). See  
http://kainhofer.com/~lilypond/Documentation/notation/index.html for an  
example.
To build the docs with this search enabled, you need to set the AJAX_SEARCH  
env variable in the make command:
    make AJAX_SEARCH=1 doc
6) We have also included translations of the texi2html strings for several  
more languages.


If you have further questions (that's a rhetorical question, I don't expect  
anyone to understand that file on his own), feel free to ask here or via  
private mail.

Cheers,
Reinhold