Re: Re-write of documentation tree build process

[Jan Nieuwenhuizen]

John Mandereau <address@hidden> writes:

> Should I send a patch again, or work according to your remarks and push
> to stable/2.10 (and possibly master) if Jan agrees?

Please push to stable/2.10.

> I've already junked a bit of clearly unused stuff, but I didn't try to
> check whether every bit of code is necessary to the HTML files of Lily
> docs. For instance, I wonder whether remove_self_ref() is really used.
> I'll try to use the Python debugger to find the unused bits of code.

> - could we scrap i18n() and move the code to do_file(), as we may add
> i18n in do_file too? (I'd like the footer to be translated, for
> instance).

Yes.

> - we don't add any custom header, so all stuff using the "header"
> variable could be dropped. 

If it's not too much of a mess, keep the header stuff in.  We might
want to add a header.

> - what do all these '[.]' in regular expressions mean? If they should
> match a dot in a string,

Yes.

> why not just use r'\.' ?

I never want to know how many \ to use in what kind of string.  [.]
fixes that.

> I've already experienced that '[.]' is bogus in some cases.

I'm not aware of that?

> Does the 'EN' means that the page language is English? If so, it should
> be modified to handle pages of any language.

Yes, I think so.

> That can simply be done in mirrortree.hardlink_tree(), which could
> return the HTML files list. Let's go for that.

I have two remarks, but given the state add-html-footer was in, I
hardly feel I can make any demands; you're free to ignore me.

+mirrortree.hardlink_tree (input_roots = doc_dirs,
+                          process_dirs = outdir,
+                          strip_dir_names = outdir,
+                          exclude_dirs = r'(fr|po|out|\w*?-root)(/|$)',
+                          process_files = 
'.*[.](?:midi|pdf|png|txt|ly|signature)$|VERSION',
+                          exclude_files = 'lily-[0-9a-f]+.*.pdf',
+                          target_pattern = target_pattern,
+                          targets = targets)

in general, if a function takes much more 3 parameters, you may want
to take a second look why that is.  It may be to be too generic, or
perhaps it tries to do too many things and can be split into several
functions, or some parameters can more naturally be grouped in a
class.

IIRC Han-Wen suggested to write Python scripts, because the mess of
make and shell got unmaintainable, so adding to that would be unwise.
Using python should result in a reduction of lines of code, and much
clearer lines as well.  I'm not sure that was achieved yet.  Comparing
hardlink_tree and say this snippet

-       for dir in $(outdir)/web-root/ ; do  \
-               cd $$dir && \
-               for a in `find . -name out-www`; do \
-                       rsync -a  --link-dest $$a/ $$a/ $$a/.. ; \
-                       rm -rf $$a ; \
-               done \
-       done

(hardlink_tree does much more?).  Having all logic in python is VERY
NICE, but I would not hesitate to call system ('rsync ..') from python
if that would dramatically simplify things.

Jan.

-- 
Jan Nieuwenhuizen <address@hidden> | GNU LilyPond - The music typesetter
http://www.xs4all.nl/~jantien       | http://www.lilypond.org