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

Interim doc push

Browse Source 
Starting major update of documentation technical content, but need
to rework tree structure.  Therefore, pushing up existing changes.
They are not intented to be complete nor accurate yet.  More to come.

Signed-off-by: Jeff Scheel <scheel@us.ibm.com>
master
Jeff Scheel 9 years ago
parent bd86323a76
commit 3da73be554
4 changed files with 70 additions and 36 deletions
Show Stats Download Patch File Download Diff File

34
doc/template/bk_main.xml vendored
Unescape Escape View File

@ -9,7 +9,7 @@
<!-- TODO: When ready to publish document, remove the 'status="draft"' statement from the book object above. -->

<!-- TODO: Pick a Title for the new document -->
<title>Template Guide</title>
<title>Master Template Guide</title>
<!-- TODO: Either add a subtitle or remove the following line -->
<subtitle>A quick start template</subtitle>

@ -17,14 +17,14 @@
<author>
<personname>
<!-- TODO: Insert appropriate firstname and surnames -->
<firstname>Firstname</firstname>
<surname>Lastname</surname>
<firstname>Jeff</firstname>
<surname>Scheel</surname>
</personname>
<!-- TODO: Set correct email address of document author -->
<email>Email@domain</email>
<email>scheel@us.ibm.com</email>
<affiliation>
<!-- TODO: Insert appropriate orgname -->
<orgname>Company</orgname>
<orgname>IBM</orgname>
</affiliation>
</author>
<copyright>
@ -33,7 +33,7 @@
<holder>OpenPOWER Foundation</holder>
</copyright>
<!-- TODO: Set the correct document releaseinfo -->
<releaseinfo>Revision 0.9</releaseinfo>
<releaseinfo>Revision 0.9.1</releaseinfo>
<productname>OpenPOWER</productname>
<pubdate/>

@ -57,8 +57,28 @@
-->

<revhistory>
<!-- TODO: Set the initial version information and clear any old information out -->
<revision>
<date>2016-01-25</date>
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Version 0.9.1: Technical and process updates.</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision>
<date>2015-08-20</date>
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>Version 0.9: Draft for format review with TSC.</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
<revision>
<!-- TODO: Set the initial version information -->
<date>2014-09-03</date>
<revdescription>
<itemizedlist spacing="compact">

20
doc/template/sec_template_getting_started.xml vendored
Unescape Escape View File

@ -22,14 +22,14 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_getting_star
source and maven provides the build framework to create the published content in PDF and html form.
Installation steps for these tools varies by operating system.</para>
<para>On Debian-based Linux operating systems (Ubuntu and Debian), install maven and git as follows:
<screen><prompt>$</prompt><userinput>sudo apt-get install git</userinput>
<prompt>$</prompt><userinput>sudo apt-get install maven</userinput></screen></para>
<screen><prompt>#</prompt><userinput>apt-get install git</userinput>
<prompt>#</prompt><userinput>apt-get install maven</userinput></screen></para>
<para>On RPM-based Linux operating systems (Fedora, RHEL, openSUSE, SLES), install maven and git as follows:
<screen><prompt>$</prompt><userinput>sudo yum install git</userinput>
<prompt>$</prompt><userinput>sudo yum install maven</userinput></screen></para>
<screen><prompt>#</prompt><userinput>yum install git</userinput>
<prompt>#</prompt><userinput>yum install maven</userinput></screen></para>
<para>On Mac OS X, use Macports to install maven and git as follows:
<screen><prompt>$</prompt><userinput>sudo port install git</userinput>
<prompt>$</prompt><userinput>sudo port install maven3</userinput></screen></para>
<screen><prompt>#</prompt><userinput>port install git</userinput>
<prompt>#</prompt><userinput>port install maven3</userinput></screen></para>
<para>or use Homebrew to install maven and git as follows:
<screen><prompt>$</prompt><userinput>brew install git</userinput>
<prompt>$</prompt><userinput>brew install maven</userinput></screen></para>
@ -48,9 +48,13 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_getting_star

<section>
<title>Creating accounts</title>
<para>All OpenPOWER project documentation is maintained in GitHub trees, public and private. To join the GitHub community,
<para>All OpenPOWER project documentation is maintained in GitHub trees, public and private. The first
step to creating documentation will be joining the GitHub community.</para>
<para>To join the GitHub community,
apply at <link xlink:href="https://github.com/join">https://github.com/join</link>.</para>
<para>If you will be participating in private OpenPOWER Foundation trees, you will need to visit the OpenPOWER Foundation Members
<para>The private trees are grouped in the OpenPOWER Foundation project at
<link xlink:href="https://github.com/OpenPOWERFoundation">https://github.com/OpenPOWERFoundation</link>.
If you will be participating in private OpenPOWER Foundation trees, you will need to visit the OpenPOWER Foundation Members
Area wiki to find administrators for the appropriate git tree.</para>
<para>To learn more about using git, see the online article in GitHub Help, "Good Resources for Learning Git and GitHub." at
<link xlink:href="https://help.github.com/articles/good-resources-for-learning-git-and-github/">

5
doc/template/sec_template_new_document.xml vendored
Unescape Escape View File

@ -48,6 +48,11 @@ Checking connectivity... done.
<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.

47
doc/template/sec_template_policies.xml vendored
Unescape Escape View File

@ -1,29 +1,34 @@
<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_policies">

<title>Policies and conventions</title>
<title>Policies and conventions</title>
<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>The recommended documentation structure guidelines are as follows:
<orderedlist>
<listitem>
<para>The head book file should be named with the prefix "bk_".</para>
</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>
</listitem>
<listitem>
<para>Chapters files should be named with the prefix "ch_".</para>
</listitem>
<listitem>
<para>Section and sub-section files should be named with the prefix "sec_".</para>
</listitem>
<listitem>
<para>Appendix files should be named with the prefix "app_".</para>
</listitem>
<listitem>
<para>Figures source and images should be placed in the <literal>figures</literal> sub-directory for the document.</para>
</listitem>
</orderedlist>
<orderedlist>
<listitem>
<para>The head book file should be named with the prefix "bk_".</para>
</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>
</listitem>
<listitem>
<para>Chapters files should be named with the prefix "ch_".</para>
</listitem>
<listitem>
<para>Section and sub-section files should be named with the prefix "sec_".</para>
</listitem>
<listitem>
<para>Appendix files should be named with the prefix "app_".</para>
</listitem>
<listitem>
<para>Figures source and images should be placed in the <literal>figures</literal> sub-directory for the document.</para>
</listitem>
</orderedlist>
</para>
<para>In addition to documentation documentation structure, general community/project guidelines are as follows
<orderedlist>
<listitem><para></para></listitem>
</orderedlist>
</para>

</section>

Write Preview
Loading…
Cancel
Save