docs/1.6/admon.xml

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"\r
   3   xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="admonitions">\r
   4   <title>Admonitions</title>\r
   5   <section>\r
   6     <title>Overview</title>\r
   7     <para>Admonitions are pieces of text that are offset from the main flow of text. They include\r
   8       things like warnings, notes, and tips. They should be used sparingly because they interrupt\r
   9       the flow of the text. However, if you think one is needed, use one.</para>\r
  10     <para>As a general rule, warnings and notes are the <emphasis role="bold">preferred</emphasis>\r
  11       admonitions in Evergreen' documentation. That does not mean the use of the other types are\r
  12       prohibited. It only means that they should be used with caution.</para>\r
  13   </section>\r
  14   <section xml:id="warn">\r
  15     <title>Warnings</title>\r
  16     <simplesect>\r
  17       <title>Overview</title>\r
  18       <para>Warnings are used to call out instances where a serious loss of data could occur. The\r
  19         text of the warning should make it clear what will cause the data loss and what data is at\r
  20         risk. For example, if using a value greater than 1 million will cause a method invocation to\r
  21         return garbage, use a warning to mention this.</para>\r
  22     </simplesect>\r
  23     <simplesect>\r
  24       <title>Markup</title>\r
  25       <para>Warnings are marked up using a <tag class="element">warning</tag> element. The <tag\r
  26           class="element">warning</tag> element should contain a single <tag class="element"\r
  27           >para</tag> element that contains the text for the warning.</para>\r
  28       <para>The <tag class="element">warning</tag> element can, however, contain more than one\r
  29         paragraph, a code listing, or a table. These are exceptions that are to be used\r
  30         sparingly.</para>\r
  31     </simplesect>\r
  32   </section>\r
  33   <section xml:id="note">\r
  34     <title>Notes</title>\r
  35     <simplesect>\r
  36       <title>Overview</title>\r
  37       <para>Notes are used to call out information that the reader should be aware of, but is\r
  38         ancillary to the topic being discussed in the main flow of the text.</para>\r
  39     </simplesect>\r
  40     <simplesect>\r
  41       <title>Markup</title>\r
  42       <para>Notes are marked up using a <tag class="element">note</tag> element. Like the <tag\r
  43           class="element">warning</tag> element, the <tag class="element">note</tag> element should\r
  44         contain a single <tag class="element">para</tag> element that contains the text for the\r
  45         warning. The <tag class="element">note</tag> element can also contain more than one\r
  46         paragraph, a code listing, or a table.</para>\r
  47     </simplesect>\r
  48   </section>\r
  49   <section xml:id="caution">\r
  50     <title>Cautions</title>\r
  51     <simplesect>\r
  52       <title>Overview</title>\r
  53       <para>Cautions are intended for use when a <link linkend="warn">warning</link> is too strong.\r
  54         For example, a caution may be used when an action will potentially cause a service to return\r
  55         an exception, but not crash or result in any loss of critical data. In general, it is best\r
  56         to use a <link linkend="warn">warning</link>.</para>\r
  57     </simplesect>\r
  58     <simplesect>\r
  59       <title>Markup</title>\r
  60       <para>Cautions are marked up using the <tag class="element">caution</tag> element. As with\r
  61         warnings elements, the <tag class="element">caution</tag> element should contain only a\r
  62         single <tag class="element">para</tag> element.</para>\r
  63     </simplesect>\r
  64   </section>\r
  65   <section xml:id="important">\r
  66     <title>Important Notes</title>\r
  67     <simplesect>\r
  68       <title>Overview</title>\r
  69       <para>Important notes are used to point out information that is important for the user to\r
  70         know, but that may not be obvious. For example, if you change a value in a context and the\r
  71         new value overrides a transport setting for the service. Or if the new value persists for\r
  72         all future uses of the context.</para>\r
  73     </simplesect>\r
  74     <simplesect>\r
  75       <title>Markup</title>\r
  76       <para>Important notes are marked up using the <tag class="element">important</tag> element.\r
  77         The <tag class="element">important</tag> element should contain only a single <tag\r
  78           class="element">para</tag> element. However, it is allowable to use other block elements\r
  79         in an important note.</para>\r
  80     </simplesect>\r
  81   </section>\r
  82   <section xml:id="tip">\r
  83     <title>Tips</title>\r
  84     <simplesect>\r
  85       <title>Overview</title>\r
  86       <para>Tips are bits of information that may help a user be more productive, but that are not\r
  87         critical to using the product. In general, this type of information should either be worked\r
  88         directly into the text or placed in a <link linkend="note">note</link>.</para>\r
  89     </simplesect>\r
  90     <simplesect>\r
  91       <title>Markup</title>\r
  92       <para>Tips are marked up using the <tag class="element">tip</tag> element. The <tag\r
  93           class="element">tip</tag> element should contain only a single <tag class="element"\r
  94           >para</tag> element. However, it is allowable to use other block elements in a tip.</para>\r
  95     </simplesect>\r
  96   </section>\r
  97   <section>\r
  98     <title>Footnotes</title>\r
  99     <simplesect>\r
 100       <title>Overview</title>\r
 101       <para>Footnotes are not used in Evergreen documentation. </para>\r
 102     </simplesect>\r
 103   </section>\r
 104 </chapter>\r