[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: lilypond
Subject: Re: Issue 1000 in lilypond: communicate with upstream texi2html project
Date: Wed, 12 Oct 2011 23:13:36 +0000

        Cc: address@hidden

Comment #9 on issue 1000 by address@hidden: communicate with upstream texi2html project

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.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]