FW: [Gdb-discuss] Style Conventions for Documentation?

FW: [Gdb-discuss] Style Conventions for Documentation?

[Mann, Benjamin (Jr)]

Hello,

Can you help me out?  I am looking for style convention information used
in the GNU documentation, if such guidelines exist. 

Jim Blandy recommended I submit the query to you. If there's a better,
more appropriate way to find the information I seek, please let me know.

See my message (and Jim's reply) below.

Thank you.

***************************
Ben Mann, Jr.
Hewlett-Packard Company
110 Spit Brook Road
Nashua, NH  03062
e-mail: Ben.Mann@hp.com
telephone: 603-884-3477

-----Original Message-----
From: jimb@zenia.home [mailto:jimb@zenia.home] On Behalf Of Jim Blandy
Sent: June 09, 2004 12:16 PM
To: Mann, Benjamin (Jr)
Cc: gdb-discuss@gnu.org
Subject: Re: [Gdb-discuss] Style Conventions for Documentation?



"Mann, Benjamin (Jr)" <ben.mann@hp.com> writes:
> I am a technical editor who has been asked to review the HP WDB 
> version of Debugging with GDB.  Please forgive my ignorance of 
> information that may be readily available; this is my first exposure 
> to open source documentation.  I have been unable to find any 
> guidelines or reference information on your Web site about the 
> preferred writing style and typographic conventions for GNU-related 
> documentation.
> 
> Do you have, or know where I might find, a listing of typographic
style
> conventions that are recommended for use in the documentation?
Because
> there have been many contributors to the documentation (from many 
> companies and with different points of view), many styles are 
> implemented for similar items.  For example, sometimes command options

> are in single quotes, sometimes not.  Or lead-ins to lists or code 
> examples sometimes end with a colon, sometimes with no punctuation, 
> and sometimes with a period.
> 
> As an editor I value consistency (among other things like clear 
> writing, conciseness, and so forth), so I am looking for any guidance 
> about writing style preferences you have or know of, if any.
> 
> Thank you for any direction you can provide.

Probably the best place to post this question would be
gdb@sources.redhat.com.  Eli Zaretskii <eliz@elta.co.il> is our
documentation maintainer; he's listed in gdb/MAINTAINERS.

Re: FW: [Gdb-discuss] Style Conventions for Documentation?

[Eli Zaretskii]

> Date: Wed, 9 Jun 2004 12:27:29 -0400
> From: "Mann, Benjamin (Jr)" <ben.mann@hp.com>
> 
> Can you help me out?  I am looking for style convention information used
> in the GNU documentation, if such guidelines exist. 

For general guidelines, see the Texinfo manual and the standards.texi
manual (be sure to find the latest version from the GNU FTP site).

> Because there have been many contributors to the documentation (from
> many companies and with different points of view), many styles are
> implemented for similar items.  For example, sometimes command
> options are in single quotes, sometimes not.

Could you please give a concrete example or two?  I'm not sure I
understand the context.

> Or lead-ins to lists or code examples sometimes end with a colon,
> sometimes with no punctuation, and sometimes with a period.

This depends on the specifics of the text, but again, please provide
an example.

> As an editor I value consistency (among other things like clear
> writing, conciseness, and so forth)

Same here.