[open-ils-commits] r14001 - trunk/docs/1.6/styleguide (kgs)

[svn at svn.open-ils.org]

Author: kgs
Date: 2009-09-09 16:34:34 -0400 (Wed, 09 Sep 2009)
New Revision: 14001

Added:
   trunk/docs/1.6/styleguide/admon.xml
Log:
Adding first of a series of files to the styleguide section.

Added: trunk/docs/1.6/styleguide/admon.xml
===================================================================
--- trunk/docs/1.6/styleguide/admon.xml	                        (rev 0)
+++ trunk/docs/1.6/styleguide/admon.xml	2009-09-09 20:34:34 UTC (rev 14001)
@@ -0,0 +1,104 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
+  xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="admonitions">
+  <title>Admonitions</title>
+  <section>
+    <title>Overview</title>
+    <para>Admonitions are pieces of text that are offset from the main flow of text. They include
+      things like warnings, notes, and tips. They should be used sparingly because they interrupt
+      the flow of the text. However, if you think one is needed, use one.</para>
+    <para>As a general rule, warnings and notes are the <emphasis role="bold">preferred</emphasis>
+      admonitions in Evergreen' documentation. That does not mean the use of the other types are
+      prohibited. It only means that they should be used with caution.</para>
+  </section>
+  <section xml:id="warn">
+    <title>Warnings</title>
+    <simplesect>
+      <title>Overview</title>
+      <para>Warnings are used to call out instances where a serious loss of data could occur. The
+        text of the warning should make it clear what will cause the data loss and what data is at
+        risk. For example, if using a value greater than 1 million will cause a method invocation to
+        return garbage, use a warning to mention this.</para>
+    </simplesect>
+    <simplesect>
+      <title>Markup</title>
+      <para>Warnings are marked up using a <tag class="element">warning</tag> element. The <tag
+          class="element">warning</tag> element should contain a single <tag class="element"
+          >para</tag> element that contains the text for the warning.</para>
+      <para>The <tag class="element">warning</tag> element can, however, contain more than one
+        paragraph, a code listing, or a table. These are exceptions that are to be used
+        sparingly.</para>
+    </simplesect>
+  </section>
+  <section xml:id="note">
+    <title>Notes</title>
+    <simplesect>
+      <title>Overview</title>
+      <para>Notes are used to call out information that the reader should be aware of, but is
+        ancillary to the topic being discussed in the main flow of the text.</para>
+    </simplesect>
+    <simplesect>
+      <title>Markup</title>
+      <para>Notes are marked up using a <tag class="element">note</tag> element. Like the <tag
+          class="element">warning</tag> element, the <tag class="element">note</tag> element should
+        contain a single <tag class="element">para</tag> element that contains the text for the
+        warning. The <tag class="element">note</tag> element can also contain more than one
+        paragraph, a code listing, or a table.</para>
+    </simplesect>
+  </section>
+  <section xml:id="caution">
+    <title>Cautions</title>
+    <simplesect>
+      <title>Overview</title>
+      <para>Cautions are intended for use when a <link linkend="warn">warning</link> is too strong.
+        For example, a caution may be used when an action will potentially cause a service to return
+        an exception, but not crash or result in any loss of critical data. In general, it is best
+        to use a <link linkend="warn">warning</link>.</para>
+    </simplesect>
+    <simplesect>
+      <title>Markup</title>
+      <para>Cautions are marked up using the <tag class="element">caution</tag> element. As with
+        warnings elements, the <tag class="element">caution</tag> element should contain only a
+        single <tag class="element">para</tag> element.</para>
+    </simplesect>
+  </section>
+  <section xml:id="important">
+    <title>Important Notes</title>
+    <simplesect>
+      <title>Overview</title>
+      <para>Important notes are used to point out information that is important for the user to
+        know, but that may not be obvious. For example, if you change a value in a context and the
+        new value overrides a transport setting for the service. Or if the new value persists for
+        all future uses of the context.</para>
+    </simplesect>
+    <simplesect>
+      <title>Markup</title>
+      <para>Important notes are marked up using the <tag class="element">important</tag> element.
+        The <tag class="element">important</tag> element should contain only a single <tag
+          class="element">para</tag> element. However, it is allowable to use other block elements
+        in an important note.</para>
+    </simplesect>
+  </section>
+  <section xml:id="tip">
+    <title>Tips</title>
+    <simplesect>
+      <title>Overview</title>
+      <para>Tips are bits of information that may help a user be more productive, but that are not
+        critical to using the product. In general, this type of information should either be worked
+        directly into the text or placed in a <link linkend="note">note</link>.</para>
+    </simplesect>
+    <simplesect>
+      <title>Markup</title>
+      <para>Tips are marked up using the <tag class="element">tip</tag> element. The <tag
+          class="element">tip</tag> element should contain only a single <tag class="element"
+          >para</tag> element. However, it is allowable to use other block elements in a tip.</para>
+    </simplesect>
+  </section>
+  <section>
+    <title>Footnotes</title>
+    <simplesect>
+      <title>Overview</title>
+      <para>Footnotes are not used in Evergreen documentation. </para>
+    </simplesect>
+  </section>
+</chapter>