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.
402 lines
25 KiB
XML
402 lines
25 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_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><xref linkend="section_cloning_project" endterm="section_cloning_project_title"/></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><xref linkend="section_finding_framework" endterm="section_finding_framework_title"/></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><xref linkend="section_modifying_project" endterm="section_modifying_project_title"/></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><xref linkend="section_adding_content" endterm="section_adding_content_title"/></para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>Before undertaking one of these activities, it may be helpful to read the
|
|
<xref linkend="section_template_structure" endterm="section_template_structure_title"/>
|
|
section to learn the basics about the documentation project structure.</para>
|
|
|
|
<section xml:id="section_cloning_project">
|
|
<title xml:id="section_cloning_project_title">Cloning a project</title>
|
|
<para>All documentation projects reside in a Git project directory, either locally or in the cloud at GitHub.
|
|
As described in <xref linkend="section_cloning_master_doc"/>, your document project directory must reside locally in the
|
|
same directory as the <literal>Docs-Master</literal> framework.</para>
|
|
|
|
<para>To clone a project in which to work, select from one of the two approaches below:</para>
|
|
<itemizedlist>
|
|
<listitem><para><xref linkend="section_clone_existing_project" endterm="section_clone_existing_project_title"/></para>
|
|
</listitem>
|
|
<listitem><para><xref linkend="section_creating_new_project" endterm="section_creating_new_project_title"/></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Complete the project cloning and then continue with the next step in
|
|
<xref linkend="section_template_new_document" endterm="section_template_new_document_title"/>.</para>
|
|
|
|
<section xml:id="section_clone_existing_project">
|
|
<title xml:id="section_clone_existing_project_title">Cloning an existing project</title>
|
|
|
|
<para>To work in an existing OpenPOWER Foundation project like the <citetitle>Documentation Development
|
|
Guide</citetitle> (<literal>Docs-Template</literal>),
|
|
use the following command in the same directory that contains
|
|
<literal>Docs-Master</literal>:<screen><prompt>$ </prompt><userinput>git clone https://github.com/OpenPOWERFoundation/Docs-Template.git</userinput>
|
|
Cloning into 'Docs-Template'...
|
|
remote: Counting objects: 163, done.
|
|
remote: Total 163 (delta 0), reused 0 (delta 0), pack-reused 163
|
|
Receiving objects: 100% (163/163), 275.60 KiB | 494.00 KiB/s, done.
|
|
Resolving deltas: 100% (96/96), 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 immediately following the "Cloning into..." message.
|
|
When cloning public projects such as <literal>Docs-Template</literal>, these prompts are skipped.</para></note>
|
|
|
|
<para>A list of additional OpenPOWER Foundation projects can be found at
|
|
<link xlink:href="https://github.com/OpenPOWERFoundation/">https://github.com/OpenPOWERFoundation/</link>. To work
|
|
on an existing project, note its name it the list and apply the above steps replacing <literal>Docs-Template</literal>
|
|
with your preferred project from the 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>The existing project should now be cloned. Continue with the next step in
|
|
<xref linkend="section_template_new_document" endterm="section_template_new_document_title"/>.</para>
|
|
</section>
|
|
|
|
<section xml:id="section_creating_new_project">
|
|
<title xml:id="section_creating_new_project_title">Creating a new project locally</title>
|
|
|
|
<para>To create a new project locally, the simplest way is to clone the <citetitle>Documentation Development
|
|
Guide</citetitle> (<literal>Docs-Template</literal>) into a new project. In
|
|
our directions, <literal>my_project</literal> will be our new project name.
|
|
Use the following command in the same directory that contains
|
|
<literal>Docs-Master</literal>:<screen><prompt>$ </prompt><userinput>git clone https://github.com/OpenPOWERFoundation/Docs-Template.git my_project</userinput>
|
|
Cloning into 'my_project'...
|
|
remote: Counting objects: 163, done.
|
|
remote: Total 163 (delta 0), reused 0 (delta 0), pack-reused 163
|
|
Receiving objects: 100% (163/163), 275.60 KiB | 494.00 KiB/s, done.
|
|
Resolving deltas: 100% (96/96), 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>
|
|
|
|
<para>The new project should now be generally setup. Continue with the next step in
|
|
<xref linkend="section_template_new_document" endterm="section_template_new_document_title"/>.</para>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section xml:id="section_finding_framework">
|
|
<title xml:id="section_finding_framework_title">Finding a document framework</title>
|
|
|
|
<para>When creating a new document, the simplest way to start is to use an existing document. This ensures
|
|
that you have a basic document structure and allows you to start with a working document from which to make
|
|
changes. Select from one of the following scenarios for detailed directions on creating your document framework:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>If your project exits on GitHub in the OpenPOWER Foundation area and it contains a <literal>doc_template</literal> directory,
|
|
then follow the directions in
|
|
<xref linkend="section_moving_template_document" endterm="section_moving_template_document_title"/>
|
|
to use this document as a base.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>If you have an existing document in your project that you want to use as a
|
|
base for your new document, then follow the directions in
|
|
<xref linkend="section_copying_existing_document" endterm="section_copying_existing_document_title"/>
|
|
to establish your base document.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Otherwise, the instructions in
|
|
<xref linkend="section_copying_template_document" endterm="section_copying_template_document_title"/>
|
|
will clone and copy this document as a base.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<section xml:id="section_moving_template_document">
|
|
<title xml:id="section_moving_template_document_title">Moving the template document into your new document framework</title>
|
|
|
|
<para>If this is your first document, in a brand new OpenPOWER Foundation project (on GitHub), 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>doc_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>doc_template</literal> folder used to prime the project.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Rename the <literal>doc_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 doc_template/ my_doc</userinput></screen></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Change the project name in the Workgroup POM file (<literal>my_project/pom.xml</literal>). Using your editor, change this line
|
|
between the <modules> and the </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>Your new document frameword has been copied from the <citetitle>Document Development Guide</citetitle>.
|
|
Continue with the next step in
|
|
<xref linkend="section_template_new_document" endterm="section_template_new_document_title"/>.</para>
|
|
|
|
</section>
|
|
|
|
<section xml:id="section_copying_existing_document">
|
|
<title xml:id="section_copying_existing_document_title">Copying an existing document as a new document framework</title>
|
|
|
|
<para>If you have another document within your project that would serve as a good base for your new one,
|
|
you can copy the existing document as the source for your new document. 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 file (<literal>my_project/pom.xml</literal>).
|
|
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>
|
|
|
|
<para>You are now ready to begin making updates to your new document. Continue with the next step in
|
|
<xref linkend="section_template_new_document" endterm="section_template_new_document_title"/>.</para>
|
|
|
|
</section>
|
|
|
|
<section xml:id="section_copying_template_document">
|
|
<title xml:id="section_copying_template_document_title">Copying the Document Development Guide as a new document framework</title>
|
|
|
|
<para>Instead of copying an existing document, you may want to start with the <citetitle>Document Development Guide</citetitle>
|
|
(<literal>Doces-Template</literal>) 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 this guide:</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 <citetitle>Documentation Development Guide</citetitle>
|
|
(<literal>Docs-Template</literal>) 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'...
|
|
remote: Counting objects: 163, done.
|
|
remote: Total 163 (delta 0), reused 0 (delta 0), pack-reused 163
|
|
Receiving objects: 100% (163/163), 275.60 KiB | 0 bytes/s, done.
|
|
Resolving deltas: 100% (96/96), 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/doc_dev_guide</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/doc_dev_guide/* 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 not
|
|
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 file (<literal>my_project/pom.xml</literal>).
|
|
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>
|
|
|
|
<para>You are now ready to begin making updates to your new document. Continue with the next step in
|
|
<xref linkend="section_template_new_document" endterm="section_template_new_document_title"/>.</para>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section xml:id="section_modifying_project">
|
|
<title 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><!-- 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>In the <literal>pom.xml</literal> file, pick your settings for document work product type (<literal><workProduct></literal>,
|
|
work flow status (<literal><documentStatus></literal>), and
|
|
security (<literal><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>In addition to the document settings, 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>
|
|
|
|
<para>In the <literal>book.xml</literal> file, you will find the following document unique values which you most likely want to change:
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><literal><title></literal></term>
|
|
<listitem>
|
|
<para>The main title of the document. This appears in the largest font at the top of the title page.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal><subtitle></literal></term>
|
|
<listitem>
|
|
<para>The second title of the document. This title appears in a smaller font below the <literal><title></literal> on the title page.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><literal><realeaseinfo></literal></term>
|
|
<listitem>
|
|
<para>The document version value. This value should take the form of "Revision V.R.M" as described in
|
|
<xref linkend="section_template_policies"/> recommendation <xref linkend="section_template_vrm_policy" xrefstyle="select: nopage"/>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
</para>
|
|
<para>When ready, build your new document using standard maven commands like
|
|
this:<screen><prompt>$ </prompt><userinput>cd my_project/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/<webhelpDirname>/<pdfFilenameBase>.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>
|
|
|
|
<para>You have completed updates to core project files for your new document. Continue with the next step in
|
|
<xref linkend="section_template_new_document" endterm="section_template_new_document_title"/>.</para>
|
|
|
|
</section>
|
|
|
|
<section xml:id="section_adding_content">
|
|
<title xml:id="section_adding_content_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 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 <file name></literal> command to
|
|
add new files to the git tree.</para></note>
|
|
</section>
|
|
|
|
</section>
|
|
|