Patch to move spelling/terminology conventions to codingconventions.html
Joseph S. Myers
jsm28@cam.ac.uk
Wed Nov 7 06:04:00 GMT 2001
This patch moves the list of terminology and spelling conventions from
comments in gcc.texi to codingconventions.html and adds some more
discussion there of Texinfo style (both the style choices I've tried
to make the GCC manuals follow consistently, and some general Texinfo
style issues for the benefit of those who haven't read the Texinfo
manual). It passes "make info" and "make dvi". OK to commit?
2001-11-07 Joseph S. Myers <jsm28@cam.ac.uk>
* doc/gcc.texi: Move terminology and spelling conventions to
htdocs/codingconventions.html.
--- gcc.texi.orig Sat Nov 3 13:16:37 2001
+++ gcc.texi Wed Nov 7 13:11:02 2001
@@ -41,26 +41,6 @@
@c
@c anything else? --mew 10feb93
-@c For consistency, use the following:
-@c - "32-bit" rather than "32 bit" as an adjective.
-@c - American rather than British spelling (in particular -or and -ize).
-@c - "back end" as a noun, "back-end" as an adjective.
-@c - "bit-field" not "bitfield" or "bit field" (following the C and C++
-@c standards).
-@c - "built-in" as an adjective ("built-in function"), or sometimes
-@c "built in", not "builtin" (which isn't a word).
-@c - "dependent" as an adjective, and "dependency".
-@c - "front end" as a noun, "front-end" as an adjective.
-@c - "GCC" for the GNU Compiler Collection, both generally
-@c and as the GNU C Compiler in the context of compiling C;
-@c "G++" for the C++ compiler; "gcc" and "g++" (lowercase),
-@c marked up with @command, for the commands for compilation when the
-@c emphasis is on those; "GNU C" and "GNU C++" for language dialects;
-@c and try to avoid the older term "GNU CC".
-@c - "nonzero" rather than "non-zero".
-@c - "@code{NULL}" rather than "NULL".
-@c - "Objective-C" rather than "Objective C".
-
@macro gcctabopt{body}
@code{\body\}
@end macro
--- codingconventions.html.orig Tue Oct 16 11:47:30 2001
+++ codingconventions.html Wed Nov 7 13:51:26 2001
@@ -173,6 +173,135 @@
href=" http://gcc.gnu.org/ml/gcc-patches/2000-10/msg00792.html" ;>message</a>.</p>
+<h2>Spelling, terminology and markup</h2>
+
+<p>The following conventions of spelling and terminology apply
+throughout GCC, including the manuals, web pages, diagnostics,
+comments, and (except where they require spaces or hyphens to be used)
+function and variable names, although consistency in user-visible
+documentation and diagnostics is more important than that in comments
+and code. The following table lists some simple cases:</p>
+
+<table cellpadding="4">
+ <tr>
+ <th>Use...</th><th>...instead of</th><th>Rationale</th>
+ </tr>
+ <tr>
+ <td>American spelling (in particular -ize, -or)</td>
+ <td>British spelling (in particular -ise, -our)</td>
+ <td></td>
+ <tr>
+ <td>"32-bit" (adjective)</td>
+ <td>"32 bit"</td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>"back end" (noun)</td>
+ <td>"back-end" or "backend"</td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>"back-end" (adjective)</td>
+ <td>"back end" or "backend"</td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>"bit-field"</td>
+ <td>"bit field" or "bitfield"</td>
+ <td>Spelling used in C and C++ standards</td>
+ </tr>
+ <tr>
+ <td>"built-in" as an adjective ("built-in function") or "built in"</td>
+ <td>"builtin"</td>
+ <td>"builtin" isn't a word</td>
+ </tr>
+ <tr>
+ <td>"dependent" (adjective), "dependence", "dependency"</td>
+ <td>"dependant", "dependance", "dependancy"</td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>"front end" (noun)</td>
+ <td>"front-end" or "frontend"</td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>"front-end" (adjective)</td>
+ <td>"front end" or "frontend"</td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>"nonzero"</td>
+ <td>"non-zero" or "non zero"</td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>"Objective-C"</td>
+ <td>"Objective C"</td>
+ </tr>
+</table>
+
+<p>"GCC" should be used for the GNU Compiler Collection, both
+generally and as the GNU C Compiler in the context of compiling C;
+"G++" for the C++ compiler; "gcc" and "g++" (lowercase), marked up
+with <code>@command</code> when in Texinfo, for the commands for
+compilation when the emphasis is on those; "GNU C" and "GNU C++" for
+language dialects; and try to avoid the older term "GNU CC".</p>
+
+<p>In Texinfo manuals, Texinfo 4.0 features may be used, and should be
+used where appropriate. URLs should be marked up with
+<code>@uref</code>; email addresses with <code>@email</code>;
+command-line options with <code>@option</code>; names of commands with
+<code>@command</code>; environment variables with <code>@env</code>.
+NULL should be written as <code>@code{NULL}</code>. Tables of
+contents should come just after the title page; printed manuals will
+be formatted (for example, by <code>make dvi</code>) using
+<code>texi2dvi</code> which reruns TeX until cross-references
+stabilize, so there is no need for a table of contents to go at the
+end for it to have correct page numbers. The <code>@refill</code>
+feature is obsolete and should not be used. All manuals should use
+<code>@dircategory</code> and <code>@direntry</code> to provide Info
+directory information for <code>install-info</code>.</p>
+
+<p>It is useful to read the <a
+href=" http://www.gnu.org/manual/texinfo/" ;>Texinfo manual</a>. Some
+general Texinfo style issues discussed in that manual should be
+noted:</p>
+
+<ul>
+
+ <li>For proper formatting of the printed manual, TeX quotes (matched
+ <code>`</code> or <code>``</code> and <code>'</code> or
+ <code>''</code>) should be used; neutral ASCII double quotes
+ (<code>"..."</code>) should not be. Similarly, TeX dashes
+ (<code>--</code> (two hyphens) for an en dash and <code>---</code>
+ (three hyphens) for an em dash) should be used; normally these
+ dashes should not have whitespace on either side. Minus signs
+ should be written as <code>@minus{}</code>.
+
+ <li>For an ellipsis, <code>@dots{}</code> should be used; for a
+ literal sequence of three dots in a programming language, the dots
+ should be written as such (<code>...</code>) rather than as
+ <code>@dots{}</code>.</li>
+
+ <li>English text in programming language comments in examples should
+ be enclosed in <code>@r{}</code> so that it is printed in a
+ non-fixed-width font.</li>
+
+ <li>For Info output, full stops that end sentences should be
+ followed by two spaces or by end of line. For printed output, full
+ stops that are preceded by a lower-case letter but do not end a
+ sentence should be followed by <code>@:</code> if they are not
+ followed by other punctuation such as a comma; full stops, question
+ marks and exclamation marks that end a sentence but are preceded by
+ an upper-case letter should be written as "<code>@.</code>",
+ "<code>@?</code>" and "<code>@!</code>", respectively. (This is not
+ required if the capital letter is within <code>@code</code> or
+ <code>@samp</code>.)</li>
+
+</ul>
+
+
<h2>Upstream packages</h2>
<p>Some files and packages in the CVS tree are imported from elsewhere,
--
Joseph S. Myers
jsm28@cam.ac.uk
More information about the Gcc-patches
mailing list