aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml
diff options
context:
space:
mode:
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml')
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml90
1 files changed, 89 insertions, 1 deletions
diff --git a/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml
index c1e9fbde52..fb6746f935 100644
--- a/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml
@@ -27,7 +27,7 @@
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
- $Id: chapter.sgml,v 1.3 1999-07-30 21:09:07 nik Exp $
+ $Id: chapter.sgml,v 1.4 1999-09-03 17:22:43 nik Exp $
-->
<chapter id="writing-style">
@@ -128,6 +128,94 @@
<para>For more information about writing style, see <ulink
url="http://www.columbia.edu/acis/bartleby/strunk/">Elements of
Style</ulink>, by William Strunk.</para>
+
+ <sect1>
+ <title>Style guide</title>
+
+ <para>To keep the source for the Handbook consistent when many different
+ people are editing it, please follow these style conventions.</para>
+
+ <sect2>
+ <title>Letter case</title>
+
+ <para>Tags are entered in lower case, <literal>&lt;para&gt;</literal>,
+ <emphasis>not</emphasis> <literal>&lt;PARA&gt;</literal>.</para>
+
+ <para>Text that appears in SGML contexts is generally written in upper
+ case, <literal>&lt!ENTITY&hellip;&gt;</literal>, and
+ <literal>&lt;!DOCTYPE&hellip;&gt;</literal>, <emphasis>not</emphasis>
+ <literal>&lt;!entity&hellip;&gt;</literal> and
+ <literal>&lt;!doctype&hellip;&gt;</literal>.</para>
+ </sect2>
+
+ <sect2>
+ <title>Indentation</title>
+
+ <para>Each file starts with indentation set at column 0,
+ <emphasis>regardless</emphasis> of the indentation level of the file
+ which might contain this one.</para>
+
+ <para>Every start tag increases the indentation level by 2 spaces, and
+ every end tag decreases the indentation level by 2 spaces. Content
+ within elements should be indented by two spaces if the content runs
+ over more than one line.</para>
+
+ <para>For example, the source for this section looks something
+ like;</para>
+
+ <programlisting>
+<![ CDATA [+--- This is column 0
+V
+<chapter>
+ <title>...</title>
+
+ <sect1>
+ <title>...</title>
+
+ <sect2>
+ <title>Indentation</title>
+
+ <para>Each file starts with indentation set at column 0,
+ <emphasis>regardless</emphasis> of the indentation level of the file
+ which might contain this one.</para>
+
+ <para>Every start tag increases the indentation level by 2 spaces, and
+ every end tag decreases the indentation level by 2 spaces. Content
+ within elements should be indented by two spaces if the content runs
+ over more than one line.</para>
+
+ ...
+ </sect2>
+ </sect1>
+</chapter>]]></programlisting>
+
+ <para>If you use <application>Emacs</application> or
+ <application>Xemacs</application> to edit the files then
+ <literal>sgml-mode</literal> should be loaded automatically, and the
+ Emacs local variables at the bottom of each file should enforce these
+ styles.</para>
+ </sect2>
+
+ <sect2>
+ <title>White space changes</title>
+
+ <para>When committing changes, <emphasis>do not commit changes to the
+ content at the same time as changes to the
+ formatting</emphasis>.</para>
+
+ <para>This is so that the teams that convert the Handbook to other
+ languages can quickly see what content has actually changed in your
+ commit, without having to decide whether a line has changed because of
+ the content, or just because it has been refilled.</para>
+
+ <para>For example, if you have added two sentances to a paragraph, such
+ that the line lengths on the paragraph now go over 80 columns, first
+ commit your change with the too-long line lengths. Then fix the line
+ wrapping, and commit this second change. In the commit message for
+ the second change, be sure to indicate that this is a whitespace-only
+ change, and that the translation team can ignore it.</para>
+ </sect2>
+ </sect1>
</chapter>
<!--