OpenPOWER Library

 1.4. Modifying an existing document

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 Section 1.1.4, “Cloning master document information”.

To obtain a copy of the desired document source, clone its project. For example, to clone this document, Documentation Development Guide, from the public OpenPOWER Foundation git repository, use this command:

$ git clone https://github.com/OpenPOWERFoundation/Docs-Template.git
Cloning into 'Docs-Template'...
Username for 'https://github.com': my_userid
Password for 'https://[email protected]': my_password
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.
$ 

To build a specific document such as this guide, follow these steps from the directory where you just cloned:

$ cd Docs-Template/doc_dev_guide
$ mvn clean
[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] ------------------------------------------------------------------------
$ mvn generate-sources
[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] ------------------------------------------------------------------------
$ 
[Note]Note

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 mvn clean generate-sources would accomplish the same thing as the above sequence of commands.

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

For assistance correcting commmon build failures, see Section 1.5, “Debugging build failures”.

[Note]Note

Projects may contain multiple documents. While specific documents can be built by executing a mvn clean generate-sources in the specific document directory, executing this command in the base project directory will build all projects identified in the <module> list in the top-level pom.xml file, known as the "Workgroup POM".

Before diving deeply into text updates, you should consider the following items for your project and document:

  • Ensure that the previous version of the tree is tagged.

    The command git tag may be used to see existing tree tags and set new ones. See Section 1.9, “Common git commands” for more specifics on git tag commands.

  • Reset the document status.

    The pom.xml file contains the <documentStatus> field which generally needs to be reset to the draft value. In addition, for non-public work groups, the <security> field should be returned to workgroupConfidential or foundationConfidential values during the document update process. More information on document development process can be found in Section 1.6, “Publishing OpenPOWER Documents”. Detailed information on key document settings can be found in Section 1.6.1, “Understanding document marking variables in the pom.xml file” and Section 1.6.2, “Navigating the OpenPOWER Foundation documentation publishing process”.

  • Incement the new document release information.

    The bk_main.xml file contains the <releaseinfo> 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.

    More details on the release information can be found in Section 1.7, “Policies and conventions” recommendation 2.

  • Create a new entry in the revision history.

    The bk_main.xml file contains the revision history in <revhistory> table. To start a new entry, add a new <revision> entry with <date> and <revdescription> fields at the top of the list of revisions.

You are now ready to make textual updates.


loading table of contents...