CAPI-SNAP-Doc/doc_dev_guide/sec_template_existing_document.xml

<!--
  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.
  
-->
<section version="5.0" xml:lang="en" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_existing_document">

  <title xml:id="section_template_existing_document_title">Modifying an existing document</title>

    <para>To begin editing an existing document, you may need to clone up to two projects -- 
    the specific document project, and if not already cloned, the master document framework project too.
    If needed, clone the master document as described in <xref linkend="section_cloning_master_doc"/>.</para>
      
    <para>To obtain a copy of the desired document source, clone its project.  For example, to clone this document, 
    <citetitle>Documentation Development Guide</citetitle>, from the 
    public OpenPOWER Foundation git repository, use this 
    command:<screen><prompt>$ </prompt><userinput>git clone https://github.com/OpenPOWERFoundation/Docs-Template.git</userinput>
Cloning into 'Docs-Template'...
Username for 'https://github.com': <userinput>my_userid</userinput>
Password for 'https://my_userid@github.com': <userinput>my_password</userinput>
remote: Counting objects: 62, done.
remote: Compressing objects: 100% (10/10), done.
remote: Total 62 (delta 2), reused 0 (delta 0), pack-reused 52
Unpacking objects: 100% (62/62), done.
Checking connectivity... done.
<prompt>$ </prompt></screen></para>

    <para>To build a specific document such as this guide, follow these steps from the directory where 
    you just cloned:<screen><prompt>$ </prompt><userinput>cd Docs-Template/doc_dev_guide</userinput>
<prompt>$ </prompt><userinput>mvn clean</userinput>
[INFO] Scanning for projects...
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] Building OpenPOWER Template Guide 1.0.0-SNAPSHOT
[INFO] ------------------------------------------------------------------------
[INFO] 
[INFO] --- maven-clean-plugin:2.5:clean (default-clean) @ openpower-template-guide ---
[INFO] Deleting ~/Docs-Template/doc_dev_guide/target
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 0.353s
[INFO] Finished at: Wed Feb 25 12:54:47 CST 2015
[INFO] Final Memory: 3M/7M
[INFO] ------------------------------------------------------------------------
<prompt>$ </prompt><userinput>mvn generate-sources</userinput>
[INFO] Scanning for projects...
[INFO]                                                                         
[INFO] ------------------------------------------------------------------------
[INFO] Building OpenPOWER Template Guide 1.0.0-SNAPSHOT
[INFO] ------------------------------------------------------------------------
[INFO] 
[INFO] --- openpowerdocs-maven-plugin:1.0.0:generate-webhelp (generate-webhelp) @ openpower-template-guide ---
[INFO] Processing input file: bk_main.xml
...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 20.361s
[INFO] Finished at: Wed Feb 25 12:55:15 CDT 2015
[INFO] Final Memory: 30M/390M
[INFO] ------------------------------------------------------------------------
<prompt>$ </prompt></screen></para>

    <note><para>The permutations of Maven invocations may be combined into one operation where the parameters are specified in the order
    in which one wishes to execute them.  Thus, the command <literal>mvn clean generate-sources</literal> would accomplish the 
    same thing as the above sequence of commands.</para></note>

    <para>If all goes well, the generated pdf should be available in <literal>~/Docs-Template/doc_dev_guide/target/docbkx/webhelp/template-guide/</literal>.</para>

    <para>For assistance correcting commmon build failures, see <xref linkend="section_template_debug"/>.</para>

    <note><para>Projects may contain multiple documents. While specific documents can be built by executing a 
    <literal>mvn clean generate-sources</literal> in the specific document directory, executing this command in
    the base project directory will build all projects identified in the <literal>&lt;module></literal> list in the
    top-level <literal>pom.xml</literal> file, known as the "Workgroup POM".</para></note>
    
    <para>Before diving deeply into text updates, 
    you should consider the following items for your project and document:
    <itemizedlist>
      <listitem>
        <para>Ensure that the previous version of the tree is tagged.</para>
        
        <para>The command <literal>git tag</literal> may be used to see existing tree tags
        and set new ones.
        See <xref linkend="section_template_git_commands"/> for more specifics on <literal>git tag</literal> commands.</para>
      </listitem>
      <listitem>
        <para>Reset the document status.</para>
        <para>The <literal>pom.xml</literal> file contains the <literal>&lt;documentStatus></literal> field which generally
        needs to be reset to the <literal>draft</literal> value.  In addition, for non-public work groups, the <literal>&lt;security></literal>
        field should be returned to <literal>workgroupConfidential</literal> or <literal>foundationConfidential</literal>
        values during the document update process.  More information on 
        document development process can be found in <xref linkend="section_template_process"/>.  Detailed information on
        key document settings can be found in <xref linkend="section_template_process_pom"/> and 
        <xref linkend="section_template_process_flowchart"/>.</para>
      </listitem>
      <listitem>
        <para>Incement the new document release information.</para>
        <para>The <literal>bk_main.xml</literal> file contains the <literal>&lt;releaseinfo></literal> field
        which contains the Versions, Release, and Modification values.  Typically, new documents when first being edited will increment the correct value,
        reset sub-values to zero, and append a "_preN" tag.  During the development process, you will likely increment the "N-value" in your "pre" release 
        information.  Then, at publish, you can remove the "_preN" suffix.</para>
        <para>More details on the release information can be found in <xref linkend="section_template_policies"/> recommendation 
        <xref linkend="section_template_vrm_policy" xrefstyle="select: nopage"/>.</para>
      </listitem>
      <listitem>
        <para>Create a new entry in the revision history.</para>
        <para>The <literal>bk_main.xml</literal> file contains the revision history in <literal>&lt;revhistory></literal> table.  To start a new entry,
        add a new <literal>&lt;revision></literal> entry with <literal>&lt;date></literal> and <literal>&lt;revdescription></literal> fields at the top
        of the list of revisions.</para>
      </listitem>
    </itemizedlist></para>
    
    <para>You are now ready to make textual updates.</para>
    
</section>