svn commit: r44192 - head/en_US.ISO8859-1/books/fdp-primer/writing-style

[Warren Block]

Author: wblock
Date: Sat Mar  8 00:15:43 2014
New Revision: 44192
URL: http://svnweb.freebsd.org/changeset/doc/44192

Log:
  Add non-trivial indentation examples and an example of moving an element
  to the next line to improve readability.

Modified:
  head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml

Modified: head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml	Fri Mar  7 22:02:49 2014	(r44191)
+++ head/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml	Sat Mar  8 00:15:43 2014	(r44192)
@@ -325,6 +325,33 @@
   <tag class="endtag">sect1</tag>
 <tag class="endtag">chapter</tag></programlisting>
 
+      <para>Tags containing long attributes follow the same
+	rules.  Following the indentation rules in this case helps
+	editors and writers see which content is inside the
+	tags:</para>
+
+      <programlisting><tag class="starttag">para</tag>See the <tag class="starttag">link
+    linkend="gmirror-troubleshooting"</tag>Troubleshooting<tag class="endtag">link</tag>
+  section if there are problems booting.  Powering down and
+  disconnecting the original <tag class="starttag">filename</tag>ada0<tag class="endtag">filename</tag> disk
+  will allow it to be kept as an offline backup.<tag class="endtag">para</tag>
+
+<tag class="starttag">para</tag>It is also possible to journal the boot disk of a &os;
+  system.  Refer to the article <tag class="starttag">link
+    xlink:href="&url.articles.gjournal-desktop;"</tag>Implementing UFS
+    Journaling on a Desktop PC<tag class="endtag">link</tag> for detailed
+  instructions.<tag class="endtag">para</tag>></programlisting>
+
+      <para>When an element is too long to fit on the remainder of a
+	line without wrapping, moving the start tag to the next line
+	can make the source easier to read.  In this example, the
+	<literal>systemitem</literal> element has been moved to the
+	next line to avoid wrapping and indenting:</para>
+
+      <programlisting><tag class="starttag">para</tag>With file flags, even
+  <tag class="starttag">systemitem class="username"</tag>root<tag class="endtag">systemitem</tag> can be
+  prevented from removing or altering files.<tag class="endtag">para</tag></programlisting>
+
       <para>Configurations to help various text editors conform to
 	these guidelines can be found in
 	<xref linkend="editor-config"/>.</para>