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.
CAPI-SNAP-Doc/template/sec_template_new_document.xml

259 lines
16 KiB
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 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>Cloning the project source.</para>
</listitem>
<listitem>
<para>Finding a document framework.</para>
</listitem>
<listitem>
<para>Modifying core project files.</para>
</listitem>
<listitem>
<para>Adding new document content.</para>
</listitem>
</orderedlist>
<section>
<title>Clone the project source.</title>
<para>All documentation projects reside in a project directory maintained in GitHub, just like the
<literal>Docs-Master</literal> framework described in <xref linkend="section_cloning_master_doc"/>. In the same directory
where the <literal>Docs-Master</literal> project has been cloned, you will need to
clone the documentation source for your project. A list of the OpenPOWER Foundation projects can be found at
<link xlink:href="https://github.com/OpenPOWERFoundation/">https://github.com/OpenPOWERFoundation/</link>. Select
the project from this list.</para>
<note><para>If you do not see the project for which you are looking, you may not be authorized to it. See
<xref linkend="section_creating_accounts"/> for details about joining the OpenPOWER Foundation private projects. If you
feel that you need a new GitHub project, work with the
Technical Steering Committee Chair, <email>tsc-chair@openpowerfoundation.org</email>, to request and get this setup.</para></note>
<para>To clone an OpenPOWER Foundation project like <literal>Docs-Template</literal> issue the following
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> The results should look roughly something like above with actual numbers of objects, files, etc. varying
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>
<title>Finding a document framework</title>
<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>
<listitem>
<para>Navigate down to your project directory, called <literal>my_project</literal> for this example. This can be achieved
using the <literal>cd</literal> command:
<screen><prompt>$ </prompt><userinput>cd ~/my_project</userinput>
<prompt>$ </prompt></screen></para>
<para>This directory should contain the <literal>template</literal> folder used to prime the project.</para>
</listitem>
<listitem>
<para>Rename the <literal>template</literal> document directory to something new like <literal>my_doc</literal>.
To accomplish this, use the <literal>mv</literal> command::
<screen><prompt>$ </prompt><userinput>mv template/ my_doc</userinput></screen></para>
</listitem>
<listitem>
<para>Change the project name in the workgroup POM.xml file. Using your editor, change this line
between the &lt;modules> and the &lt;/modules> tags near the top of the
file:<programlisting><![CDATA[<module>template</module>
]]></programlisting> to read like this:<programlisting><![CDATA[<module>my_doc</module>
]]></programlisting></para>
</listitem>
</orderedlist>
<para>If this is not the first document in the project, then you can either begin by copying an existing document or by cloning the
<literal>Docs-Template</literal> project. To copy an existing project, follow these steps:</para>
<orderedlist>
<listitem>
<para>Navigate down to your project directory, called <literal>my_project</literal> for this example.
This can be achieved using the <literal>cd</literal> command:
<screen><prompt>$ </prompt><userinput>cd ~/my_project</userinput>
<prompt>$ </prompt></screen></para>
<para>This directory should contain the folder name of the document wishing to be copied, called <literal>source_doc</literal>
for clarity in these directions.</para>
</listitem>
<listitem>
<para>To create a new document directory, simply create a new directory and copy the contents of the <literal>source_doc</literal>
directory. If creating a new directory named <literal>my_doc</literal> via a command line, the command
sequence would look like this:
<screen><prompt>$ </prompt><userinput>mkdir my_doc</userinput>
<prompt>$ </prompt><userinput>cp -r source_doc/* my_doc</userinput>
<prompt>$ </prompt></screen></para>
</listitem>
<listitem>
<para>Add the new project to the workgroup 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_doc</module>
]]></programlisting></para>
</listitem>
</orderedlist>
<para>Instead of copying an existing document, you may want to start with the template document source. The steps to do this
are similar to those above, but with a few more commands. The following commands will create a new document based on the
the master template:</para>
<orderedlist>
<listitem>
<para>Navigate down to your project directory, called <literal>my_project</literal> for this example.
This can be achieved using the <literal>cd</literal> command:
<screen><prompt>$ </prompt><userinput>cd ~/my_project</userinput>
<prompt>$ </prompt></screen></para>
<para>This directory should contain any existing document folders along with at least a <literal>pom.xml</literal> file, a
<literal>LICENSE</literal> file, and a <literal>README.md</literal> file.</para>
</listitem>
<listitem>
<para>Clone the the template project into your working directory with 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>
</listitem>
<listitem>
<para>To create a new project directory, simply create a new directory and copy the contents of the <literal>Docs-Template/template</literal>
directory. If creating a new project named <literal>my_doc</literal> via a command line, the command
sequence would look like this:
<screen><prompt>$ </prompt><userinput>mkdir my_doc</userinput>
<prompt>$ </prompt><userinput>cp -r Docs-Template/template/* my_doc</userinput>
<prompt>$ </prompt></screen></para>
</listitem>
<listitem>
<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 &lt;modules> and the &lt;/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 xml:id="section_modifying_project">
<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>
<para>Pick your setting for document work product type (<literal>&lt;workProduct></literal>,
work flow status (<literal>&lt;documentStatus></literal>), and
security (<literal>&lt;security></literal>)
carefully. <xref linkend="section_template_process"/> provides an overview of the process
and details the various settings needed in the document core project files. If you still have
questions after reading this section, consult with your Technical Steering Committee
representative.</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 ready, build your new document using standard maven commands like
this:<screen><prompt>$ </prompt><userinput>cd my_proj/my_doc</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 ~/my_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>
<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>
<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="../../Docs-Master/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"/>
<!-- The app_foundation.xml appendix file is required by all documents. -->
<xi:include href="../../Docs-Master/common/app_foundation.xml"/>
<!-- TODO: The following template document may be modified to create additional appendices as needed. -->
<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>