From f2707b16c24228ddbe5f20038a80025bde45b1a1 Mon Sep 17 00:00:00 2001 From: Robert Soulliere Date: Tue, 19 Oct 2010 08:02:44 -0400 Subject: [PATCH] Add DocBook style guide from Jeremy Buhler. --- style_guide/glossary.xml | 597 +++++++++++++++++++++++++++++++++++++++ style_guide/image.xml | 104 +++++++ style_guide/links.xml | 61 ++++ style_guide/pi.xml | 63 +++++ style_guide/root.xml | 42 +++ style_guide/tips.xml | 41 +++ 6 files changed, 908 insertions(+) create mode 100644 style_guide/glossary.xml create mode 100644 style_guide/image.xml create mode 100644 style_guide/links.xml create mode 100644 style_guide/pi.xml create mode 100644 style_guide/root.xml create mode 100644 style_guide/tips.xml diff --git a/style_guide/glossary.xml b/style_guide/glossary.xml new file mode 100644 index 0000000000..ccd9243981 --- /dev/null +++ b/style_guide/glossary.xml @@ -0,0 +1,597 @@ + + + + DIG DocBook reference + +
+ + Elements + + Below is a non-exhaustive list of DocBook elements used in Evergreen documentation. + Authors may use other elements but are encouraged to draw from this list first. Each + term links to the authoritative DocBook 5 reference pages at http://www.docbook.org/tdg5/en/html/part2.html. + + + <glossentry xml:id="section"> + <glossterm> + <link xlink:href="http://www.docbook.org/tdg5/en/html/section.html" + >section</link> + </glossterm> + <glossdef> + <para>A titled subdivision of a <markup linkend="chapter">chapter</markup>, only + required if a chapter has two or more sections. Sections appear in TOC and + have their own pages in HTML output (use <markup linkend="simplesect" + >simplesect</markup> to exclude from TOC). The <markup linkend="xmlid" + >xml:id</markup> attribute is optional and can be applied ad hoc when + linking to a section.</para> + <para>The section element can be nested to + create subsections. Here are some examples used in <emphasis>The Book of Evergreen</emphasis>: </para> + <itemizedlist> + <listitem> + <para><emphasis>section -> section</emphasis> (for a section and + subsection, both appearing in TOC)</para> + </listitem> + <listitem> + <para><emphasis>section -> simplesect</emphasis> (for a section and + subsection, w/ only the top level in the TOC)</para> + </listitem> + <listitem> + <para><emphasis>section -> section -> simplesect</emphasis> (for a + section, subsection, and sub-subsection, with the top 2 in the + TOC))</para> + </listitem> + </itemizedlist> + </glossdef></glossentry> + <glossentry xml:id="xref"> + <glossterm> + <link xlink:href="http://www.docbook.org/tdg5/en/html/xref.html">xref</link> + </glossterm> + <glossdef> + <para>A cross reference to another part of the document (use <markup + linkend="link">link</markup> for external links). The destination is set + with the <markup linkend="linkend">linkend</markup> attribute, which matches + the <markup linkend="xmlid">xml:id</markup> of the destination element. Link + text is auto-generated.</para> + <para><application>oXygen</application> returns a validation error if the link + destination is in another xml file; this is resolved when the files are + assembled for publication and can be ignored.</para> + </glossdef></glossentry> + <glossentry xml:id="guimenu"> + <glossterm> + <link xlink:href="http://www.docbook.org/tdg5/en/html/guimenu.html" + >guimenu</link> + </glossterm> + <glossdef> + <para>Use for the names of staff client menus; formatted in italics.</para> + </glossdef></glossentry> + <glossentry xml:id="menuchoice"> + <glossterm> + <link xlink:href="http://www.docbook.org/tdg5/en/html/menuchoice.html" + >menuchoice</link> + </glossterm> + <glossdef> + <para>Use to describe a menu selection. Usually contains <markup + linkend="guimenu">guimenu</markup> and <markup linkend="guimenuitem" + >guimenitiem</markup> elements (may also contain <markup + linkend="guisubmenu">guisubmenu</markup>). Output displays an arrow + between each child element. <programlisting><![CDATA[ + <para>To clear the staff client cache go to + <menuchoice> + <guimenu>Admin</guimenu> + <guisubmenu>For developers</guisubmenu> + <guisubmenuitem>Clear Cache</guisubmenuitem> + </menuchoice> + </para>]]> + + </programlisting> displays as <informalexample> + <para>To clear the staff client cache go to <menuchoice> + <guimenu>Admin</guimenu> + <guisubmenu>For developers</guisubmenu> + <guimenuitem>Clear Cache</guimenuitem> + </menuchoice> + </para> + </informalexample></para> + </glossdef></glossentry> + <glossentry xml:id="guimenuitem"> + <glossterm> + <link xlink:href="http://www.docbook.org/tdg5/en/html/guimenuitem.html" + >guimenuitem</link> + </glossterm> + <glossdef> + <para>An option in a staff client menu or submenu; formatted in italics.</para> + </glossdef></glossentry> + <glossentry xml:id="guibutton"> + <glossterm> + <link xlink:href="http://www.docbook.org/tdg5/en/html/guibutton.html" + >guibutton</link> + </glossterm> + <glossdef> + <para>A button in the staff client. Currently formatted with italics, though this can be changed in the stylesheets.<programlisting><![CDATA[ +<para>Click <guibutton>Modify Copies</guibutton> to save your changes</para>]]> + + </programlisting> + displays as<informalexample> + <para>Click <guibutton>Modify Copies</guibutton> to save your + changes</para> + </informalexample></para> + </glossdef></glossentry> + <glossentry xml:id="informalfigure"> + <glossterm> + <link xlink:href="http://www.docbook.org/tdg5/en/html/informalfigure.html" + >informalfigure</link> + </glossterm> + <glossdef> + <para>A wrapper for a <markup>mediaobject</markup> and optional + associated text. Stylesheet customizations ensure the contents of an informfigure are kept together during PDF pagination. The + <markup linkend="step">step</markup> in the following example will not + split across a page break: <programlisting> <![CDATA[ +<step> + <informalfigure> + <para>STEP TEXT GOES HERE</para> + <mediaobject> + <alt>OPTIONAL DESCRIPTION OF IMAGE</alt> + <imageobject> + <imagedata scalefit="0" fileref="media/FILENAME_HERE.png"/> + </imageobject> + </mediaobject> + </informalfigure> +</step>]]> + + </programlisting></para> + </glossdef></glossentry> + <glossentry xml:id="figure"> + <glossterm> + <link xlink:href="http://www.docbook.org/tdg5/en/html/figure.html">figure</link> + </glossterm> + <glossdef> + <para>Wrapper for a <markup linkend="mediaobject">mediaobject</markup> that has + a title and appears in list of figures (in the book's front matter). Content in <markup + linkend="figure">figure</markup> and <markup linkend="informalfigure" + >informalfigure</markup> is not split across PDF page breaks.</para> + </glossdef></glossentry> + <glossentry xml:id="example"> + <glossterm> + <link xlink:href="http://www.docbook.org/tdg5/en/html/example.html" + >example</link> + </glossterm> + <glossdef> + <para>An example with a title.</para> + </glossdef></glossentry> + <glossentry xml:id="informalexample"> + <glossterm> + <link xlink:href="http://www.docbook.org/tdg5/en/html/informalexample.html" + >informalexample</link> + </glossterm> + <glossdef> + <para>An example with no title.</para> + </glossdef></glossentry> + <glossentry xml:id="formalpara"> + <glossterm> + <link xlink:href="http://www.docbook.org/tdg5/en/html/formalpara.html" + >formalpara</link> + </glossterm> + <glossdef> + <para>A titled paragraph. The following <programlisting><![CDATA[ +<formalpara> + <title>Paragraph title + Paragraph body... +]]> + + + displays as + + Paragraph title + Paragraph body... + + + + + + mediaobject + + + A wrapper for imageobjects. May be wrapped in an + informalfigure to keep image and text together across page breaks. See for more + on image formatting. + + + + alt + + + Metadata describing an element, usually for accessibility. For example, each mediaobject may contain an + alt element with a generic description of the + image content. + + + + imageobject + + + Contained by mediaobject and a + wrapper for imagedata. See for more on + image formatting in The Book of Evergreen. + + + + imagedata + + + Contained by imageobject, its + attributes determine sizing, scaling, alignment, and source file. See for more on Sitka image formatting. + + + + guilabel + + + Use for labels and titles in the staff client. Where applicable guimenu, guimenuitem, and guibutton are preferred. HTML is formatted in italics, PDF is + not formatted. + + + + guisubmenu + + + A staff client submenu. Used when a submenu is part of a menuchoice sequence. Not italicized. + + + + + keycap + + + The label on a keyboard button; formatted in bold (eg Press + F5). + + + + keycap + + + For a combination of two or more keystrokes, wrap keycap elements in a keycombo. Format is bold with a + between + keystrokes. Open a new tab with + + Ctrl + T + + ]]> + + displays as + Open a new tab with + Ctrl + T + + + + + + + application + + + The name of a software program or application such as + Evergreen. Currently not formatted, but + consistent use would allow for future batch formatting (e.g. italicize content of all application tags). + + + + emphasis + + + Use to italicize regular text. Use with the ROLE attribute for bold text + For italic and bold output. +]]> + + displays as + For italic and bold output. + + + + + + tip + + + Enclose tip text and images in this element for consistent formatting. + Display options are set with CSS and XSL stylesheets and include custom tip + text, icons, formatting, etc. + + + Tip text goes here + ]]> + + displays as + + Tip text goes here + + + + + + + + glossary + + + Wrapper for a glossary. Must contain title element (to hide the title in published + output use an empty ]]> tag). + + + + glossentry + + + Wrapper for each glossary entry. Should always have an xml:id for cross referencing. Entries are + sorted alphabetically in published output, regardless of order in xml source + document (this is optional and is set with stylesheet parameters). Full glossentry markup including child elements is shown below: + guisubmenu + + A staff client submenu. Used primarily when a submenu is part + of a menuchoice sequence. Not italicized. + + +]]> + + + + + + glossterm + + + Wrapper for the term in a glossentry. + + + + glosssee + + + A "see" link that points from one glossentry to another. Always has an otherterm attribute that corresponds to the + xml:id of the referenced term. + + + + glossseealso + + + A "see also" link that points from one glossentry to another. Always has an otherterm attribute corresponds to the + xml:id of the referenced term. + + + + itemizedlist + + + A bulleted list with an optional title. + + + + orderedlist + + + A numbered list with an optional title. + + + + listitem + + + Wrapper for individual entries on an itemizedlist or orderedlist. + + + + programlisting + + + When used with , text in a + programlisting is published exactly as it appears in the xml file (including + line breaks and white space). Formatted as a block with a shaded background, + used only for coding examples (see + /style/style_glossary.xml for syntax example). + + + + + link + + + For external links. Must have an xlink:href attribute with the destination URL. In PDF output + the full URL is printed in brackts after the link text. + + + + procedure + + + A multi-step process consisting of two or more steps. Applies to most converted Sitka docs. + step + + + + step + + + Component part of a procedure. Steps + are auto-numbered and may contain text, figures, examples, etc. The xml:id attribute is optional and only required + if linking to a particular step. To keep step content together during + pagination (eg text w/ associated image), use informalfigure. + + + + para + + + A paragraph; a required wrapper for text in most contexts. + + + + info + + + A wrapper for metadata about an element, including title. + + + + book + + + The top level element for Evergreen documentation, appears only in the file + root.xml + + + + part + + + A subdivision of a book. Used only in + root.xml; each part should have a title and xml:id. + + + + + chapter + + + A subdivision of a part, further divided + into sections. In Evergreen documentation each chapter + is a separate xml file referenced by root.xml. Each chapter should + have an xml:id. The xml:id is required for cross-referencing and stable links to published html files. If there is no xml:id the generated html files names may change as content is added or re-located. + + + + title + + + Sets the title for the element which contains it. Required in + chapters and sections. + + + + + date + + + Wrapper for date info in any context. Mandatory component of chapter + revision entries. Format is YYYY-MM-DD + + + + + authorinitials + + + An author's initials, mandatory componenet of the chapter revision element. + + + + simplesect + + A subdivision of a section that does + not appear in the TOC. A simplesect is terminal, i.e. cannot be further + subdivided with section or simplesect elements. + + +
+
+ Attributes + DocBook elements can be modified by one or more attributes. The attibutes below are commonly used in The Book of Evergreen. More info on DocBook 5 attributes is available at http://www.docbook.org/tdg5/en/html/ref-elements.html#common.attributes + + + Attributes + + + + xml:id + + + Optional xml identifier for an element, required for cross references and + linking. Must be unique within the entire documentation set. Good practice is to make sure that, at minimum, all + book, part, chapter, and glossentry elements have an + xml:id. In html output, the xml:id becomes the name the html file and the URL for that segment of the documentation (if there is no xml:id, the html file is auto-numbered). + + + + + linkend + + + Attribute that sets the link destination. Any DocBook 5 inline + element can become a link by adding a linkend attribute that corresponds to the + xml:id of the destination. See + for more detailed info. + + + + otherterm + + + Applied exclusively to glosssee and + glossseealso elements, it points + to the referenced glossary term. ]]>displays as See also date. + + + + role + + + ParaApplied to + para tags to track changes to draft + docs for approval by other editors. Can have value of + added, deleted, or + changed; in html output will be highlighted in + green, red, and yellow + respectively. + + + +
+ diff --git a/style_guide/image.xml b/style_guide/image.xml new file mode 100644 index 0000000000..17c5fd038b --- /dev/null +++ b/style_guide/image.xml @@ -0,0 +1,104 @@ + + + + + Image Formatting + + + + + .png is the preferred image format, though .jpg from legacy conversions are + acceptable + + + Images are stored in media directories for each part. + + + Images up to 900px wide can be displayed without resizing. Images larger than + 900px are scaled down with the scalefit="1" attribute as shown + below. + + + When scaling DocBook uses both the size (pixels) and resolution (dpi or pixels/in) + of image files. Source images should be at 96dpi, a default chosen to match legacy + images. 96dpi seems to be standard in FullShot; if using Gimp change the default for + new images from 72 pixels/in to 96 pixels/in under + File + Preferences + Default Image + + + + + + Images 900px wide or less + If the source image is 900px wide or less use the following code + + OPTIONAL DESCRIPTION OF IMAGE + + + + ]]> + + + In HTML output, the image will display at actual size; in PDF it will be scaled down + to 75% (scale percentage set in + ~/stylesheets/sitka_fo_graphics.xsl). + + + + + Images wider than 900px + If the source image is wider than 900px use the following code + + OPTIONAL DESCRIPTION OF IMAGE + + + + ]]> + + + In HTML the image will scale down to 900px width + (default.image.width setting in + ~/stylesheets/sitka_xhtml.xsl). In PDF it will scale down to + page width. + + + Wrap the mediaobject tag in a para to + add a small space between the image and preceding content. + + + + + Keeping image and text together + Content wrapped in any formal or informal object (eg informalfigure, + formalfigure, informalexample, formalexample) is kept together on the + same page in pdf output. Use informalfigure to keep an image with + associated text, as in this example of a step:. + + + STEP TEXT HERE + + + OPTIONAL DESCRIPTION OF IMAGE + + + + + + + ]]> + + + + + + + + + diff --git a/style_guide/links.xml b/style_guide/links.xml new file mode 100644 index 0000000000..b44ab6684e --- /dev/null +++ b/style_guide/links.xml @@ -0,0 +1,61 @@ + + + + + + Creating Links + + +There are many way to link w/ docbook but the options in the table below cover the most common documentation scenarios. + + + + + + + + + Linking scenario + Syntax + Output + Notes + + + + + + + + + Internal link with auto-generated link text + ]]> + + + + The linkend value (style-glossary) is the xml:id of + the target element; link text is auto-generated from the target. The tag is + self-closing (no ]]> closing tag required> + + + Internal link with custom link text + The DIG glossary page ]]> + The DIG glossary page + linkend is the xml:id of the target element; link text is supplied by author + + + External link + http://evergreen-ils.org/ ]]> + http://evergreen-ils.org/ + xlink:href is the target URL. It is good practice to show full URL so users can see it in PDF or copy and paste from pages displayed in the staff client (to open in a separate browser) + + + + + + + + For internal links the hover tip text is generated automatically; for external links please include an xlink:title, otherwise the link hover text will be the name of the section or chapter where the link appears. + + + diff --git a/style_guide/pi.xml b/style_guide/pi.xml new file mode 100644 index 0000000000..664b745b44 --- /dev/null +++ b/style_guide/pi.xml @@ -0,0 +1,63 @@ + + + + Processing instructions + + + Processing instructions (PIs) are written into the xml when the desired output cannot be + achieved with DocBook elements and attributes alone. PIs may also be used to force special + formatting in only part of a document. For a more technical introduction see Bob Stayton's + DocBook + XSL: The Complete Guide. There are also lists of DocBook-specific processing + instructions for html and pdf output. + + PIs should be used sparingly: it is easier to maintain documents that achieve the desired + output with DocBook elements and stylesheet parameters. However, there are a few cases where PIs may be + necessary: + + + + + Force line break + Line breaks should not be used for spacing between elements; this is much + better done with CSS and XSL. Hoever, if entering multiple lines that must be + displayed in succession but without the separation of a new paragraph, you may + use the linebreak PI. The following code + + + First line Second line Third line]]> + + Will output + First line Second line Third line + + This only works if + custom stylesheets include the following code, described in Bob Stayton's + DocBook XSL. Sitka's customization layer includes this template as of June + 30, 2010: + + + + ]]> + + + + + Include external contentTo insert external content into the html output use the dbhtml-include processing instruction as described in DocBook XSL. + This could be used to add a custom search box to the title page, an animated tutorial in the relevant section, or any other content in valid xhtml. + + + + diff --git a/style_guide/root.xml b/style_guide/root.xml new file mode 100644 index 0000000000..dc27c663e3 --- /dev/null +++ b/style_guide/root.xml @@ -0,0 +1,42 @@ + + + + DIG/Evergreen DocBook Style Guide + + + + + 2010 + Evergreen Community + + + + + + + + + + + This document was updated October 18, 2010. + + + + + + + + + + + + + + + + diff --git a/style_guide/tips.xml b/style_guide/tips.xml new file mode 100644 index 0000000000..3e2a4111fd --- /dev/null +++ b/style_guide/tips.xml @@ -0,0 +1,41 @@ + + + + + + Miscellaneous Tips + + + + + Table column width + + If column width is not specified in the XML, tables will look different depending on + the output format. In HTML the columns automatically adjust to fit contents, but in PDF + the page width is divided evenly by the number of columns. This often wastes space in + PDF tables so setting relative column widths for all tables is recommended. + In the example below, the colwidth parameter defines relative + column width. Columns 1 and 2 are of equal width, each using a quarter of the page. + Column 3 is twice the size and covers the remaining half of the page. + + + Title of Table Here + + + + ]]> + + + + For details see DocBook XSL: The + Complete Guide. + + + + + + -- 2.43.2