[PATCH] consistently capitalize section names

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

[PATCH] consistently capitalize section names

Bob Wilson
Here's the last of my doc patches for now....

With the exception of some of the more recently written parts of the GDB doc,
there appears to be a strong convention of capitalizing only the first word of
section titles.  (All the major words in chapter and appendix titles are
capitalized.)  Some of the section titles do not follow this convention.  This
is most visible when you read the table of contents in the TeX-generated output.
  This patch makes all the section titles consistently capitalized.

Some comments:

* I also changed one of the node titles to be plural (see the changelog entry),
since it seemed like the singular form didn't make sense.

* I changed the capitalization of all the references I could find to these
sections.  Two of those sections (the "free software" sections) are referenced
in the document license.  I don't know if changing the license in this way might
be an issue.  If so, I guess we could leave those section titles as they were.

* A good number of the changes here are to subheadings and subsubheadings in the
GDB/MI chapter.  These don't normally show up in the table of contents, so their
inconsistent capitalization is much less visible.  If you don't want to change
all these headings for some reason, I don't think they matter as much as the
other sections.

2007-03-26  Bob Wilson  <[hidden email]>
       
        * gdb.texinfo: Consistently capitalize only the first word of section
        names at the section level and lower.
        (Starting and Stopping Trace Experiment): Renamed this node to....
        (Starting and Stopping Trace Experiments): ...this.
        * agentexpr.texi: Change section name capitalization.


gdb-doc-section-names.patch.gz (18K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH] consistently capitalize section names

Eli Zaretskii
> Date: Mon, 26 Mar 2007 11:25:26 -0700
> From: Bob Wilson <[hidden email]>
>
> With the exception of some of the more recently written parts of the GDB doc,
> there appears to be a strong convention of capitalizing only the first word of
> section titles.  (All the major words in chapter and appendix titles are
> capitalized.)  Some of the section titles do not follow this convention.  This
> is most visible when you read the table of contents in the TeX-generated output.
>   This patch makes all the section titles consistently capitalized.

Thanks for doing this, but unfortunately the capitalization style
you've chosen is wrong.  The Texinfo manual says:

   * By convention, node names are capitalized just as they would be for
     section or chapter titles--initial and significant words are
     capitalized; others are not.

IOW, the correct capitalization style is, e.g., "Commands to Set
Tracepoints", not "Commands to set tracepoints".  If you can afford
that, please redo the capitalization to use this style.

Thanks again for working on this.

Reply | Threaded
Open this post in threaded view
|

Re: [PATCH] consistently capitalize section names

Bob Wilson
Eli Zaretskii wrote:
> Thanks for doing this, but unfortunately the capitalization style
> you've chosen is wrong.

I think consistency is the important thing here, and I was trying to match the
existing convention.  If you exclude recent additions to the manual, almost all
of the headings at the section level and lower have only the first word capitalized.

> The Texinfo manual says:
>
>    * By convention, node names are capitalized just as they would be for
>      section or chapter titles--initial and significant words are
>      capitalized; others are not.

I'm not opposed to changing the capitalization style, but I don't think that
quote requires it.  Before the part you quoted, it says "Here are three
suggestions".  Besides, this is addressing the question of node names and only
indirectly mentions the capitalization of section titles, assuming they will be
handled the same as chapter titles.

Like I said, I'm not opposed to your suggestion.  This seems to me a matter of
choosing between two equally correct styles.  Someone in the past must have made
a conscious choice to capitalize section titles differently than chapter titles.

Anyway, it sounds like you want to change that convention, which is fine with me.

>
> IOW, the correct capitalization style is, e.g., "Commands to Set
> Tracepoints", not "Commands to set tracepoints".  If you can afford
> that, please redo the capitalization to use this style.

Hmm.  Yes, well, I really ought to be working on other things, but I might
manage to squeeze it in sometime.

--Bob

Reply | Threaded
Open this post in threaded view
|

Re: [PATCH] consistently capitalize section names

Eli Zaretskii
> Date: Mon, 26 Mar 2007 14:20:44 -0700
> From: Bob Wilson <[hidden email]>
> CC:  [hidden email]
>
> I'm not opposed to changing the capitalization style, but I don't think that
> quote requires it.  Before the part you quoted, it says "Here are three
> suggestions".  Besides, this is addressing the question of node names and only
> indirectly mentions the capitalization of section titles, assuming they will be
> handled the same as chapter titles.

I agree that it's vague, but that's the capitalization style I
consider correct, and other GNU manuals use it.

> > IOW, the correct capitalization style is, e.g., "Commands to Set
> > Tracepoints", not "Commands to set tracepoints".  If you can afford
> > that, please redo the capitalization to use this style.
>
> Hmm.  Yes, well, I really ought to be working on other things, but I might
> manage to squeeze it in sometime.

Thank you.
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH] consistently capitalize section names

Bob Wilson
Eli Zaretskii wrote:
> I agree that it's vague, but that's the capitalization style I
> consider correct, and other GNU manuals use it.

Yes, it is good to be consistent with the other GNU manuals -- especially since
GDB pulls in sections from the readline documentation.  I prefer this style anyway.

How's this?  (There are a few places where this intersects with my other pending
patch, and this one doesn't include the changes from the other.  I'll merge them
as needed.)

2007-03-27  Bob Wilson  <[hidden email]>
       
        * gdb.texinfo: Consistently capitalize all significant words in
        node names, chapter titles, section titles, and headings.  Update
        cross references to match.
        (Starting and Stopping Trace Experiment): Make node name plural.
        (Breakpoint related warnings): Hyphenate "Breakpoint-related".


gdb-doc-capitalize.patch.gz (37K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH] consistently capitalize section names

Eli Zaretskii
> Date: Tue, 27 Mar 2007 12:34:37 -0700
> From: Bob Wilson <[hidden email]>
> CC:  [hidden email]
>
> Eli Zaretskii wrote:
> > I agree that it's vague, but that's the capitalization style I
> > consider correct, and other GNU manuals use it.
>
> Yes, it is good to be consistent with the other GNU manuals -- especially since
> GDB pulls in sections from the readline documentation.  I prefer this style anyway.
>
> How's this?

Fine, thanks.  Please commit.