Adding first of a series of files to the styleguide section.

git-svn-id: svn://svn.open-ils.org/ILS/trunk@14001 dcc99617-32d9-48b4-a31d-7c20da2025e4

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