- Technical updates to reflect new project structure.
- Addition of project structure section to explain project relationships.
- General readability improvements.
Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
<title>Example of code citations and user input</title>
<title>Example of code citations and user input</title>
<para>When showing user input, you want a nice sceen-looking layout, a prompt, monospace text, and a way to differentiate input from output. Here's an example:
<para>When showing user input, you want a nice sceen-looking layout, a prompt, monospace text, and a way to differentiate input from output. Here's an example:
<para>Docbook also allows for formatting and display of common languages, allowing for whitespace
<para>Docbook also allows for formatting and display of common languages, allowing for whitespace
and line returns just as they are written. Here's a sample snippet of C code with line numbering enabled:<programlisting linenumbering="numbered"><![CDATA[#include<stdio.h>
and line returns just as they are written. Here's a sample snippet of C code with line numbering enabled:<programlisting linenumbering="numbered"><![CDATA[#include<stdio.h>
<para>Maven/docbkx failures generally fall into one of two categories, validation errors or build failures. Correcting the document begins with understanding which type of failure has occurred and understanding where to look in your document source.</para>
<para>Maven/docbkx failures generally fall into these categories:</para>
<para>Correcting the document errors starts with understanding which type of failure has occurred and
understanding where to look in your document source.</para>
<section>
<title>Project structure errors</title>
<para>Because the OpenPOWER Foundation documentation projects are not self-contained in the
GitHub repositories, forgetting to clone the <literal>Docs-Master</literal> project in addition
to the document project or cloning it in the wrong location is a common problem. Failures of this kind
produce the following error:</para>
<screen>...
[INFO] Scanning for projects...
[ERROR] The build could not read 1 project -> [Help 1]
[ERROR]
[ERROR] The project org.openpowerfoundation.docs:workgroup-pom:1.0.0-SNAPSHOT (/home/scheel/Docs-Template/pom.xml) has 1 error
[ERROR] Non-resolvable parent POM: Could not find artifact org.openpowerfoundation.docs:master-pom:pom:1.0.0-SNAPSHOT and 'parent.relativePath' points at wrong local POM @ line 6, column 11 -> [Help 2]
[ERROR]
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR]
[ERROR] For more information about the errors and possible solutions, please read the following articles:
<para>The location within the file of the syntax error. For the above example, the key information is "<literal>lineNumber: 272; columnNumber: 70</literal>.</para>
<para>The location within the file of the syntax error. For the above example, the key information is "<literal>lineNumber: 272; columnNumber: 70</literal>.</para>
@ -35,6 +79,12 @@ lineNumber: 272; columnNumber: 70; text not allowed here; expected element "add
<para>An explanation of the failure. This information in the above error reads, "text not allowed here; expected element "address", ...".</para>
<para>An explanation of the failure. This information in the above error reads, "text not allowed here; expected element "address", ...".</para>
</listitem>
</listitem>
</orderedlist>
</orderedlist>
</section>
<section>
<title>Build failures</title>
<para>Build errors are easily identified as well. Below is an example:
<para>Build errors are easily identified as well. Below is an example:
[ERROR] Failed to execute goal org.openpowerfoundation.docs:openpowerdocs-maven-plugin:1.0.0:generate-webhelp (generate-webhelp) on project openpower-template-guide: Execution generate-webhelp of goal org.openpowerfoundation.docs:openpowerdocs-maven-plugin:1.0.0:generate-webhelp failed: XInclude resource error (sec_template_new_document.xml) and no fallback provided. XProc error err:XD0011: org.xml.sax.SAXParseException; systemId: file:/home/user1/openpower-foundation-docbkx-framework/doc/template/sec_template_new_document.xml; lineNumber: 55; columnNumber: 17; The element type "para" must be terminated by the matching end-tag "</para>". -> [Help 1]...
[ERROR] Failed to execute goal org.openpowerfoundation.docs:openpowerdocs-maven-plugin:1.0.0:generate-webhelp (generate-webhelp) on project openpower-template-guide: Execution generate-webhelp of goal org.openpowerfoundation.docs:openpowerdocs-maven-plugin:1.0.0:generate-webhelp failed: XInclude resource error (sec_template_new_document.xml) and no fallback provided. XProc error err:XD0011: org.xml.sax.SAXParseException; systemId: file:/home/user1/openpower-foundation-docbkx-framework/doc/template/sec_template_new_document.xml; lineNumber: 55; columnNumber: 17; The element type "para" must be terminated by the matching end-tag "</para>". -> [Help 1]...
</screen></para>
</screen></para>
<para>Like validation errors, three key pieces of information are again provided:</para>
<para>Like validation errors, three key pieces of information are again provided:</para>
<orderedlist>
<orderedlist>
<listitem>
<listitem>
<para>The full path and filename of our failure is
<para>The full path and filename of our failure is
<para>The location within the file of the error is "<literal>lineNumber: 55; columnNumber: 17</literal>.</para>
<para>The location within the file of the error is "<literal>lineNumber: 55; columnNumber: 17</literal>.</para>
</listitem>
</listitem>
<listitem>
<listitem>
<para>An explanation of the failure begins with the text, "The element type "para" must be terminated by the matching end-tag "</para>."</para>
<para>An explanation of the failure begins with the text, "The element type "para" must be terminated by the
matching end-tag "</para>."</para>
</listitem>
</listitem>
</orderedlist>
</orderedlist>
<para>With these details in hand for either error, one simply locates the offending syntax and makes the appropriate correction. Online resources such as those listed in <xref linkend="section_template_references"/> may be helpful.</para>
<para>With these details in hand for either error, one simply locates the offending syntax and makes the appropriate
correction. Online resources such as those listed in <xref linkend="section_template_references"/> may be helpful.</para>
<para>To obtain a copy of the existing template document framework and all public documents from the
public OpenPOWER git repository, simply clone the project using this command:<screen><prompt>$</prompt><userinput>git clone https://github.com/open-power/openpower-foundation-docbkx-framework.git</userinput>
<para>To begin editing an existing document, you must first clone two projects -- the master document framework project and
Cloning into 'openpower-foundation-docbkx-framework'...
the specific document project. Begin by cloning the master document as described in <xref linkend="section_cloning_master_doc"/>.</para>
<para>To build a document such as the template guide, follow these steps from the directory where you just cloned:<screen><prompt>$</prompt><userinput>cd openpower-foundation-docbkx-framework/doc/template</userinput>
<para>To build a specific document such as the template guide, follow these steps from the directory where
<para>If all goes well, the generated pdf should be available in <literal>~/openpower-foundation-docbkx-framework/doc/template/target/docbkx/webhelp/template-guide/</literal>.</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/template/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>To successfully build OpenPOWER Foundation documents, common document files must be in place in addition to the specific
document files. These common files are obtained by cloning the OpenPOWER Foundation public project <literal>Docs-Master</literal>.</para>
<para>To clone the master template document framework use the clone git command:<screen><prompt>$ </prompt><userinput>git clone https://github.com/OpenPOWERFoundation/Docs-Master.git</userinput>
<para>Creating a new document from scratch follows four simple steps:</para>
<para>Creating a new document from scratch follows four simple steps:</para>
<orderedlist>
<orderedlist>
<listitem>
<listitem>
<para>Clone the appropriate template document framework.</para>
<para>Cloning the project source.</para>
</listitem>
</listitem>
<listitem>
<listitem>
<para>Copy the template directory into a new project directory.</para>
<para>Finding a document framework.</para>
</listitem>
</listitem>
<listitem>
<listitem>
<para>Modify core project files.</para>
<para>Modifying core project files.</para>
</listitem>
</listitem>
<listitem>
<listitem>
<para>Begin adding document content, either from scratch or from another document.</para>
<para>Adding new document content.</para>
</listitem>
</listitem>
</orderedlist>
</orderedlist>
<section>
<section>
<title>Cloning the base document framework</title>
<title>Clone the project source.</title>
<para>All new projects need to begin by cloning the appropriate documentation template. The template document project resides at <link xlink:href="https://github.com/open-power/openpower-foundation-docbkx-framework.git">https://github.com/open-power/openpower-foundation-docbkx-framework.git</link>. This template should be used for both private and public OpenPOWER Foundation documents.</para>
<para>All documentation projects reside in a project directory maintained in GitHub, just like the
<para>To clone the existing template document framework use the clone git command:<screen><prompt>$</prompt><userinput>git clone https://github.com/open-power/openpower-foundation-docbkx-framework.git</userinput>
<literal>Docs-Master</literal> framework described in <xref linkend="section_cloning_master_doc"/>. In the same directory
Cloning into 'openpower-foundation-docbkx-framework'...
where the <literal>Docs-Master</literal> project has been cloned, you will need to
remote: Counting objects: 288, done.
clone the documentation source for your project. A list of the OpenPOWER Foundation projects can be found at
<prompt>$ </prompt></screen> The results should look roughly something like above with actual numbers of objects, files, etc. varying
<para>This command clones the head of the git tree into your current working directory. If successful, the contents of the current directory should now include a new <literal>openpower-foundation-docbkx-framework</literal> directory.</para>
for different projects.</para>
<note><para>Private projects prompt for a GitHub userid and and password. When cloning public projects, these prompts
are skipped.</para></note>
<para>The base project has now been cloned.</para>
</section>
</section>
<section>
<section>
<title>Copying the template directory into a new project directory</title>
<title>Finding a document framework</title>
<para>To create a new document directory, follow these steps:</para>
<para>If this is your first document, in a brand new project (git tree), you have the fewest number of steps
to perform because your project should have been primed with a single project based on <literal>Docs-Template</literal>.
You can verify this by inspecting
the files in your project directory. A new project will contain a <literal>template</literal> directory, a <literal>pom.xml
</literal> file, a <literal>LICENSE</literal> file, and a <literal>README.md</literal> file. If this is the case, you simply
need to perform the following three steps:</para>
<orderedlist>
<orderedlist>
<listitem>
<listitem>
<para>Navigate down to the <literal>doc</literal> sub-directory. On Linux and Mac OS command lines, this can be achieved using the <literal>cd</literal> command:
<para>Navigate down to your project directory, called <literal>my_project</literal> for this example. This can be achieved
<para>This directory should contain at least two directories, one named <literal>doc</literal> and another <literal>template</literal>, as well as a <literal>pom.xml</literal> file.</para>
<prompt>$ </prompt></screen></para>
<para>This directory should contain the <literal>template</literal> folder used to prime the project.</para>
</listitem>
</listitem>
<listitem>
<listitem>
<para>To create a new project directory, simply create a new directory and copy the contents of the <literal>template</literal> directory. If creating a new project named <literal>my_proj</literal> via a command line in Linux or Mac OS, the command sequence would look like this:
<para>Rename the <literal>template</literal> document directory to something new like <literal>my_doc</literal>.
<para>Once copied, the Docs-Template directory and all its contents should be removed from your project so that it does accidentally get
included in your project. The command <userinput>rm -rf Docs-Template</userinput></para>
</listitem>
<listitem>
<para>Finally, add the new project to the workgroup POM.xml file. Using your editor, add the following lines
between the <modules> and the </modules> tags near the top of the file:<programlisting><![CDATA[<module>my_doc</module>
]]></programlisting></para>
</listitem>
</orderedlist>
<note><para>Before committing the project back to git, you will need to add the new directory to the git repository. This can
be performed using the <literal>git add my_doc/</literal> command on the whole directory.</para></note>
<warning><para></para></warning>
<para>You are now ready to begin making updates to your new document. The next section will provided detailed steps of where to
get started.</para>
</section>
</section>
<section>
<section xml:id="section_modifying_project">
<title>Modifying core project files</title>
<title>Modifying core project files</title>
<para>The first step to customizing a new project is to modify two core project files--<literal>pom.xml</literal> and <literal>bk_main.xml</literal>. Within these two files are XML comment tags that begin "<literal><!-- TODO:</literal>" to identify places which need customization. The surrounding comments will provide guidance on what needs to change and how it may be changed. Simply work through each item, making updates as requested.</para>
<para>The first step to customizing a new project is to modify two core project files--<literal>pom.xml</literal>
<note><para>Be sure to remember two key values you used in the <literal>pom.xml</literal> file, <literal><webhelpDirname></literal> and <literal><pdfFilenameBase></literal>, as these will be used to locate your generated document.</para></note>
and <literal>bk_main.xml</literal>. Within these two files are XML comment tags that begin "<literal><!-- TODO:</literal>"
<para>When complete, be sure to build your new document using standard maven commands like this:<screen><prompt>$</prompt><userinput>cd openpower-foundation-docbkx-framework/doc/template</userinput>
to identify places which need customization. The surrounding comments will provide guidance on what needs to change and how
<para>If all goes well, the new generated pdf should be available in <literal>target/docbkx/webhelp/<webhelpDirname>/<pdfFilenameBase>.pdf</literal>.</para>
<para>If all goes well, the new generated pdf should be available in
<para>For assistance correcting commmon build failures, see <xref linkend="section_template_debug"/>.</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>
</section>
</section>
<section>
<section>
<title>Adding new content</title>
<title>Adding new content</title>
<para>The starting point for book content is the <literal>bk_main.xml</literal> file (or whatever to which it was renamed in the previous step). Removal and additions of the main chapter files files will be controlled by entries near the end of that file which appear as follows:<programlisting><![CDATA[ <!-- The ch_preface.xml file is required by all documents -->
<xi:include href="../common/ch_preface.xml"/>
<para>The starting point for book content is the <literal>bk_main.xml</literal> file (or whatever to which it was renamed
in the previous step). Removal and additions of the main chapter files files will be controlled by entries near the
end of that file which appear as follows:<programlisting><![CDATA[ <!-- The ch_preface.xml file is required by all documents -->
<!-- TODO: The following template document may be modified to create additional appendices -->
<!-- TODO: The following template document may be modified to create additional appendices as needed. -->
<xi:include href="app_template.xml"/>
<xi:include href="app_template.xml"/>
]]></programlisting></para>
]]></programlisting></para>
<para>Copying and modifying existing files from the template or other documents is a great way to get started. When creating whole new chapter or appendix files from scratch, the <literal>ch_example.xml</literal> and <literal>app_template.xml</literal> files may serve as excellent starting points. For XML examples of various document structures, please see <xref linkend="section_template_examples"/> and its supporting source files in this document. Online resources such as those listed in <xref linkend="section_template_references"/> may also be helpful.</para>
<note><para>When creating new files for the project, remember to use the <literal>git add <file name></literal> command to add new files to the git tree.</para></note>
<para>Copying and modifying existing files from the template or other documents is a great way to get started. When creating
whole new chapter or appendix files from scratch, the <literal>ch_example.xml</literal> and <literal>app_template.xml</literal> files
may serve as excellent starting points. For XML examples of various document structures, please see <xref linkend="section_template_examples"/>
and its supporting source files in this document. Online resources such as those listed in <xref linkend="section_template_references"/>
may also be helpful.</para>
<note><para>When creating new files for the project, remember to use the <literal>git add <file name></literal> command to
<para>Most document style policies are established simply by using the template documentation framework. However, by applying some conventions to the document source structure, community members will be able to work across more documentation projects.</para>
<para>Most document style policies are established simply by using the template documentation framework. However,
by applying some conventions to the document source structure, community members will be able to work across more d
ocumentation projects.</para>
<para>The recommended documentation structure guidelines are as follows:
<para>The recommended documentation structure guidelines are as follows:
<orderedlist>
<orderedlist>
<listitem>
<listitem>
<para>The head book file should be named with the prefix "bk_".</para>
<para>The head book file should be named with the prefix "bk_".</para>
</listitem>
</listitem>
<listitem>
<listitem>
<para>The document versioning as defined by the <literal>releaseinfo</literal> tag in the main book file <literal>bk_xxx</literal> should be named "Revision N.N", not "Version N.N" or simply "N.N"</para>
<para>The document versioning as defined by the <literal>releaseinfo</literal> tag in the main book
file <literal>bk_xxx</literal> should be named "Revision N.N", not "Version N.N" or simply "N.N"</para>
</listitem>
</listitem>
<listitem>
<listitem>
<para>Chapters files should be named with the prefix "ch_".</para>
<para>Chapters files should be named with the prefix "ch_".</para>
Jeff Scheel
9 years ago
