Re: syntax changes before beta version

[Reinhold Kainhofer]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Am Samstag, 19. Juli 2008 schrieb John Mandereau:
> On 2008/07/18 01:24 +0200, Reinhold Kainhofer wrote:
> > - -) 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.

The big disadvantage of using an external script to generate the file names is 
that I basically have to duplicate the code (for generating the file name and 
deciding into which files to put the subsections) that is also in the 
texi2html init file. Plus, I'll have to write a basic texinfo parser, too 
(well, at least it needs to extract @node, @chapter, @(sub)*section, 
@unnumbered((sub)*sec)?, @translationof, @include, @ignore, @ifhtml, and of 
course all texinfo constructs used in any of the section titles...).

In dev/texi2html, all this is already implemented (took about 8 lines, 1 for 
storing the generated file name in a has and the others to write them out to 
disk).

> 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.  

Yes, that would be great. Unfortunately, in Lilypond we are restrained to 
using the released version, so for lilypond it will be a little more into the 
future:(

> 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.

Yes, I saw that. I'm already subscribed to both the texinfo as well as the 
texi2html mailing lists.

> > - -) 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.

hehe, which brings us to the point: Who is going to create the design?

> > 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?  

No, what I meant was that even if 2.12 was released before merging in 
dev/texi2html, the online docs can always be replaced by the ones generated 
by texi2html. I don't know how others work, but I mainly use the online docs 
(at kainhofer.com/~lilypond/texi2html-out) when working with lilypond, rather 
than locally installed docs.

> > 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, 

Hmm, I thought the German and Spanish translations are basically complete 
(maybe not right now for GDP, but at least for the latest released version)

> > - -) How should the translated section titles and the
> > unnumbered-into-the-same-file  features work exactly? 
> > [...] 
> Yes, I'd expect cross-references to work exactly like this. 

Okay, so I understood things correctly.

Cheers,
Reinhold
- -- 
- ------------------------------------------------------------------
Reinhold Kainhofer, Vienna University of Technology, Austria
email: address@hidden, http://reinhold.kainhofer.com/
 * Financial and Actuarial Mathematics, TU Wien, http://www.fam.tuwien.ac.at/
 * K Desktop Environment, http://www.kde.org, KOrganizer maintainer
 * Chorvereinigung "Jung-Wien", http://www.jung-wien.at/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)

iD8DBQFIggSaTqjEwhXvPN0RAgzuAKC0ORH/z8w9aTqPRo0Tfjz4Qm0r7ACfQpXC
+60kDMbqpr3ZsUFmXhXZupg=
=recG
-----END PGP SIGNATURE-----