Re: syntax changes before beta version

[John Mandereau]

On 2008/07/19 21:19 +0200, Reinhold Kainhofer wrote:
> Okay, I've now added the script buildscripts/extract_texi_filenames.py to 
> create that list (tab-separated file with entries 
> NODENAME\tFILENAME\tANCHORNAME). I took the texi-gettext.py file and adjusted 
> it (basically rewrote everything, but the ideas can still be seen in my 
> script).

This sounds good.  I'll compile and look at dev/texi2html tomorrow or
later, to see what you did and what I can do.


> To be honest, I have never understood the makefile structure of lilypond.  
> There are some files in make and some in stepmake, both apparently containing 
> similar rules.

Here's bits of general design.  LilyPond GNUmakefiles use (Stepmake)
templates to reuse make code.  Generic templates are located in
stepmake/stepmake and are intended to be usable for many projects; local
templates are located in make/ and are quite Lily-specific.  Each
template FOO is usually made of three files; FOO-vars.make,
FOO-rules.make and FOO-targets.make (theses names are quite
self-explanatory).


>  Where exactly do I have to add the following rule:
> 
> %_xref.map: %.texi
>       $(PYTHON) $(buildscript-dir)/extract_texi_filenames.py %<

texinfo-rules.make


> And where do I have to add the variable 
> XREF_MAP_FILES := $(MASTER_TEXI_FILES:%.texi=%_xref.map)

texinfo-vars.make


> and where $(XREF_MAP_FILES) as prerequisites for a target?

in texinfo-targets.make, e.g.

local-WWW-1: $(XREF_MAP_FILES) [[other possibly existing prerequisites]]


> Since texi2html is called in WWW2, once the .init script loads those 
> *_xref.map files, everything should work.

Agreed.


> The only issue that I see with the makefiles is that if one .tely file 
> changes 
> a node name, where other manuals point to, how can we make sure that those 
> other manuals get rebuilt with the new link target file name? The *_xref.map 
> file for that changed manual will be updated, but I don't see a way to 
> automatically rebuild the other manuals except by adding all _xref.map files 
> as prerequisites for all texinfo files. This would then mean that just one 
> node name change would trigger a rebuild of all .html files, which is far 
> from ideal...

I can't see a reasonable solution other than adding _xref.map files 
as prerequisites.  The best thing for compiling the documentation would
be to write yet another script which would write .dep files as needed to
force regenerating docs compilation, but there are much more important
issues IMHO.


> > including shell commands to 
> > move node trees info files to a common location (e.g. (top)/out/, and
> > the real call of texi2html in local-WWW2.
> 
> What do you mean by this? I can't really move the nodename<=>filename map out 
> of the tree, because then texi2html will not be able to find them. For now 
> I'm thinking of creating the _xref.map file in the same directory as 
> the .texi file. This way, it's quite easy to find it in texi2html...

We have one Texinfo document (called 'lilypond-snippets') in input/lsr,
and all other in Documentation/user.  We want to share info for cross
references between all these documents, so the best place is to create a
new directory at <top-dir>/out.  Of course, this requires adding a -I or
--include option so that texi2html finds the _ref.map files.

For a simpler solution, we could just turn off cross-references advanced
resolution you implemented from and to lilypond-snippets, which would
work with cross-references we currently use.



> BTW, is there a place for regression test cases of our buildscripts? I have 
> generated a small texinfo file to test the output of my 
> extract_texi_filenames.py, but didn't find any place in git to put it...

We have no regtests for our buildscripts.  This is usually not a
problem, as buildscripts are (or at least should be) designed only for
our needs, and we generally junk unused code and scripts, so most of the
scripts code is tested when building Lily.  If you really think regtests
are necessary, maybe we could create a directory in buildscripts/?

BTW no Python script besides musicxml2ly has regression tests either;
I'd be glad to remedy to this and develop new features, if I'm sponsored
(otherwise don't ask me).

Cheers,
John