lilypond-devel
[Top][All Lists]
Advanced

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

Re: texi2html status


From: John Mandereau
Subject: Re: texi2html status
Date: Wed, 28 May 2008 21:54:10 +0200

On 2008/05/23, Graham Percival wrote: 
> What's the status of the texi2html output?
> 
> 1)  Are there any remaining bugs or missing features in texi2html
> that we'd like to see?  Patrick is planning on making a release
> soon, and it would be silly if we discovered an important problem
> right after a release:
> http://lists.gnu.org/archive/html/texi2html-bug/2008-05/msg00000.html
> 
> (I'd *really* like to have a texi2html that works with our docs
> before switching to texi2html in the official build)

The biggest problem is about resolving cross-references to other
manuals.  If I understand correctly, texi2html needs to know about the
node trees of all other manuals in order to guess the right HTML file
name of the link target of each cross-reference.

Splitting docs compilation in 3 stages could help solving this problem:

- WWW-1 (recursing into subdirs): generate all Texinfo sources (mainly
call lilypond-book and generate-documentation.ly), compile Texinfo docs
into PDF and Info, generate files that describe the node tree for each
Texinfo documents and copy these files to e.g. out/texinfo-node-trees.
Figuring out how to generate these files and use them in texi2html is up
to Perl hackers like Reinhold.

- WWW-2 (recursing into subdirs): compile all Texinfo docs into HTML,
using files in out/texinfo-node-trees.

- WWW-post (at toplevel only, not recursing into subdirs): current
local-WWW-post toplevel target (GNUmakefile.in). 

Compilation of Texinfo docs in PDF and Info should be done just after
lilypond-book running i.e. in WWW-1, otherwise this could slow down the
building, in case there is not enough free memory so that files
generated by lilypond-book are no longer in disk cache when 'makeinfo
--info' and texi2pdf read them.  Moreover, builders who want to check
their changes on documentation only on PDF docs only need to run WWW-1
target with this scheme.

Reinhold, if you think this make structure is useful, I'll start working
on it on my branch.


> 2)  Are there any remaining technical issues with our build system
> (ie translations)?

I think the technical infrastructure is almost ready besides the problem
of cross-references above.  I wish translated docs could be updated to
match reorganized sections before we switch to texi2html, but this is
not a requirement (see my email on -devel about translations).


> 3)  If the answer to the previous two is `no', when is a good time
> to start discussing the silly aesthetic issues on -user?  (ie "I
> don't like that color" or "the fonts are too small")
> 
> - we need to have at least one CSS person with git access with
>   free time when this happens, so if everybody is finishing their
> operas or publishing or classes or whatever,

On my side, I'll only have a bunch of time for LilyPond in the two last
weeks of July.


> we should wait a few
> weeks even if there's no technical issues.

If we don't have enough time to switch to texi2html in master, we
probably won't have time either for making changes in formatting
suggested on -user, except trivial changes on CSS.

Cheers,
John





reply via email to

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