[open-ils-commits] r14001 - trunk/docs/1.6/styleguide (kgs)
svn at svn.open-ils.org
svn at svn.open-ils.org
Wed Sep 9 16:34:39 EDT 2009
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>
More information about the open-ils-commits
mailing list