From d8e057fd62d48909f5023dac929214982b5d1c49 Mon Sep 17 00:00:00 2001 From: kgs Date: Wed, 9 Sep 2009 20:34:34 +0000 Subject: [PATCH] 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 --- docs/1.6/styleguide/admon.xml | 104 ++++++++++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) create mode 100644 docs/1.6/styleguide/admon.xml diff --git a/docs/1.6/styleguide/admon.xml b/docs/1.6/styleguide/admon.xml new file mode 100644 index 0000000000..53a1a30aac --- /dev/null +++ b/docs/1.6/styleguide/admon.xml @@ -0,0 +1,104 @@ + + + Admonitions +
+ Overview + 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. + As a general rule, warnings and notes are the preferred + 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. +
+
+ Warnings + + Overview + 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. + + + Markup + Warnings are marked up using a warning element. The warning element should contain a single para element that contains the text for the warning. + The warning element can, however, contain more than one + paragraph, a code listing, or a table. These are exceptions that are to be used + sparingly. + +
+
+ Notes + + Overview + 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. + + + Markup + Notes are marked up using a note element. Like the warning element, the note element should + contain a single para element that contains the text for the + warning. The note element can also contain more than one + paragraph, a code listing, or a table. + +
+
+ Cautions + + Overview + Cautions are intended for use when a warning 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 warning. + + + Markup + Cautions are marked up using the caution element. As with + warnings elements, the caution element should contain only a + single para element. + +
+
+ Important Notes + + Overview + 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. + + + Markup + Important notes are marked up using the important element. + The important element should contain only a single para element. However, it is allowable to use other block elements + in an important note. + +
+
+ Tips + + Overview + 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 note. + + + Markup + Tips are marked up using the tip element. The tip element should contain only a single para element. However, it is allowable to use other block elements in a tip. + +
+
+ Footnotes + + Overview + Footnotes are not used in Evergreen documentation. + +
+ -- 2.43.2