docs/54999: Documentation Project Primer doesn't conform to style guide
Steven James Huwig
sjh13 at cwru.edu
Mon Jul 28 23:10:20 UTC 2003
>Number: 54999
>Category: docs
>Synopsis: Documentation Project Primer doesn't conform to style guide
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: doc-bug
>Submitter-Id: current-users
>Arrival-Date: Mon Jul 28 16:10:17 PDT 2003
>Closed-Date:
>Last-Modified:
>Originator: Steven James Huwig
>Release: FreeBSD 4.8-RELEASE i386
>Organization:
>Environment:
System: FreeBSD mulder.intranet 4.8-RELEASE FreeBSD 4.8-RELEASE #0: Mon Jun 30 22:41:17 EDT 2003 steve at mulder.intranet:/usr/obj/usr/src/sys/MULDER2002 i386
>Description:
Chapter 10 of the FDP Primer reads "Use American English Spelling,"
yet there are many instances of the British versions of words (e.g.
'organise,' 'normalise,' et cetera.
>How-To-Repeat:
>Fix:
Attached are diffs correcting "ise" words to their "ize" equivalents.
--- examples/appendix.sgml.orig Mon Jul 28 17:41:22 2003
+++ examples/appendix.sgml Mon Jul 28 17:26:14 2003
@@ -48,7 +48,7 @@
<para>To avoid confusion, these examples use the standard DocBook 3.1 DTD
rather than the FreeBSD extension. They also use the stock stylesheets
- distributed by Norm Walsh, rather than any customisations made to those
+ distributed by Norm Walsh, rather than any customizations made to those
stylesheets by the FreeBSD Documentation Project. This makes them more
useful as generic DocBook examples.</para>
@@ -265,7 +265,7 @@
<calloutlist>
<callout arearefs="examples-co-jade-3-tex-backend">
- <para>Customises the stylesheets to use various options
+ <para>Customizes the stylesheets to use various options
specific to producing output for TeX.</para>
</callout>
--- sgml-markup/chapter.sgml.orig Mon Jul 28 17:44:37 2003
+++ sgml-markup/chapter.sgml Mon Jul 28 17:17:00 2003
@@ -466,7 +466,7 @@
<title>In-line elements</title>
<sect3>
- <title>Emphasising information</title>
+ <title>Emphasizing information</title>
<para>You have two levels of emphasis available in HTML,
<sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag>.
@@ -482,8 +482,8 @@
<para>Use:</para>
- <programlisting><![ CDATA [<p><em>This</em> has been emphasised, while
- <strong>this</strong> has been strongly emphasised.</p>]]></programlisting>
+ <programlisting><![ CDATA [<p><em>This</em> has been emphasized, while
+ <strong>this</strong> has been strongly emphasized.</p>]]></programlisting>
</example>
</sect3>
@@ -716,7 +716,7 @@
<title>Formal Public Identifier (FPI)</title>
<para>In compliance with the DocBook guidelines for writing FPIs for
- DocBook customisations, the FPI for the FreeBSD extended DocBook DTD
+ DocBook customizations, the FPI for the FreeBSD extended DocBook DTD
is;</para>
<programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"</programlisting>
@@ -731,7 +731,7 @@
<para>A book is organized into <sgmltag>chapter</sgmltag>s. This is a
mandatory requirement. There may be <sgmltag>part</sgmltag>s between
- the book and the chapter to provide another layer of organisation.
+ the book and the chapter to provide another layer of organization.
The Handbook is arranged in this way.</para>
<para>A chapter may (or may not) contain one or more sections. These
@@ -954,7 +954,7 @@
<sect3>
<title>Subdividing using <sgmltag>part</sgmltag>s</title>
- <para>You can introduce another layer of organisation between
+ <para>You can introduce another layer of organization between
<sgmltag>book</sgmltag> and <sgmltag>chapter</sgmltag> with one or
more <sgmltag>part</sgmltag>s. This cannot be done in an
<sgmltag>article</sgmltag>.</para>
@@ -1573,9 +1573,9 @@
<title>In-line elements</title>
<sect3>
- <title>Emphasising information</title>
+ <title>Emphasizing information</title>
- <para>When you want to emphasise a particular word or phrase, use
+ <para>When you want to emphasize a particular word or phrase, use
<sgmltag>emphasis</sgmltag>. This may be presented as italic, or
bold, or might be spoken differently with a text-to-speech
system.</para>
@@ -2579,7 +2579,7 @@
in <xref linkend="chapter1-sect1">.</para>]]></programlisting>
<para>The text of the link will be generated automatically, and will
- look like (<emphasis>emphasised</emphasis> text indicates the text
+ look like (<emphasis>emphasized</emphasis> text indicates the text
that will be the link);</para>
<blockquote>
@@ -2620,7 +2620,7 @@
<link linkend="chapter1-sect1">this</link> section.</para>]]></programlisting>
<para>This will generate the following
- (<emphasis>emphasised</emphasis> text indicates the text that will
+ (<emphasis>emphasized</emphasis> text indicates the text that will
be the link);</para>
<blockquote>
--- sgml-primer/chapter.sgml.orig Mon Jul 28 17:45:25 2003
+++ sgml-primer/chapter.sgml Mon Jul 28 17:18:28 2003
@@ -53,7 +53,7 @@
<para>Inevitably, this was not enough. Once you have text in a
machine-usable format, you expect machines to be able to use it and
manipulate it intelligently. You would like to indicate that certain
- phrases should be emphasised, or added to a glossary, or be hyperlinks.
+ phrases should be emphasized, or added to a glossary, or be hyperlinks.
You might want filenames to be shown in a <quote>typewriter</quote> style
font for viewing on screen, but as <quote>italics</quote> when printed,
or any of a myriad of other options for presentation.</para>
@@ -90,7 +90,7 @@
<para>The extra information stored in the markup <emphasis>adds
value</emphasis> to the document. Adding the markup to the document
must typically be done by a person—after all, if computers could
- recognise the text sufficiently well to add the markup then there would
+ recognize the text sufficiently well to add the markup then there would
be no need to add it in the first place. This <emphasis>increases the
cost</emphasis> (i.e., the effort required) to create the
document.</para>
@@ -199,7 +199,7 @@
<para>A tag is used to identify where a particular element starts, and
where the element ends. <emphasis>The tag is not part of the element
itself</emphasis>. Because each DTD was normally written to mark up
- specific types of information, each one will recognise different
+ specific types of information, each one will recognize different
elements, and will therefore have different names for the tags.</para>
<para>For an element called <replaceable>element-name</replaceable> the
@@ -251,7 +251,7 @@
<title>Elements within elements; <sgmltag>em</sgmltag></title>
<programlisting><![ CDATA [<p>This is a simple <em>paragraph</em> where some
- of the <em>words</em> have been <em>emphasised</em>.</p>]]></programlisting>
+ of the <em>words</em> have been <em>emphasized</em>.</p>]]></programlisting>
</example>
<para>The DTD will specify the rules detailing which elements can contain
@@ -643,7 +643,7 @@
<para>ISO 9070:1991 defines how registered names are generated; it
might be derived from the number of an ISO publication, an ISBN
- code, or an organisation code assigned according to ISO 6523.
+ code, or an organization code assigned according to ISO 6523.
In addition, a registration authority could be created in order
to assign registered names. The ISO council delegated this to
the American National Standards Institute (ANSI).</para>
@@ -796,7 +796,7 @@
your document. Everything between these delimiters is SGML syntax as
you might find within a DTD.</para>
- <para>As you may just have realised, the <link
+ <para>As you may just have realized, the <link
linkend="sgml-primer-doctype-declaration">DOCTYPE declaration</link>
is an example of SGML syntax that you need to include in your
document…</para>
@@ -1051,7 +1051,7 @@
<step>
<para>Load <filename>example.sgml</filename> into your web browser
(you may need to copy it to <filename>example.html</filename>
- before your browser recognises it as an HTML document).</para>
+ before your browser recognizes it as an HTML document).</para>
<para>Unless your browser is very advanced, you will not see the entity
reference <literal>&version;</literal> replaced with the
@@ -1064,10 +1064,10 @@
</step>
<step>
- <para>The solution is to <emphasis>normalise</emphasis> your
- document using an SGML normaliser. The normaliser reads in valid
+ <para>The solution is to <emphasis>normalize</emphasis> your
+ document using an SGML normalizer. The normalizer reads in valid
SGML and outputs equally valid SGML which has been transformed in
- some way. One of the ways in which the normaliser transforms the
+ some way. One of the ways in which the normalizer transforms the
SGML is to expand all the entity references in the document,
replacing the entities with the text that they represent.</para>
@@ -1075,7 +1075,7 @@
<screen>&prompt.user; <userinput>sgmlnorm example.sgml > example.html</userinput></screen>
- <para>You should find a normalised (i.e., entity references
+ <para>You should find a normalized (i.e., entity references
expanded) copy of your document in
<filename>example.html</filename>, ready to load into your web
browser.</para>
@@ -1156,7 +1156,7 @@
entities.</para>
<para>Suppose that you had many chapters in your document, and you
- reused these chapters in two different books, each book organising the
+ reused these chapters in two different books, each book organizing the
chapters in a different fashion.</para>
<para>You could list the entities at the top of each book, but this
@@ -1242,7 +1242,7 @@
</step>
<step>
- <para>Produce <filename>example.html</filename> by normalising
+ <para>Produce <filename>example.html</filename> by normalizing
<filename>example.sgml</filename>.</para>
<screen>&prompt.user; <userinput>sgmlnorm -d example.sgml > example.html</userinput></screen>
@@ -1299,7 +1299,7 @@
</step>
<step>
- <para>Produce <filename>example.html</filename> by normalising
+ <para>Produce <filename>example.html</filename> by normalizing
<filename>example.sgml</filename>.</para>
<screen>&prompt.user; <userinput>sgmlnorm -d example.sgml > example.html</userinput></screen>
@@ -1455,7 +1455,7 @@
from your document you could cut it out, or wrap it in
comments.</para>
- <para>It becomes more useful when you realise you can use <link
+ <para>It becomes more useful when you realize you can use <link
linkend="sgml-primer-parameter-entities">parameter entities</link>
to control this. Remember that parameter entities can only be used
in SGML contexts, and the keyword of a marked section
@@ -1542,7 +1542,7 @@
</step>
<step>
- <para>Normalise this file using &man.sgmlnorm.1; and examine the
+ <para>Normalize this file using &man.sgmlnorm.1; and examine the
output. Notice which paragraphs have appeared, which have
disappeared, and what has happened to the content of the CDATA
marked section.</para>
@@ -1551,7 +1551,7 @@
<step>
<para>Change the definition of the <literal>text.output</literal>
entity from <literal>INCLUDE</literal> to
- <literal>IGNORE</literal>. Re-normalise the file, and examine the
+ <literal>IGNORE</literal>. Re-normalize the file, and examine the
output to see what has changed. </para>
</step>
</procedure>
@@ -1564,7 +1564,7 @@
<para>That is the conclusion of this SGML primer. For reasons of space
and complexity several things have not been covered in depth (or at
all). However, the previous sections cover enough SGML for you to be
- able to follow the organisation of the FDP documentation.</para>
+ able to follow the organization of the FDP documentation.</para>
</sect1>
</chapter>
--- structure/chapter.sgml.orig Mon Jul 28 17:46:09 2003
+++ structure/chapter.sgml Mon Jul 28 17:20:35 2003
@@ -45,7 +45,7 @@
<listitem>
<para>promote consistency between the different documentation
- organisations, to make it easier to switch between working on
+ organizations, to make it easier to switch between working on
different documents</para>
</listitem>
@@ -76,7 +76,7 @@
<seg>Contains files that are not specific to the various translations
and encodings of the documentation. Contains subdirectories to
- further categorise the information. For example, the files that
+ further categorize the information. For example, the files that
comprise the &man.make.1; infrastructure are in
<filename>share/mk</filename>, while the additional SGML support
files (such as the FreeBSD extended DocBook DTD) are in
--- stylesheets/chapter.sgml.orig Mon Jul 28 17:47:05 2003
+++ stylesheets/chapter.sgml Mon Jul 28 17:19:38 2003
@@ -44,7 +44,7 @@
<sect1 id="stylesheets-dsssl">
<title>* DSSSL</title>
- <para>The Documentation Project uses a slightly customised version of
+ <para>The Documentation Project uses a slightly customized version of
Norm Walsh's modular DocBook stylesheets.</para>
<para>These can be found in
@@ -55,7 +55,7 @@
found in <filename>doc/share/sgml/freebsd.dsl</filename>. It is well
commented, and pending completion of this section you are encouraged to
examine that file to see how some of the available options in the
- standard stylesheets have been configured in order to customise the
+ standard stylesheets have been configured in order to customize the
output for the FreeBSD Documentation Project. That file also contains
examples showing how to extend the elements that the stylesheet
understands, which is how the FreeBSD specific elements have been
--- tools/chapter.sgml.orig Mon Jul 28 17:48:00 2003
+++ tools/chapter.sgml Mon Jul 28 17:14:40 2003
@@ -95,7 +95,7 @@
<listitem>
<para>A suite of applications, including a validating SGML parser,
- and an SGML normaliser.</para>
+ and an SGML normalizer.</para>
</listitem>
</varlistentry>
--- translations/chapter.sgml.orig Mon Jul 28 17:48:35 2003
+++ translations/chapter.sgml Mon Jul 28 17:22:44 2003
@@ -66,8 +66,8 @@
<answer>
<para><phrase>i18n</phrase> means
- <phrase>internationalisation</phrase> and <phrase>l10n</phrase>
- means <phrase>localisation</phrase>. They are just a convenient
+ <phrase>internationalization</phrase> and <phrase>l10n</phrase>
+ means <phrase>localization</phrase>. They are just a convenient
shorthand.</para>
<para><phrase>i18n</phrase> can be read as <quote>i</quote> followed by
@@ -196,7 +196,7 @@
<para>First, decide whether or not you have got the time to spare. Since
you are the only person working on your language at the moment it is
- going to be your responsibility to publicise your work and
+ going to be your responsibility to publicize your work and
coordinate any volunteers that might want to help you.</para>
<para>Write an e-mail to the Documentation Project mailing list,
>Release-Note:
>Audit-Trail:
>Unformatted:
More information about the freebsd-doc
mailing list