CAPI-SNAP-Doc/doc_dev_guide/bk_main.xml

<?xml version="1.0" encoding="UTF-8"?>
<!--
  Copyright (c) 2016 OpenPOWER Foundation
  
  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
  
-->

<!-- The following entity variable is used to reflect the version of the 
     template document master used for building a document.  This value
     should be set by copy of the of template used to create a new
     document and should not be changed.  Use of this value is in
     in the Abstract section in this file. --> 
<!DOCTYPE book [
<!ENTITY template_version "1.1.0">
]>

<book xmlns="http://docbook.org/ns/docbook"
  xmlns:xi="http://www.w3.org/2001/XInclude"
  xmlns:xlink="http://www.w3.org/1999/xlink"
  version="5.0"
  xml:id="bk_main">

    <!-- TODO: Pick a Title for the new document -->
    <title>Documentation Development Guide</title>
    <!-- TODO: Either add a subtitle or remove the following line -->
    <subtitle>A quick start template</subtitle>

    <info>
    <author>
      <!-- TODO: Set to the appropriate owning Work Group, not an individual -->
      <personname>
          System Software Work Group
      </personname>
      <!-- TODO: Set email address of document author to the Work Group Chair -->
      <email>syssw-chair@openpowerfoundation.org</email>
      <affiliation>
          <orgname>OpenPower Foundation</orgname>
      </affiliation>
    </author>
    <copyright>
      <!-- TODO: Set copyright year -->
      <year>2015, 2016, 2017, 2018</year>
      <holder>OpenPOWER Foundation</holder>
    </copyright>
    <!-- TODO: Set the correct document releaseinfo -->
    <releaseinfo>Revision 1.2</releaseinfo>
    <productname>OpenPOWER</productname>
    <pubdate/>

    <!-- TODO: Select one of the two following legalnotice role= values:
           "apache2" for an Apache V2 license or 
           "opfExternal" for an official OpenPOWER Foundation external license text.
         If you don't know which one to select, change to "opfExternal" and ask your TSC representative. -->
    <legalnotice role="apache2">
    <!--legalnotice role="opfExternal"-->

      <annotation>
          <remark>Copyright details are filled in by the template.</remark>
      </annotation>
    </legalnotice>
    
    <!-- TODO: Update the following text with the correct document description (first paragraph),
               Work Group name, and Work Product track (both in second paragraph). -->
    <abstract>
      <para>The purpose of this document is to provide a guide for OpenPOWER
      documentation writers.  As such, it provides directions, policies, references, and 
      examples of the XML Docbook environment.  It is intended to be used both in final product form
      (PDF and html) as a document and in source form as a template for new documents.</para>
      <para>This document is a Non-standard Track, Work Group Note work product owned by the
      System Software Workgroup and handled in compliance with the requirements outlined in the
      <citetitle>OpenPOWER Foundation Work Group (WG) Process</citetitle> document.  It was
      created using the <citetitle>Document Development Guide</citetitle> version &template_version;.
      Comments, questions, etc. can be submitted to the public mailing list  for this document at 
      <email>syssw-doc_devel_guide@mailinglist.openpowerfoundation.org</email>.  Additionally,
      the #doc-devel channel in the OpenPOWER Foundation Slack room 
      (<link xlink:href="https://openpowerfoundation.slack.com/">openpowerfoundation.slack.com</link>)
      can be used to answer more interactive questions.</para>
    </abstract>

    <revhistory>
      <!-- TODO: Set the initial version information and clear any old information out -->
      <revision>
          <date>2018-08-27</date>
          <revdescription>
            <para>Version 1.2 additional updates:
            <itemizedlist spacing="compact">
              <listitem>
                <para>Add a section on circumventing Java AWT exception.</para>
              </listitem>
              <listitem>
                <para>Add information on key document tags which need update for new documents.</para>
              </listitem>
              <listitem>
                <para>Extend information on modifying an existing document to include a step-by-step description of how to get started.</para>
              </listitem>
              <listitem>
                <para>Rename the <literal>template</literal> directory to <literal>doc_dev_guide</literal>.</para>
              </listitem>
            </itemizedlist></para>
          </revdescription>
      </revision>
      <revision>
          <date>2018-04-11</date>
          <revdescription>
            <para>Version 1.2 updates:
            <itemizedlist spacing="compact">
              <listitem>
                <para>Extend the Getting Started section to include a first document build.</para>
              </listitem>
              <listitem>
                <para>Add a section on document packaging for publish in the Publishing OpenPOWER Documents section.</para>
              </listitem>
               <listitem>
                <para>Add examples for background color in tables, and variablelists.</para>
              </listitem>
           </itemizedlist></para>
          </revdescription>
      </revision>
      <revision>
          <date>2017-02-17</date>
          <revdescription>
            <para>Version 1.1.0 updates:
            <itemizedlist spacing="compact">
              <listitem>
                <para>Enhancements document creation to address project creation and update process.</para>
              </listitem>
              <listitem>
                <para>Add "git" error to troubleshooting sections until JAR dependency removed.</para>
              </listitem>
              <listitem>
                <para>Add optional font installation step to getting started.</para>
              </listitem>
              <listitem>
                <para>Provide samples of how to access symbols by value, including extension for
                new symbol library.</para>
              </listitem>
              <listitem>
                <para>Provide example usage of OPF Docbook extensions -- hard page breaks, soft line breaks,
                font-size changes, setting text color, and explicitly using symbol library.</para>
              </listitem>
              <listitem>
                <para>Extend explanation of versioning policy.</para>
              </listitem>
              <listitem>
                <para>Correct, improve miscellenous wording and grammar.</para>
              </listitem>
            </itemizedlist></para>
          </revdescription>
      </revision>
      <revision>
          <date>2016-09-13</date>
          <revdescription>
            <itemizedlist spacing="compact">
              <listitem>
                <para>Version 1.0.1: Minor updates to guide naming.</para>
              </listitem>
            </itemizedlist>
          </revdescription>
      </revision>
      <revision>
          <date>2016-08-25</date>
          <revdescription>
            <itemizedlist spacing="compact">
              <listitem>
                <para>Version 1.0.0: Document approval for publish</para>
              </listitem>
            </itemizedlist>
          </revdescription>
      </revision>
      <revision>
          <date>2016-04-28</date>
          <revdescription>
            <itemizedlist spacing="compact">
              <listitem>
                <para>Version 0.9.5: Removal of confidentiality and preview of change notations for final review by TSC.</para>
              </listitem>
            </itemizedlist>
          </revdescription>
      </revision>
      <revision>
          <date>2016-03-21</date>
          <revdescription>
            <itemizedlist spacing="compact">
              <listitem>
                <para>Version 0.9.4: Review version for TSC.</para>
              </listitem>
            </itemizedlist>
          </revdescription>
      </revision>
      <revision>
          <date>2016-02-25</date>
          <revdescription>
            <itemizedlist spacing="compact">
              <listitem>
                <para>Version 0.9.3: Technical and process updates. Addition of documentation lifecycle and git command cheat sheets.</para>
              </listitem>
            </itemizedlist>
          </revdescription>
      </revision>
      <revision>
          <date>2016-02-25</date>
          <revdescription>
            <itemizedlist spacing="compact">
              <listitem>
                <para>Version 0.9.2: Technical and process updates. Explanation of project structure.</para>
              </listitem>
            </itemizedlist>
          </revdescription>
      </revision>
      <revision>
          <date>2016-01-25</date>
          <revdescription>
            <itemizedlist spacing="compact">
              <listitem>
                <para>Version 0.9.1: Technical and process updates.</para>
              </listitem>
            </itemizedlist>
          </revdescription>
      </revision>
      <revision>
          <date>2015-08-20</date>
          <revdescription>
            <itemizedlist spacing="compact">
              <listitem>
                <para>Version 0.9: Draft for format review with TSC.</para>
              </listitem>
            </itemizedlist>
          </revdescription>
      </revision>
      <revision>
          <date>2014-09-03</date>
          <revdescription>
            <itemizedlist spacing="compact">
              <listitem>
                <para>Creation based on OpenStack documentation</para>
              </listitem>
            </itemizedlist>
          </revdescription>
      </revision>
     </revhistory>
    </info>

  <!-- The ch_preface.xml file is required by all documents -->
  <xi:include href="../../Docs-Master/common/ch_preface.xml"/>

  <!-- TODO: Add your chapter heading files here.  Remove both files and insert your own. -->
  <!--       See the template document for naming conventions and location of files.      -->
  <xi:include href="ch_template_overview.xml"/>
  <xi:include href="ch_example.xml"/>

  <!-- The app_foundation.xml appendix file is required by all documents. -->
  <xi:include href="../../Docs-Master/common/app_foundation.xml"/>

  <!-- TODO: The following template document may be modified to create additional appendices as needed. -->
  <xi:include href="app_template.xml"/>

</book>