CAPI-SNAP-Doc/template/sec_template_new_document.xml

<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_new_document">

  <title>Creating a new document</title>
     <para>Creating a new document from scratch follows four simple steps:</para>
        <orderedlist>
	  <listitem>
            <para>Clone the appropriate template document framework.</para>
          </listitem>
	  <listitem>
            <para>Copy the template directory into a new project directory.</para>
          </listitem>
          <listitem>
            <para>Modify core project files.</para>
          </listitem>
	  <listitem>
            <para>Begin adding document content, either from scratch or from another document.</para>
          </listitem>
        </orderedlist>

        <section>
          <title>Cloning the base document framework</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>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>
Cloning into 'openpower-foundation-docbkx-framework'...
remote: Counting objects: 288, done.
remote: Compressing objects: 100% (157/157), done.
remote: Total 288 (delta 121), reused 288 (delta 121)
Receiving objects: 100% (288/288), 12.41 MiB | 8.04 MiB/s, done.
Resolving deltas: 100% (121/121), done.
Checking connectivity... done.
<prompt>$</prompt></screen></para>
            <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>
        </section>

        <section>
          <title>Copying the template directory into a new project directory</title>
            <para>To create a new document directory, follow these steps:</para>
            <orderedlist>
	      <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:
<screen><prompt>$</prompt><userinput>cd /openpower-foundation-docbkx-framework/doc</userinput>
<prompt>$</prompt></screen></para>
                <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>
              </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:
<screen><prompt>$</prompt><userinput>mkdir my_proj</userinput>
<prompt>$</prompt><userinput>cp -r template/* my_proj</userinput>
<prompt>$</prompt></screen></para>
              </listitem>
              <listitem>
                <para>Add the new project to the master POM.xml file.  Using your editor, add the following lines
                between the &lt;modules> and the &lt;/modules> tags near the top of the file:<programlisting><![CDATA[<module>my_proj</module>
]]></programlisting></para>
              </listitem>
              <listitem>
                <para>Finally, make sure to add the new directory to the git repository.
<screen><prompt>$</prompt><userinput>git add my_proj</userinput></screen></para>
              </listitem>
            </orderedlist>
	</section>

        <section>
          <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>&lt;!-- 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>
            <note><para>Be sure to remember two key values you used in the <literal>pom.xml</literal> file, <literal>&lt;webhelpDirname&gt;</literal> and <literal>&lt;pdfFilenameBase&gt;</literal>, as these will be used to locate your generated document.</para></note>
            <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>
<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 ~/openpower-foundation-docbkx-framework/doc/my_proj/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>
    <para>If all goes well, the new generated pdf should be available in <literal>target/docbkx/webhelp/&lt;webhelpDirname&gt;/&lt;pdfFilenameBase&gt;.pdf</literal>.</para>
	</section>

        <section>
          <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"/>

  <!-- 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"/>

  <!-- TODO: The following appendices are optional but highly recommended. You may add others as needed. -->
  <xi:include href="../common/app_foundation.xml"/>

  <!-- TODO: The following template document may be modified to create additional appendices -->
  <xi:include href="app_template.xml"/>
]]></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 &lt;file name&gt;</literal> command to add new files to the git tree.</para></note>
	</section>

</section>