Re: [PATCH] Update & announcement

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

Re: [PATCH] Update & announcement

John Mandereau
Hi guys,

Dénes made a bunch of suggestions to avoid repetitions in docs, which
would require a fair amount of maintenance work.  I'm replying on the
lists for the record and possibly for discussion, but I'm too budy to
tackle these suggestions before next year; I propose to register these
suggestions in the tracker with label Type-Maintenance.

Le dimanche 06 décembre 2009 à 22:23 +0100, Harmath Dénes a écrit :

> An example from macros.itexi:
>
> @ifset bigpage
>
> @macro rglos{TEXT}
> @vindex \TEXT\
> @ref{\TEXT\,,,music-glossary-big-page,Zenei fogalomtár}
> @end macro
>
> ...
>
> @ifclear bigpage
>
> @ifnotinfo
>
> @macro rglos{TEXT}
> @vindex \TEXT\
> @ref{\TEXT\,,,music-glossary,Zenei fogalomtár}
> @end macro
>
> Apparently, only one argument of those macro calls differs. There
> should be a way to eliminate the duplication of the other arguments.
We might be able to achieve this by defining macros that uses themselves
macro definitions and/or @set.


> Regarding node title references, it would be better if there would be
> an internal international identifier to refer to so that a change in a
> translation of a node not affect all verbatim references to it.
> E.g. @ref{Első lecke} would become @ref{tutorial} in all places.

It might possible to make this work, but I'm reluctant to hack Texinfo
fomatters to support this (the Info/XML/Docbook/HTML formatter is a
25000 lines plate of Perl spaghetti, difficult to digest, and for PDF
output I don't master TeX).  Better is offering a maintenance tool to
update cross-references when updating a node name (for both docs in
English and translations).  In the meantime, find and grep are your
friends.


> Another case with the definition of node title translations:
>
> @node Zene bevitele
> @subsection Zene bevitele
> @translationof Entering input
>
> I can't imagine why the title has to be defined twice. I suspect these
> are all limitations of the texinfo technology, but unfortunately I'm
> not too good at it.
>
Historically, nodes have been used for cross-references, and section
commands.  The node name format is more restricted than the section
title, as it must not contain any comma, and it should not be too long
and should not contain any formatting @-command.  For LilyPond docs,
many section titles are identical to their respective node names; I'll
see about the possibility of defining a macro that would yield a @node
and a section command with the same argument, and writing a little
script that converts alll current docs to use this new macro, but as we
have scripts that scan Texinfo docs using regexps instead of really
parsing them, we can't do this until I've finished my Texinfo parser and
make the scripts use it (probably not before the end of the year).

Best,
John

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

Re: [PATCH] Update & announcement

John Mandereau
Le mercredi 09 décembre 2009 à 01:19 +0000, Graham Percival a écrit :
> Only if you accept responsibility for making it work in makeinfo,
> texi2pdf, and texi2html.  This duplicates 10 or 20 commands in
> macros.itexi.  That's one file.  When you change a manual name,
> you need to update 4 lines of texinfo.

4 lines of Texinfo multiplied by the number of languages, which
completely changes the deal.  I'm sorry to contradict you whenever there
is such an issue in docs whose annoyance is multiplied by the number of
languages (currently seven), but as you already did at least one thing
in several languages (renaming general to web, only three languages),
you probably see what I mean.


> IMO, the "time saved" vs. "time spent"... including debugging any
> fancy macro games in all the doc-building programs, including
> debugging any problems that people with other versions of those
> tools have... is totally not worth it.

All this is wrong:
- this change wouldn't involve the build system at all;
- we don't have to support different versions: texinfo.tex is included
in sources (and TeX is stable enough so it doesn't matter), we already
require a specific version of Texi2HTML, and makeinfo syntax support is
stable enough;
- we can hardly predict which future decisions will make us create,
split or renames manuals.

That said, this issue has a medium priority on my to-do list (FWIW the
low priority items are supporting translations of automatically
generated documentation, i.e. the markup command lists, the Internals
and consorts).


> No.  Even if you had such a patch already written, I veto it.
> - how are tools like emacs texinfo-all-menus-update supposed to
>   play with the new macro?

I don't know, but such tools (like our current maintenance and build
scripts too) are broken by design, unless they use a real parser, which
is not unreasonable for a quite simple language like Texinfo.  That
said, this is the only real reason I see for not doing this right now.


> - we'd lose internal consistency if we ever wanted to change the
>   section name

I don't understand this point.

> - again, the benefit vs. time spent is totally not worth it.

This would be done using regexp substitution, so there would be quite
little time spent on this.


> Duplicating the node/section name is a basic feature of texinfo.
> It's not a big deal.

It makes translation a bit more tedious, though.

Cheers,
John

signature.asc (205 bytes) Download Attachment