Re: Another patch & questions

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view

Re: Another patch & questions

John Mandereau
Le mardi 22 décembre 2009 à 09:26 +0100, Harmath Dénes a écrit :
> (BTW, the 'Ancient notation templates' node has the following comment:
> @c bad node name to avoid node name conflict
> and in the menu:
> @c bad node name for ancient notation to avoid conflict
> What does this comment mean for us?)

(It's a reminder for documentation editors in English that a node name
should be unique, which implies that some node names are intentionally a
bit weird.  The node name unicity requirement also holds for

> > ** Unknown command with braces `@insertcopying'
> > ** Unknown command with braces `@insertcopying'
> > ** Unknown command with braces `@insertcopying'
> That's strange, because it appears with braces as @insertcopying{} in
> the English original too (in macros.itexi and web.texi). Should I
> remove the braces from the translation?

No, I just fixed this in all languages (in my working tree, will push as
soon as my other changes compile fine).

> > WARNING: Unable to find node 'Szövegszerkesztői támogatás' in book usage.
> > WARNING: Unable to find node 'Tanácsok LilyPond bemeneti fájlok írásához' in book usage.
> These are links in the tutorial to nodes in usage I already translated
> but not the target node titles. Should I revert the links to the
> original or translate the target node titles, or just leave alone
> both?

Does the following paragraph I'm adding to the CG in "Translating the
Learning Manual and other Texinfo documentation", just after the
paragraph that introduces @untranslated, answers your question?

@warning{you do not have to translate the node name of a cross-reference
to a node that you do not have translated.  If you do, you must define
an @qq{empty} node like explained just above; this will produce a
cross-reference with the translated node name in output, although the
target node will still be in English.  On the opposite, if all
cross-references that refer to an untranslated node use the node name in
English, then you do not have to define such an @qq{empty} node, and the
cross-reference text will appear in English in the output.  The choice
between these two strategies implies its particular maintenance
requirements and is left to the translators, although the opinion of the
Translation meister leans towards not translating these

BTW, I'm adding this paragraph too:

If you wonder whether a word, phrase or larger piece of text should be
translated, whether it is an argument of a Texinfo command or a small
piece sandwiched between two Texinfo commands, try to track whether and
where it appears in PDF and/or HTML output as visible text.  This piece
of advice is especially useful for translating @file{macros.itexi}.

>  (Anyway, this is exactly a consequence of the information duplication
> I mentioned - references to a text should *not* depend on the text's
> exact translation.)

(References to a node should use the exact node name, I don't see why
this rule shouldn't apply to a Texinfo document in a language other than
English.  That said, we probably agree that there is still much to do to
make translation of Texinfo documents more comfortable.)

> That latter may be the case, since I use Eclipse to maintain the
> translation, which is very convenient, but consumes most of my RAM. On
> second thought, with enough free RAM, the process is not significantly
> faster, so I'm planning to upgrade from 2 GB to 3 or 4 for
> Christmas. :)

I sincerely hope MacOS X handles well so much memory. Really, I'm a bit
pissed that my X server eats so much of my 4 GB just for 3D desktop
effects, so I haven't tried to demonstrate that GNU/Linux is always
technically better :-)

> Yeah, the MacBook's HD may be not the top, and maybe OS X's different
> behaviour also plays a role. However, I can't do much against it.

In an ideal world we wouldn't have so much HTML postprocessing with
regular expressions; currently Texi2HTML offers some flexibility but
it's quite cumbersome to use it.  We generally suffer from the lack of a
proper way of representing and manipulating a document, its output and
its connexions with other documents (including translations) in all
Texinfo formatters.

> > Sure, all node names should be translated, I don't see why Manuals and
> > Community should be an exception.
> There is only web.texi, introduction.itexi and download.itexi among
> the 1st priority files, that's why I was confused. But do you mean
> that all node names of chapters, sections etc. in all web files should
> be translated in manuals.itexi and community.itexi (and maybe other
> files) also?

Again, that's your choice: this is the same problem as what I explained
above about texi2html warnings "Unable to find node".

> I always do git pull -r. After a bit of investigation, I learned that
> surrounding it with git stash and git stash pop sometimes helps.

Certainly. It's recommended to have a clean working tree when pulling,
which means committing or junking all changes before pulling, but it's
not always practical in real life.  Generally speaking, if you think
such a real life situations should be described in the CG, please send a
request and the text you'd like to add (a patch would be best but not
necessary) to -devel list.


signature.asc (205 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view

Re: Another patch & questions

John Mandereau
Le dimanche 27 décembre 2009 à 01:03 +0100, Harmath Dénes a écrit :
> On 2009.12.23., at 23:34, John Mandereau wrote:
> > (It's a reminder for documentation editors in English that a node name
> > should be unique, which implies that some node names are intentionally a
> > bit weird.  The node name unicity requirement also holds for
> > translations.)
> Oh, I see. Another argument for providing internal IDs in source for
> nodes instead of full, translated text. :)

Good idea, but not before Texinfo 6 or 7 (upcoming major version 5 will
replace Makeinfo with Texi2HTML).  There is currently no Texinfo
formatter which is flexible enough to implement what you suggest with a
reaonable difficulty (see also my rant below).

> Thanks, this clarifies this. Fixed this.

Thanks, applied (I'm always wondering whether there is an email client
on GNU/Linux that can insert attachments in the middle of an email).
However, I'm afraid you get a silly conflict because of whitespace
(probably added by Emacs update-all-menus macro):

$ git am --whitespace=fix 0001-Docs-hu-Fix-Other-templates-in-menu.patch
Applying: Docs-hu: Fix Other templates in menu Translated website except of Community
/home/lilydev/git/lily/.git/rebase-apply/patch:389: trailing whitespace.
Minden logó és termékábrázolás szerzői joggal védett.
/home/lilydev/git/lily/.git/rebase-apply/patch:405: trailing whitespace.
* Unix::                        
/home/lilydev/git/lily/.git/rebase-apply/patch:406: trailing whitespace.
* Mac OS X::                    
/home/lilydev/git/lily/.git/rebase-apply/patch:407: trailing whitespace.
* Windows::                    
/home/lilydev/git/lily/.git/rebase-apply/patch:408: trailing whitespace.
* Forrás::                      
warning: squelched 32 whitespace errors
warning: 37 lines applied after fixing whitespace errors.

> Of course a node reference should appear to end users as the exact
> node name, but in the sources, it must not. Computers can use
> automated processing to reduce dependency and avoid duplication, don't
> they? :)

You're right in theory.  As for the real world, LilyPond manuals are
probably the first Texinfo documents that are translated, and from my
2-years experience on Texinfo lists, LilyPond manuals have been the most
demanding for bugfixes and support of languages other than English.
This means that there is still little built-in support for translating a
Texinfo document, so translation of LilyPond manuals is still very
experimental and half-baked; even with the perl script Texi2HTML
replacing the old C implementation of Makeinfo, I don't see that
changing much within one year, as Texi2HTML code does not significantly
look less than a dish of spaghetti than Makeinfo, and its
customizability is quite coarse compared to e.g. LilyPond.  Moreover,
there is no standard object implementation in Perl as far as I know, so
almost all my concerns with Texi2HTML are the fact of the programming

> Is there a way to achieve that files resulting from *.itexi files be
> rebuilt without touching their including *.texi files? I always forget
> to touch them, and though with 4 GB RAM, the docs build "only" in
> ~2:30, it is still discouraging to rebuild once again because of the
> forgotten touch.

There is a way, but I'd better spend my time on other LilyPond tasks
than fine-tuning a build system that we're going to junk.

> I think something like the following should be inserted in the
> Updating command section:
> If your working tree is dirty (you have modified some of the files),
> you can use
> git stash
> git pull -r
> git stash -pop

You meant 'git stash pop' (without a dash).

> to avoid conflicts when updating.

I prefer "to make pulling possible when pulled changes affect some files
that are also dirty in your working tree -- note that you may have to
resolve a conflict then, see section Conflicts in git-merge man page."

As the CG is being revised by Mark Polesky, I'll send this suggestion to
-devel list instead of pushing a commit on the CG.

> One more thing: somehow, the reference
> @rweb{Könnyebb bevitel}
> in hu/tutorial.tely didn't work. I hope it works at Kainhofer's server.

It looks like it doesn't depend on the build host but that
hu/macros.itexi is not up to date; check for check-translation in the CG
section about documentation translation (and/or reread a recent reply to
you from Francisco ;-)


signature.asc (205 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view

Re: Another patch & questions

John Mandereau
Le samedi 02 janvier 2010 à 13:42 +0100, Harmath Dénes a écrit :
> That's great also. What really matters is that the documentation build
> turnaround be minimal; waiting 2.5 minutes for a rebuild and then
> committing and pushing just to make a small change hinders incremental
> enhancement of the docs.

I guess it will take months to switch to another build system.  In the
meantime, I'm almost sure you could rebuild faster than 2 minutes and a
half with

touch files_to_be_touched.tely
make -C Documentation/hu # or whatever the right directory is w.r.t current directory
make out=www WWW-post # from top build directory

> Great, it works on (strangely not on

This is not strange; with our current build system, only clean builds
always produce correct results. Reinhold, could you please delete all
generated version.texi and version.itexi files on


signature.asc (205 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view

Re: Another patch & questions

John Mandereau
In reply to this post by John Mandereau
Le vendredi 01 janvier 2010 à 23:57 +0100, John Mandereau a écrit :
> Yeah, I think setting the number of items of each color and the order of
> colors is much better, as it avoids hardcoding language-dependent node
> names in Texi2HTML init file.  I proposed Graham to prepare the patch,
> I'll try to find a moment within one week to implement it.


signature.asc (205 bytes) Download Attachment