diff options
Diffstat (limited to 'en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml')
| -rw-r--r-- | en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml | 90 |
1 files changed, 89 insertions, 1 deletions
diff --git a/en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml index c1e9fbde52..fb6746f935 100644 --- a/en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml +++ b/en_US.ISO_8859-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><para></literal>, + <emphasis>not</emphasis> <literal><PARA></literal>.</para> + + <para>Text that appears in SGML contexts is generally written in upper + case, <literal><!ENTITY…></literal>, and + <literal><!DOCTYPE…></literal>, <emphasis>not</emphasis> + <literal><!entity…></literal> and + <literal><!doctype…></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> <!-- |