Re: syntax changes before beta version

[John Mandereau]

On 2008/07/18 01:24 +0200, Reinhold Kainhofer wrote:
> Just today, I started implementing the sectionname<=>filename map (which 
> needs 
> to be written out to a file on disk, so that external refs from other manuals 
> can load this and look up the correct file/anchor to point to). I'm already 
> generating that map and writing it out in tab-separated form to a file 
> (basename)_xref.map. The loading of this is not yet implemented (in 
> lilypond_external_href, which is currently simply copied from the texi2html 
> code; I already laid out the steps there but didn't write the code).

Good points.


> - -) decide how to modify the build process to use the 
> secname->filename/anchor 
> map. We can either run texi2html twice on all files (run it once on all files 
> and only after that we can run it a second time, this time with all maps from 
> the other files available) or try to create a hand-written script to extract 
> that map and then run texi2html only once. I'd prefer running texi2html 
> twice, but that (1) takes longer and (2) I don't know how hard it would be to 
> implement in the makefiles...

As you have probably noticed in dev/texi2html branch, I've already
splitted WWW into two stages WWW-1 and WWW-2.  When you want to test the
code from the makefiles, just add a call of the hand-made script that
writes files containing node trees (or texi2html, but I don't like this
option for the reasons you mentioned) "at the end of local-WWW-1" i.e. a
rule depending on $(outdir)/*.texi files, 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.


In a hopefully not too distant future, it will be possible to run
texi2html only to parse the input and then do what you want with it,
e.g. generating info for externals cross-references.  If you wish to
join Texinfo development team and assign contributions to texi2html to
GNU, please contact Karl Berry privately.  Discussion on replacing
makeinfo recently took place on bug-texinfo list.


> - -) Proper real-world testing. This is a point that takes time and should 
> not 
> be hurried, so I'm not in favor of last-minute pushes before a release. In 
> particular, since section names can now be translated directly in the file, 
> translators need to adjust, and I'd like to give them some time to adjust to 
> it.

I generally agree about not hurrying too much.  I vote for merging
dev/texi2html into master as soon as the docs look good enough: no or
very few broken links, decent (even if non-perfect) graphical design.
Final polishing and testing can be done by all users then.


> Once you know some programming language (or rather paradigms like procedural 
> or functional), other languages are just a different syntax, but otherwise 
> not hard to learn. I am typically not even aware of the language I'm coding, 
> because I look at the existing code and automatically adjust to it. 

You're right about paradigms, but style(s) of each particular language
matters a lot too, e.g. when it comes to read code written by other
people.  E.g. I sigh whenever I read Python code written like C instead
of using builtin library modules and Python language specific features
(though I haven't sighed much for this reason :-).  The style and good
coding practices matter a lot too, and this partially depends on the
language.


> After all, the most important spot of the docs is the 
> homepage, and we can always replace the version on the homepage by a 
> texi2html one later on. We don't even need a release for this.

Are you talking about the documentation index?  I see no advantage in
using texi2html to generate it.


> Concerning the texi2html, I still have some questions:
> - -) Do I see it correctly that we don't create translated versions of the 
> "one 
> big page" single-file manuals?

It's correct; only fully translated manuals should be compiled in a
single page format, because partially translated manuals are sort of a
mess with a long succession of empty sections in single page format, a
bit like PDF format -- but PDF output is necessary for people who want
to read the docs in printed format.


> - -) How should the translated section titles and the 
> unnumbered-into-the-same-file  features work exactly? Imagine we have a 
> section
>     @node Title
>     @section Title
> ...
>    @node Paragraph title
>    @unnumberedsubsubsec Paragraph title
> in the .tely file. The German translation would then use
>     @node Überschrift
>     @section Überschrift
>     @translationof Title
> ...
>    @node Absatzüberschrift
>    @unnumbered Absatzüberschrift
>    @translationof Paragraph title
> right? How do cross-references to these sections work? I suppose that they 
> should always use the translated titles and the texi2html init script 
> automatically retrieves the correct file name / anchor for the link. Do I 
> understand this correctly? I.e. internal refs are:
>    @ref{Überschrift}
>    @ref{Absatzüberschrift}
> and external refs are:
>    @rlearning{Überschrift}
>    @rlearning{Absatzüberschrift}

Yes, I'd expect cross-references to work exactly like this.

Cheers,
John