You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
131 lines
7.6 KiB
XML
131 lines
7.6 KiB
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><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><documentStatus></literal> field which generally
|
|
needs to be reset to the <literal>draft</literal> value. In addition, for non-public work groups, the <literal><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><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><revhistory></literal> table. To start a new entry,
|
|
add a new <literal><revision></literal> entry with <literal><date></literal> and <literal><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>
|
|
|