systemsoftware
/
CAPI-SNAP-Doc
33
0
Fork 0
Code Issues Pull Requests Projects Releases 1 Wiki Activity

Multiple updates as follows:

Browse Source 
- Start 1.2 release (_pre1)
- Add subsection in Getting Started to include first build
- Add subsection in OpenPOWER Documentation Process on document packaging

Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
master
Jeff Scheel 7 years ago
parent 0751965d7f
commit b74af890cf
3 changed files with 135 additions and 2 deletions
Show Stats Download Patch File Download Diff File

18
template/bk_main.xml
Unescape Escape View File

@ -50,11 +50,11 @@
</author>
<copyright>
<!-- TODO: Set copyright year -->
<year>2015, 2016, 2017</year>
<year>2015, 2016, 2017, 2018</year>
<holder>OpenPOWER Foundation</holder>
</copyright>
<!-- TODO: Set the correct document releaseinfo -->
<releaseinfo>Revision 1.1.0</releaseinfo>
<releaseinfo>Revision 1.2_pre1</releaseinfo>
<productname>OpenPOWER</productname>
<pubdate/>

@ -90,6 +90,20 @@

<revhistory>
<!-- TODO: Set the initial version information and clear any old information out -->
<revision>
<date>2018-04-07</date>
<revdescription>
<para>Version 1.2 updates:
<itemizedlist spacing="compact">
<listitem>
<para>Extend the Getting Started section to include a first document build.</para>
</listitem>
<listitem>
<para>Add a section on document packaging for publish in the Publishing OpenPOWER Documents section.</para>
</listitem>
</itemizedlist></para>
</revdescription>
</revision>
<revision>
<date>2017-02-17</date>
<revdescription>

79
template/sec_template_getting_started.xml
Unescape Escape View File

@ -32,6 +32,9 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_getting_star
<listitem>
<para><xref linkend="section_cloning_master_doc" endterm="section_cloning_master_doc_title"/></para>
</listitem>
<listitem>
<para><xref linkend="section_building_first_doc" endterm="section_building_first_doc_title"/></para>
</listitem>
</orderedlist>
</para>

@ -123,5 +126,81 @@ Checking connectivity... done.
https://github.com/OpenPOWERFoundation/Docs-Master</link>. Additional details about the OpenPOWER Foundation documentation structure
are explained in <xref linkend="section_template_structure"/> of this document.</para>
</section>
<section xml:id="section_building_first_doc">
<title xml:id="section_building_first_doc_title">Building the first document</title>
<para>The final step of setting up your environment to perform the first build. The following steps are recommended:</para>
<orderedlist>
<listitem>
<para>Clone the <citetitle>Documentation Development Guide</citetitle> (this document) as source from which to build.
To accomplish this, issue the following command in the same directory as as the master document clone from <xref linkend="section_cloning_master_doc" />.
<screen><prompt>$ </prompt><userinput>git clone https://github.com/OpenPOWERFoundation/Docs-Template.git</userinput>
Cloning into 'Docs-Template'...
remote: Counting objects: 253, done.
remote: Total 253 (delta 0), reused 0 (delta 0), pack-reused 253
Receiving objects: 100% (253/253), 468.94 KiB | 0 bytes/s, done.
Resolving deltas: 100% (151/151), done.
Checking connectivity... done.
<prompt>$ </prompt></screen></para>
</listitem>
<listitem>
<para>Change the working directory into the source directory for the <citetitle>Documentation Development Guide</citetitle>.
<screen><prompt>$ </prompt><userinput>cd Docs-Template/template</userinput>
<prompt>Docs-Template/template$ </prompt></screen></para>
</listitem>
<listitem>
<para>Build the document in Maven.<screen><prompt>Docs-Template/template$ </prompt><userinput>mvn generate-sources</userinput>
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building Documentation Development Guide 1.0.0-SNAPSHOT
[INFO] ------------------------------------------------------------------------
[INFO]
[INFO] --- openpowerdocs-maven-plugin:1.1.0:generate-webhelp (generate-webhelp) @ openpower-template-guide ---
[INFO] Processing input file: bk_main.xml
[WARNING] Property not found in com.agilejava.docbkx.maven.DocbkxWebhelpMojo
[WARNING] Property not found in com.agilejava.docbkx.maven.DocbkxWebhelpMojo
[WARNING] Property not found in com.agilejava.docbkx.maven.DocbkxWebhelpMojo
[WARNING] Property not found in com.agilejava.docbkx.maven.DocbkxWebhelpMojo
Feb 27, 2018 11:43:28 AM org.apache.fop.apps.FopFactoryConfigurator configure
INFO: Default page-height set to: 11in
Feb 27, 2018 11:43:28 AM org.apache.fop.apps.FopFactoryConfigurator configure
...snip...
[INFO] Applying customization parameters

&lt;!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"&gt;
Parsing: /home/scheel/mydocs/Docs-Template/template/target/docbkx/webhelp/doc-devel-guide/content/section_cloning_project.html
...snip...
The created index files are located in /home/scheel/mydocs/Docs-Template/template/target/docbkx/webhelp/doc-devel-guide/content/search/.js
[INFO] See /home/scheel/mydocs/Docs-Template/template/target/docbkx/webhelp/bk_main for generated file(s)
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 31.547 s
[INFO] Finished at: 2018-02-27T11:43:45-06:00
[INFO] Final Memory: 83M/729M
[INFO] ------------------------------------------------------------------------
<prompt>Docs-Template/template$ </prompt></screen></para>
<note><para>The first time one builds in a Maven environment, the build time will be noticeably
long due to JAR file downloads associated with the new Maven project types. In future builds, these JAR files will
only be downloaded when they are updated. As such, one should both allow for this extra time and not be discouraged
by the duration of the first build.</para></note>
</listitem>
</orderedlist>
<para>Once complete, there should be a single directory in the <literal>target/docbkx/webhelp/</literal> directory. For the
Docs-Template project, that directory is <literal>doc-devel-guide</literal>. Inside this directory will
be both the PDF file and the <literal>index.html</literal> file for the HTML document.</para>
<para>To verify this for the <citetitle>Documentation Development Guide</citetitle>, perform these commands:
<screen><prompt>Docs-Template/template$ </prompt><userinput>cd target/docbkx/webhelp/</userinput>
<prompt>Docs-Template/template/target/docbkx/webhelp$ </prompt><userinput>ls</userinput>
doc-devel-guide
<prompt>Docs-Template/template/target/docbkx/webhelp$ </prompt><userinput>cd doc-devel-guide</userinput>
<prompt>Docs-Template/template/target/docbkx/webhelp/doc-devel-guide$ </prompt><userinput>ls</userinput>
bookinfo.xml common content doc-devel-guide-20180227.pdf favicon.ico index.html
webapp</screen></para>
<para>Now, you are ready to begin working on your own document. Useful information on how to proceed can
be found in <xref linkend="section_template_new_document" /> and <xref linkend="section_template_existing_document" />.</para>
</section>
</section>

40
template/sec_template_process.xml
Unescape Escape View File

@ -420,6 +420,46 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_process">
Following this approval, the document POM (<literal>pom.xml</literal>) variable
<literal>&lt;workProduct&gt;</literal> should be set to <literal>openpowerStandard</literal>.</para>
</section>
<section xml:id="section_template_packaging_document_for_publish">
<title xml:id="section_template_packaging_document_for_publish_title">Packaging the document for publish</title>
<para>The OpenPOWER Foundation process for publishing documents from WordPress in the
Resource Catalog on openpowerfoundatoin.org website has the following requirements:</para>
<itemizedlist>
<listitem>
<para>The PDF and all HTML source must be bundled in a self-contained zip file.</para>
</listitem>
<listitem>
<para>The zip file is expected to contain a single directory in which the document PDF and <literal>index.html</literal> file are found.</para>
</listitem>
<listitem>
<para>The filename of the zip file must be the same name as the contained directory.</para>
</listitem>
</itemizedlist>
<para>To create this package for the <citetitle>Documentation Development Guide</citetitle>, one would perform the following commands
in Linux from the document source directory (<literal>.../Docs-Template/template/</literal>):
<screen><prompt>Docs-Template/template$ </prompt><userinput>cd target/docbkx/webhelp/</userinput>
<prompt>Docs-Template/template/target/docbkx/webhelp$ </prompt><userinput>ls</userinput>
doc-devel-guide
<prompt>Docs-Template/template/target/docbkx/webhelp$ </prompt><userinput>zip -rv doc-devel-guide.zip doc-devel-guide/</userinput>
adding: doc-devel-guide/ (in=0) (out=0) (stored 0%)
adding: doc-devel-guide/favicon.ico (in=806) (out=806) (stored 0%)
adding: doc-devel-guide/index.html (in=654) (out=385) (deflated 41%)
...snip...
adding: doc-devel-guide/doc-devel-guide-20180406.pdf (in=413655) (out=305492) (deflated 26%)
...snip...
adding: doc-devel-guide/common/ (in=0) (out=0) (stored 0%)
adding: doc-devel-guide/common/main.js (in=5674) (out=2119) (deflated 63%)
...snip...
adding: doc-devel-guide/common/jquery/jquery-ui-1.8.2.custom.min.js (in=87032) (out=22729) (deflated 74%)
total bytes=3342807, compressed=1332882 -> 60% savings
<prompt>Docs-Template/template/target/docbkx/webhelp/doc-devel-guide$ </prompt><userinput>ls</userinput>
doc-devel-guide doc-devel-guide.zip</screen></para>
<para>For MacOS and Windows, the steps will be similar with slight variations on the command to create the zip file.</para>
<para>This zip file can be sent to the person managing the documents in the OpenPOWER Resource Catalog.</para>
</section>

</section>

Write Preview
Loading…
Cancel
Save