From 54291eae7ac26dc1f0724ce1577755608609f13f Mon Sep 17 00:00:00 2001 From: kgs Date: Wed, 9 Sep 2009 19:51:08 +0000 Subject: [PATCH] Checked into the wrong repository, removing. git-svn-id: svn://svn.open-ils.org/ILS-Contrib/evergreen-ils.org@678 6d9bc8c9-1ec2-4278-b937-99fde70a366f --- docs/styleguide/admon.xml | 104 ----- docs/styleguide/authoring.xml | 93 ----- docs/styleguide/books.xml | 256 ------------- docs/styleguide/build.xml | 37 -- docs/styleguide/chapter.xml | 117 ------ docs/styleguide/conditional.xml | 203 ---------- docs/styleguide/exclude.xml | 370 ------------------ docs/styleguide/figures.xml | 169 --------- docs/styleguide/filenames.xml | 76 ---- docs/styleguide/general.xml | 208 ---------- docs/styleguide/glossary.xml | 18 - docs/styleguide/indexterms.xml | 74 ---- docs/styleguide/links.xml | 489 ------------------------ docs/styleguide/lists.xml | 400 -------------------- docs/styleguide/overview.xml | 149 -------- docs/styleguide/programming.xml | 493 ------------------------ docs/styleguide/structure.xml | 133 ------- docs/styleguide/styleguide.xml | 26 -- docs/styleguide/tables.xml | 818 ---------------------------------------- 19 files changed, 4233 deletions(-) delete mode 100644 docs/styleguide/admon.xml delete mode 100644 docs/styleguide/authoring.xml delete mode 100644 docs/styleguide/books.xml delete mode 100644 docs/styleguide/build.xml delete mode 100644 docs/styleguide/chapter.xml delete mode 100644 docs/styleguide/conditional.xml delete mode 100644 docs/styleguide/exclude.xml delete mode 100644 docs/styleguide/figures.xml delete mode 100644 docs/styleguide/filenames.xml delete mode 100644 docs/styleguide/general.xml delete mode 100644 docs/styleguide/glossary.xml delete mode 100644 docs/styleguide/indexterms.xml delete mode 100644 docs/styleguide/links.xml delete mode 100644 docs/styleguide/lists.xml delete mode 100644 docs/styleguide/overview.xml delete mode 100644 docs/styleguide/programming.xml delete mode 100644 docs/styleguide/structure.xml delete mode 100644 docs/styleguide/styleguide.xml delete mode 100644 docs/styleguide/tables.xml diff --git a/docs/styleguide/admon.xml b/docs/styleguide/admon.xml deleted file mode 100644 index 53a1a30..0000000 --- a/docs/styleguide/admon.xml +++ /dev/null @@ -1,104 +0,0 @@ - - - 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. - -
- diff --git a/docs/styleguide/authoring.xml b/docs/styleguide/authoring.xml deleted file mode 100644 index 9d45c84..0000000 --- a/docs/styleguide/authoring.xml +++ /dev/null @@ -1,93 +0,0 @@ - - - Authoring Documentation - - - DocBook .... - - -
- Structure: Concept, Task, Reference - Every chapter in Evergreen documentation, and in some cases sections, should begin by - explaining this chapter's concepts, or core ideas, to the reader. This gives you the - opportunity to clarify new or ambiguous terminology for otherwise experienced readers: - for example, in a circulation overview you will want to differentiate non-cataloged - items vs. pre-cataloged items. Explaining concepts also gives less experienced readers a - chance to fill in gaps in their knowledge. - For example, in the circulation section of the manual, you may write the following - set of tasks: - - - Checking out an item Checking in an item Renewing items Recording in-house - uses - - - Separating the concepts from the tasks gives your readers the chance to jump directly - to the task they want to complete, if they are already familiar with the concepts. - When you write your task information, try to organize it as a set of numbered steps - that covers the most common cases. Compose each step in two sentences: first, describe - the action the reader must complete, followed by a sentence describing the results of - successfully performing the action if applicable. Preface optional steps with - (Optional):. For example: - To check out a cataloged item to a patron: - - - In the staff client, select Circulation→Check Out Items. The Check Out tab - appears. - - - Enter the patron barcode in the Barcode text field. The system retrieves and - displays the patron information, with the Check Out button highlighted in the - action bar. - - - Enter the item barcode in the text field beside the Barcode: selection in the - drop-down menu. - - - - - (Optional): Select a different due date from the date selector. 4. Click Submit to - check out the item to the patron. The item barcode, due date, and title appear in the - transaction summary table. 5. Repeat steps 3 and 4 for each additional item the patron - wants to borrow. 6. (Optional): Click Print Receipt to print a receipt summarizing the - transactions for the patron. The Print Receipt window opens. Reference Reference - information consists of lists of commands, configuration files and settings, software - prerequisites, APIs, etc that need to be rigorously documented to support use cases - outside the core task documentation. Reference information is typically organized by - type, then by alphabetical order. For example, all system commands will be documented in - their own section of the manual in alphabetical order, and all APIs will be documented - in their own section of the manual in alphabetical order. System commmands: * autogen.sh - * import_holdings.pl * marc2bre.pl * osrf_ctl.sh * … APIs: * - open-ils.auth.authenticate.complete * open-ils.auth.authenticate.init * … Discuss how - each system feature would be used by each scenario institution If applicable, provide an - example of how each institutional scenario (Le Grande University vs. Metropolitan Public - Library Consortium) would likely put the feature being discussed into use. You will - probably want to include this information in the concept topic(s) introducing the - feature, or as a separate concept topic or set of topics following the introductory - concept topic. The scenarios give you a few different facets to describe when explaining - the topic to your reader: * academic vs. public libraries * consortiums vs. standalone - libraries * libraries with large collections vs. libraries with small collections Style - guidelines Use the active voice Avoid the passive voice. For example: Rather than: The - barcode is checked for a valid check digit when it is scanned. Use the active voice: - When you scan the barcode, the system checks for a valid check digit. If your sentence - contains “is”, be careful: it might be using the passive voice. Write concise sentences - Try to keep your sentences brief. Avoiding complex phrases with related clauses helps - readers concentrate on a single idea at a time. It also helps translators. Prefix - conditional clauses If your sentence is conditional, place the conditional clause at the - beginning of the sentence. When your reader skims your text and only sees the first part - of the sentence, they might take the wrong action. For example: Rather than: Click the - **Cancel** button to prevent the changes from being applied if the results did not match - your expectations. Use: If the results did not match your expectations, click the - **Cancel** button to prevent the changes from being applied. Contractions, - abbreviations, and acronyms Do not use contractions (“you're”, “we've”, “it's”) or Latin - abbreviations (e.g., etc., i.e.). These can be hard to translate and hard to read. If - you use an acronym, provide the full form of the acronym and include the acronym in - parentheses in the first use in your topic. After the acronym has been introduced, you - can use the acronym on its own for the remainder of the topic. Highlighting Use bold to - highlight the names of GUI elements such as field and button labels, window names, and - menu options. -
- diff --git a/docs/styleguide/books.xml b/docs/styleguide/books.xml deleted file mode 100644 index 2d69f24..0000000 --- a/docs/styleguide/books.xml +++ /dev/null @@ -1,256 +0,0 @@ - - - Creating a Book - - - Books are the top level of organization for topics in a library. They are a collection - of sub-topics organized into chapters. This chapter describes how to create books in XML. - - - In most cases Evergreen documentation authors will not create books, but will be - authoring chapters or sections within books, as described in the chapter on document - structure. - - - - -
- Common Elements - - Overview - XML based books share a number of common elements. These include: - - - A XML version and encoding element - - - A root element - - - A title element - - - An info element describing the book's front matter - - - - - Root element - The root element of an XML book is the book element. The book element provides a wrapper for parts, chapters, appendices, - indexes, and glossaries. - The book element needs to include the XML namespace - declarations shown in : - - XML Namespace Declarations - <book xmlns="http://docbook.org/ns/docbook" -xmlns:xi="http://www.w3.org/2001/XInclude" -xmlns:xl="http://www.w3.org/1999/xlink" -... > - - The book element's version - attribute must be set to 5.0. - You must also specify a value for the book element's xml:id attribute. - You can also use the book element's status attribute to embed a draft stamp in the book. You do this by setting status attribute to draft. - - - Title - The first child of the book element is the title element. The contents of the title - element is the title of the book. - - - Front matter - The production templates fill in the required graphics and other formatting for the - front matter of a book. However, the author needs to include the proper legal notices and - copyright information. All of the legal notices should be imported from the template folder - in the library. This way you do not have to worry about updating your books when the legal - notices change. - The front matter also includes the following information: - - - The release date - - - The product name and version - - - The date the document was updated - - - The common keywords for the book - - - The graphics for the front page - - - All of the information in the front matter is boiler plate and should not be - updated. - shows a book file with the front matter imported. - - - Front Matter Imported - <?xml version="1.0" encoding="UTF-8"?> -<book 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="overview"> -<title>What is &prodname;?</title> -<info> -<xi:include href="../common/keywords.xml" /> -<mediaobject> - <imageobject role="html"> - <imagedata depth="100" contentwidth="146" contentdepth="55" - valign="middle" fileref="./imagesdb/cover_logo.gif"/> - </imageobject> -</mediaobject> -<productname>&prodname;?</productname> -<releaseinfo>Version &version;?</releaseinfo> -<date>&reldate?</date> -<xi:include href="../common/legalblurb.xml" /> -<xi:include href="../common/copynotice.xml" /> -<xi:include href="../common/copydate.xml" /> -<pubdate><?dbtimestamp format="d b Y"?></pubdate> -<corpauthor>Evergreen Documentation Interest Group</corpauthor> -</info> -... -</book> - - -
-
- Preface - - Overview - The preface of your book is placed into the XML file just after the info element. It is specified inside of a preface - element. The preface should be created in a separate file and imported, using an xinclude element, into the book file. - - - Parts of the preface - The preface of your book will have the following sections that are unique to a - book: - - - What is covered in this book? - - - Who should read this book? - - - How to use this book? - - - In addition there are several sections that are common to all of the books in the - library. These include: - - - Library - - - How to get the latest updates - - - Additional support resources - - - Documentation conventions - - - These common sections should be imported, using xinclude - elements, from a common template area. This ensures that any changes are propagated across - the entire library. - - - Adding content to a preface - Writing a preface is identical to writing a chapter. This is discussed in . - - - Example - shows a preface that can be imported into a book file. - - - Book Preface - <?xml version="1.0" encoding="UTF-8"?> -<preface 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="inferno"> -<title>Preface</title> -<section> -<title>What is Covered in This Book</title> -<para>A bunch of technical stuff.</para> -</section> -<section> -<title>Who Should Read This Book</title> -<para>Engineers interested in learning about the stuff discussed.</para> -</section> -<section> -<title>How to Use This Book</title> -<para>Very carefully...</para> -</section> -<xi:include href="../common/library.xml" /> -<xi:include href="../common/latest.xml" /> -<xi:include href="../common/searching.xml" /> -<xi:include href="../common/resources.xml" /> -<xi:include href="../common/coventions.xml" /> -</preface> - - -
-
- Chapters - - Overview - After the preface, you add the chapters to your book. Chapters are created in separate - files and imported into the book file using xinclude elements. - You do not need to worry about adding a table of contents, list of figures, or list of - tables. These are all created when the book is published. - - - Writing chapters - Adding content to a chapter is discussed in the - - - Importing chapters - Chapters are imported into a book using xinclude - elements. - -
-
- Example Book - shows a book. - - - An XML Book - <?xml version="1.0" encoding="UTF-8"?> -<book 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="overview"> -<title>Evergreen Guide to Martian Living</title> -<info> -<xi:include href="../common/legalblurb.xml" /> -<xi:include href="../common/copynotice.xml" /> -<xi:include href="../common/copydate.xml" /> -</info> -<xi:include href="preface.xml" /> -<xi:include href="migration.xml" /> -<xi:include href="housekeeping.xml" /> -<xi:include href="recipes.xml" /> -<xi:include href="shopping.xml" /> -<index /> -</book> - -
- diff --git a/docs/styleguide/build.xml b/docs/styleguide/build.xml deleted file mode 100644 index f21cb32..0000000 --- a/docs/styleguide/build.xml +++ /dev/null @@ -1,37 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/styleguide/chapter.xml b/docs/styleguide/chapter.xml deleted file mode 100644 index 754fb87..0000000 --- a/docs/styleguide/chapter.xml +++ /dev/null @@ -1,117 +0,0 @@ - - - Chapters and Other Root Elements -
- Guidance for Evergreen Authors - The following information is intended to clarify the elements in the documents you are - working with. If you use the Evergreen templates, they will at minimum have top-level - declarations filled out. - In most cases, you will be working with chapters or sections, as described below. However, - in some cases you may need to create a document from another root element, such as glossary. -
-
- Top-level Declarations - The first few lines of an XML chapter contains boilerplate markup. These lines include the - XML encoding statement and an entity declarations for the variables used in the chapter. If - you use the Evergreen templates, these will be filled out for you. -
-
- Root Element - The root element of an XML chapter is the chapter element. The - chapter element provides a wrapper for sections and - blocks. - The chapter element needs to include the XML namespace - declarations shown in : - - XML Namespace Declarations - <chapter xmlns="http://docbook.org/ns/docbook" -xmlns:xi="http://www.w3.org/2001/XInclude" -xmlns:xl="http://www.w3.org/1999/xlink"> - - The chapter element's version - attribute must be set to 5.0. -
-
- Title - The first child of the chapter element is the title element. The contents of the title - element is the title of the chapter, such as Evergreen Circulation or Evergreen System - Administration. - Titles in Evergreen documentation are determined by the DIG, and follow the format: - Evergreen [Function]. -
-
- Chapter Info - After the title element, a chapter should have an info element. This element contains the chapter summary and a list of - keywords that will be put into the generated metadata for this chapter. - The chapter summary is placed inside an abstract element. The - abstract element requires a nested para element to wrap the text. - The keyword list is placed inside of a keywordset element. Each - keyword in the list must be wrapped in a keyword element. (Do we - want to use this?) -
-
- Structural Elements - - Overview - Chapters are broken into sections and blocks. - - - Sections - Generally, a chapter should have five or fewer sections. If you need more sections, it - may be because the topic for your chapter is too broad or you need to reconsider how you are - chunking the information. Top level sections are denoted using section elements. - Top-level sections can be broken down into five or fewer subsections. Subsections are - also denoted using section elements. - - - Blocks (simplesect) - Block are the smallest structural unit of organization in a chapter. They divide up the - information in a section into manageable chunks of information. There should be no more than - five block-sections in a section. - Block-sections are denoted using simplesect elements. Blocks - cannot be subdivided. - - - Example - shows a more detailed view of a chapter. - - - Detailed View of a Chapter - <?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="chapter"> - <title>This is a Chapter</title> - <info> - <abstract> - <para>This is a chapter summary.</para> - </abstract> - </info> - <section id="section"> - <title>This is a section</title> - ... - </section> - <section id="..."> - ... - <section id="subsection"> - <title>Sample Subsection</title> - ... - <simplesect id="block"> - <title>Sample Block Section</title> - ... - </simplesect> - </section> - </section> -</chapter> - - -
- diff --git a/docs/styleguide/conditional.xml b/docs/styleguide/conditional.xml deleted file mode 100644 index c56b999..0000000 --- a/docs/styleguide/conditional.xml +++ /dev/null @@ -1,203 +0,0 @@ - - - Conditional Text -
- Writing with Conditional Text - - Overview - The guidelines on using conditional text are based on the Profiling - chapter from DocBook XSL: The - Complete Guide, by Bob Stayton. The current chapter does not describe all of the - features supported by DocBook XSL. In particular, this chapter discusses profiling using - only the condition attribute, whereas the DocBook - XSL book also describes how to support profiling using other DocBook - attributes. - - - Conditionalizing elements - To conditionalize an element, set the element's condition - attribute to the name of the condition you want to apply. For example, to conditionalize a - text block with the fuse condition: - <simplesect condition="fuse"> - ... -</simplesect> - When you conditionalize an element, the condition is applied to all of the - enclosed text and every sub-element of the conditionalized element. This - mechanism is flexible, because every element in DocBook supports the condition attribute. For example, you can conditionalize an entire chapter, a section, a figure, an example, or even an individual - code element. - - - Conditionalizing free-standing text - There is one special case not covered by the mechanism for conditionalizing elements. - What do you do, if you want to conditionalize a fragment of text that does not correspond to - an element? For example, you might want to conditionalize a sentence within a paragraph. In - this case, you can use the phrase element to enclose the text - fragment and then apply the requisite condition to the phrase - element. - The following example shows how to conditionalize a sentence so that it appears only in - the Artix version of the book: - <para>&prodname; supports a multitude of integration options. -<phrase condition="artix">In particular, you can optionally plug in a mainframe integration kit</phrase> -</para> - - - Conditionalizing comments - You can also use conditional text to manage draft comments in a book. These are the kind - of comments that you would like to make visible in a draft copy of the output: for example, - reminders to self and directions to the reviewer. It is recommended that you insert comments - using the remark element with the comment condition applied. For - example: - <remark condition="comment">REVISIT - Your comment here!</remark> - To simplify entering comments, the Evergreen template for the Oxygen editor includes a - custom option, DocBook4 | Insert Comment, which automatically - inserts a conditionalized remark element. - - - Applying multiple conditions - If required, you can apply multiple conditions to a single element, using the semicolon, - ;, as the separator character. For example, to apply both the - unix and win conditions to a simplesect element, set the condition attribute as - follows: - <simplesect condition="unix;win"> ... </simplesect> - Semantically, the effect of setting both of these conditions is that, at build time, the - simplesect element will be included in the output if either the - unix condition OR the win condition is enabled. - -
-
- Building Books with Conditional Text - - Overview - When building a book with conditional text, you need to use a special Ant build file to - produce the output. The targets of the conditional build file are the same as a regular - build file, but the process for generating the output is slightly different. When building a - conditional book, the build system first generates an intermediate file, - bookname.prfl, which contains a version - of the bookname.xml book where all of the - conditions have been applied. The - bookname.prfl file is then used as the - input for the next stage of book building, using the regular templates for HTML and - PDF. - - - Steps for building with conditions - To build a book with conditions, perform the following steps: - - - - - - - - - - - - - - Get the conditional build.xml file - To build a book with conditional text, use the conditional version of the Ant - build.xml file. In the docs_tools SVN - repository, look for the following file: - trunk/docbook-output/dcbk/custom/build_book_with_conditions.xml - Copy this build file into your book directory and rename it to - build.xml. - - - Set conditions in build.xml - In addition to the usual book properties that you must set in a - build.xml file (that is, ROOT, DOCID, and - LOGO), you must also set a CONDITIONS property that lists the - conditions you want to enable. If you want to enable multiple conditions, separate them - using a semicolon character, for example: - <property name="CONDITIONS" value="condition1;condition2" /> - This setting would ensure that any conditions marked with condition1 AND - any conditions marked with condition2 are included in the output. In other - words, the more conditions you specify here, the more output text you might get. - - - Build the book - The conditional build.xml file supports the same Ant targets for - building a book as the normal build.xml file. For example, to build - both the HTML and PDF output, you can execute Ant with the default target, as - follows: - > ant - The build file also supports the db, pdf, and - html Ant targets. In the course of generating the document output, the build - file produces an intermediate file, - bookname.prfl, which is a DocBook XML file - to which the conditions have been applied. - - - Example - shows the top of the - build.xml file for the FUSE Mediation Router Programmer's Guide, - including conditional settings. This book is shared between the FUSE and Artix product. - FUSE-specific parts of the book are marked with the condition, fuse, and - Artix-specific parts of the book are marked, artix. shows the settings for building the FUSE version of - the book in draft format. - - Sample Settings in a Conditional build.xml File - <?xml version="1.0" encoding="UTF-8"?> -<project name="MRGettingStarted" default="all" basedir="."> - <property environment="env" /> - <!-- Choose one of the following common build files to import: - build_artix_common.xml (Artix) - build_fuse_common.xml (FUSE) - --> - <import file="${env.DBCK_HOME}/lib/build_fuse_common.xml"/> - - <!-- Edit the following properties for your book: --> - <property name="ROOT" value="prog_guide" /> - <property name="DOCID" value="FuseMRProg" /> - <property name="LOGO" value="fmr" /> - <property name="CONDITIONS" value="fuse;comment" /> - - <!-- DO NOT MODIFY ANYTHING BELOW THIS LINE --> - ... - - Where the CONDITIONS property specifies two conditions: fuse - and comment. This build file processes the conditions as follows: - - - Unmarked elements not enclosed by conditionalized elements are included in the - output. - - - Elements marked with the artix condition are - excluded from the output. - - - Elements marked with the fuse condition are - included in the output. - - - Elements marked with the comment condition are - included in the output. - - - - - Managing comments - Unlike other conditions, which typically remain unchanged for a long time, the - comment condition changes relatively frequently, as you switch between - producing draft copies and release copies. It is something that you need to keep in mind, - when building a release, that you need to disable the comment condition before - building the output. - - - Building without conditions - It is not possible to build a book with a blank CONDITIONS property. If you - want to build a book without conditions, you could either replace the conditional - build.xml file with a regular build.xml file or - you could enable every condition in the CONDITIONS property (thereby ensuring - that the complete source is processed). - -
- diff --git a/docs/styleguide/exclude.xml b/docs/styleguide/exclude.xml deleted file mode 100644 index 3da6953..0000000 --- a/docs/styleguide/exclude.xml +++ /dev/null @@ -1,370 +0,0 @@ - - - Elements Currently Unused in Evergreen Documentation - Evergreen documentation uses a subset of elements defined by DocBook. The following elements - are not planned to be used. If you believe you need to use one of these tags, contact the - Documentation Interest Group for more guidance. - - - ackno - - - address - - - affiliation - - - artpagenums - - - audiodata - - - audioobject - - - authorblurb - - - beginpage - - - bibliocoverage - - - bibliodiv - - - biblioentry - - - bibliography - - - bibliographyinfo - - - biblioid - - - bibliolist - - - bibliomixed - - - bibliomset - - - biblioref - - - bibliorelation - - - biblioset - - - bibliosource - - - blockinfo - - - citation - - - citebiblioid - - - citerefentry - - - citetitle - - - city - - - collab - - - collabname - - - colophone - - - confdates - - - confgroup - - - conftitle - - - contractnum - - - contractsponsor - - - corpname - - - country - - - dedication - - - fax - - - firstname - - - glossaryinfo - - - highlights - - - honorific - - - informalequation - - - inlineequation - - - invpartnumber - - - isbn - - - issn - - - issuenum - - - jobtitle - - - lineage - - - manvolnum - - - modespec - - - orgdiv - - - otheraddr - - - pagenums - - - partintro - - - personblurb - - - personname - - - phone - - - pob - - - postcode - - - prefaceinfo - - - primaryie - - - printhistory - - - productnumber - - - publisher - - - publishername - - - pubsnumber - - - refsect1 - - - refsect1info - - - refsect2 - - - refsect2info - - - refsect3 - - - refsect3info - - - revdescription - - - revhistory - - - revision - - - screeninfo - - - secondaryie - - - sect1 - - - sect1info - - - sect2 - - - sect2info - - - sect3 - - - sect3info - - - sect4 - - - sect4info - - - sect5 - - - sect5info - - - seealsoie - - - seeie - - - seg - - - seglistitem - - - segmentedlist - - - segtitle - - - seriesvolnums - - - shortaffil - - - sidebar - - - sidebarinfo - - - simpara - - - state - - - street - - - surname - - - tertiaryie - - - titleabbrev - - - toc - - - tocback - - - tocchap - - - tocentry - - - tocfront - - - toclevel1 - - - toclevel2 - - - toclevel3 - - - toclevel4 - - - toclevel5 - - - tocpart - - - videodata - - - videoobject - - - volumenum - - - diff --git a/docs/styleguide/figures.xml b/docs/styleguide/figures.xml deleted file mode 100644 index cc8c725..0000000 --- a/docs/styleguide/figures.xml +++ /dev/null @@ -1,169 +0,0 @@ - - - Figures, Diagrams, Screen Shots, and In-Line Graphics -
- Overview - Graphics, such as a diagram or a screen shot of a user interface, make a document more - readable. Often, graphics also help clarify abstract concepts. - Figures, diagrams, and screen shots contain images stored in external files. They are - denoted using one of two elements: figure or screenshot. The figure element is used to denote a figure - or a diagram. The screenshot element is used to denote a screen - shot. -
-
- Image Data - The preferred data format for images is PNG. However, images can be accepted in the - following formats: - - - JPEG - - - GIF - - - Images should be placed in an images folder - directly under the folder containing the document source. - Image size... -
-
- Image Size - Image files should have a maximum width of 900 pixels. - Image scaling should be set to 75%. This is ignored for HTML output and ensures images are - optimally sized for PDF files. -
-
- Figures and Diagrams - Figures and diagrams are marked up the same way. They are both placed in a figure element. The figure element is a - container for the caption and data that make up the figure or diagram. - The caption is specified by a title element. The title element is the first child element of thefigure element. The contents of the title element is the - caption used for the figure. It is also the default text used when you cross reference the - figure. - The image data is specified in a mediaobject element. The mediaobject element is a wrapper for an imageobject element. The imageobject element is also a - wrapper element. The imageobject element wraps an imagedata element that specifies the name of the file containing the - image. - The imagedata element has no content. All of the information is - specified using three attributes: - - Attributes for imagedata Element - - - - Attribute - Description - - - - - - align - - Specifies how the image is aligned on the page. Valid values are left, right, and center. - - - - fileref - - Specifies the location of the file containing the image. - - - - format - - Specifies the type of data used to specify the image. Valid values are GIF, JPG, and PNG. - - - -
- shows the mark-up for a figure. - - Mark-up for a Figure - <figure xml:id="fig_1"> - <title>CeltiXfire WAR Structure</title> - <mediaobject> - <imageobject> - <imagedata align="center" - fileref="./images/tomcat_war.gif" - format="GIF" /> - </imageobject> - </mediaobject> - ... -</figure> - -
-
- Screen Shots - Screen shots are also marked up using a figure element. - However, a screen shot uses one additional wrapper element. The screenshot element wraps the mediaobject element as shown - in . - - Mark-up for a Screen Shot - <figure xml:id="screen_1"> - <title>SOA Tools Welcome Screen</title> - <screenshot> - <mediaobject> - <imageobject> - <imagedata align="center" - fileref="./images/welcome.gif" - format="GIF" /> - </imageobject> - </mediaobject> - </screenshot> - ... -</figure> - -
-
- In-Line Graphics - Graphical elements that need to be placed in-line with the text of a paragraph are marked - up using the inlinemediaobject element. Like the mediaobject element, the inlinemediaobject - element is a wrapper for an imageobject element. shows the mark-up for an in-line graphic. - - Mark-up for an In-Line Graphic - <inlinemediaobject> - <imageobject> - <imagedata align="center" fileref="./images/larrow.gif" - format="GIF" /> - </imageobject> - ... -</inlinemediaobject> - -
-
- Adding Alternative Text - For better accessibility and to comply with federal and local accessibility guidelines, - all images in DocBook files should include alternative text. - To include alternative text with a graphic, add a textobject - element after the imageobject element. The textobject element has a single phrase child element. The - value of the phrase element is the alternative text used when the - documentation is generated to HTML. - - Mark-up for Alternative Text - <mediaobject> - <imageobject> - <imagedata align="center" fileref="./images/config.gif" - format="GIF" /> - </imageobject> - <textobject> - <phrase>Configuration Hierarchy</phrase> - </textobject> -</mediaobject> - -
- diff --git a/docs/styleguide/filenames.xml b/docs/styleguide/filenames.xml deleted file mode 100644 index f729c83..0000000 --- a/docs/styleguide/filenames.xml +++ /dev/null @@ -1,76 +0,0 @@ - - - File Structure and Filenames - - - - This chapter describes the physical file structure for Evergreen documentation and file - naming conventions, including the olink element. - - -
- File Structure for Evergreen Documentation - - Overview - The files for Evergreen documentation reside within a public directory on - evergreen-ils.org. - - - File structure for Evergreen documents - - - The set is represented by set.xml, a single file in the docs subdirectory of - evergreen-ils.org - - - The two book elements are in separate subdirectories under the docs subdirectory, - and are labeled book1.xml and book2.xml - - - Chapter elements are in their own separate subdirectories under their respective - book directories - - - Glossaries and similar chapter-like elements are treated like chapters, and are in - separate subdirectories under their respective book directories - - - Images and similar media files are placed in subdirectories under their respective - folders. - - - -
-
- Filename conventions - - - Evergreen filenames are in lower case without underscores or periods. - - - The folders for images and other multimedia are named media. - - - The XML id for the chapter is the same as the XML filename, such as sysadmin. - - -
- -
- Conventions for olinks - - - To simplify the creation of olinks between between books, every Evergreen file has a - document id that parallels the file's filename and xml:id - attribute. Therefore, a book-level file called book2.xml has an xml:id of book2 and a - document id of book2, while a chapter file called sysadmin.xml has an xml:id of sysadmin - and also a document id of sysadmin. - - - The document id is the first element within the file after the xml declaration, and - has the structure element id="name". - - -
- diff --git a/docs/styleguide/general.xml b/docs/styleguide/general.xml deleted file mode 100644 index a0fc586..0000000 --- a/docs/styleguide/general.xml +++ /dev/null @@ -1,208 +0,0 @@ - - - General Elements and Other Elements not Discussed Elsewhere -
- Overview - Since DocBook was defined to describe a wide range of publishable content, it includes a - number of elements that are used to perform common tasks. These elements include ones that - specify superscripts and emphasis. -
-
- Formatting Elements - The following are common formatting elements used in DocBook: - - Element - Description - - - emphasis - - Specifies that the content of the element is to be emphasized by either - italics or boldface. The default - is to use italics. Specify boldface by setting the role - attribute to bold. - - - literallayout - - Specifies that the content of the element is to be reproduced with all of the - whitespace preserved. - - - subscript - - Specifies that the content of the element is a subscript as in - H2O. - - - superscript - - Specifies that the content of the element is a superscript as in - E=MC2. - -
-
- General Computing Elements - The following are elements used for describing computer technology: - - Element - Description - - - action - - Specifies that content describes a response to some user initiated action. - - - application - - Specifies that the content is the name of a piece of software. - - - computeroutput - - Specifies that the content is text printed on a computer display. - - - database - - Specifies that the content is the name of a database, or part of a database. - - - email - - Specifies that the content is an e-mail address. - - - envar - - Specifies that the content is the name of an environment variable. - - - errorcode - - Specifies that the content is an error code. - - - errorname - - Specifies that the content is the name of an error. - - - errortext - - Specifies that the content is the text generated when an error occurs. - - - filename - - Specifies that the content is the name of a file. - - - hardware - - Specifies that the content is a piece of computer hardware. - - - option - - Specifies that the content is an option to a command. - - - prompt - - Specifies that the content is the string used as a prompt for data on a computer - screen. - - - userinput - - Specifies that the content is data a user enters into a computer system. - -
-
- Other General Elements - The following are other general use elements used in DocBook: - - Element - Description - - - abbrev - - Specifies that the content is an abbreviation. - - - acronym - - Specifies that the content is an acronym. - - - firstterm - - Specifies that the content is the first occurrence of a new term or is a term that is - used a context specific manner. - - - literal - - Specifies that the content is a literal value. - - - optional - - Specifies that the content is optional information. It is typically used in command - synopsis. - - - replaceable - - Specifies that the content represents a value that will be replaced by the user in - using the product. - -
-
- GUI Elements - The following are DocBook elements used in documenting a GUI: - - Element - Description - - - accel - - Specifies that the content is a keyboard shortcut. - - - guibutton - - Specifies that the content is the label on a GUI button. - - - guilabel - - Specifies that the content is a label on a GUI element other than a button. - - - guimenu - - Specifies that the content is the name of a menu. - - - guimenuitem - - Specifies that the content is a selectable item on a menu. - - - guisubmenu - - Specifies that the content is the name of a sub-menu. - - - mousebutton - - Specifies that the content is the name of a mouse button. - -
- diff --git a/docs/styleguide/glossary.xml b/docs/styleguide/glossary.xml deleted file mode 100644 index 08cebcc..0000000 --- a/docs/styleguide/glossary.xml +++ /dev/null @@ -1,18 +0,0 @@ - - - - The recommendation here is to build a glossary database (Chapter 17 of Stayton's - book) that is writable by any author or editor with commit privileges. Authors can - populate it with whatever terms they like, using a simple rule for id - disambiguation (such as gloss.term, where gloss is constant and term is the term - itself). If we need to disambiguate two forms of the same term, we can add a - suffix. The build process described in Stayton's book builds a glossary for each - document based on the terms used in that document. - - For authors without commit privileges, this becomes a little more complex. One - thought would be to have authors submit their glossary entries in a separate file, - which editor-committers can then upload. - - diff --git a/docs/styleguide/indexterms.xml b/docs/styleguide/indexterms.xml deleted file mode 100644 index 7c0b79b..0000000 --- a/docs/styleguide/indexterms.xml +++ /dev/null @@ -1,74 +0,0 @@ - - - Marking Terms for Dynamic Index Creation - - - This chapter describes how to mark up terms for generating a dynamic index of Evergreen - documentation. - - -
- Marking Terms for Index Entry - - Overview - DocBook supports two methods for generating an index. One is to explicitly create the - index. The other is to generate the index when the book is published based on elements - included in the text. We use the second approach. - Authors are not required to mark up index elements; editors will complete any index - tagging not accomplished at the authoring stage. - - - Specifying index entries - Index entries are specified by adding indexterm elements in - the text of the book. An index entry must contain one primary - element. The value of the primary element is the top-level entry - that will appear in the generated index. - In addition, an indexterm element can contain the following - optional elements: - - - One secondary element that specifies a second level entry - in the generated index. - - - One tertiary element that specifies a third level index - entry. - - - One see element that specifies an alternate entry to - which the reader is redirected. - - - One seealso element that specifies an additional entry - with relevant information. - - - If you want to mark an indexterm and you aren't sure what - elements to assign it, use the primary element. - - - Example: Marking a Primary Index Term - The Open Scalable Request Framework ( - OpenSRF - , pronounced 'open surf'), is a stateful, decentralized service architecture - that allows developers to create applications for Evergreen with a minimum of knowledge of - its structure. - - - Example: Marking a Secondary Index Term - Indexed-field weighting, which controls relevance ranking in Evergreen, is configured - in the 'weight' column of the - Evergreen Tables - config.metabib_field - table of the Evergreen database. - - - Specifying where the Index is Generated - In order for the index to auto-generate, every Evergreen book has an index element. The index will be generated in the position that - corresponds to the element's location in the book file. The index element follows all other chapters and appendices. - -
- diff --git a/docs/styleguide/links.xml b/docs/styleguide/links.xml deleted file mode 100644 index 022aabf..0000000 --- a/docs/styleguide/links.xml +++ /dev/null @@ -1,489 +0,0 @@ - - - Cross-References and Links - - - DocBook has three linking elements that are used to create internal cross-references, - external cross-references, and links to locations on the Web. Some of the linking elements - perform multiple tasks and some have overlapping functionality. Authors choose the proper - element based on the specifics of the task at hand. A portion of the link text is generated - by the publication system and the author has some control over it. - - -
- Cross-References within the Same File or Book - - Overview - Internal cross-references link to targets within the same file or book. There are two - linking elements that can be used to make an internal cross-reference: - - - - xref - -generates a cross-reference whose target is in the same file. - - - - link - -generates a cress-reference whose target is in the same file but allows the - author to provide the link text. - - - - olink - -generates a cross-reference whose target is in a different file. The olink element allows the author to use either generated link - text or author supplied link text. - - - - - Inserting a cross-reference in the same file, using generated text - - xref element - - - linking - using generated text - - - cross referencing - - The xref element creates a link to an element in the same - file. It requires the use of the linkend attribute to identify - the target element. - The xref element does not have any content. The link text is - generated based on the contents of the target element. If the - target element has a title element, such as a section element or an example element, - the contents of the title element is used as the link text. - Alternatively, the value of the target element's xreflabel - attribute will be used as the link text. - - If the referenced element has both a title element and a - value specified in its xreflabel attribute, the value of the - xreflabel attribute is used. - - - The default generated text for a PDF cross-reference includes the page number of the - target. The generated text can be changed using the xrefstyle - attribute. See . - - shows an example of a cross reference whose text is - derived from the title element of the referenced element. The - resulting link text would be the section called "Coco Crisp" - shows. - - Cross Reference to a Titled Element - <para><xref linkend="topsect" /> shows ...</para> -... -<section id="topsect"> - <title>Coco Crisp</title> -... -</section> - - shows an example of a cross reference whose text is - derived from the xreflabel attribute of the targeted element. - The resulting link text would be outfielder shows. - - Cross Reference to an Element with an xreflabel - <para><xref linkend="example1" /> shows ...</para> -... -<example id="example1" xreflabel="outfielder"> - <title>Catching Coco Crisp</title> - ... -</example> - - - - Inserting link using author supplied text - - link element - - - linking - using author text - - Internal links are created using the link element. The link element has one required attribute, linkend, whose value is the id of element anchoring the link. The anchoring element - can be any valid DocBook element that uses the xml:id - attribute. For example if you wanted to create a link to an image in your document, you - would use the id of the figure element that wraps the - image. - The text used for the link is the content of the link - element. shows the mark up for this link - to the top of this section. - - Example of an Internal Link - <section xml:id="link"> - ... - <para>... this <link linkend="link">link to the top</link> of ...</para> - ... -</section> - - - The default generated text for a PDF link includes the page number of the target. The - generated text can be changed using the xrefstyle attribute. - See . - - - - Inserting a link to a target element in a different source file - - olink element - - - linking - external source file - - The olink element facilitates cross-linking among DocBook - files (just as xref and link elements - enable linking within files). - - olink element - - - linking - across books - - - site map - - You create a link to another book using the olink - element. - Two attributes associated with the olink element are used to - specify the link target: - - - - targetptr - - - The value of the link target's xml:id - attribute - - - - - targetdoc - - - The value of the targetdoc attribute of the target - document. - - - - For simplicity's sake, use the document's xml:id attribute as the document identifier; - it will then function as both the targetdoc and targetptr element. So the olink reference - for this file would be filenames, as in this example: - See the chapter on <olink targetdoc="lists" targetpr="lists">creating - lists</olink> - -
-
- Cross-References to Other Books - - Overview - Authors can create cross-references to a different book in a set using the olink element. When linking to a different book, an author needs to - use an additional attribute to specify the book in which the target element is located. The - external linking mechanism relies on a site map and a number of target databases. - - - Specifying the link text - DocBook provides two methods for specifying link text for olink elements: author-supplied and auto-generated. Evergreen documentation uses - author-supplied link text. - Creating an olink between books - adfasfsda - - - Setting up the olink site map - - site map - - - linking - external XML source - making a site map - - - - Most Evergreen documentation authors do not have to worry about creating or - maintaining the site map for olinks in Evergreen documentation. This is set up in - advance by the same team that manages the file commits. - - - Stayton notes in DocBook XSL, "To form cross references between documents in HTML, their - relative locations must be known." The olink site map defines how the published - documentation set will be laid out and allows the publication system to resolve the links - between all of the documents in the set. - The site map for a documentation set is placed at the root of the documentation source - tree and is always called site.xml. shows a sample site map. - - - Document Set Site Map - <?xml version="1.0" encoding="utf-8"?> -<targetset> - <targetsetinfo> - <title>Library Title</tite> - <desc>Site map for the Evergreen XML Style Guide</desc> - </targetsetinfo> - <sitemap> - <dir name="docs_rls_inferno"> - <dir name="fluff"> - <dir name="overview"> - <document targetdoc="InfernoOverview"> - <xi:include href="overview/target.db" xmlns:xi="http://www.w3.org/2001/XInclude" /> - </document> - </dir> - </dir> - <dir name="install_guide"> - <document targetdoc="InfernoInstall"> - <xi:include href="install_guide/target.db" xmlns:xi="http://www.w3.org/2001/XInclude" /> - </document> - </dir> - <dir name="getting_started"> - <document targetdoc="InfernoGetStarted"> - <xi:include href="get_started/target.db" xmlns:xi="http://www.w3.org/2001/XInclude" /> - </document> - </dir> - </dir> - </sitemap> -</targetset> - - - Elements of the Site Map - - The site map should always be encoded as UTF-8. This ensures that all of the - generated target data has the same encodings regardless of the encodings used by the XML - source files. - - - The targetset element is the root of the site map. - - - The targetsetinfo element allows you to provide a - description for the document set or any other information that is relevant to the site - map. - - - The title element allows you to provide a title to be - used on the generated index page. - - - The desc element allows you to provide a description for - the document set that will appear at the top of the generated index page. - - - The sitemap element contains the directory layout of the - output files. - - - The name of the top-level directory is not important in the generation of the target - databases for the links. The links are generated relative to the top-level - directory. - - - This is a directory that only contains other directories. - - - This directory holds a generated book. - - - The document element's targetdoc attribute specifies the identifier used in the olink element's targetdoc attribute when linking - to targets in the document. - - - The target database is included in the site map using an xi:include element. The path for each book's target database should be - book_src_dir/target.db. - - - -
-
- Linking to Web Pages - - Creating the link - - link element - xl:href attribute - - - linking - Web pages - - Links to Web pages are created using the link element. You - identify the target Web site using the xl:href attribute. The - value must be a valid URL. - - - Specifying the link text - The link text can be specified in one of two ways. You can specified the desired link - text as the value of the link element. If you leave the link element empty, the value of the xl:href attribute will be used as the link text. - - The PDF will always show the URL in the generated text. - - - - Examples - shows an example of an external link with supplied link - text. - - External Link with Link Text - <link xl:href="http://www.cxf.org">CXF Home</link> - - shows an example of an external link that uses the - default link text. - - External Link Using Default Link Text - <link xl:href="http://www.cxf.org" /> - - -
-
- Creating Anchor Points - - anchor element - - - linking - creating a target - - - Overview - Authors can create anchor points in your text using the anchor element. The anchor element does not have any - content and does not result in any generated text. It simply marks a place in the content - that can be the target of a link. - - - Marking an anchor point - The anchor element is empty. It has a required xml:id attribute that is the ID used for linking to the anchor. In - addition, it can take a xreflabel attribute that provides the - generated text for an xref element or an empty olink element. - - - Example - shows the mark-up for placing an anchor in a document. - - Creating an Anchor - <section ...> - ... - <anchor xml:id="anchorID" xreflabel="here" /> - ... - <para><xref linkend="anchorID" /> is a link to an anchor.</para> - ... -</section> - The generated text from the mark-up in is here is - a to an anchor. and the here would be a link back to the - anchor. - - -
-
- Controlling the Generated Link Text - - Overview - The publication system adds page numbers to all cross-references in PDF books. For - cross-references that use generated text, the publication makes choices about what text is - appropriate for the cross-reference. In some cases the defaults used by the publication is - not appropriate. In these cases, the author can modify the generated link text using the - xrefstyle attribute. - - - The xrefstyle attribute - The xrefstyle attribute's value is a string pattern. All of - the patterns that can be used are described in Bob Stayton's DocBook XSL: The - Complete Guide. - The pattern most commonly used in the Evergreen authoring system is the - select pattern. This pattern is specified using the syntax shown in - . - - Syntax for the Select Pattern - <xref ... xrefstyle="select: opt1 opt2 ... optN" /> - - The values for optN select the text generated for the link - text. - - - Turning off page numbers - Authors can turn off the generation of page numbers in the PDF using the - nopage option in the select pattern. This option instructs the link - generation algorithm to not generate page numbers, however it does not provide any guidance - about what to include in the generated text. For link elements - and olink elements that provide a value for the link text, the - nopage option produces a the supplied link text without a page number. - For xref elements and olink elements - that rely on the publication system to generate the link text, the nopage - is insufficient to create a valid link. The author will need to provide either the label option to the pattern or the - title option to the selection - pattern. - shows a link element that - would not generate a page number. - - - Example of an Internal Link with no Page Number - <section xml:id="link"> - ... - <para>... this <link linkend="link" xrefstyle="select: nopage">link to the top</link> of ...</para> - ... -</section> - - - - Using the target's label - Figures, tables, and examples have labels that are used to generate the link text. To - ensure that an xref element or an olink element that relies on the publication system to generate the link text will - produce link text when page numbering is turned off, the author needs to provide the - label option to the selection pattern. - shows an xref element that - generates a label without a page number. - - - A Cross-Reference to a Figure with no Page Number - <figure xml:id="link"> - ... -</figure> -<para><xref linkend="link" xrefstyle="select: nopage label" /> shows ...</para> -... - - - - - Using the target's title - Chapters, sections, and blocks have titles that are used to generate the link text. To - ensure that an xref element or an olink element that relies on the publication system to generate the link text will - produce link text when page numbering is turned off, the author needs to provide the - title option to the selection pattern. - shows an xref element that - generates a title without a page number. - - - A Cross-Reference to a Block with no Page Number - <simplesect xml:id="link"> - ... -</simplesect> -... -<para>As discussed in <olink targetptr="link" xrefstyle="select: nopage label" /> ...</para> -... - - - -
- diff --git a/docs/styleguide/lists.xml b/docs/styleguide/lists.xml deleted file mode 100644 index b1d125c..0000000 --- a/docs/styleguide/lists.xml +++ /dev/null @@ -1,400 +0,0 @@ - - - Lists - - - DocBook has several list structures to choose from. It has the standard numbered lists - and bulleted lists. In addition it provides specialized types of lists for glossaries and - other occasions. All of these lists may be used in Evergreen documentation. - - -
- Simple Lists - - Overview - Simple lists are like a grocery list. They are a simple list of words or phrases without - any delimiter. Their elements can only consist of simple, in-line tags, and therefore cannot - contain sublists, examples, code listings or multiple paragraphs. Simple lists are rarely - used in Evergreen' documentation. - - - Specifying a simple list - A simple list is specified by a simplelist element. simplelist has two optional attributes: - - Attributes of the <tag class="element">simplelist</tag> Element - - - - Attribute - Values - Description - - - - - - type - - inline, horiz, vert (default) - Specifies how the items in the list are to be listed. - - - - columns - - >=1 - Specifies the number of columns to use when type - is set to horiz or vert. - - - -
- The elements of a simple list are specified using a member - element. The contents of each member element can only contain - character data and in-line elements. - - - Example - shows the markup for a simple list. - - Simple List Markup - <simplelist> - <member>Swedish Fish</member> - <member>Mike & Ike</member> - <member>Sour Patch Kids</member> - <member>Gummy Bears</member> -</simplelist> - - -
-
- Itemized Lists - - Overview - An itemized list is used for lists where the order of the items in the list does not - matter. They are like bulleted lists or the lists that are created by the ul tag in HTML. - - - Specifying an itemized list - An itemized list is specified by an itemizedlist element. You - can specify an xml:id attribute for itemized lists. If the list - is going to referenced by an xref element, you should also - specify a value for the xreflabel attribute. - Each item in an itemized list is specified by a listitem - element. The listitem element is a wrapper element and can - contain any container elements such as a para element. All - content within a listitem element will be indented to the same - level. You can also specify sub-lists within a listitem - element. - - - Example - shows the markup for an itemized list. - - Itemized List Markup - <itemizedlist> - <listitem> - <para>This is the first item in my list</para> - </listitem> - <listitem> - <para>This is the second item in my list.</para> - <para>It has two paragraphs.</para> - </listitem> - <listitem> - <para>This item has a sublist.</para> - <itemizedlist> - <listitem><para>first</para></listitem> - <listitem><para>second</para></listitem> - </itemizedlist> - </listitem> -</itemizedlist> - - -
-
- Ordered List - - Overview - An ordered list is a list where the order of the elements is important and made - explicit. They are like numbered lists and lists that are created using the ol tag in HTML. - - - Specifying an ordered list - Ordered lists are specified by an orderedlist element. In - addition to the xml:id attribute and xreflabel attribute, orderedlist elements have three - optional elements. - - Attributes of the <tag class="element">orderedlist</tag> Element - - - - Attribute - Values - Description - - - - - - continuation - - continues, restarts - (default) - Specifies whether the item numbering should restart at one or continue from the - previous ordered list. - - - - inheritnum - - inherit, ignore - (default) - Valid only for nested lists. Specifies whether the items in the nested list - contain a reference to the item of the parent list. - - - - numeration - - arabic, loweralpha, - lowerroman, upperalpha, - upperroman - Specifies the numbering style to use for the list. - - - -
- Items in an ordered list are specified using a listitem - element. The listitem element is a wrapper element and can - contain any container elements such as a para element. All - content within a listitem element will be indented to the same - level. You can also specify sub-lists within a listitem - element. - -
-
- Variable Lists - - Overview - A variable list looks similar to a glossary. It consists of a word, or phrase, and some - text describing the word, or phrase. shows a variable list. - - List of Rooms - - Kitchen - - The room where food is stored and prepared. - - - - Garage - - Where the cars are parked. - - Bikes are also here. - - - - - Living room - Family room - - This is where we watch TV. - - - - - - Specifying the list - Variable lists are specified by a variablelist element. The - variablelist element can have the optional xml:id attribute and xreflabel - attribute specified. You can also supply a title for a variable list by adding a title element as the variablelist - element's first child. - The items in a variable list are specified using a varlistentry element. The varlistentry element has two - children elements that specify the contents of the item: - - - term - - - listitem - - - - - Specifying terms - You can specify one or more term elements in a varlistentry element. Each term element - can contain text and in-line markup elements. Each term element - should contain a single term or phrase that the list item describes. - - - Describing a term - You describe the term, or terms, defined by the term elements - using a single listitem element. The listitem element is a wrapper element and can contain any container elements such - as a para element. All content within a listitem element will be indented to the same level. You can also specify sub-lists - within a listitem element. - - - Example - shows the markup representing . - - Variable List Markup - <variablelist xml:id="varexample"> - <title>List of Rooms</title> - <varlistentry> - <term>Kitchen</term> - <listitem> - <para>The room where food is stored and prepared.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>Garage</term> - <listitem> - <para>Where the cars are parked.</para> - <note> - <para>Bikes are also here.</para> - </note> - </listitem> - </varlistentry> - <varlistentry> - <term>Living room</term> - <term>Family room</term> - <listitem> - <para>This is where we watch TV.</para> - </listitem> - </varlistentry> -</variablelist> - - -
-
- Glossary Lists - - Overview - A glossary list is a special case of a variable list. It is used specifically for lists - that define terms and where you may want to refer the reader back to the definition of a - specific term. shows a use - of a glossary list. - - List of Terms - - consumer - - The end user of a service, also called a client for that service. - - - endpoint - - The point of contact that a service - provides for its consumers. - - - service - - A collection of operations that perform a useful set of functions in a network, - access to which is implemented as an endpoint. In a service-oriented network, services are defined by a - service contract. - - - service consumer - - - - - Specifying the list - A glossary list is specified using the glosslist element. If - you want to refer back to a glossary list, you can provide values for the xml:id attribute and the xreflabel - attribute. Like variable lists, glossary lists can have titles. - The entries in a glossary list are specified using a glossentry element. The glossentry element typically has - two children: glossterm and glossdef. - You can also use the glosssee element to xref with other - definitions. - - - Specifying a term - A glossentry element can have only one glossterm element. This element specifies the term being defined by this entry. If - you are going to refer back to this term, you can supply a value for the parent glossentry element's xml:id - attribute. - - The glossterm element can also be used in text entries to - refer to terms defined in a glossary entry. When used in this manner, you supply a value - for the linkend attribute. - - - - Defining a term - You define a term using either one or more glossdef elements - or a glosssee element. The glossdef - element is a content element that contains markup specifying a definition. If you use more - than one glossdef element, they are treated as separate - definitions for the same term. - The glosssee element redirects the reader to a term with the - same meaning. It acts like a "See" entry in a dictionary. It has one attribute, - otherterm, whose value is the id of the term to which the - reader is redirected. - - - Example - shows the markup for . - - - Glossary List Markup - <glosslist xml:id="glossexample" xreflabel="List of terms";> - <glossentry xml:id="consumerdef"> - <glossterm>consumer</glossterm> - <glossdef> - <para>The end user of a service, also called a - client for that service.</para> - </glossdef> - </glossentry> - <glossentry xml:id="endptdef"> - <glossterm>endpoint</glossterm> - <glossdef> - <para>The point of contact that a - <glossterm linkend="servicedef">service</glossterm> - provides for its - <glossterm linkend="consumerdef">consumers</glossterm>. - </para> - </glossdef> - </glossentry> - <glossentry xml:id="servicedef"> - <glossterm>service</glossterm> - <glossdef> - <para>A collection of operations that perform a - useful set of functions in a network, access to - which is implemented as an - <glossterm linkend="endptdef">endpoint</glossterm>. - In a service-oriented network, services are defined - by a service contract.</para> - </glossdef> - </glossentry> - <glossentry> - <glossterm>service consumer</glossterm> - <glosssee otherterm="consumerdef" /> - </glossentry> -</glosslist> - - -
- diff --git a/docs/styleguide/overview.xml b/docs/styleguide/overview.xml deleted file mode 100644 index 8f3c09f..0000000 --- a/docs/styleguide/overview.xml +++ /dev/null @@ -1,149 +0,0 @@ - - - Evergreen and DocBook -
- About our approach - - Overview - This is the style guide for documentation produced for the Evergreen open-source library - software project. This manual is intended to help everyone involved in the documentation - "supply chain" by providing guidance wherever a decision about documentation formats needs - to be made, from image size to file-naming conventions and the approved lists of tags and - XSL stylesheets. - This is a living document in a fairly new endeavor, so your feedback on areas that need - correction or expansion is encouraged and warmly appreciated. - - - History - In May, 2009, the Evergreen Documentation Interest Group committed to single-source, - XML, using the DocBook 5.0 documentation standard, for all Evergreen-wide documentation, and - committed to working as a group. - The rationales for this approach were as follows: - - - The Evergreen project needed to move past the gaps and duplicated efforts of having - documentation written within local library systems and leverage its size and skills - toward a common goal. - - - The commitment to single-source documentation means that core Evergreen - documentation would be could be repurposed as necessary into many different formats -- - one core set of files, many outputs. - - - XML provides structure to a document and semantic "meaningfulness." - - - The DocBook standard is a commonly-used documentation standard that has the - advantages over other standards of relative ease of use and a long, well-established - history of development and stewardship. DocBook is also the de facto standard XML schema - and publishing tool set for a number of open source projects, so we will be able to - capitalize on the work others have done before us. - - - - - DocBook 5.0 - DocBook 5.0 is the authoring language for Evergreen documentation. DocBook 5.0 provides - a structured XML-based grammar for writing complex technical documentation. It is also an - OASIS standard. The remainder of this style guide discusses how Evergreen uses - DocBook. - - - Our production model in a nutshell - (Note: this primarily applies to documentation that is making its way into the Evergreen - documentation XML toolchain for the first time. We have not yet developed a production model - for revising XML documents.) - - - - Documentation writers author Evergreen - documentation in whatever format they choose (this is a guiding principal of the - Evergreen documentation project), using the editors of their choice. While authors are - encouraged to produce documentation in DocBook 5.0, we will accept new documentation - in any form the author chooses to write it (and however "localized" it may be). Note - that the DIG project will be providing heavily-commented template files for DocBook - XML production. - - - Authors submit documents to the intake team, who - will submit the documentation to functional testing and revise content accordingly. - - - - If documentation needs conversion from its format to DocBook 5.0, the DIG - XML conversion team wrangles it. - - - One the files are in valid, well-formed XML conforming to the DocBook 5.0 - standard, DIG XML editors (the human kind of editors) - review the files for conformance with Evergreen documentation style guidelines. - - - When the XML files are ready, the DIG transform - team members use a variety of back-end tools to process the files (or, in - DocBook and XML terminology, transform the files) into HTML, - PDF, and other formats. Web designers play a crucial - role at this stage as well, creating and maintaining the Cascading Stylesheets (CSS) - that make the documentation aesthetically pleasing and more user-friendly. Finally, a - small group of "the buck stops here" editors move the - HTML and PDF files into their folders on the website. - - - - - - -
-
- Formatting XML - - Overview - Documentation writers who author in XML generally fall into two camps: those who prefer - a full-featured WYSIWYG editor with built-in validation tools, and those who prefer to code - XML "by hand." - DIG is neutral on this issue, but can recommend software for those interested in - authoring, editing, revising, updating, or validating XML files. Documentation editors - higher up in the XML chain will ultimately reformat all XML so it has appropriate indenting - and wrapping. If you are using an editor such as oXygen, most of this formatting is already - done for you by the software. If you are coding XML by hand, you are encouraged but not - required to keep lines under 80 characters long, and to avoid leaving white space between - elements. - - - Validation - More crucially than indenting and white space, the DIG would appreciate it if authors - producing XML would attempt to validate their files prior to submitting them to ensure the - markup is valid and well-formed XML that conforms with DocBook 5. However, if you run - against insoluble validation problems, please do not let that hold you up; just submit the - files and we will fix the problems and advise you of what we found. - -
-
- Other Resources - - DocBook References - For more general references and familiarization with with DocBook, see the - following: - - - - DocBook.org - - - - - The Crash Course to - DocBook - - - - - Norman Walsh's DocBook page - - - - -
- diff --git a/docs/styleguide/programming.xml b/docs/styleguide/programming.xml deleted file mode 100644 index c4538fb..0000000 --- a/docs/styleguide/programming.xml +++ /dev/null @@ -1,493 +0,0 @@ - - - Working with Code - - - There are several instances when you will need to show code in documentation. You may need to use a class name, an interface name, - or an element name as part of a sentence. You will also need to provide long code samples in many places. DocBook has a number of - elements that are used for placing code in your documentation. - - -
- Code Listings - There are two types of code listings: - - - Formal examples with titles - - - Untitled code blocks - - - Often when making long code listings a writer also needs to explain what specific lines of code do. This can be done using - callouts as explained in -
- Examples - - When to use - Examples are formal code listings that have a title. They are useful for code listings that are linked to from other places in - the text. They are also added to the List of Examples. - - - Marking up an example - example element - programlisting element - Examples are marked up using the example element. You should always provide a descriptive value for - the example element's xml:id attribute. The - example element also takes a pgwide attribute that signals that the - code listing should span the width of the page.The pgwide attribute is not currently - supported by the publication system. Writers will also need the PI for making code blocks wide as shown in - . - The first child of the example element is a title element. The contents of - the title element will be used as the caption of the example. It will also be used as the text for any cross references. - The last child of the example element is the programlisting element. The - programlisting element contains the code sample itself. Any text placed inside the - programlisting element is treated literally. Therefore, any spacing that you use will be exactly reproduced - when the document is produced. - - When using XML inside a programlisting element you must not use the < or - > characters. Instead use &lt; and &gt;. - - The programlisting element takes a language attribute that - specifies the type of code in the example. describes the acceptable values. - - Values for the Program Listing Language Attribute - - - - Value - Description - - - - - java - Specifies that the listing is Java code. - - - spring - Specifies that the listing is Spring XML. This is often used in configuration files. - - - wsdl - Specifies that the listing is WSDL. - - - xmlschema - Specifies that the code listing is XML Schema. This is often seen in the type's section of a WSDL document. - - - xml - Specifies that the code listing is XML. - - - -
- - - Example - shows the mark-up for an example. - - - Example Mark-Up - <example id="example_example"> -<title>Example Service</title> -<programlisting language="java">public class ServiceName extends javax.xml.ws.Service -{ - ... - public ServiceName(URL wsdlLocation, QName serviceName) { } - - public ServiceName() { } - - public Greeter getPortName() { } - . - . - . -}</programlisting> -</example> - - The mark-up shown in is generated into . - - Example Service - public class ServiceName extends javax.xml.ws.Service -{ - ... - public ServiceName(URL wsdlLocation, QName serviceName) { } - - public ServiceName() { } - - public Greeter getPortName() { } - . - . - . -} - - - - Making the example span the page - The code used for an example does not always fit properly in the space allotted for text in the PDF output template. To fix this - writers can specify that an example should span the entire page from the left margin to the right margin using the - <?dbfo pgwide="1"?> PI. - As shown in , the <?dbfo pgwide="1"?> PI is placed directly - after the opening example tag. - - - Wide Example Mark-Up - <example id="examplePgwideEx"> -<?dbfo pgwide="1"?> -<title>Example Service</title> -<programlisting language="java"> - . - . - . -}</programlisting> -</example> - - -
-
- Code Blocks - - When to use - Code blocks are useful for short code listings that show a specific action. They are not appropriate for code listings - that need to be referenced later. They also do not appear in the List of Examples. - - - Mark-up - informalexample element - programlisting element - Code blocks are marked up using the informalexample element. - The only child of the informalexample element is a programlisting element. - This element contains the code listing itself. Any text placed inside the programlisting element is - treated literally. Therefore, any spacing that you use will be exactly reproduced when the document is produced. - - When using XML inside a programlisting element you must not use the < or - > characters. Instead use &lt; and &gt;. - - The programlisting element takes a language attribute that - specifies the type of code in the example. describes the acceptable values. - - - Example - shows the mark-up for a standalone block of code. - - - Example Code Block - <informalexample> - <programlisting language="javascript">var WebServiceProvider1 = { - 'wsdlLocation': 'file:./wsdl/hello_world.wsdl', - 'serviceName': 'SOAPService1', - 'portName': 'SoapPort1', - 'targetNamespace': http://objectweb.org/hello_world_soap_http', -};</programlisting> -</informalexample> - - The mark-up shown in would be published as follows: - - var WebServiceProvider1 = { - 'wsdlLocation': 'file:./wsdl/hello_world.wsdl', - 'serviceName': 'SOAPService1', - 'portName': 'SoapPort1', - 'targetNamespace': 'http://objectweb.org/hello_world_soap_http', -}; - - - - Making the code block span the page - Code listings do not always fit properly in the space allotted for text in the PDF output template. To fix this - writers can specify that a code listing should span the entire page from the left margin to the right margin using the - <?dbfo pgwide="1"?> PI. - As shown in , the <?dbfo pgwide="1"?> PI is placed directly - after the opening informalexample tag. - - - Wide Code Block Mark-Up - <informalexample id="codeBlockPgwideEx"> -<?dbfo pgwide="1"?> -<programlisting language="java"> - . - . - . -}</programlisting> -</informalexample> - - -
-
- Using Callouts - co element - calloutlist element - It is often helpful to use callouts to explain what it happening in a section of code. Specifying callouts is a two step process: - - - Specify where in the code listing you want to place callout markers. - - - Specify the callout text for each callout. - - - - Specifying the callout locations - To specify the placement of a callout in a program listing you place a co element at the location inside of the program listing you want the callout to appear. The co element requires that you set a value for its id attribute. The value is used to associate the callout marker with the text that describes it. You should also provide a value for the co element's linkends attribute. This value will match the value of the id attribute of the associated text. Using this attribute allows for a links to be generated between the callout and the associated text. - - Setting the linkends attribute before entering the callout text will result in an invalid XML file. Once you add the callout text, the file should be valid. - - - - Specifying the callout text - The text associated with a callout is specified outside of the programlisting element and the example element. Shortly after the example element, preferably immediately after, you need to place a calloutlist element. The calloutlist element wraps the elements that specify the callout text. It contains an optional title element and one callout element for each callout specified for the associated program listing. - Each callout element must have its arearefs attribute set to the value of id attribute of the callout for which it defines the text. If you set the linkends attribute of the associated co element, you must also set the callout element's id attribute to the matching value. The callout text is the value of the callout element. - - - Example - shows the mark-up for . - - - Using Callouts - <example xml:id="LinksCalloutExample"> -<dbfo pgwide="1"?> - <title>Document Set Site Map</title> - <programlisting><?xml version="1.0" encoding="utf-8"?> <co linkends="sitemapptr0" xml:id="sitemapco0"/> -<targetset> <co linkends="sitemapptr3" xml:id="sitemapco3"/> - <targetsetinfo> <co linkends="sitemapptr4" xml:id="sitemapco4"/> - Site map for the Evergreen XML Style Guide - </targetsetinfo> - <sitemap> <co linkends="sitemapptr5" xml:id="sitemapco5"/> - <dir name="docs_rls_inferno"> <co linkends="sitemapptr6" xml:id="sitemapco6"/> - <dir name="fluff"> <co linkends="sitemapptr75" xml:id="sitemapco75"/> - <dir name="overview"> <co linkends="sitemapptr7" xml:id="sitemapco7"/> - <document targetdoc="InfernoOverview"> <co linkends="sitemapptr8" xml:id="sitemapco8"/> - <xi:include href="overview/target.db" xmlns:xi="http://www.w3.org/2001/XInclude" /> <co linkends="sitemapptr9" xml:id="sitemapco9"/> - </document> - </dir> - </dir> - <dir name="install_guide"> - <document targetdoc="InfernoInstall"> - <xi:include href="install_guide/target.db" xmlns:xi="http://www.w3.org/2001/XInclude" /> - </document> - </dir> - <dir name="getting_started"> - <document targetdoc="InfernoGetStarted"> - <xi:include href="get_started/target.db" xmlns:xi="http://www.w3.org/2001/XInclude" /> - </document> - </dir> - </dir> - </sitemap> -</targetset></programlisting> -</example> -<calloutlist> - <title>Elements of the Site Map</title> - <callout arearefs="sitemapco0" xml:id="sitemapptr0"> - <para>The site map should always be encoded as UTF-8. This ensures that all of the generated target data has the same encodings regardless of the encodings used by the XML source files.</para> - </callout> - <callout arearefs="sitemapco3" xml:id="sitemapptr3"> - <para>The <tag class="element">targetset</tag> element is the root of the site map.</para> - </callout> - <callout arearefs="sitemapco4" xml:id="sitemapptr4"> - <para>The <tag class="element">targetsetinfo</tag> element allows you to provide a description for the document set or any other information that is relevant to the site map.</para> - </callout> - <callout arearefs="sitemapco5" xml:id="sitemapptr5"> - <para>The <tag class="element">sitemap</tag> element contains the directory layout of the output files.</para> - </callout> - <callout arearefs="sitemapco6" xml:id="sitemapptr6"> - <para>The name of the top-level directory is not important in the generation of the target databases for the links. The links are generated relative to the top-level directory.</para> - </callout> - <callout arearefs="sitemapco75" xml:id="sitemapptr75"> - <para>This is a directory that only contains other directories.</para> - </callout> - <callout arearefs="sitemapco7" xml:id="sitemapptr7"> - <para>This directory holds a generated book.</para> - </callout> - <callout arearefs="sitemapco8" xml:id="sitemapptr8"> - <para>The <tag class="element">document</tag> element's <tag class="attribute">targetdoc</tag> attribute specifies the identifier used in the <tag class="element">olink</tag> element's <tag class="attribute">targetdoc</tag> attribute when linking to targets in the document.</para> - </callout> - <callout arearefs="sitemapco9" xml:id="sitemapptr9"> - <para>The target database is included in the site map using an <tag class="element">xi:include</tag> element. The path for each book's target database should be <filename><replaceable>book_src_dir</replaceable>/target.db</filename>.</para> - </callout> -</calloutlist> - - -
-
-
- In-line Code - - DocBook programming elements - There are many instances where you need to place a code artifact in a block of text such as when you are referring to a Java class - or an XML element. DocBook has a number of specialized elements for placing code artifacts in-line. The ones commonly used - include: - - - tag - - - classname - - - interfacename - - - methodname - - - uri - - - package - - - code - - - - - XML artifacts - When placing XML artifacts such as element names or attribute names in your text wrap them in an - tag element. To specify the type of XML artifact, the tag element's - class attribute is always used. shows the values used for the - class attribute. - - Values for the <tag class="attribute">class</tag> Attribute - - - - - Value - Description - - - - - attribute - Specifies that the artifact is an attribute of an XML element. - - - element - Specifies that the artifact is an XML element. - - - attvalue - Specifies that the artifact is the value of an XML element's attribute. - - - emptytag - Specifies an XML element that does not hold any data such as foo. - - - -
- - - Web Addresses, URIs, and E-Mail Addresses - To specify a Web address or URI you use the uri element. - To specify an E-Mail address use the email element. - - - General programming language artifacts - DocBook defines a number of in-line tags for specifying programming artifacts. The commonly used tags are listed in - . - - Elements for In-Line Programming Artifacts - - - - - - Element - Description - - - - - type - Specifies that the artifact is a data type such as int. - - - constant - Specifies that the artifact is a constant such as NULL or 9. - - - exceptionname - Specifies that the artifact is an exception. It could be the name of the exception or the name of the class that - implements the exception. - - - function - Specifies that the artifact is a function such as println(). - - - parameter - Specifies that the artifact is a parameter to a function or a method. - - - varname - Specifies that the artifact is a variable. - - - code - Used for generic code entries that do not fit into any other category. - - - code role="annotation" - Used for Java annotations. - - - -
- - - Object-oriented programming language artifacts - In addition to the elements listed in , DocBook defines a number of elements that are used - specifically for object-oriented programming artifacts. They are listed in . - - Elements for In-Line OO Programming Artifacts - - - - - - Element - Description - - - - - interfacename - Specifies that the artifact is a Java interface the user must implement. - - - oointerface - Specifies that the artifact is a Java interface the user must implement. Requires the use of an modifier element that contains details about if the interface is public or private. - - - classname - Specifies that the artifact is a Java class or an instantiated object. - - - ooclass - Specifies that the artifact is a Java class. Requires the use of an modifier element that - contains details about if the class is public/private or static/final. - - - methodname - Specifies that the artifact is a method. Methods are different from functions in that methods are associated with classes and objects. - - - ooexception - Specifies that the artifact is a Java exception. Requires the use of an modifier element that - contains details about if the exception is public or private. - - - package - Specifies that the artifact is the name of a Java or C++ package. - - - -
- -
- \ No newline at end of file diff --git a/docs/styleguide/structure.xml b/docs/styleguide/structure.xml deleted file mode 100644 index fcd46c2..0000000 --- a/docs/styleguide/structure.xml +++ /dev/null @@ -1,133 +0,0 @@ - - - The Structure of Evergreen Documentation - - - This chapter describes the structure of Evergreen documentation, common elements in XML - files, and allowable documentation types. - - -
- Top-level Elements in Evergreen Documentation - - Overview - There are two central books for Evergreen documentation, organized within a single set. - The documentation files are arranged it hierarchically, beginning with docs, followed by the - version: - http://evergreen-ils.org/docs/1.6 ... - The following is a common structural pattern for our documentation: - - - set - - - book - - - chapter--a major topic - area, such as Circulation - - - section--a subsection of - an area, such as Patron Registration - - - simplesect--subdivision - of section, such as Family Accounts - - - para--a basic paragraph - marker - - - Most authors will be working at the chapter or section level. Chapters are created in separate files and imported - into the book file using xinclude elements. - There are many more DocBook elements. The above is only intended to be illustrative of - the "tree" that shapes Evergreen documentation. There are also exceptions to the "chapter" - element, such as the glossary element. - The final chapter of this styleguide lists excluded tags for Evergreen documentation. - - -
-
- The Sets and Chapters of Evergreen Documentation - - Overview - Evergreen documentation has the following high-level set, books, and chapters. Filenames - are in parentheses: - - - - set (set.xml) - - - book Evergreen - Technical Reference (book1.xml) - - - chapter Installing - (installing.xml) - - - chapter Upgrading - (upgrading.xml) - - - chapter Migrating from - other Integrated Library Systems (migrating.xml) - - - chapter System - Administration (sysadmin.xml) - - - chapter Software - Developers' Reference (softwaredev.xml) - - - chapter Web - Developers' Reference (webdev.xml) - - - book Evergreen (?) - Reference (book2.xml) - - - chapter Local - Administration (localadmin.xml) - - - chapter The OPAC - (opac.xml) - - - chapter Cataloging - (cataloging.xml) - - - chapter Circulation - (circulation.xml) - - - chapter Reports - (reports.xml) - - - chapter Acquisitions - (acquisitions.xml) - - - chapter Future - Development (futuredev.xml) - - - chapter Glossary - (glossary.xml) - - - - -
- diff --git a/docs/styleguide/styleguide.xml b/docs/styleguide/styleguide.xml deleted file mode 100644 index 32bd252..0000000 --- a/docs/styleguide/styleguide.xml +++ /dev/null @@ -1,26 +0,0 @@ - - - Evergreen Documentation Style Guide (Draft .01) - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/styleguide/tables.xml b/docs/styleguide/tables.xml deleted file mode 100644 index d5f6f0a..0000000 --- a/docs/styleguide/tables.xml +++ /dev/null @@ -1,818 +0,0 @@ - - - Tables -
- Types of Tables - There are two types of tables in DocBook: - - - Informal tables - - - Tables - - - An informal table is simply a table that does not have a title. Tables -must have a title element and are listed in a list of tables if it is -generated. -
-
- Specifying a Table - Both informal tables and tables use the same markup elements to define -their structure. The differences are as follows: - - - Informal tables are specified using the informaltable element and tables are specified using -the table element. - - - Informal tables cannot contain a title element and tables require a title element. - - - Creating a table involves the following steps: - - - Specify the proper root element. - - - If you are creating a table, add a title element. - - - Add a tgroup element to wrap the -contents of the table. - - - If needed, add colspec elements to -specify properties for specific columns. - - - If needed, add spanspec elements to -define reusable column spans. - - - If desired, add a thead element to specify a header -row. - - - Add a row element. - - - Add an entry element for each column -heading. - - - - - Add a tbody element to contain the -body of the table. - - - Add one row element for each row in -the table. - - - In the row elements, add an entry element for each value that appear in the -row. - - - - -
- Table Root Elements - Depending on the type of table you are using you will use either the -informaltable element or the table element as the root element of your table. -Both elements use the attributes listed in . - - Attributes for <tag class="element">table</tag> Element and <tag class="element">informaltable</tag> Element - - - - - Attribute - Description - Values - - - - - - tablepgwide - pgwide - - Specifies whether the table will be span the whole page in PDF output. - 0 (default), 1 - - - - colsep - - Specifies whether a rule will be drawn between the columns in the table. - 0, 1 (default) - - - - frame - - Specifies how the table will be framed. - all, bottom, none, sides, top, topbot - - - - orient - - Specifies how the table will be oriented in relationship to the rest of the text. - land, port (default) - - - - rowsep - - Specifies whether a rule will be drawn between the rows in the table. - 0, 1 (default) - - - - xml:id - - Specifies a unique identifier used to reference the table. - a unique string - - - - xreflabel - - - Specifies a label to be used when cross referencing the table. - - a string - - - -
- - Attributes not listed in are not used in Evergreen' documentation. - -
-
- The tgroup Element - tgroup - The tgroup element groups together the logical components of a table. It specifies the number of columns in a table and contains the column and span specifications used by the table. All of the rows, including the header, are defined inside of the tgroup element. - While most tables contain a single tgroup element, it is possible for a complex table to have multiple tgroup elements. In such a case, each tgroup element would define a unique portion of table where the columns and spans had different specifications. - - Attributes - shows the attributes for the tgroup element. Attributes in the tgroup element override the corresponding attributes -from the table's root element. - - Attributes for the <tag class="element">tgroup</tag> Element - - - - - Attribute - Description - Values - - - - - - colsep - - Specifies whether a rule will be drawn between the columns of the group. - 0, 1 (default) - - - - rowsep - - Specifies whether a rule will be drawn between the rows of the group. - 0, 1 (default) - - - - align - - Specifies the horizontal alignment of the entries in the group. - center, justify, right, left (default) - - - - cols - - A required attribute that specifies the number of columns in the group. - >=1 - - - -
- - Attributes not listed in are not used in Evergreen' documentation. - - - - Example - shows the markup for a tgroup element that defines a 3 column table. - - <informaltable ...> - <tgroup cols="3" colsep="1" rowsep="1" > - ... - </tgroup> -</table> - - -
-
- Specifying Column Properties - If you desire, you can specify a number of the display properties for -the column in a table by adding colspec -elements to a tgroup element. A colspec element defines properties for all of the -entries in one column in a group. You can set different properties for each -column in a group. - - Attributes - shows the attributes for the colspec element. Attributes in the colspec element override corresponding attributes in -the parent tgroup element and the table's -root element. - - Attributes for the <tag class="element">colspec</tag> Element - - - - - Attribute - Description - Values - - - - - - colsep - - Specifies whether a rule will be drawn to the right of entries in the column. - 0, 1 (default) - - - - rowsep - - Specifies whether a rule will be drawn between the rows in the column. - 0, 1 (default) - - - - align - - Specifies the horizontal alignment of the entries in the column. - center, justify, right, left (default) - - - - colnum - - Specifies the number of the column being specified. - 1<=X<=number of columns - - - - colname - - Specifies a unique identifier by which the column can be referenced by other elements in the group. - a unique string - - - - colwidth - - Specifies the width of the column. - Can be either a fixed measure using either points (pts), inches (in), or centimeters (cm). - - - -
- - Attributes not listed in are not used in Evergreen' documentation. - - - - Example - shows the markup for specifying a -column that is two inches wide and whose content is justified. - - - Setting Column Properties - <table ...> - <title>...</title> - <tgroup ... > - <colspec align="justify" colwidth="2in" colname="2incol" /> - ... - </tgroup> -</table> - - -
-
- Defining Spans - DocBook allows you to define properties for cells that span columns and -name them for use by the cells in the group. To define a span you use the -spanspec element. - - Required Attributes - The spanspec element has three -required attributes as described in . - - Required Attributes for the <tag class="element">spanspec</tag> Element - - - - - Attribute - Description - - - - - - spanname - - Specifies the name by which cells will refer to the span. - - - - namest - - Specifies the name, as declared in a colspec element's colname attribute, of the starting column for the span. - - - - nameend - - Specifies the name, as declared in a colspec element's colname attribute, of the ending column for the span. - - - -
- - - Optional Attributes - In addition to the required attributes, the spanspec element can also have the attributes -described in . Attributes in the spanspec element override corresponding attributes -in the parent tgroup element and the -table's root element. - - Optional Attributes for the <tag class="element">spanspec</tag> Element - - - - - Attribute - Description - Values - - - - - - colsep - - Specifies whether a rule will be drawn to the right of entries in the span. - 0, 1 (default) - - - - rowsep - - Specifies whether a rule will be drawn below the rows in the span. - 0, 1 (default) - - - - align - - Specifies the horizontal alignment of the entry in the span. - center, justify, right, left (default) - - - -
- - Attributes not listed in are not used in Evergreen' documentation. - - - - Example - shows the markup for a span that crosses -the second and third column of a five column table. The contents of the span -are centered. - - - Defining a Span - <informaltable ...> - <tgroup cols="5" > - <colspec colnum="2" colname="c2" /> - <colspec colnum="3" colname="c3" /> - <spanspec spanname="midspan" namest="c2" nameend="c3" - align="center" /> - ... -</informaltable> - - -
-
- Adding a Heading Row to a Table - Tables in Evergreen documentation generally have one heading row. They are specified -using a thead element. The thead element is a child of a -tgroup element. It must be placed after any colspec elements and spanspec elements. It should also be placed before -any tbody elements. - - Attributes - lists the attributes of the thead element. - - Attributes for the <tag class="element">thead</tag> Element - - - - - Attribute - Description - Values - - - - - - valign - - Specifies the vertical alignment of the entry in the heading. - top, bottom, middle (default) - - - -
- - - Adding content - The content of the heading row is specified using a single row element and one entry child element for each column in the table. For more -information on the row element and the entry element see and . - - - Example - shows the markup for tables used in this -chapter. - - Adding a Table Header - <table ...> - <tgroup cols="3" > - <colspec ... /> - <thead> - <row> - <entry align="center"> - Attribute - </entry> - <entry align="center"> - Description - </entry> - <entry align="center"> - Values - </entry> - </row> - </thead> - ... - </tgroup> -</informaltable> - - -
-
- Adding Rows to a Table - The rows that make up the body of a table are defined inside of a -tbody element. Each row in the table is -defined using a row element. The contents -of each column in the row is defined using an entry element. - - The <tag class="element">tbody</tag> Element - The tbody element is a wrapper for -all of the rows in the body of a group. It is placed after all of the colspec elements, all of the spanspec elements, and the thead element. It has a single attribute, valign, that is described in . - - - The <tag class="element">row</tag> Element - Rows in a table are defined using the row element. -Each row element wraps a number of entry -children elements that cannot exceed the number columns specified in the -tgroup element's cols attribute. It is -possible to have less entry child elements. This can happen -when you wish to have empty columns, when one entry spans multiple columns, or -if there is an entry from a previous row that vertically spans the row being -specified. - - When spans are being used the number of entry -elements plus the number of columns being spanned cannot add up to more than -the number of columns defined for the group. - - The row element has two attributes as -described in . Attributes in the row element override corresponding attributes in the -parent tbody element, the enclosing -tgroup element, the colspec elements in the group, and the table's root -element. - - Attributes for the <tag class="element">row</tag> Element - - - - - Attribute - Description - Values - - - - - - rowsep - - Specifies whether a rule will be drawn below all of the entries in the row. - 0, 1 (default) - - - - valign - - Specifies the vertical alignment of the entry in the heading. - top, bottom, middle (default) - - - -
- - - The <tag class="element">entry</tag> Element - The contents of of a table are specified using entry -elements. entry elements are children of the -row element and hold the contents for a column in the -row. - The contents of a table entry can be specified using either text with -in-line markup elements or using block-level markup elements such as the -para element, the procedure element, or one of the list types. -However, if you intend to use one of the block-level markup elements you must -place all of the content inside a block-level element. For example, if you -want to use a list in a table entry, along with some text outside the list, -you must place all of the content, including the list, inside a para element. - The entry element's attributes are -described in . Attributes in the entry element override corresponding attributes in -the parent row element, the enclosing -tbody element, the enclosing tgroup element, the colspec elements in the group, the spansec elements in the group, and the table's root -element. - - Attributes for the <tag class="element">entry</tag> Element - - - - - Attribute - Description - Values - - - - - - rowsep - - Specifies whether a rule will be drawn below the entry. - 0, 1 (default) - - - - valign - - Specifies the vertical alignment of the entry. - top, bottom, middle (default) - - - - colsep - - Specifies whether a rule will be drawn to the right of the entry. - 0, 1 (default) - - - - namest - - Specifies the name of the left-most column the entry will span. - The value of the name attribute of the colspec element defining the left-most column of the span. - - - - nameend - - Specifies the right-most column the entry will span. - The value of the name attribute of the colspec element defining the right-most column of the span. - - - - spanname - - Specifies a defined span to use for the entry. This attribute should not be used with namest and nameend. - The value of the name attribute of the spanspec element defining the span to use for the entry. - - - - align - - Specifies the horizontal alignment of the contents in the entry. - center, justify, right, left (default) - - - - morerows - - Specifies the number of additional rows the entry will span. - >1 - - - - colname - - - Specifies the column, defined by a colspec element, in which the entry belongs. - Note: You must specify entries rom left to right. - - The value of the name attribute of the colspec element defining the column of the span. - - - -
- - Attributes not listed in are not used in Evergreen' documentation. - - - - Example - shows the markup for tables used in this -chapter. - - - Add Rows to a Table - <table ...> - <tgroup cols="3" > - <colspec ... /> - ... - <tbody> - <row> - <entry> - <tag class="attribute">colsep</tag> - </entry> - <entry>Specifies whether a rule will be drawn to - the right of entries in the span.</entry> - <entry> - <tag class="attvalue">0</tag>, - <tag class="attvalue">1</tag> - (default)</entry> - </row> - <row> - <entry> - <tag class="attribute">rowsep</tag> - </entry> - <entry>Specifies whether a rule will be drawn below - the rows in the span.</entry> - <entry> - <tag class="attvalue">0</tag>, - <tag class="attvalue">1</tag> - (default)</entry> - </row> - <row> - <entry><tag>align</tag></entry> - <entry>Specifies the horizontal alignment of - the entry in the span.</entry> - <entry> - <tag class="attvalue">center</tag>, - <tag class="attvalue">justify</tag>, - <tag class="attvalue">right</tag>, - <tag class="attvalue">left</tag> - (default)</entry> - </row> - </tbody> - </tgroup> -</informaltable> - - -
-
- Example - shows a table that uses most of the -features of a table. - - Complicated Table - - - - - - - - - - - - c1 - c2 - c3 - c4 - c5 - c6 - - - - - Pomegranate - Pineapple - Mango - Carambola - Banana - Papaya - - - Apples - Kiwis - Passion Fruits - Watermelon - - - Strawberries - Cantaloupe - Tamarind - - - Lichee - Boysenberry - Guava - - - -
- shows the markup for . - - - Markup for a Table - <table xml:id="tableexample" pgwide="1"> - <title>Complicated Table</title> - <tgroup cols="6"> - <colspec align="center" colname="c1" colnum="1" /> - <colspec align="justify" colname="c2" colnum="2" /> - <colspec colname="c3" /> - <colspec colname="c4" colnum="4" /> - <colspec align="right" colname="c5" colnum="5" /> - <colspec align="left" colname="c6" /> - <spanspec align="center" nameend="c5" namest="c2" - spanname="25" /> - <spanspec align="left" nameend="c4" namest="c1" - spanname="14" /> - <thead> - <row> - <entry>c1</entry> - <entry>c2</entry> - <entry>c3</entry> - <entry>c4</entry> - <entry>c5</entry> - <entry>c6</entry> - </row> - </thead> - <tbody> - <row> - <entry>Pomegranate</entry> - <entry>Pineapple</entry> - <entry>Mango</entry> - <entry>Carambola</entry> - <entry>Banana</entry> - <entry>Papaya</entry> - </row> - <row> - <entry>Apples</entry> - <entry align="right">Kiwis</entry> - <entry align="center" nameend="c5" - namest="c3">Passion - Fruits</entry> - <entry>Watermelon</entry> - </row> - <row> - <entry spanname="14">Strawberries</entry> - <entry>Cantaloupe</entry> - <entry>Tamarind</entry> - </row> - <row> - <entry>Lichee</entry> - <entry spanname="25">Boysenberry</entry> - <entry>Guava</entry> - </row> - </tbody> - </tgroup> -</table> - -
-
- -- 2.11.0