Directs output of texi2html to log files (GOP 9)

Directs output of texi2html to log files (GOP 9) for translated docs.  There is a slight gotcha with this change, that if there is an error in running texi2html, then the dev has to know to look at the relevant log file.  However, it's highly unlikely this will ever occur - we leave --error-limit for texi2html at its default value of 1000, so it's almost impossible to cause it to fail.  The huge benefit of this change is further reduced output from make doc, and the ability to get a list of all the errors in the docs in a logfile. These could be sent to the relevant author/translator.

[PhilEHolmes, 2011-12-19 16:37:10]

Please review

[Julien Rioux, 2011-12-19 20:23:29]

On 2011/12/19 16:37:10, PhilEHolmes wrote:
> Please review

Hi Phil,

I was just looking at the translated manuals recently, please see
http://code.google.com/p/lilypond/issues/detail?id=2125

Among the suggested changes in issue 2125 is to remove all the TEXI2HTML calls
in make/doc-i18n-root-rules.make, since that information, on how to build an
html from a texi file, is already provided in
stepmake/stepmake/texinfo-rules.make. So if we think these changes are good,
stepmake/stepmake/texinfo-rules.make should be modified to redirect the output
of texi2html.

Regards,
Julien

[mail_philholmes.net, 2011-12-19 20:34:31]

----- Original Message ----- 
From: <julien.rioux@gmail.com>
To: <PhilEHolmes@googlemail.com>; <graham@percival-music.ca>
Cc: <reply@codereview-hr.appspotmail.com>; <lilypond-devel@gnu.org>
Sent: Monday, December 19, 2011 8:23 PM
Subject: Re: Directs output of texi2html to log files (GOP 9) (issue 
5495092)


> On 2011/12/19 16:37:10, PhilEHolmes wrote:
>> Please review
>
> Hi Phil,
>
> I was just looking at the translated manuals recently, please see
> http://code.google.com/p/lilypond/issues/detail?id=2125
>
> Among the suggested changes in issue 2125 is to remove all the TEXI2HTML
> calls in make/doc-i18n-root-rules.make, since that information, on how
> to build an html from a texi file, is already provided in
> stepmake/stepmake/texinfo-rules.make. So if we think these changes are
> good, stepmake/stepmake/texinfo-rules.make should be modified to
> redirect the output of texi2html.
>
> Regards,
> Julien


Julien,

I'm happy to be guided by you as the best way of doing this.  I think the 
simplest way is to add the redirection to your patch and I'll pull mine.

--
Phil Holmes

[Julien Rioux, 2011-12-19 20:53:49]

On 2011/12/19 20:34:31, mail_philholmes.net wrote:
> ----- Original Message ----- 
> From: <mailto:julien.rioux@gmail.com>
> To: <PhilEHolmes@googlemail.com>; <mailto:graham@percival-music.ca>
> Cc: <reply@codereview-hr.appspotmail.com>; <mailto:lilypond-devel@gnu.org>
> Sent: Monday, December 19, 2011 8:23 PM
> Subject: Re: Directs output of texi2html to log files (GOP 9) (issue 
> 5495092)
> 
> 
> > On 2011/12/19 16:37:10, PhilEHolmes wrote:
> >> Please review
> >
> > Hi Phil,
> >
> > I was just looking at the translated manuals recently, please see
> > http://code.google.com/p/lilypond/issues/detail?id=2125
> >
> > Among the suggested changes in issue 2125 is to remove all the TEXI2HTML
> > calls in make/doc-i18n-root-rules.make, since that information, on how
> > to build an html from a texi file, is already provided in
> > stepmake/stepmake/texinfo-rules.make. So if we think these changes are
> > good, stepmake/stepmake/texinfo-rules.make should be modified to
> > redirect the output of texi2html.
> >
> > Regards,
> > Julien
> 
> 
> Julien,
> 
> I'm happy to be guided by you as the best way of doing this.  I think the 
> simplest way is to add the redirection to your patch and I'll pull mine.
> 
> --
> Phil Holmes
> 
> 

Oh, I don't mean to suggest to pull your patch. I don't know if mine survives a
review, for example. At the moment, I can see that they conflict. But the
changes you suggest in this patch are useful. If they would be applied to
stepmake/stepmake/texinfo-rules.make then that would apply to all of make doc.

Regards,
Julien

[Graham Percival, 2011-12-20 19:19:51]

On 2011/12/19 20:53:49, Julien Rioux wrote:
> Oh, I don't mean to suggest to pull your patch. I don't know if mine survives
a
> review, for example. At the moment, I can see that they conflict. But the
> changes you suggest in this patch are useful. If they would be applied to
> stepmake/stepmake/texinfo-rules.make then that would apply to all of make doc.

Does stepmake/stepmake/texinfo-rules.make apply to translations?  I thought
translations only used make/doc-whatever-i18n.

Anyway, I'm slightly hesitant to include the patch until there's a notification
of errors (as recently discussed on -devel).  With that concern, as well as the
question about which files the change should be applied to, and conflicts with
Julien's work, I think this patch should have another revision after Julien's
patch is pushed (presumably in a few hours?).

[Julien Rioux, 2011-12-20 19:33:15]

On 2011/12/20 19:19:51, Graham Percival wrote:
> Does stepmake/stepmake/texinfo-rules.make apply to translations?  I thought
> translations only used make/doc-whatever-i18n.

Since very recently, yes. I added texinfo in
9ac7a5aaff66f2bd19184c9a23bccd195323e193.

> Anyway, I'm slightly hesitant to include the patch until there's a
notification
> of errors (as recently discussed on -devel).  With that concern, as well as
the
> question about which files the change should be applied to, and conflicts with
> Julien's work, I think this patch should have another revision after Julien's
> patch is pushed (presumably in a few hours?).

If applied to stepmake/stepmake/texinfo-rules then the changes discussed here
would not cause conflict.

[Graham Percival, 2011-12-20 19:39:28]

On Tue, Dec 20, 2011 at 07:33:15PM +0000, julien.rioux@gmail.com wrote:
> On 2011/12/20 19:19:51, Graham Percival wrote:
> >Does stepmake/stepmake/texinfo-rules.make apply to translations?  I
> thought
> >translations only used make/doc-whatever-i18n.
> 
> Since very recently, yes. I added texinfo in
> 9ac7a5aaff66f2bd19184c9a23bccd195323e193.

oh, *that's* what the STEPMAKE_TEMPLATES line does!

Cheers,
- Graham

[Julien Rioux, 2011-12-20 19:41:10]

On Tue, Dec 20, 2011 at 8:39 PM, Graham Percival
<graham@percival-music.ca> wrote:
> oh, *that's* what the STEPMAKE_TEMPLATES line does!
>
> Cheers,
> - Graham

Yes, and things started to make a lot more sense once I made that connection.
At some point in the new year I'll try to document what I learned
about stepmake.

Cheers,
Julien

[Graham Percival, 2011-12-20 19:46:22]

On Tue, Dec 20, 2011 at 08:41:10PM +0100, Julien Rioux wrote:
> Yes, and things started to make a lot more sense once I made that connection.
> At some point in the new year I'll try to document what I learned
> about stepmake.

I trust that you've seen
  Documentation/contributor/build-notes.itexi
?

Cheers,
- Graham

[Julien Rioux, 2011-12-20 19:54:11]

On Tue, Dec 20, 2011 at 8:46 PM, Graham Percival
<graham@percival-music.ca> wrote:
> On Tue, Dec 20, 2011 at 08:41:10PM +0100, Julien Rioux wrote:
>> Yes, and things started to make a lot more sense once I made that connection.
>> At some point in the new year I'll try to document what I learned
>> about stepmake.
>
> I trust that you've seen
>  Documentation/contributor/build-notes.itexi
> ?
>
> Cheers,
> - Graham

Yes of course, it was useful to read and I might contribute a bit more to it.
Cheers,
Julien

[mail_philholmes.net, 2011-12-21 09:29:37]

----- Original Message ----- 
From: <graham@percival-music.ca>
To: <PhilEHolmes@googlemail.com>; <julien.rioux@gmail.com>; 
<mail@philholmes.net>
Cc: <lilypond-devel@gnu.org>; <reply@codereview-hr.appspotmail.com>
Sent: Tuesday, December 20, 2011 7:19 PM
Subject: Re: Directs output of texi2html to log files (GOP 9) (issue 
5495092)


> On 2011/12/19 20:53:49, Julien Rioux wrote:
>> Oh, I don't mean to suggest to pull your patch. I don't know if mine
> survives a
>> review, for example. At the moment, I can see that they conflict. But
> the
>> changes you suggest in this patch are useful. If they would be applied
> to
>> stepmake/stepmake/texinfo-rules.make then that would apply to all of
> make doc.
>
> Does stepmake/stepmake/texinfo-rules.make apply to translations?  I
> thought translations only used make/doc-whatever-i18n.
>
> Anyway, I'm slightly hesitant to include the patch until there's a
> notification of errors (as recently discussed on -devel).  With that
> concern, as well as the question about which files the change should be
> applied to, and conflicts with Julien's work, I think this patch should
> have another revision after Julien's patch is pushed (presumably in a
> few hours?).
>
> http://codereview.appspot.com/5495092/
>

I'll hold on this one and look again once Julien's patch is pushed.  As I 
said, it's almost inconceivable that there would be an error from texi2pdf 
causing the build to fail.  As a default, it tolerates 1000 errors before 
terminating.  Most of our translated docs already have a few hundred errors 
which would cause the build to fail if we set the --error-limit to a lower 
value.  Part of the difficulty in testing this patch was trying to get 
texi2pdf to fail so I could see what happened!  I got some very strange docs 
in all my (failed) attempts to get it to fail, before I 
discovered --error-limit.

--
Phil Holmes

[Graham Percival, 2011-12-21 14:16:32]

On Wed, Dec 21, 2011 at 09:29:31AM -0000, Phil Holmes wrote:
> I'll hold on this one and look again once Julien's patch is pushed.
> As I said, it's almost inconceivable that there would be an error
> from texi2pdf causing the build to fail.

I've seen half a dozen in the past month.  (my fault, it was
problems in @example vs. @verbatim).

> As a default, it tolerates 1000 errors before terminating.  Most
> of our translated docs already have a few hundred errors which
> would cause the build to fail if we set the --error-limit to a
> lower value. 

Are you sure?  I'd expect it to tolerate 1000 *warnings* before
terminating.  Warnings are not errors.

...
hmm, as far as I can see, texi2pdf doesn't have any --error-limit
flag, but makeinfo does.

$ man makeinfo
...
   General options:
       --error-limit=NUM
              quit after NUM errors (default 100)

WTF?!  David: is this seriously giving a zero return value if
there's any "errors" ?  Or does it still return a zero, but print
out multiple errors?


> Part of the difficulty in testing this patch was trying to get
> texi2pdf to fail so I could see what happened!

Easy way to make it fail immediately: add

@example
@\
@end example

to some file.  I recommend something in the CG.

makeinfo will not fail, but texi2pdf will fail.


What do you see if you set --error-limit=0 for makeinfo?  I'm
wondering if this is why we sometimes see "make" compiling the
docs but "make doc" failing.  If we can get "make" to be stricter
about checking the texinfo, this could save a lot of time in
writing docs.

If it would take less than 10 hours to fix the english docs, I
think we should set --error-limit=0.  We can leave it at 100 for
the translations for the next X months.

Wow, this is a really good find.

Cheers,
- Graham

[email_philholmes.net, 2011-12-21 14:39:57]

----- Original Message ----- 
From: "Graham Percival" <graham@percival-music.ca>
To: "Phil Holmes" <mail@philholmes.net>
Cc: <PhilEHolmes@googlemail.com>; <julien.rioux@gmail.com>; 
<lilypond-devel@gnu.org>; <reply@codereview-hr.appspotmail.com>
Sent: Wednesday, December 21, 2011 2:16 PM
Subject: Re: Directs output of texi2html to log files (GOP 9) (issue 
5495092)


> On Wed, Dec 21, 2011 at 09:29:31AM -0000, Phil Holmes wrote:
>> I'll hold on this one and look again once Julien's patch is pushed.
>> As I said, it's almost inconceivable that there would be an error
>> from texi2pdf causing the build to fail.
>
> I've seen half a dozen in the past month.  (my fault, it was
> problems in @example vs. @verbatim).
>
>> As a default, it tolerates 1000 errors before terminating.  Most
>> of our translated docs already have a few hundred errors which
>> would cause the build to fail if we set the --error-limit to a
>> lower value.
>
> Are you sure?  I'd expect it to tolerate 1000 *warnings* before
> terminating.  Warnings are not errors.

My mistake - it's texi2html.

> ...
> hmm, as far as I can see, texi2pdf doesn't have any --error-limit
> flag, but makeinfo does.
>
> $ man makeinfo
> ...
>   General options:
>       --error-limit=NUM
>              quit after NUM errors (default 100)
>
> WTF?!  David: is this seriously giving a zero return value if
> there's any "errors" ?  Or does it still return a zero, but print
> out multiple errors?
>
>
>> Part of the difficulty in testing this patch was trying to get
>> texi2pdf to fail so I could see what happened!
>
> Easy way to make it fail immediately: add
>
> @example
> @\
> @end example
>
> to some file.  I recommend something in the CG.
>
> makeinfo will not fail, but texi2pdf will fail.

If you try that with texi2html, I'm 99% certain it won't fail.  It was 
driving me crazy trying to make it.

>
> What do you see if you set --error-limit=0 for makeinfo?  I'm
> wondering if this is why we sometimes see "make" compiling the
> docs but "make doc" failing.  If we can get "make" to be stricter
> about checking the texinfo, this could save a lot of time in
> writing docs.
>
> If it would take less than 10 hours to fix the english docs, I
> think we should set --error-limit=0.  We can leave it at 100 for
> the translations for the next X months.

I'd have to experiment with the English docs, but I'm deep in .Net and 
access on another project for another day.

> Wow, this is a really good find.
>
> Cheers,
> - Graham

:-)

--
Phil Holmes