Re: [PATCH] documentation: page break

[Ralf Wildenhues]

Hi William,

* William Pursell wrote on Mon, Nov 24, 2008 at 08:49:22AM CET:
>
> You mentioned that
> I should not edit the ChangeLog--are you generating it
> automatically?

Well, more or less.  I have macros to covert from ChangeLog entry to
git commit log entry and vice versa.  And a script to generate a stub
ChangeLog entry.  The latter is vc-chlog from the vc-dwim package:
<http://www.gnu.org/software/vc-dwim/>

Paolo posted a script a little while ago, I think on autoconf-patches.

> Really, the question is, do you want
> me to put "* doc/automake.texi:" in my git log message?

Yes, if that's no problem for you.

> 2nd question, how important is the subject line of
> the email to you?  ie, would it help if I gave some
> specificity regarding the sections modified, or perhaps
> started a counter and put it in the subject?  I suspect
> I'll be done with the manual in fairly short time (although
> I don't get much time to look at it during the week) so
> this is probably not a big deal.

Well, the absolute easiest is if you format your mail message with
'git format-patch'.  If you've never seen this, look at the git mailing
list how they send patches there (with additional comments put between
the '---' line and the diffstat lines).  This format allows me to pipe
your mail into 'git am' which automatically generates a commit from it
then.  Almost no work.  :-)

If you decide to do this, you can also keep the ChangeLog entries in the
patch.  Gnulib has a git merge driver called git-merge-changelog which
helps merging ChangeLog entries should they not fit perfectly any more.

> I am disappointed with myself for taking so long to get
> to reading the manual straight through.

I'm not sure if I can do anything to address this.  :-)

> I recall trying
> to read it back when I first started looking at automake,
> and remember it being mostly incomprehensible.  It now
> reads very well, though, and I can't think of any way to
> improve its readability for the novice without making it
> 3 times as long.  (Nor am I sure that making it into
> an introductory text is a good idea.)

Me neither.

>     Removing superflous page break in automake.texi
>
>     (Mixing Fortran 77 With C and C++):  Removed a page break
>     that serves no purpose but to break the flow of the narrative.

This looks good, but why stop here and leave the next @page in?

Also, if you are interested in cleaning up the structure of the manual,
Karl has an interesting comment that I haven't got around to addressing
yet: <http://thread.gmane.org/gmane.comp.sysutils.automake.bugs/4205>.
I never found the time to go through the patch and think of a nice
consistent markup that looks good both in info and pdf.  (This patch
would not be for branch-1-10, I don't want to change HTML file names
arbitrarily there.)

Cheers,
Ralf