commit cd9832e406aabdae19bc688f96704027536f19b6
Author: Eric Christensen <echriste(a)redhat.com>
Date: Sat Mar 22 18:10:29 2014 -0400
Added style guide
en-US/Revision_History.xml | 13 ++
en-US/style.xml | 323 ++++++++++++++++++++++----------------------
2 files changed, 174 insertions(+), 162 deletions(-)
---
diff --git a/en-US/Revision_History.xml b/en-US/Revision_History.xml
index f5293fb..020fb34 100644
--- a/en-US/Revision_History.xml
+++ b/en-US/Revision_History.xml
@@ -8,6 +8,19 @@
<simpara>
<revhistory>
<revision>
+ <revnumber>0.4-0</revnumber>
+ <date>Sat Mar 22 2014</date>
+ <author>
+ <firstname>Eric</firstname>
+ <surname>Christensen</surname>
+
<email>sparks(a)fedoraproject.org</email>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Added style
guide.</member>
+ </simplelist>
+ </revdescription>
+ </revision> <revision>
<revnumber>0.3-0</revnumber>
<date>Mon May 28 2012</date>
<author>
diff --git a/en-US/style.xml b/en-US/style.xml
index 412665c..116259e 100644
--- a/en-US/style.xml
+++ b/en-US/style.xml
@@ -2830,179 +2830,178 @@ Avoid using this term.
<section
id="sect-documentation_guide-style-quick_reference-abbreviations">
<title>Abbreviations</title>
<para/>
- </section>
-<!--
-
-=== Abbreviations ===
-
-==== The United States ====
-
-* As a noun appearing alone, use "United States."
-
-<pre>
-...the government of the United States...
-</pre>
-
-* As a noun appearing as part of a locality, use "US" with no periods and no
spaces.
-
-<pre>
-Raleigh, NC, US
-US, Earth
-</pre>
-
-* As an adjective, use "U.S." with no spaces.
-
-<pre>
-...the U.S. government...
-</pre>
-
-===== States =====
-
-* Spell out state names when they appear alone.
-
-<pre>
-...the government of North Carolina...
-</pre>
-
-* When abbreviating state names, use their two-letter ZIP standard abbreviations.
-* Abbreviate state names when they appear as part of a locality.
-
-<pre>
-Raleigh, NC
-</pre>
-
-* Place one comma between the city and state name and another after the state name,
unless it ends the sentence or is part of a dateline.
-
-<pre>
-...founded in Raleigh, NC, by Red Hat...
-...managed from Raleigh, NC.
-</pre>
-
-==== Academic Degrees ====
-
-* Avoid abbreviating degrees.
-* Use an apostrophe in bachelor's degree, master's, etc.
-* Do not use an apostrophe in Bachelor of Arts, Master of Science, etc.
-* Use abbreviations only when the preferred method would be cumbersome.
-* Use abbreviations only after a full name.
-* Set abbreviations apart with commas.
-
-==== Dates ====
-
-* Spell out days of the week and separate them from dates using a comma.
-* When listing a day, month and year, use ISO 8601 dates (YYYY-MM-DD). Read more about
dates and times on the [
http://fedoraproject.org/wiki/DocsProject/StyleGuide/DatesAndTimes
DatesAndTimes] page.
-* When listing a day and month:
-* List the day first.
-* Spell out the day.
-* Set the day and month apart with "of."
-* Spell out the month.
-* When listing a month and year:
-* List the month first.
-* Spell out the month.
-* Set the month and year apart with "of."
-* Use Arabic numerals for the year.
-
-<pre>
+ <section
id="sect-documentation_guide-style-quick_reference-abbreviations-United_States">
+ <title>The United States</title>
+ <variablelist>
+ <varlistentry><term>As a noun appearing alone, use "United
States."</term><listitem><para>...the government of the United
States...</para></listitem></varlistentry>
+ <varlistentry><term>As a noun appearing as part of a locality, use
"US" with no periods and no
spaces.</term><listitem><para>Raleigh, NC,
US</para></listitem></varlistentry>
+ <varlistentry><term>As an adjective, use "U.S." with no
spaces.</term><listitem><para>...the U.S.
government...</para></listitem></varlistentry>
+ </variablelist>
+ <section
id="sect-documentation_guide-style-quick_reference-abbreviations-United_States-states">
+ <title>States</title>
+ <variablelist>
+ <varlistentry><term>Spell out state names when they appear
alone.</term><listitem><para>...the government of North
Carolina...</para></listitem></varlistentry>
+ <varlistentry><term>When abbreviating state names, use their two-letter
ZIP standard abbreviations.</term><term>Abbreviate state names when they
appear as part of a locality.</term><listitem><para>Raleigh,
NC</para></listitem></varlistentry>
+ <varlistentry><term>Place one comma between the city and state name and
another after the state name, unless it ends the sentence or is part of a
dateline.</term><listitem><para>...founded in Raleigh, NC, by Red
Hat...</para><para>...managed from Raleigh,
NC.</para></listitem></varlistentry>
+ </variablelist>
+ </section>
+ </section>
+ <section
id="sect-documentation_guide-style-quick_reference-abbreviations-academic_degrees">
+ <title>Academic Degrees</title>
+ <para>
+ <simplelist>
+ <member>Avoid abbreviating degrees.</member>
+ <member>Use an apostrophe in bachelor's degree, master's,
etc.</member>
+ <member>Do not use an apostrophe in Bachelor of Arts, Master of Science,
etc.</member>
+ <member>Use abbreviations only when the preferred method would be
cumbersome.</member>
+ <member>Use abbreviations only after a full name.</member>
+ <member>Set abbreviations apart with commas.</member>
+ </simplelist>
+ </para>
+ </section>
+ <section
id="sect-documentation_guide-style-quick_reference-abbreviations-dates">
+ <title>Dates</title>
+ <para>
+ <simplelist>
+ <member>Spell out days of the week and separate them from dates using a
comma.</member>
+ <member>When listing a day, month and year, use ISO 8601 dates (YYYY-MM-DD).
Read more about dates and times on the <ulink
url="http://fedoraproject.org/wiki/DocsProject/StyleGuide/DatesAndTi...
page.</member>
+ </simplelist>
+ </para>
+ <para>When listing a day and month:
+ <simplelist>
+ <member>List the day first.</member>
+ <member>Spell out the day.</member>
+ <member>Set the day and month apart with "of."</member>
+ <member>Spell out the month.</member>
+ </simplelist>
+ </para>
+ <para>When listing a month and year:
+ <simplelist>
+ <member>List the month first.</member>
+ <member>Spell out the month.</member>
+ <member>Set the month and year apart with "of."</member>
+ <member>Use Arabic numerals for the year.</member>
+ </simplelist>
+<literallayout>
Sunday, 2000-01-01
2000-01-01
The first of January
January of 2000
-</pre>
-
-==== Times ====
-
-* Use 24-hour time formats.
-* Always use figures.
-* Follow absolute times with a timezone specification.
-* Separate days, hours, minutes and seconds with a colon and no spaces.
-* Separate seconds and fractions thereof with periods.
-* If the scope of a specification is unclear, increase the precision or specify the scope
of the lowest precision.
-* Use Coordinated Universal Time (UTC) for all worldwide events. Refer to the
[
http://fedoraproject.org/wiki/DocsProject/StyleGuide/DatesAndTimes DatesAndTimes] page
for more information about UTC.
-* Localized events may be specified using UTC or the local time, but always specify a
timezone or offset.
-
-<pre>
+</literallayout>
+ </para>
+ </section>
+ <section
id="sect-documentation_guide-style-quick_reference-abbreviations-times">
+ <title>Times</title>
+ <para>
+ <simplelist>
+ <member>Use 24-hour time formats.</member>
+ <member>Always use figures.</member>
+ <member>Follow absolute times with a timezone specification.</member>
+ <member>Separate days, hours, minutes and seconds with a colon and no
spaces.</member>
+ <member>Separate seconds and fractions thereof with periods.</member>
+ <member>If the scope of a specification is unclear, increase the precision or
specify the scope of the lowest precision.</member>
+ <member>Use Coordinated Universal Time (UTC) for all worldwide events. Refer
to the <xref
linkend="sect-documentation_guide-style-dates_and_times-absolute_dates_and_times-absolute_times"
/> section for more information about UTC.</member>
+ <member>Localized events may be specified using UTC or the local time, but
always specify a timezone or offset.</member>
+ </simplelist>
+<literallayout>
15:00 UTC
1:15:00:00.50 (1 day, 15 hours, 0 minutes, 0 seconds and 50/100 of one second)
15:00 minutes (15 minutes)
15:30 hours (15 hours and 30 minutes)
The global conference will take place at 15:00 UTC.
The event will be in Raleigh, NC, and will take place at 11:00 UTC-4.
-</pre>
-
-=== Punctuation ===
-
-==== Periods ====
-
-==== Commas ====
-
-For consistency and to avoid ambiguity, use a serial comma after every item in a list
save the last. This usage is sometimes called the "Harvard comma" or the
"Oxford comma."
-
-<pre>spam, spam, spam, and eggs
-</pre>
-
-Do not use a serial comma in the name of companies such as law firms.
-
-<pre>Dewey, Cheatam & Howe
-</pre>
-
-==== Colons ====
-
-==== Other Punctuation ====
-
-{{Anchor|Lists}}
-=== Lists ===
-
-* Capitalize and use periods when the list items are complete sentences.
-* Make them agree so that there aren't a mixture of sentences and fragments.
-
-You could also have a list with a colon:
-* that was lowercase and not punctuated
-* that again doesn't mix forms
-* that is likely very short
-
-=== Titles ===
-
-* Avoid punctuation in titles, with the exception of hyphens.
-* Avoid abbreviations in titles. Spell words out and introduce abbreviations in the body
text.
-
-=== Units of Measure ===
-
-* Metric units are preferred.
-* Use the prefixes published by the International Electrotechnical Commission (IEC) as
part of IEC 60027-2 A.2 to express quantities of binary data.
-
-=== Markup ===
-
-=== Common Technology Terms ===
-
-* cyberspace
-* database
-* dot-com
-* DSL
-* email
-* FLOSS (free/libre open source software)
-* home page
-* hyperlink
-* hypertext
-* Internet
-* intranet
-* log in (intransitive verb)
-* log into
-* login (noun)
-* online
-* shareware
-* Web (proper noun)
-* webcast
-* webmaster
-* website
-* World Wide Web
-
-=== Denoting trademarks ===
-
-Never use the trademark symbol (™) or the registration mark (®). If for
any reason the Fedora Project is obliged by contract to mention other trademarks in a
legend, add the legend as required by the contract.
-
-In addition, all documentation should contain the disclaimer: "All other trademarks
are the property of their respective owners." This marking is standard in all Fedora
Documentation toolchains at the time of this writing.
-
+</literallayout>
+ </para>
+ </section>
+ </section>
+ <section
id="sect-documentation_guide-style-quick_reference-punctuation">
+ <title>Punctuation</title>
+ <para />
+<!-- <section
id="sect-documentation_guide-style-quick_reference-punctuation-periods">
+ <title>Periods</title>
+ <para />
+ </section>
-->
+ <section
id="sect-documentation_guide-style-quick_reference-punctuation-commas">
+ <title>Commas</title>
+ <para>For consistency and to avoid ambiguity, use a serial comma after every
item in a list save the last. This usage is sometimes called the "Harvard
comma" or the "Oxford comma."
+<literallayout>
+spam, spam, spam, and eggs
+</literallayout> </para>
+ <para>Do not use a serial comma in the name of companies such as law firms.
+<literallayout>
+Dewey, Cheatam & Howe
+</literallayout>
+ </para>
+ </section>
+ </section>
+ <section id="sect-documentation_guide-style-quick_reference-lists">
+ <title>Lists</title>
+ <para>
+ <simplelist>
+ <member>Capitalize and use periods when the list items are complete
sentences.</member>
+ <member>Make them agree so that there aren't a mixture of sentences and
fragments.</member>
+ </simplelist>
+ </para>
+ <para>You could also have a list with a colon:
+ <simplelist>
+ <member>that was lowercase and not punctuated</member>
+ <member>that again doesn't mix forms</member>
+ <member>that is likely very short</member>
+ </simplelist>
+ </para>
+ </section>
+ <section
id="sect-documentation_guide-style-quick_reference-titles">
+ <title>Titles</title>
+ <para>
+ <simplelist>
+ <member>Avoid punctuation in titles, with the exception of
hyphens.</member>
+ <member>Avoid abbreviations in titles. Spell words out and introduce
abbreviations in the body text.</member>
+ </simplelist>
+ </para>
+ </section>
+ <section
id="sect-documentation_guide-style-quick_reference-units_of_measure">
+ <title>Units of Measure</title>
+ <para>
+ <simplelist>
+ <member>Metric units are preferred.</member>
+ <member>Use the prefixes published by the International Electrotechnical
Commission (IEC) as part of IEC 60027-2 A.2 to express quantities of binary
data.</member>
+ </simplelist>
+ </para>
+ </section>
+ <section
id="sect-documentation_guide-style-quick_reference-common_technology_terms">
+ <title>Common Technology Terms</title>
+ <para>
+ <simplelist>
+ <member>cyberspace</member>
+ <member>database</member>
+ <member>dot-com</member>
+ <member>DSL</member>
+ <member>email</member>
+ <member>FLOSS (free/libre open source software)</member>
+ <member>home page</member>
+ <member>hyperlink</member>
+ <member>hypertext</member>
+ <member>Internet</member>
+ <member>intranet</member>
+ <member>log in (intransitive verb)</member>
+ <member>log into</member>
+ <member>login (noun)</member>
+ <member>online</member>
+ <member>shareware</member>
+ <member>Web (proper noun)</member>
+ <member>webcast</member>
+ <member>webmaster</member>
+ <member>website</member>
+ <member>World Wide Web</member>
+ </simplelist>
+ </para>
+ </section>
+ <section
id="sect-documentation_guide-style-quick_reference-denoting_trademarks">
+ <title>Denoting trademarks</title>
+ <para>Never use the trademark symbol (™) or the registration mark
(®). If for any reason the Fedora Project is obliged by contract to mention other
trademarks in a legend, add the legend as required by the contract.</para>
+ <para>In addition, all documentation should contain the disclaimer: "All
other trademarks are the property of their respective owners." This marking is
standard in all Fedora Documentation toolchains at the time of this writing.</para>
+ </section>
</section>
<section id="sect-documentation_guide-style-resources">
<title>Resources</title>