[PATCH] consistently capitalize section names

[PATCH] consistently capitalize section names

[Bob Wilson]

[-- Attachment #1: Type: text/plain, Size: 1658 bytes --]

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  <bob.wilson@acm.org>
	
	* 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.


[-- Attachment #2: gdb-doc-section-names.patch.gz --]
[-- Type: application/x-gzip, Size: 13815 bytes --]

Re: [PATCH] consistently capitalize section names

[Eli Zaretskii]

> Date: Mon, 26 Mar 2007 11:25:26 -0700
> From: Bob Wilson <bwilson@tensilica.com>
> 
> 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.

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

Re: [PATCH] consistently capitalize section names

[Eli Zaretskii]

> Date: Mon, 26 Mar 2007 14:20:44 -0700
> From: Bob Wilson <bwilson@tensilica.com>
> CC:  gdb-patches@sources.redhat.com
> 
> 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.

Re: [PATCH] consistently capitalize section names

[Bob Wilson]

[-- Attachment #1: Type: text/plain, Size: 818 bytes --]

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  <bob.wilson@acm.org>
	
	* 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".


[-- Attachment #2: gdb-doc-capitalize.patch.gz --]
[-- Type: application/x-gzip, Size: 28071 bytes --]

Re: [PATCH] consistently capitalize section names

[Eli Zaretskii]

> Date: Tue, 27 Mar 2007 12:34:37 -0700
> From: Bob Wilson <bwilson@tensilica.com>
> CC:  gdb-patches@sources.redhat.com
> 
> 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.