Updates:
Cc: pertu...@free.fr
Comment #9 on issue 1000 by reinhold...@gmail.com: 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
_______________________________________________
bug-lilypond mailing list
bug-lilypond@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-lilypond
