diff --git a/doc_dev_guide/app_template.xml b/doc_dev_guide/app_template.xml
deleted file mode 100644
index f4b7ae4..0000000
--- a/doc_dev_guide/app_template.xml
+++ /dev/null
@@ -1,30 +0,0 @@
-
-
-
-
- Appendix template
- This is the first paragraph of a new appendix...
-
- Section title
- Section text...
-
-
diff --git a/doc_dev_guide/bk_main.xml b/doc_dev_guide/bk_main.xml
deleted file mode 100644
index 642ec5c..0000000
--- a/doc_dev_guide/bk_main.xml
+++ /dev/null
@@ -1,268 +0,0 @@
-
-
-
-
-
-]>
-
-
-
-
- Documentation Development Guide
-
- A quick start template
-
-
-
-
-
- System Software Work Group
-
-
- syssw-chair@openpowerfoundation.org
-
- OpenPower Foundation
-
-
-
-
- 2015, 2016, 2017, 2018
- OpenPOWER Foundation
-
-
- Revision 1.2
- OpenPOWER
-
-
-
-
-
-
-
- Copyright details are filled in by the template.
-
-
-
-
-
- The purpose of this document is to provide a guide for OpenPOWER
- documentation writers. As such, it provides directions, policies, references, and
- examples of the XML Docbook environment. It is intended to be used both in final product form
- (PDF and html) as a document and in source form as a template for new documents.
- This document is a Non-standard Track, Work Group Note work product owned by the
- System Software Workgroup and handled in compliance with the requirements outlined in the
- OpenPOWER Foundation Work Group (WG) Process document. It was
- created using the Document Development Guide version &template_version;.
- Comments, questions, etc. can be submitted to the public mailing list for this document at
- syssw-doc_devel_guide@mailinglist.openpowerfoundation.org. Additionally,
- the #doc-devel channel in the OpenPOWER Foundation Slack room
- (openpowerfoundation.slack.com)
- can be used to answer more interactive questions.
-
-
-
-
-
- 2018-08-27
-
- Version 1.2 additional updates:
-
-
- Add a section on circumventing Java AWT exception.
-
-
- Add information on key document tags which need update for new documents.
-
-
- Extend information on modifying an existing document to include a step-by-step description of how to get started.
-
-
- Rename the template directory to doc_dev_guide.
-
-
-
-
-
- 2018-04-11
-
- Version 1.2 updates:
-
-
- Extend the Getting Started section to include a first document build.
-
-
- Add a section on document packaging for publish in the Publishing OpenPOWER Documents section.
-
-
- Add examples for background color in tables, and variablelists.
-
-
-
-
-
- 2017-02-17
-
- Version 1.1.0 updates:
-
-
- Enhancements document creation to address project creation and update process.
-
-
- Add "git" error to troubleshooting sections until JAR dependency removed.
-
-
- Add optional font installation step to getting started.
-
-
- Provide samples of how to access symbols by value, including extension for
- new symbol library.
-
-
- Provide example usage of OPF Docbook extensions -- hard page breaks, soft line breaks,
- font-size changes, setting text color, and explicitly using symbol library.
-
-
- Extend explanation of versioning policy.
-
-
- Correct, improve miscellenous wording and grammar.
-
-
-
-
-
- 2016-09-13
-
-
-
- Version 1.0.1: Minor updates to guide naming.
-
-
-
-
-
- 2016-08-25
-
-
-
- Version 1.0.0: Document approval for publish
-
-
-
-
-
- 2016-04-28
-
-
-
- Version 0.9.5: Removal of confidentiality and preview of change notations for final review by TSC.
-
-
-
-
-
- 2016-03-21
-
-
-
- Version 0.9.4: Review version for TSC.
-
-
-
-
-
- 2016-02-25
-
-
-
- Version 0.9.3: Technical and process updates. Addition of documentation lifecycle and git command cheat sheets.
-
-
-
-
-
- 2016-02-25
-
-
-
- Version 0.9.2: Technical and process updates. Explanation of project structure.
-
-
-
-
-
- 2016-01-25
-
-
-
- Version 0.9.1: Technical and process updates.
-
-
-
-
-
- 2015-08-20
-
-
-
- Version 0.9: Draft for format review with TSC.
-
-
-
-
-
- 2014-09-03
-
-
-
- Creation based on OpenStack documentation
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/doc_dev_guide/ch_example.xml b/doc_dev_guide/ch_example.xml
deleted file mode 100644
index d2f6804..0000000
--- a/doc_dev_guide/ch_example.xml
+++ /dev/null
@@ -1,369 +0,0 @@
-
-
-
-
- Documentation examples
-
-
-
- Section Title goes here
- This Section covers something of interest to a limited number of people and shows a 1st level section
-
-
- Example Itemized List
-
- Here is an example of an itemized list
-
- A list title is completely optional
-
-
- Item you don't care about
-
-
- Perhaps you'd like a sub-list
-
-
- Oooh, here's about another
-
-
-
-
-
-
-
- Item you might care about
-
-
-
- Item you do care about
-
-
-
-
- Example ordered list
-
- All good documents need ordered lists.
-
- Another purely optional title
-
- First item
-
-
- Second item
-
-
- first indented item
-
-
- second indented item
-
-
-
-
- Third item
-
-
-
-
- Example variable list
-
- One of my favorite list types for formating items with definitions is called a variablelist.
- Here is an example with an embedded variablelist.
-
- KirkCaptain
- CrewMembers
-
- ScottyEngineering
- McCoyDoctor
- SpockScience Officer
-
-
-
-
-
-
- Example figure with embedded graphic
-
- Here is how you embed a graphic.
-
- Example figure
-
-
-
-
-
-
- Raw images such as the bitmap (bmp) file above may become blurry as they are scaled.
- Scalable graphic formats like SVG (Scalable Vector Graphics) embed and scale the best.
-
-
-
- Example table
- Of course all good documents need tables. Here's how you build a basic table.
-
-
- Example Table Title
-
-
-
-
-
-
-
-
-
- 1st Column Heading
-
-
-
-
- 2nd Column Heading
-
-
-
-
- 3rd Column Heading
-
-
-
-
- 4th Column Heading
-
-
-
-
-
-
-
- Yes
-
-
- Red
- Green
- Blue
- Custom (Amber)
-
-
- MAIN_Junk
-
-
- More_Junk
-
-
-
-
- merged cells horizontal
-
-
- cell_stuff
-
-
-
-
- Merge cells vertical
-
-
- filler
-
-
- merge cells both ways
-
-
-
-
- filler 2
-
-
-
-
- How about we put a list in the table cell
-
-
- item 1
-
-
- item 2
-
-
- item 2
-
-
-
-
- Another Cell
-
-
- Yet Another Cell
-
-
- Finally the last cell
-
-
-
-
-
- This Row
-
-
- Has
-
-
- background
-
-
- color
-
-
-
-
- Eenie
-
-
- Meenie
-
-
- Meinie
-
-
-
- Entry with background color
-
-
-
-
-
-
-
- Example of crossreferences and footnotes
- To reference another section or table is pretty easy. For example: see for how tables look.
- Lists are shown in and if you need to make a footnote
- The footnote text goes here and can reference something like for additional explanation.
- For clarification that is easy. Of course you might want an additional reference to the footnote which can also be done easily.
- Lastly you probably want to mark text by making it italic text example or Bold Text Example.
-
-
- Example of code citations and user input
- When showing user input, you want a nice sceen-looking layout, a prompt, monospace text, and a way to differentiate input from output. Here's an example:
- $ echo "Hello world"
-Hello world
-$
-
- Docbook also allows for formatting and display of common languages, allowing for whitespace
- and line returns just as they are written. Here's a sample snippet of C code with line numbering enabled:
-main()
-{
- printf("Hello world\n");
-}]]>
- If code formatting is not quite what you need, simply displaying text "literally" may suffice as follows: This is my literal
-text. It ignores whitespace.
-
-
- Example of special characters in text
- Sometimes in text you need special characters. These can be provided using their UNICODE values such as ≠ (≠),
- Ω (Ω), and ∆ (∆).
- These can be "coded" using the form &#ddddd; where ddddd is
- the up to five digit decimal representation of the character. The form &#xhhhh; where
- hhhh is the up to 4 digit hexidecimal representation of the character.
- This formatting works well as long as the symbol to which you are referring is contained in the font set
- used for the document -- Arimo for standard text and Cousine for monospace. If when building a document, you see a message like
- "WARNING, Glyph...not available in font 'Arimo',"
- see in for details on using the provided symbol fonts explicitly.
-
-
-
-
-
- Examples of OpenPOWER Foundation Docbook extensions
-
- The OpenPOWER Foundation Maven Plugin supports a number of extensions that are not pure Docbook. These are:
-
-
- Setting text color explicitly
-
- Text color can be controlled using <phrase role="color:color_name">
- tag where color_name contains the color setting. For example, this
- text:A red sentence contains a blue word.]]> produces this sentence:
- A red sentence contains a blue word.
- Valid colors include either a keyword color name or a numerical RGB specification. Keyword names are common with the HTML 4 specificiation:
- aqua, black, blue, fuchsia, gray,
- green, lime, maroon, navy, olive,
- purple, red, silver, teal, white,
- and yellow. Additionally, RGB values can be #nnnnnn where nnnnnn is a hexidecimal color value or
- rgb(n1, n2, n3) where n1, n2, and n3 are integers 0-255.
- This tag has also been implemented on the following tags: <thead>,
- <tbody>, and <tfoot>.
- This parameter should only be used for tags listed above.
-
-
-
- Inserting line breaks
- Line breaks can be introduced using <?linebreak?> tags. For example, this
- text:A line break in the middle of text]]> produces this sentence:
- A line break in the middle of text
- This tag becomes useful in table text spacing.
-
-
-
- Inserting page breaks
- Page breaks can be introduced using <?hard-pagebreak?> tags. For example, this
- text:A page breakBetween two paragraphs]]> produces this output:
- A page breakBetween two paragraphs
- This tag becomes useful in placing tables on page. Placing this statement before a large table may prevent it from spanning a page.
- Because the XSL template behind the Processing Instruction generates
- a ]]> in
- the book FO output, this instruction should be used in the outer most blocks of a section to work effectively. Use inside lists and other structural
- components may result in the text after the break being dropped. User beware!.
-
-
-
- Varying the font size
- Font sizes can also be set using the
- <phrase role="font-size:size">
- tag where size contains a size value such as "6pt" or "50%" or "1.5em".
- For example, a paragraph can be made to be 6 point as follows:A sentence that contains some 6pt font,
-50% font, and
-1.5em font in it.]]> produces this output:
- A sentence that contains some 6pt font,
- 50% font, and 1.5em font in it.
- This tag has also been implemented on the following tags: <para>,
- <thead>, <tbody>, and <tfoot>.
- This parameter should only be used for tags listed above.
-
-
-
- Using additional symbols
- If you find that the Arimo and Cousine fonts do not contain the special symbol you need
- for your document, you may use the additional symbol font provided for document (STIX Two Math).
- Due to an unimplemented feature in the Apach FO Processor, selection of this
- font needs to be explicitly performed using the
- <symbol role="symbolfont"> wrapper around your symbol value.
-
- For example, the symbol coding of should produce
- a circle with a cross in here "⨁", but instead creates a "Glyph...not available in font 'Arimo'" error
- on document build and the PDF renders as a "#".
-
- Re-coding this to use ⨁]]> produces
- the correct symbole here "⨁".
- If this still does not provide the symbol you expected, double check the code and the font maps found at
- http://www.stixfonts.org/charactertable.html.
-
-
-
-
-
diff --git a/doc_dev_guide/ch_template_overview.xml b/doc_dev_guide/ch_template_overview.xml
deleted file mode 100644
index 9e04783..0000000
--- a/doc_dev_guide/ch_template_overview.xml
+++ /dev/null
@@ -1,97 +0,0 @@
-
-
-
- Document development overview
-
- The OpenPOWER Foundation Documentation Development Guide
- provides a framework for OpenPOWER public and private
- documentation. The goal of the document is to describe the documentation development
- process, to promote community contributions to OpenPOWER documenation and to enable new
- contributions with a common look and feel.
-
- The major sections of this document addresses the following topics:
-
-
- :
- This section details tools and commands used to contribute to OpenPOWER documentation.
- All users who are new to OpenPOWER Foundation documentation should start here.
-
-
- :
- This section provides detailed descriptions of the various project
- components and their roles in the documentation creation process.
-
-
- :
- This section provides step-by-step instructions on how to create a new document
- from scratch. Use this section to start a new document.
-
-
- :
- This section highlights common steps in editing an existing OpenPOWER
- Foundation document. Use this section as a guideline for contributing to an existing document.
-
-
- :
- This section provides examples of the two most common types of build failures
- and helps users find the relevant failure information.
-
-
- :
- This section explains key document types and the appropriate work flow for publishing OpenPOWER Foundation
- documents.
-
-
- : This section contains
- the generally accepted guidelines for creating OpenPOWER documentation. Use this section as a reference
- for documentation source contruction and community process.
-
-
- :
- This section answers common questions. Use this section when the other sections
- do not answer your questions.
-
-
- :
- This section contains examples of commonly used git commands. Reference this section
- to find information on a specific git operation.
-
-
- :
- This section provides pointers to on-line information about XML, Docbook,
- Maven, and other relevant references.
-
-
-
- In addition to OpenPOWER Foundation specific topics,
- provides examples of common documenation constructs in XML.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/doc_dev_guide/figures/example_graphic.bmp b/doc_dev_guide/figures/example_graphic.bmp
deleted file mode 100644
index 296b4ea..0000000
Binary files a/doc_dev_guide/figures/example_graphic.bmp and /dev/null differ
diff --git a/doc_dev_guide/figures/example_graphic.odg b/doc_dev_guide/figures/example_graphic.odg
deleted file mode 100644
index 9a0a43e..0000000
Binary files a/doc_dev_guide/figures/example_graphic.odg and /dev/null differ
diff --git a/doc_dev_guide/figures/project_process_non-std_track_doc_variables_graphic.odg b/doc_dev_guide/figures/project_process_non-std_track_doc_variables_graphic.odg
deleted file mode 100644
index 2826841..0000000
Binary files a/doc_dev_guide/figures/project_process_non-std_track_doc_variables_graphic.odg and /dev/null differ
diff --git a/doc_dev_guide/figures/project_process_non-std_track_doc_variables_graphic.svg b/doc_dev_guide/figures/project_process_non-std_track_doc_variables_graphic.svg
deleted file mode 100644
index de04fc3..0000000
--- a/doc_dev_guide/figures/project_process_non-std_track_doc_variables_graphic.svg
+++ /dev/null
@@ -1,546 +0,0 @@
-
-
-
\ No newline at end of file
diff --git a/doc_dev_guide/figures/project_process_non-std_track_graphic.odg b/doc_dev_guide/figures/project_process_non-std_track_graphic.odg
deleted file mode 100644
index f144a01..0000000
Binary files a/doc_dev_guide/figures/project_process_non-std_track_graphic.odg and /dev/null differ
diff --git a/doc_dev_guide/figures/project_process_non-std_track_graphic.svg b/doc_dev_guide/figures/project_process_non-std_track_graphic.svg
deleted file mode 100644
index b2dd55d..0000000
--- a/doc_dev_guide/figures/project_process_non-std_track_graphic.svg
+++ /dev/null
@@ -1,161 +0,0 @@
-
-
-
\ No newline at end of file
diff --git a/doc_dev_guide/figures/project_process_std_track_doc_variables_candidate_graphic.odg b/doc_dev_guide/figures/project_process_std_track_doc_variables_candidate_graphic.odg
deleted file mode 100644
index 5d7b33a..0000000
Binary files a/doc_dev_guide/figures/project_process_std_track_doc_variables_candidate_graphic.odg and /dev/null differ
diff --git a/doc_dev_guide/figures/project_process_std_track_doc_variables_candidate_graphic.svg b/doc_dev_guide/figures/project_process_std_track_doc_variables_candidate_graphic.svg
deleted file mode 100644
index a22b7fb..0000000
--- a/doc_dev_guide/figures/project_process_std_track_doc_variables_candidate_graphic.svg
+++ /dev/null
@@ -1,420 +0,0 @@
-
-
-
\ No newline at end of file
diff --git a/doc_dev_guide/figures/project_process_std_track_doc_variables_draft_graphic.odg b/doc_dev_guide/figures/project_process_std_track_doc_variables_draft_graphic.odg
deleted file mode 100644
index 552c5f9..0000000
Binary files a/doc_dev_guide/figures/project_process_std_track_doc_variables_draft_graphic.odg and /dev/null differ
diff --git a/doc_dev_guide/figures/project_process_std_track_doc_variables_draft_graphic.svg b/doc_dev_guide/figures/project_process_std_track_doc_variables_draft_graphic.svg
deleted file mode 100644
index 6a034e0..0000000
--- a/doc_dev_guide/figures/project_process_std_track_doc_variables_draft_graphic.svg
+++ /dev/null
@@ -1,382 +0,0 @@
-
-
-
\ No newline at end of file
diff --git a/doc_dev_guide/figures/project_process_std_track_doc_variables_graphic.odg b/doc_dev_guide/figures/project_process_std_track_doc_variables_graphic.odg
deleted file mode 100644
index d0041fa..0000000
Binary files a/doc_dev_guide/figures/project_process_std_track_doc_variables_graphic.odg and /dev/null differ
diff --git a/doc_dev_guide/figures/project_process_std_track_doc_variables_graphic.svg b/doc_dev_guide/figures/project_process_std_track_doc_variables_graphic.svg
deleted file mode 100644
index 28e3ede..0000000
--- a/doc_dev_guide/figures/project_process_std_track_doc_variables_graphic.svg
+++ /dev/null
@@ -1,1114 +0,0 @@
-
-
-
\ No newline at end of file
diff --git a/doc_dev_guide/figures/project_process_std_track_doc_variables_review_draft_graphic.odg b/doc_dev_guide/figures/project_process_std_track_doc_variables_review_draft_graphic.odg
deleted file mode 100644
index d086d4e..0000000
Binary files a/doc_dev_guide/figures/project_process_std_track_doc_variables_review_draft_graphic.odg and /dev/null differ
diff --git a/doc_dev_guide/figures/project_process_std_track_doc_variables_review_draft_graphic.svg b/doc_dev_guide/figures/project_process_std_track_doc_variables_review_draft_graphic.svg
deleted file mode 100644
index 9d8f895..0000000
--- a/doc_dev_guide/figures/project_process_std_track_doc_variables_review_draft_graphic.svg
+++ /dev/null
@@ -1,553 +0,0 @@
-
-
-
\ No newline at end of file
diff --git a/doc_dev_guide/figures/project_process_std_track_doc_variables_specification_graphic.odg b/doc_dev_guide/figures/project_process_std_track_doc_variables_specification_graphic.odg
deleted file mode 100644
index 345a45a..0000000
Binary files a/doc_dev_guide/figures/project_process_std_track_doc_variables_specification_graphic.odg and /dev/null differ
diff --git a/doc_dev_guide/figures/project_process_std_track_doc_variables_specification_graphic.svg b/doc_dev_guide/figures/project_process_std_track_doc_variables_specification_graphic.svg
deleted file mode 100644
index 51d5000..0000000
--- a/doc_dev_guide/figures/project_process_std_track_doc_variables_specification_graphic.svg
+++ /dev/null
@@ -1,459 +0,0 @@
-
-
-
\ No newline at end of file
diff --git a/doc_dev_guide/figures/project_process_std_track_graphic.odg b/doc_dev_guide/figures/project_process_std_track_graphic.odg
deleted file mode 100644
index 0960c54..0000000
Binary files a/doc_dev_guide/figures/project_process_std_track_graphic.odg and /dev/null differ
diff --git a/doc_dev_guide/figures/project_process_std_track_graphic.svg b/doc_dev_guide/figures/project_process_std_track_graphic.svg
deleted file mode 100644
index afbd985..0000000
--- a/doc_dev_guide/figures/project_process_std_track_graphic.svg
+++ /dev/null
@@ -1,218 +0,0 @@
-
-
-
\ No newline at end of file
diff --git a/doc_dev_guide/figures/project_structure_graphic.odg b/doc_dev_guide/figures/project_structure_graphic.odg
deleted file mode 100644
index 20348a2..0000000
Binary files a/doc_dev_guide/figures/project_structure_graphic.odg and /dev/null differ
diff --git a/doc_dev_guide/figures/project_structure_graphic.svg b/doc_dev_guide/figures/project_structure_graphic.svg
deleted file mode 100644
index efb8827..0000000
--- a/doc_dev_guide/figures/project_structure_graphic.svg
+++ /dev/null
@@ -1,517 +0,0 @@
-
-
-
\ No newline at end of file
diff --git a/doc_dev_guide/pom.xml b/doc_dev_guide/pom.xml
deleted file mode 100644
index 12e8739..0000000
--- a/doc_dev_guide/pom.xml
+++ /dev/null
@@ -1,161 +0,0 @@
-
-
-
-
-
- org.openpowerfoundation.docs
- workgroup-pom
- 1.0.0-SNAPSHOT
- ../pom.xml
-
- 4.0.0
-
-
- openpower-template-guide
-
- jar
-
-
- Documentation Development Guide
-
-
-
-
- 0
-
-
-
-
-
-
-
-
- org.openpowerfoundation.docs
-
- openpowerdocs-maven-plugin
-
-
-
- generate-webhelp
-
- generate-webhelp
-
- generate-sources
-
-
- ${comments.enabled}
- openpower-template-guide
- 1
- UA-17511903-1
-
- appendix toc,title
- article/appendix nop
- article toc,title
- book toc,title,figure,table,example,equation
- book/appendix nop
- book/chapter nop
- chapter toc,title
- chapter/section nop
- section toc
- part toc,title
- reference toc,title
- set toc,title
-
-
- 1
- 3
- 1
-
-
- doc-devel-guide
-
-
- doc-devel-guide
-
-
- workgroupNotes
-
-
-
-
-
-
-
- public
-
-
-
-
- published
-
-
-
-
-
-
- true
- .
-
-
- bk_main.xml
-
-
-
-
- ${basedir}/../glossary/glossary-terms.xml
- 1
- www.openpowerfoundation.org
-
-
-
-
-
diff --git a/doc_dev_guide/sec_example.xml b/doc_dev_guide/sec_example.xml
deleted file mode 100644
index 8bd05dd..0000000
--- a/doc_dev_guide/sec_example.xml
+++ /dev/null
@@ -1,25 +0,0 @@
-
-
-
- Sample section include
- This section was developed in a separate file but included in the document by using the following
- text:]]>
- where sec_example.xml is the source file name.
-
-
diff --git a/doc_dev_guide/sec_template_debugging.xml b/doc_dev_guide/sec_template_debugging.xml
deleted file mode 100644
index a0f5815..0000000
--- a/doc_dev_guide/sec_template_debugging.xml
+++ /dev/null
@@ -1,269 +0,0 @@
-
-
-
- Debugging build failures
- Maven/docbkx failures generally fall into these categories:
-
-
-
-
-
-
- Correcting the document errors starts with understanding which type of failure has occurred and
- understanding where to look in your document source.
-
-
- Project structure errors
-
- Because the OpenPOWER Foundation documentation projects are not self-contained in the
- GitHub repositories, forgetting to clone the Docs-Master project in addition
- to the document project or cloning it in the wrong location is a common problem. Failures of this kind
- produce the following error:
-...
-[INFO] Scanning for projects...
-[ERROR] The build could not read 1 project -> [Help 1]
-[ERROR]
-[ERROR] The project org.openpowerfoundation.docs:workgroup-pom:1.0.0-SNAPSHOT (/home/scheel/Docs-Template/pom.xml) has 1 error
-[ERROR] Non-resolvable parent POM: Could not find artifact org.openpowerfoundation.docs:master-pom:pom:1.0.0-SNAPSHOT and 'parent.relativePath' points at wrong local POM @ line 6, column 11 -> [Help 2]
-[ERROR]
-[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
-[ERROR] Re-run Maven using the -X switch to enable full debug logging.
-[ERROR]
-[ERROR] For more information about the errors and possible solutions, please read the following articles:
-[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/ProjectBuildingException
-[ERROR] [Help 2] http://cwiki.apache.org/confluence/display/MAVEN/UnresolvableModelException
-...
- The identifying characteristic of this error type is the message, "Non-resolvable parent POM". This occurs because the
- pom.xml file in the documentation project, called the "workgroup-pom" because of a project
- <artifactId>workgroup-pom</artifactId> declaration, expects its parent pom file to be in the
- location defined by the <relativePath>../Docs-Master/pom.xml</relativePath>, up one directory and
- then in the Docs-Master director.
-
-
- So, if you see the message "Non-resolvable parent POM", ensure that the Docs-Master project
- and your project have been cloned
- into the same parent directory. See for detailed directions on how to do this.
-
-
-
-
- Docbook validation errors
-
- Validation errors are generally indicated in the build output with text like the following:
-...
-@@@@@@@@@@@@@@@@@@@@@@
-!!!VALIDATION ERRORS!!
-!!!!!!!!!!!!!!!!!!!!!!
-
-Note: Open the temporary file:
-
-file:/home/user1/Docs-Template/doc_dev_guide/target//bk_main.xml-invalid.xml
-
-to see all the errors in context.
-You must correct the errors in the original
-source DocBook or wadl files however.
-
-You can control whether build fails or not by
-setting failOnValidationError to no in your pom.
-
-lineNumber: 272; columnNumber: 70; text not allowed here; expected element "address", ...
- This error message contains three key pieces of information:
-
-
- The full path and filename that contains the context for the failure. In the message above, this is
-/home/user1/Docs-Template/doc_dev_guide/target//bk_main.xml-invalid.xml.
-
-
- The location within the file of the syntax error. For the above example, the key information is "lineNumber: 272; columnNumber: 70.
- In some XML validation failure scenarios, the lineNumber or
- colNumber values are not specified or are -1. If you encounter such a situation,
- please post to the Documentation Development mailing list at syssw-doc_devel_guide@mailinglist.openpowerfoundation.org
- so they can assist in identifying the exact location of the failure.
-
-
- An explanation of the failure. This information in the above error reads, "text not allowed here; expected element "address", ...".
-
-
-
-
-
-
- Build failures
-
- Build errors are easily identified as well. Below is the most common example:
-...
-[INFO] ------------------------------------------------------------------------
-[INFO] BUILD FAILURE
-[INFO] ------------------------------------------------------------------------
-[INFO] Total time: 4.827s
-[INFO] Finished at: Wed Jul 29 14:55:33 CDT 2015
-[INFO] Final Memory: 17M/171M
-[INFO] ------------------------------------------------------------------------
-[ERROR] Failed to execute goal org.openpowerfoundation.docs:openpowerdocs-maven-plugin:1.0.0:generate-webhelp (generate-webhelp) on project openpower-template-guide: Execution generate-webhelp of goal org.openpowerfoundation.docs:openpowerdocs-maven-plugin:1.0.0:generate-webhelp failed: XInclude resource error (sec_template_new_document.xml) and no fallback provided. XProc error err:XD0011: org.xml.sax.SAXParseException; systemId: file:/home/user1/openpower-foundation-docbkx-framework/doc/doc_dev_guide/sec_template_new_document.xml; lineNumber: 55; columnNumber: 17; The element type "para" must be terminated by the matching end-tag "</para>". -> [Help 1]
-...
-
- Like validation errors, three key pieces of information are again provided:
-
-
- The full path and filename of our failure is
-/home/user1/Docs-Template/doc_dev_guide/sec_template_new_document.xml.
-
-
- The location within the file of the error is "lineNumber: 55; columnNumber: 17.
-
-
- An explanation of the failure begins with the text, "The element type "para" must be terminated by the
- matching end-tag "</para>."
-
-
-
- With these details in hand for either error, one simply locates the offending syntax and makes the appropriate
- correction. Online resources such as those listed in may be helpful.
-
- When creating new documentation projects, you may encounter the following error during
- your first build:...
-[ERROR] Failed to execute goal org.openpowerfoundation.docs:openpowerdocs-maven-plugin:1.0.5:generate-webhelp (generate-webhelp) on project openpower-vector-programming-guide: Execution generate-webhelp of goal org.openpowerfoundation.docs:openpowerdocs-maven-plugin:1.0.5:generate-webhelp failed: One of setGitDir or setWorkTree must be called. -> [Help 1]
-...
-
- This error results from interactions of the maven build process and git. It may be
- circumvented by issuing the git init command in your directory.
-
-
-
- FO validation failures
-
- FO (formatting objects) validation failures are a slight bit more difficult to identify and require more effort to correct. A sample appears as follows:
-...
-Error
- SXCH0003: org.apache.fop.fo.ValidationException:
- "{http://www.w3.org/1999/XSL/Format}block" is not a valid child of "fo:list-block"!
- (See position 70:-1): null:70:-1: "{http://www.w3.org/1999/XSL/Format}block" is not
- a valid child of "fo:list-block"! (See position 70:-1)
-[INFO] ------------------------------------------------------------------------
-[INFO] BUILD FAILURE
-[INFO] ------------------------------------------------------------------------
-[INFO] Total time: 35.900s
-[INFO] Finished at: Sat Mar 19 15:54:34 CDT 2016
-[INFO] Final Memory: 107M/256M
-[INFO] ------------------------------------------------------------------------
-[ERROR] Failed to execute goal org.openpowerfoundation.docs:openpowerdocs-maven-plugin:1.0.3:generate-webhelp (generate-webhelp) on project hwarch-caia-spec: Failed to transform to PDF: org.apache.fop.fo.ValidationException: "{http://www.w3.org/1999/XSL/Format}block" is not a valid child of "fo:list-block"! (See position 70:-1): null:70:-1: "{http://www.w3.org/1999/XSL/Format}block" is not a valid child of "fo:list-block"! (See position 70:-1) -> [Help 1]
-...
-
- The "org.apache.fop.fo.ValidationException" text indicates that this error was during FO validation. The key pieces of information are as follows:
-
-
-
- The error type is indicated in the text following the exception indictor. In our case, the error statement is:
- "{http://www.w3.org/1999/XSL/Format}block" is not a valid child of "fo:list-block"!. This error clearly
- has something to do with the nesting of a "fo:block" statement in a "fo:list-block" statement.
-
-
- The location of the validation error is given in the statement
- "See position 70:-1". These two values are the line number and character number of the error. So, our sample
- error occurs on line 70, but the character number
- of -1 is an indication that the line is too long to effectively point.
-
-
-
- What this information fails to detail is which file has the problem. To find the particular offending file, one must understand
- the Docbook build process. This process begins by collecting all XML into a working copy of the main book file. The build failure error
- in includes a reference to this file which will be found in the
- .../target/ directory. It generally has the same name as the main book file of the document, which if copied
- from the Documentation Development Guide project, will be bk_main.xml. When in doubt about
- this file name, you will find it in the <includes> tag in the pom.xml file.
-
- Once all information has been pulled into the working XML file, the XML statements are transformed into FO statements
- in preparation for building the PDF. This step generates a .fo
- file which can be found in the .../target/docbkx/autopdf/ directory and typically has the same base file name as
- the target PDF file. Again, the pom.xml file will clarify this name with the <pdfFilenameBase>
- variable.
-
- If one locates and opens the .fo file, it becomes obvious that it was intended as a working file and is not readily readable. Therefore, the first
- step to understanding this error is to make the FO file more readable.
- The xmllint tool can be used to create a more readable FO file. Assuming you have been
- working in the document directory, the follow steps can be used to produce a more readable XML file:
- $ cd target/docbkx/autopdf
-$ xmllint --nonet --noent --nowarning --version --timing --format -o outfile infile
-xmllint: using libxml version 20901
- compiled with: Threads Tree Output Push Reader Patterns Writer SAXv1 FTP HTTP DTDValid HTML Legacy C14N Catalog XPath XPointer XInclude Iconv ISO8859X Unicode Regexps Automata Expr Schemas Schematron Modules Debug Zlib Lzma
-Parsing took 63 ms
-Saving took 39 ms
-Freeing took 9 ms
-$
-
- For your invocation of xmllint, substitute infile with the name of the Maven-generated
- .fo file for your new project and pick a new outfile for the new .fo file.
-
- The xmllint utility may need to be loaded on your system. On an Ubuntu Linux system,
- this utility is provided in the libxml2-utils package. To locate the proper package for your system,
- you may need to reference Google.
-
- Now, with a nicely formatted FO file, we can re-invoke the FO Processor (FOP) directly and achieve a more readable error. To do this, invoke
- fop as follows:$ fop -fo fofile and -pdf pdffile
-Rendered page #1.
-Rendered page #2.
-Rendered page #3.
-Rendered page #4.
-Rendered page #5.
-Rendered page #6.
-Rendered page #7.
-Exception
-javax.xml.transform.TransformerException: org.apache.fop.fo.ValidationException: "fo:block" is not a valid child of "fo:list-block"! (See position 7830:112)
-$
-
- As expected, the FOP again reports an exception. However, this time the position information appears more complete. With this new information
- and a nicely formatted .fo file, one can find the format statements in error, find the context for the error, and then locate the correct source
- DocBook (XML) file. With this information, one can inspect the document source to decide if the error is bad DocBook syntax or a tooling bug. If the latter,
- please save the newly formatted .fo file and include it in the bug writeup.
-
- This error generally indicates a problem with documentation tooling. If you encounter such a situation,
- please post to the Documentation Development mailing list at syssw-doc_devel_guide@mailinglist.openpowerfoundation.org
- so they can assist in identifying the exact cause of the failure.
- If you wish to fully understanding the error, you may require knowing more about XSL FO syntax. Many such web sites exist for this, but
- the XSL Formatting Objects Summary from W3C (World Wide Web Consortium) provides a good starting reference online at
- https://www.w3.org/2002/08/XSLFOsummary.html.
-
-
-
-
- Java AWT exception
-
- Use of Maven in headless environments from Mac OS has uncovered an intermittent exception in the AWT libraries.
- This error looks like the following:...
----------------------------------------------------
-Exception in thread "main" java.awt.AWTError: Can't connect to X11 window server using 'localhost:11.0' as the value of the DISPLAY variable.
- at sun.awt.X11GraphicsEnvironment.initDisplay(Native Method)
- at sun.awt.X11GraphicsEnvironment.access$200(X11GraphicsEnvironment.java:65)
- at sun.awt.X11GraphicsEnvironment$1.run(X11GraphicsEnvironment.java:115)
- at java.security.AccessController.doPrivileged(Native Method)
- at sun.awt.X11GraphicsEnvironment.<clinit>(X11GraphicsEnvironment.java:74)
- at java.lang.Class.forName0(Native Method)
- at java.lang.Class.forName(Class.java:264)
- at java.awt.GraphicsEnvironment.createGE(GraphicsEnvironment.java:103)
- at java.awt.GraphicsEnvironment.getLocalGraphicsEnvironment(GraphicsEnvironment.java:82)
- at sun.awt.X11.XToolkit.<clinit>(XToolkit.java:126)
-...
-
- The circumvention for this error, is force AWT to run headless. This can be accomplished by adding the
- -Djava.awt.headless=true parameter to the maven invocation such that it looks like this:
- $ mvn clean generate-sources -Djava.awt.headless=true
-
-
-
-
diff --git a/doc_dev_guide/sec_template_existing_document.xml b/doc_dev_guide/sec_template_existing_document.xml
deleted file mode 100644
index 23a3462..0000000
--- a/doc_dev_guide/sec_template_existing_document.xml
+++ /dev/null
@@ -1,130 +0,0 @@
-
-
-
- Modifying an existing document
-
- To begin editing an existing document, you may need to clone up to two projects --
- the specific document project, and if not already cloned, the master document framework project too.
- If needed, clone the master document as described in .
-
- To obtain a copy of the desired document source, clone its project. For example, to clone this document,
- Documentation Development Guide, from the
- public OpenPOWER Foundation git repository, use this
- command:$ git clone https://github.com/OpenPOWERFoundation/Docs-Template.git
-Cloning into 'Docs-Template'...
-Username for 'https://github.com': my_userid
-Password for 'https://my_userid@github.com': my_password
-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.
-$
-
- To build a specific document such as this guide, follow these steps from the directory where
- you just cloned:$ cd Docs-Template/doc_dev_guide
-$ mvn clean
-[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 ~/Docs-Template/doc_dev_guide/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] ------------------------------------------------------------------------
-$ mvn generate-sources
-[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] ------------------------------------------------------------------------
-$
-
- 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 mvn clean generate-sources would accomplish the
- same thing as the above sequence of commands.
-
- If all goes well, the generated pdf should be available in ~/Docs-Template/doc_dev_guide/target/docbkx/webhelp/template-guide/.
-
- For assistance correcting commmon build failures, see .
-
- Projects may contain multiple documents. While specific documents can be built by executing a
- mvn clean generate-sources in the specific document directory, executing this command in
- the base project directory will build all projects identified in the <module> list in the
- top-level pom.xml file, known as the "Workgroup POM".
-
- Before diving deeply into text updates,
- you should consider the following items for your project and document:
-
-
- Ensure that the previous version of the tree is tagged.
-
- The command git tag may be used to see existing tree tags
- and set new ones.
- See for more specifics on git tag commands.
-
-
- Reset the document status.
- The pom.xml file contains the <documentStatus> field which generally
- needs to be reset to the draft value. In addition, for non-public work groups, the <security>
- field should be returned to workgroupConfidential or foundationConfidential
- values during the document update process. More information on
- document development process can be found in . Detailed information on
- key document settings can be found in and
- .
-
-
- Incement the new document release information.
- The bk_main.xml file contains the <releaseinfo> field
- which contains the Versions, Release, and Modification values. Typically, new documents when first being edited will increment the correct value,
- reset sub-values to zero, and append a "_preN" tag. During the development process, you will likely increment the "N-value" in your "pre" release
- information. Then, at publish, you can remove the "_preN" suffix.
- More details on the release information can be found in recommendation
- .
-
-
- Create a new entry in the revision history.
- The bk_main.xml file contains the revision history in <revhistory> table. To start a new entry,
- add a new <revision> entry with <date> and <revdescription> fields at the top
- of the list of revisions.
-
-
-
- You are now ready to make textual updates.
-
-
-
diff --git a/doc_dev_guide/sec_template_faq.xml b/doc_dev_guide/sec_template_faq.xml
deleted file mode 100644
index cb081dc..0000000
--- a/doc_dev_guide/sec_template_faq.xml
+++ /dev/null
@@ -1,30 +0,0 @@
-
-
-
- Frequently asked questions
- The list of questions and answers may be helpful to first time document writers:
-
-
- Do I have to follow the guidelines in of this guide?
- No. HOWEVER, doing so makes it simpler for all community members to participate in maintaining your document.
-
-
-
-
-
diff --git a/doc_dev_guide/sec_template_getting_started.xml b/doc_dev_guide/sec_template_getting_started.xml
deleted file mode 100644
index bf5be45..0000000
--- a/doc_dev_guide/sec_template_getting_started.xml
+++ /dev/null
@@ -1,206 +0,0 @@
-
-
-
- Getting started
- To begin contributing to the OpenPOWER Foundation documentation, the following steps must be completed:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Once complete, you can proceed to either or
- as needed.
-
-
- Installing tools
- Only two tools are required to update documentation, git and maven. Git manages the documentation
- 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.
- On Debian-based Linux operating systems (Ubuntu and Debian), install maven and git as follows:
- # apt-get install git
-# apt-get install maven
- On RPM-based Linux operating systems (Fedora, RHEL, openSUSE, SLES), install maven and git as follows:
- # yum install git
-# yum install maven
- On Mac OS X, use Macports to install maven and git as follows:
- # port install git
-# port install maven3
- or use Homebrew to install maven and git as follows:
- $ brew install git
-$ brew install maven
- For information on how to setup the environment on Windows, see the following websites:
-
-
- git for Windows - http://msysgit.github.io/
-
-
- Maven on Windows -
- http://maven.apache.org/guides/getting-started/windows-prerequisites.html
-
-
-
- Modification of documentation source files requires a text editor. While standard editors like vim, emacs, or gedit can be used,
- it is highly recommended that an editor be used which highlights XML or Docbook syntax. If your favorite editor does not include an
- extension or plugin to accomplish this, you might consider using Bluefish to edit your docbook files. Details on this editor
- can be found at http://bluefish.openoffice.nl/index.html.
-
-
-
- Installing fonts
- The OpenPOWER Foundation documentation utilizes opensource fonts known as the
- Chrome OS core fonts or Croscore fonts.
- The three TrueType fonts (TTFs) in this family Arimo (sans-serif), Tinos (serif), and Cousine (monospace). While
- not strictly required to have these fonts on your system, it can be helpful when designing graphics and
- other images to have them installed on your development system.
- Only two tools are required to update documentation, git and maven. Git manages the documentation
- 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.
- On Debian-based Linux operating systems (Ubuntu and Debian), install Croscore fonts as follows:
- # apt-get install fonts-croscore
- On RPM-based Linux operating systems (Fedora, RHEL, openSUSE, SLES), install Croscore fonts as follows:
- # yum install google-croscore-fonts
- On Mac OS X and Windows systems, use a font website to download and install the Croscore fonts individually. Most of
- these sites provide directions for Mac OS and Windows.
-
-
-
- Creating accounts
- All OpenPOWER project documentation is maintained in GitHub trees, public and private. The first
- step to creating documentation will be joining the GitHub community.
- To join the GitHub community,
- apply at https://github.com/join.
- The OpenPOWER Foundation documentation trees are grouped in the OpenPOWER Foundation project at
- https://github.com/OpenPOWERFoundation.
- Everyone should be able to see and access public trees like Docs-Master. However,
- if you will be participating in private OpenPOWER Foundation trees, you will need to request access from the
- Technical Steering Committee Chair, tsc-chair@openpowerfoundation.org.
- To learn more about using git, see the online article in GitHub Help, "Good Resources for Learning Git and GitHub." at
-
- https://help.github.com/articles/good-resources-for-learning-git-and-github/.
-
-
-
- Cloning master document information
- To successfully build OpenPOWER Foundation documents, common document files must be in place in addition to the specific
- document files. These common files are obtained by cloning the OpenPOWER Foundation public project Docs-Master.
- To clone the OpenPOWER Foundation master document framework,
- use the clone git command:$ git clone https://github.com/OpenPOWERFoundation/Docs-Master.git
-Cloning into 'Docs-Master'...
-remote: Counting objects: 24, done.
-remote: Compressing objects: 100% (18/18), done.
-remote: Total 24 (delta 6), reused 20 (delta 5), pack-reused 0
-Unpacking objects: 100% (24/24), done.
-Checking connectivity... done.
-$
- More information can be found about the Docs-Master project online at
- https://github.com/OpenPOWERFoundation/Docs-Master. Additional details about the OpenPOWER Foundation documentation structure
- are explained in of this document.
-
-
-
- Building the first document
- The final step of setting up your environment to perform the first build. The following steps are recommended:
-
-
- Clone the Documentation Development Guide (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 .
- $ git clone https://github.com/OpenPOWERFoundation/Docs-Template.git
-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.
-$
-
-
- Change the working directory into the source directory for the Documentation Development Guide.
- $ cd Docs-Template/doc_dev_guide
-Docs-Template/doc_dev_guide$
-
-
- Build the document in Maven.Docs-Template/doc_dev_guide$ mvn generate-sources
-[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
-
-<!DOCTYPE html
- PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-Parsing: /home/scheel/mydocs/Docs-Template/doc_dev_guide/target/docbkx/webhelp/doc-devel-guide/content/section_cloning_project.html
- ...snip...
-The created index files are located in /home/scheel/mydocs/Docs-Template/doc_dev_guide/target/docbkx/webhelp/doc-devel-guide/content/search/.js
-[INFO] See /home/scheel/mydocs/Docs-Template/doc_dev_guide/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] ------------------------------------------------------------------------
-Docs-Template/doc_dev_guide$
- 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.
-
-
- Once complete, there should be a single directory in the target/docbkx/webhelp/ directory. For the
- Docs-Template project, that directory is doc-devel-guide. Inside this directory will
- be both the PDF file and the index.html file for the HTML document.
- To verify this for the Documentation Development Guide, perform these commands:
- Docs-Template/doc_dev_guide$ cd target/docbkx/webhelp/
-Docs-Template/doc_dev_guide/target/docbkx/webhelp$ ls
-doc-devel-guide
-Docs-Template/doc_dev_guide/target/docbkx/webhelp$ cd doc-devel-guide
-Docs-Template/doc_dev_guide/target/docbkx/webhelp/doc-devel-guide$ ls
-bookinfo.xml common content doc-devel-guide-20180227.pdf favicon.ico index.html
-webapp
- Now, you are ready to begin working on your own document. Useful information on how to proceed can
- be found in and .
-
-
-
diff --git a/doc_dev_guide/sec_template_git_commands.xml b/doc_dev_guide/sec_template_git_commands.xml
deleted file mode 100644
index c66c351..0000000
--- a/doc_dev_guide/sec_template_git_commands.xml
+++ /dev/null
@@ -1,182 +0,0 @@
-
-
-
- Common git commands
- This section provides a list of commonly used git command invocations. All commands shown, except
- the first one (git clone must be issued from within the project directory.
-
-
-
-
- To clone a git tree for first time or temporary use via http,
- use:$ git clone <URL>
- The <URL> value for OpenPOWER Foundation GitHub projects can be found on the project web pages.
- They generally take the form of https://github.com/OpenPOWERFoundation/project_name where the
- project_name can be found on the OpenPOWER Foundation Git Hub community page at
- https://github.com/OpenPOWERFoundation. The result of this
- command will be a new directory with the same name as the project and in which will be the project files.
- Trees can only be cloned once. To update a tree, use a git pull or git merge
- command.
- When cloning from a private tree, you will be prompted for your GitHub userid and password.
-
-
-
- To update a git tree with new files from the remote repository,
- use:$ git pull
- This command assumes that the local tree has not been updated since the clone or last pull. If updates have been made to
- the local tree, the command will fail. Use the git status command to see what has changed in a local tree.
- When pulling from a private tree, you will be prompted for your GitHub userid and password.
-
-
-
- To see the status of the local repository,
- use:$ git status
- This command identifies files which have changed in the local repository and provides suggestions on how to handle.
-
- Adding the -s parameter to the end of the command will provide a simplified view in which changed files
- are listed with flags such as M for modified files, A for newly added files,
- and ?? for new or unknown files. This parameter also suppresses suggested action information for the files.
-
-
-
- To add a new file or directory to a git tree,
- use:$ git add <new_file>
- The <new_file> value can be either a file or a whole directory and may include the path to
- the target file or directory. This command will convert the status of file in the git status -s
- command from ?? to A or move it from the "Untracked files" section to the
- "Changes to be committed" section of the git status command.
-
-
-
- To remove a file from a git tree,
- use:$ git rm <file>
- The <file> value must be a file and may include wildcard characters or the path to
- the target file. This command will both remove the file(s) from the directory and the git tree. Removed files will show in
- a status modifier of D in the git status -s
- command and be reflected in the "Changes not staged for commit" section of thegit status command
- with a "deleted:" status.
-
-
-
- To remove a directory from a git tree,
- use:$ git rm -rf <directory>
- The <directory> value must be a directory name and may include wildcard characters or the path to
- the target directory. This command will remove all files in the directory from the git tree, but will not remove the directory locally.
- Standard operating system commands such as the Linux rmdir <directory> command must be issued separately to
- remove the local directory. All removed files will show in
- a status modifier of D in the git status -s
- command and be reflected in the "Changes not staged for commit" section of thegit status command with a
- "deleted:" status. Because git does not
- track directories, they will not be reflected in status.
-
-
-
- To move or rename a file or directory in a git tree,
- use:$ git mv <source> <destination>
- The <source> value must be a file or directory and may include the path to
- the target file. The <destination> value may be a file (if renaming a file) or a directory
- if moving a file or directory.
- This command will move or rename the file(s) in both the local and remote the git trees.
-
-
-
- To commit all local changes to the staging area for a git tree,
- use:$ git commit -a
- This command will invoke an editor for a commit message. A well-formatted commit message includes a
- title on the first line, a blank line, one or more lines of details describing the changes, and a Developer's
- Certificate of Orig (DCO) Sign-off statement at the end. Signed-off-by: Your name <your_email@domain.com>
- For information on the DCO, see Developer Certificate Of Origin at
- http://elinux.org/Developer_Certificate_Of_Origin.
-
-
-
- To push all locally staged changes to the remote git tree,
- use:$ git push
- When pushing to a private tree, you will be prompted for your GitHub userid and password.
-
-
-
- To see what tags exist in a git tree,
- use:$ git tag
-
-
-
- To create a new tag locally,
- use:$ git tag -a <tag_name> -m"text"
- The tag_name represents the simple value of the tag. The text string
- provides more description of the tag for readibility.
- This command simply tags locally. See the next command for how to push the tag to the remote repository.
-
-
-
- To push a new tag from the local tree to the remote tree,
- use:$ git push origin <tag_name>
- This commands assumes the git tag command has been run on the local tree.
-
-
-
- To discard changes from a locally changed file and return to the last copy,
- use:$ git checkout -- <file>
- The <file> value must be a file and may include wildcard characters or the path to
- the target file.
-
-
-
- To identify what changes have been made locally to a file
- use:$ git diff <file>
- The <file> value must be a file and may include wildcard characters or the path to
- the target file. The output will be in format similar to the standalone diff command.
-
-
-
-
- Additional resources about git can be found online at the following locations:
-
-
-
-
- The GitHub Glossary at
- https://help.github.com/articles/github-glossary/.
- This site provides a list of common terms associated with git and GitHub.
-
-
-
- The GitHub Git Cheat Sheet at
-
- https://training.github.com/kit/downloads/github-git-cheat-sheet.pdf.
- This two page pdf provides a quick summary of many common commands.
-
-
-
-
- The Git Reference at
- http://gitref.org/. This is a deeper and more comprehensive reference of important commands.
-
-
-
- The git-scm.com Documentation library at
- http://git-scm.com/doc. This site provides education in the form of books, videos,
- and other tutorials for common git activities.
-
-
-
-
-
-
-
diff --git a/doc_dev_guide/sec_template_new_document.xml b/doc_dev_guide/sec_template_new_document.xml
deleted file mode 100644
index 63e4a99..0000000
--- a/doc_dev_guide/sec_template_new_document.xml
+++ /dev/null
@@ -1,401 +0,0 @@
-
-
-
- Creating a new document
- Creating a new document from scratch follows four simple steps:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Before undertaking one of these activities, it may be helpful to read the
-
- section to learn the basics about the documentation project structure.
-
-
- Cloning a project
- All documentation projects reside in a Git project directory, either locally or in the cloud at GitHub.
- As described in , your document project directory must reside locally in the
- same directory as the Docs-Master framework.
-
- To clone a project in which to work, select from one of the two approaches below:
-
-
-
-
-
-
-
- Complete the project cloning and then continue with the next step in
- .
-
-
- Cloning an existing project
-
- To work in an existing OpenPOWER Foundation project like the Documentation Development
- Guide (Docs-Template),
- use the following command in the same directory that contains
- Docs-Master:$ git clone https://github.com/OpenPOWERFoundation/Docs-Template.git
-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.
-$ The results should look roughly something like above with actual numbers of objects, files, etc. varying
- for different projects.
-
- Private projects prompt for a GitHub userid and and password immediately following the "Cloning into..." message.
- When cloning public projects such as Docs-Template, these prompts are skipped.
-
- A list of additional OpenPOWER Foundation projects can be found at
- https://github.com/OpenPOWERFoundation/. To work
- on an existing project, note its name it the list and apply the above steps replacing Docs-Template
- with your preferred project from the list.
-
- If you do not see the project for which you are looking, you may not be authorized to it. See
- 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, tsc-chair@openpowerfoundation.org, to request and get this setup.
-
- The existing project should now be cloned. Continue with the next step in
- .
-
-
-
- Creating a new project locally
-
- To create a new project locally, the simplest way is to clone the Documentation Development
- Guide (Docs-Template) into a new project. In
- our directions, my_project will be our new project name.
- Use the following command in the same directory that contains
- Docs-Master:$ git clone https://github.com/OpenPOWERFoundation/Docs-Template.git my_project
-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.
-$ The results should look roughly something like above with actual numbers of objects, files, etc. varying
- for different projects.
-
- The new project should now be generally setup. Continue with the next step in
- .
-
-
-
-
-
- Finding a document framework
-
- 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:
-
-
-
- If your project exits on GitHub in the OpenPOWER Foundation area and it contains a doc_template directory,
- then follow the directions in
-
- to use this document as a base.
-
-
- 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
-
- to establish your base document.
-
-
- Otherwise, the instructions in
-
- will clone and copy this document as a base.
-
-
-
-
- Moving the template document into your new document framework
-
- 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 Docs-Template.
- You can verify this by inspecting
- the files in your project directory. A new project will contain a doc_template directory, a pom.xml
- file, a LICENSE file, and a README.md file. If this is the case, you simply
- need to perform the following three steps:
-
-
-
- Navigate down to your project directory, called my_project for this example. This can be achieved
- using the cd command:
-$ cd ~/my_project
-$
- This directory should contain the doc_template folder used to prime the project.
-
-
- Rename the doc_template document directory to something new like my_doc.
- To accomplish this, use the mv command::
-$ mv doc_template/ my_doc
-
-
- Change the project name in the Workgroup POM file (my_project/pom.xml). Using your editor, change this line
- between the <modules> and the </modules> tags near the top of the
- file:template
-]]> to read like this:my_doc
-]]>
-
-
-
- Your new document frameword has been copied from the Document Development Guide.
- Continue with the next step in
- .
-
-
-
-
- Copying an existing document as a new document framework
-
- 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:
-
-
-
- Navigate down to your project directory, called my_project for this example.
- This can be achieved using the cd command:
-$ cd ~/my_project
-$
- This directory should contain the folder name of the document wishing to be copied, called source_doc
- for clarity in these directions.
-
-
- To create a new document directory, simply create a new directory and copy the contents of the source_doc
- directory. If creating a new directory named my_doc via a command line, the command
- sequence would look like this:
-$ mkdir my_doc
-$ cp -r source_doc/*.* my_doc
-$
-
-
- Add the new project to the Workgroup POM file (my_project/pom.xml).
- Using your editor, add the following lines
- between the <modules> and the </modules> tags near the top of the file:my_doc
-]]>
-
-
-
- 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 git add my_doc/ command on the whole directory.
-
- You are now ready to begin making updates to your new document. Continue with the next step in
- .
-
-
-
-
- Copying the Document Development Guide as a new document framework
-
- Instead of copying an existing document, you may want to start with the Document Development Guide
- (Doces-Template) 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:
-
-
-
- Navigate down to your project directory, called my_project for this example.
- This can be achieved using the cd command:
-$ cd ~/my_project
-$
- This directory should contain any existing document folders along with at least a pom.xml file, a
- LICENSE file, and a README.md file.
-
-
- Clone the the Documentation Development Guide
- (Docs-Template) project into your working directory with this
- command:$ git clone https://github.com/OpenPOWERFoundation/Docs-Template.git
-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.
-$
-
-
- To create a new project directory, simply create a new directory and copy the contents of the Docs-Template/doc_dev_guide
- directory. If creating a new project named my_doc via a command line, the command
- sequence would look like this:
-$ mkdir my_doc
-$ cp -r Docs-Template/doc_dev_guide/* my_doc
-$
-
-
- 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 rm -rf Docs-Template
-
-
- Finally, add the new project to the Workgroup POM file (my_project/pom.xml).
- Using your editor, add the following lines
- between the <modules> and the </modules> tags near the top of the file:my_doc
- ]]>
-
-
-
- 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 git add my_doc/ command on the whole directory.
-
- You are now ready to begin making updates to your new document. Continue with the next step in
- .
-
-
-
-
-
-
- Modifying core project files
- The first step to customizing a new project is to modify two core project files--pom.xml
- and bk_main.xml. Within these two files are XML comment tags that begin "<!-- TODO:"
- 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.
-
- In the pom.xml file, pick your settings for document work product type (<workProduct>,
- work flow status (<documentStatus>), and
- security (<security>)
- carefully. 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.
-
- In addition to the document settings, be sure to remember two key values you used in the pom.xml
- file, <webhelpDirname>
- and <pdfFilenameBase>, as these will be used to locate your generated document.
-
- In the book.xml file, you will find the following document unique values which you most likely want to change:
-
-
- <title>
-
- The main title of the document. This appears in the largest font at the top of the title page.
-
-
-
-
- <subtitle>
-
- The second title of the document. This title appears in a smaller font below the <title> on the title page.
-
-
-
-
- <realeaseinfo>
-
- The document version value. This value should take the form of "Revision V.R.M" as described in
- recommendation .
-
-
-
-
-
- When ready, build your new document using standard maven commands like
- this:$ cd my_project/my_doc
-$ mvn clean
-[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] ------------------------------------------------------------------------
-$ mvn generate-sources
-[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] ------------------------------------------------------------------------
-$
- If all goes well, the new generated pdf should be available in
- target/docbkx/webhelp/<webhelpDirname>/<pdfFilenameBase>.pdf.
- For assistance correcting commmon build failures, see .
-
- 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 mvn clean generate-sources would accomplish the
- same thing as the above sequence of commands.
-
- You have completed updates to core project files for your new document. Continue with the next step in
- .
-
-
-
-
- Adding new content
-
- The starting point for book content is the bk_main.xml 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:
-
-
-
-
-
-
-
-
-
-
-
-
-]]>
-
- 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 ch_example.xml and app_template.xml files
- may serve as excellent starting points. For XML examples of various document structures, please see
- and its supporting source files in this document. Online resources such as those listed in
- may also be helpful.
-
- When creating new files for the project, remember to use the git add <file name> command to
- add new files to the git tree.
-
-
-
-
diff --git a/doc_dev_guide/sec_template_policies.xml b/doc_dev_guide/sec_template_policies.xml
deleted file mode 100644
index f0e7279..0000000
--- a/doc_dev_guide/sec_template_policies.xml
+++ /dev/null
@@ -1,82 +0,0 @@
-
-
-
- Policies and conventions
- Most document style policies are established simply by using the provided documentation framework. However,
- by applying some conventions to the document source structure, community members will be able to work across more d
- ocumentation projects.
- The recommended documentation structure guidelines are as follows:
-
-
- The head book file should be named with the prefix "bk_".
-
-
- The document versioning as defined by the <releaseinfo> tag in the main book
- file bk_xxx should be named "Revision V.R.M", not "Version V.R.M" or simply "V.R.M" where:
-
-
- Significant updates increment the V (Version) value while reseting the R and
- M values to 0,
-
-
- Material, but small, updates increment the R (Release) value and reset the M
- to 0, and
-
-
- Trivial updates (such as typos and grammatical changes) only need to increment the M (Modifier)
- value.
-
-
- Numbering of "pre-release" versions or draft versions of a document may be handled in multiple ways such as
- incrementing the previous modifier level until publication and then updating appropriately, setting the releases to
- the anticipated level and then appending a "_preN" suffix where "N" can be incremented during drafting. Each Work Group
- may set their own policy here.
-
-
- Chapters files should be named with the prefix "ch_".
-
-
- Section and sub-section files should be named with the prefix "sec_".
-
-
- Appendix files should be named with the prefix "app_".
-
-
- Figures source and images should be placed in the figures sub-directory for the document.
-
-
- Releases of the same document sound be contained in the same tree, but tagged at levels of interest using
- the git tag command. See the for more specifics
- on git commands.
-
-
-
- In addition to documentation structure, general community/project guidelines are as follows:
-
-
- Contributions to the documentation projects should conform to the Developer Certificate
- Of Origin as defined at
- http://elinux.org/Developer_Certificate_Of_Origin. Commits to the GitHub project need
- to contain the following line to indicate the submitter accepts the
- DCO:Signed-off-by: Your name <your_email@domain.com>
-
-
-
-
-
diff --git a/doc_dev_guide/sec_template_process.xml b/doc_dev_guide/sec_template_process.xml
deleted file mode 100644
index d7498fa..0000000
--- a/doc_dev_guide/sec_template_process.xml
+++ /dev/null
@@ -1,465 +0,0 @@
-
-
-
- Publishing OpenPOWER Documents
- The OpenPOWER Foundation Work Group (WG) Process document
- found in the OpenPOWER Foundation Members Community documents is the definitive guide for understanding
- OpenPOWER Foundation documents and their work flow. Details such as the duration and types of reviews as
- well as approval voting specifics are found in this document.
-
- This section of the guide does not attempt to provide process details, but instead strives to
- provide an overview to help writers understand enough of the basics to know how to prepare their
- document and what to expect as they proceed through various stages of document development from first
- draft to publication.
-
- The first key concept to understand about OpenPOWER Foundation documents and the first
- decision to make when creating a new document is available document types or "Work Products".
- These fall into one of two categories -- Standards Track or Non-standards Track -- with the simple
- distinguishing factor being use. If the purpose of a document is to define a specification or standard
- for hardware or software, then the document is "Standards Track". Everything else is "Non-standards
- Track." For example, this document is a Non-Stardard Work Product as noted on the title page
- and the lower right corner of every subsequent page.
-
- Non-standard Track Work Products exist simply as Work Group Notes. Their document
- lifecycle follows this simplified workflow:
-
-
- Overview of Non-standard Track Work Products
-
-
-
-
-
-
-
- Non-standard Track, Work Group Notes begin as Drafts and drop the "Draft" annotation once reviewed. As shown
- in the figure, the document lifecycle always returns to a "Draft" form for updates and new versions as needed.
-
- At any step in cycle, these documents may have security classifications as Public (non-confidential), Members-only
- (OpenPOWER Foundation Confidential), or Work-Group only (OpenPOWER Work Group Confidential) which will
- in turn dictate the review context (public or private).
-
-
-
- Standards Track Work Products begin their life as Work Group Specification and may ultimately
- become an OpenPOWER Standard. Their document lifecycle is defined in the following illustration:
-
-
- Overview of Standard Track Work Products
-
-
-
-
-
-
-
- Standard Track Work Products begin their lives as Work Group Specifications and have security classifications
- of Public (non-confidental),
- Members-only (OpenPOWER Foundation Confidental), or Work Group-only (OpenPOWER Work Group Confidential).
- The security classification impacts the review type -- either public or internal to the Foundation -- as appropriate.
- Only Work Group Specifications classified as Public may proceed into OpenPOWER Standard Documents. Confidential
- documents will remain Work Group Specifications.
-
- The following sections will provide additional details about how to control the document markings
- and what the process that dictates those markings:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Understanding document marking variables in the pom.xml file
-
- Once the document type decision has been made (Work Group Note or Work Group Specification),
- two additional markings must be considered during the documentation process: the document confidentiality and
- the document status. The next section,
- ,
- details how these values will change during the publishing process. But, before diving into the process,
- let us see what values in the document pom.xml file play a role in the document
- development process.
- The document Work Product categorization, security classification, and document status are reflected
- in the following ways:
-
-
-
-
- The document Work Product type is defined in the document pom.xml file with the
- <workProduct> variable. Valid settings are workgroupNotes,
- workgroupSpecification, candidateStandard, and openpowerStandard.
- Select the appropriate setting in the following section:
-
-workgroupNotes
-
-
-]]>
-
-
-
- The document security is set in the document pom.xml file with the
- <security> variable. Valid settings are public,
- foundationConfidential, and workgroupConfidential.
- Select the appropriate setting in the following section:
-
-workgroupConfidential
-
-]]>
-
-
-
- The document work flow status is set in the document pom.xml file with the
- <documentStatus> variable. Valid settings are draft,
- review, and published.
- Select the appropriate setting in the following section:
-
-draft
-
-]]>
-
-
-
- The final place to make updates to a new document is in the <abstract> section of
- the bk_main.xml file for the document. This section needs to be updated with the appropriate
- work group information and document information. Typical text appears as follows:
-
-
- The purpose of this document is to provide a guide for OpenPOWER
- documentation writers. As such, it provides directions, policies,
- references, and examples of the XML Docbook environment. It is intended to be
- used both in final product form (PDF and html) as a document and in source form
- as a template for new documents.
- This document is a Non-standard Track, Work Group Note work product
- owned by the System Software Workgroup and handled in compliance with the
- requirements outlined in the OpenPOWER Foundation Work Group (WG)
- Process document.
-]]>
- As stated in the comment text of the book file, the first paragraph provides a typical abstract
- statement about your particular document. The second paragraph provides more structured
- text which should be updated with the appropriate Work Group name, Work Product type,
- and Work Product process. The rest of the information in this paragraph should remain as-is.
-
-
-
-
-
-
-
-
- Navigating the OpenPOWER Foundation
- documentation publishing process
-
- As described in the previous section,
- , document
- markings for work product, document confidentiality, and document status are set by the
- <workProduct>, <security>, and
- <documentStatus> variables respectively. Selecting the appropriate value
- for each variable, however, generally depends on the status of the document in the development process.
-
- The following figures and sub-sections provide detailed information about variable settings and process
- steps. For these figures, the following standards are used:
-
-
-
- Rectangle boxes in various shades of blue represent the work product states previous introduced in
- .
-
-
- Green diamonds containing question marks,
- represent decision points with their key questions in bold green and the answers in standard green text.
-
-
- Red octagons represent actions required in the process such as reviews or approvals.
- Specific descriptions are noted in bold red text beside the octagon.
-
-
- Black text along the right side of the connecting lines, indicates changes to the
- various variables in the document pom.xml file.
-
-
-
-
-
- This flowchart expands upon the Non-Standard Track Work Product lifecycle
- first introduced in . Document markings and key
- process decisions and approvals occur as shown.
-
-
- Document work flow for Non-Standard Track Work Products
-
-
-
-
-
-
-
- The only Non-Standard Track Work Product <workProduct> setting is workgroupNotes.
- Documents in this track have this value set and never changed.
-
- During the work flow progression of the document, a common decision point for the Non-Standard Track Work Product
- centers on <security> settings. Documents may be marked as public
- just prior to review or prior to approval. Each work
- group will need to review their charter and determine whether public release of their work products is expected or allowed.
-
- The <documentStatus> variable tracks quite simply through the work flow, beginning as
- draft, transitioning to review, and finishing as published when finished.
-
- A feature which makes a Non-Standard Track document unique is that the Work Group is the only approver prior to publish
- as a Work Group Note. As will be seen in the next figure, Standard Track Work Products often require multiple reviews.
-
- The following flowchart expands upon the Standard Track Work Product lifecycle
- first introduced in . Document markings and key
- process decisions and approvals reflect a more complex process than the previous one for Non-Standard Work Products.
-
-
-
-
- Document work flow for Standard Track Work Products
-
-
-
-
-
-
-
- Like Non-Standard Track Work Products, Standard Track documents frequently evaluate the appropriate security setting.
- Unlike them, Standard Track Work Products involve many more steps, require numerous approval cycles, and ultimately create
- a public document (<security>public</security>) when they become a
- Candidate OpenPOWER Standard Work Product.
-
- While the <workProduct> type has a value of workgroupSpecification,
- the <documentStatus> variable progress as expected -- beginning as
- draft, transitioning to review, and finishing as published.
-
- Unlike the Non-Standard Work Product, the <workProduct> variable begins as
- workgroupSpecification, but may
- transition to candidateStandard as it is proposed to be a Candidate OpenPOWER Standard Work Product
- and ultimately becomes openpowerStandard if the document is approved as an OpenPOWER Standard Work Product.
- In these latter work flow stages, the <documentStatus> and <security>remain as
- published and public respectively and never change.
- However, it is work noting that a document may simply exist as a Work Group Specification Work Product for its whole
- lifecycle. Progression through Candidate OpenPOWER Standard to OpenPOWER Standard is an optional step.
-
- For a deeper look at the process, see the next section,
- , for step-by-step
- descriptions of the Standard Product work flow.
-
-
-
-
-
- Understanding the specific steps of Standard Work Product documents
-
- provides an overview of the work flow of both Non-Standard and
- Standard Work Products. While is rather straightforward,
- is larger and more complex. In an attempt to simplify
- the process, the following figures
- decompose each state into just the actions needed to progress to the next step for Standard Track Work Products.
-
- For detailed assistance with the development of Standard Track Work Products,
- select the figure which reflects your current document state. Then, follow the work flow to understand both
- the document settings and actions needed to progress to the next document state.
-
-
-
- For documents either getting started as Work Group Specification Draft or having returned to this state for updates,
- reference the following figure. Documents in this state will have
- <workProduct>workgroupSpecification</workProduct> and
- <documentStatus>draft</documentStatus> in their document POM (pom.xml).
-
-
- Document work flow for Standard Track Work Products in the Specification Draft State
-
-
-
-
-
-
-
- To proceed from a Work Group Specification Draft to a Work Group Specification Review Draft, a document requires 3 approvals, in this
- order: sponsoring Work Group, Technical Steering Committee, and Board of Directors. Following these three approvals,
- the document POM (pom.xml) variable
- <documentStatus> should be set to review. In addition, the
- <security> variable may be set to public if the review is targeted to be public.
-
-
-
- For documents currently in Work Group Specification Review Draft state
- (<workProduct>workgroupSpecification</workProduct> and
- <documentStatus>review</documentStatus>),
- consult this figure.
-
-
- Document work flow for Standard Track Work Products in the Specification Review Draft State
-
-
-
-
-
-
-
- To proceed from a Work Group Specification Review Draft to a Work Group Specification, a document requires
- a successful review and 3 approvals in this
- order: sponsoring Work Group, Technical Steering Committee, and Board of Directors. Following these three approvals,
- the document POM (pom.xml) variable
- <documentStatus> should be set to published. In addition, the
- <security> variable should be set to public if for public specifications.
-
-
-
- For Work Group Specifications marked
- <workProduct>workgroupSpecification</workProduct> and
- <documentStatus>published</documentStatus>,
- see the next figure.
-
-
- Document work flow for Standard Track Work Products in the Specification State
-
-
-
-
-
-
-
- A document in the Work Group Specification state may return to a Work Group Specification Draft or
- proceed as a Candidate OpenPOWER Standard.
-
- To make updates, the document returns to the Work Group Specification Draft state. To
- accomplish this, the <documentStatus> variable should be set to draft and
- <security> should be set to either public or
- workgroupConfidential.
-
- To proceed to a Candidate OpenPOWER Standard, a document requires 3 approvals, in this
- order: sponsoring Work Group, Technical Steering Committee, and Board of Directors. Following these three approvals,
- the <workProduct> variable should be set to candidateStandard and
- <security> should be set to public.
-
-
-
- For documents currently in Work Group Candidate OpenPOWER Standard state
- (<workProduct>candidateStandard</workProduct> and
- <documentStatus>published</documentStatus>),
- reference the following figure.
-
-
- Document work flow for Standard Track Work Products in the Candidate OpenPOWER Standard State
-
-
-
-
-
-
-
- A document in the Work Group Candidate OpenPOWER Standard state may proceed in two directions, back to a Work Group Specification Draft or on to a
- Candidate OpenPOWER Standard.
-
- To make updates to a Work Group Candidate OpenPOWER Standard document, the document returns to the Work Group Specification Draft state. To
- accomplish this, the <documentStatus> variable should be set to draft and
- <security> should be set to either public or
- workgroupConfidential depending on how the Work Group handles document drafts.
-
- To proceed to an OpenPOWER Standard, a document requires a successful review and a single approval from the Board of Directors.
- Following this approval, the document POM (pom.xml) variable
- <workProduct> should be set to openpowerStandard.
-
-
-
- Packaging the document for publish
-
- The OpenPOWER Foundation process for publishing documents from WordPress in the
- Resource Catalog on openpowerfoundatoin.org website has the following requirements:
-
-
- The PDF and all HTML source must be bundled in a self-contained zip file.
-
-
- The zip file is expected to contain a single directory in which the document PDF and index.html file are found.
-
-
- The filename of the zip file must be the same name as the contained directory.
-
-
-
- To create this package for the Documentation Development Guide, one would perform the following commands
- in Linux from the document source directory (.../Docs-Template/doc_dev_guide/):
- Docs-Template/doc_dev_guide$ cd target/docbkx/webhelp/
-Docs-Template/doc_dev_guide/target/docbkx/webhelp$ ls
-doc-devel-guide
-Docs-Template/doc_dev_guide/target/docbkx/webhelp$ zip -rv doc-devel-guide.zip doc-devel-guide/
- 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
-Docs-Template/doc_dev_guide/target/docbkx/webhelp/doc-devel-guide$ ls
-doc-devel-guide doc-devel-guide.zip
- For MacOS and Windows, the steps will be similar with slight variations on the command to create the zip file.
- This zip file can be sent to the person managing the documents in the OpenPOWER Resource Catalog.
-
-
-
-
diff --git a/doc_dev_guide/sec_template_references.xml b/doc_dev_guide/sec_template_references.xml
deleted file mode 100644
index 96a7344..0000000
--- a/doc_dev_guide/sec_template_references.xml
+++ /dev/null
@@ -1,38 +0,0 @@
-
-
-
- Finding more information
- The following lists of references may be helpful in learning about XML, Docbook, and/or Maven:
-
-
- XML In a Nutshell by Elliotte Rusy Harold and W. Scott Means. Online at http://docstore.mik.ua/orelly/xml/xmlnut/index.htm.
-
-
- DocBook 5: The Definitive Guide by Normal Walsh. Online at https://www.safaribooksonline.com/library/view/docbook-5-the/9781449380243/.
-
-
- DocBook XSL: The Complete Guide by Bob Stayton. Online at http://www.sagehill.net/docbookxsl/.
-
-
- Maven: The Complete Reference by Tim O'Brien, Manfred Moser, John Casey, Brian Fox, Jason Van Zyl, Eric Redmond, and Larry Shatzer. Online at http://books.sonatype.com/mvnref-book/reference/index.html.
-
-
-
-
-
diff --git a/doc_dev_guide/sec_template_structure.xml b/doc_dev_guide/sec_template_structure.xml
deleted file mode 100644
index 2e0ec05..0000000
--- a/doc_dev_guide/sec_template_structure.xml
+++ /dev/null
@@ -1,89 +0,0 @@
-
-
-
- Understanding the project structure
- The OpenPOWER Foundation documentation build process involves dependency on a common
- framework and shared files. As such, a deeper explanation about the relationships of key projects and their
- components may be helpful to prevent and diagnose documentation build problems. This section
- provides a pictorial layout of key files and explains their roles and relationships.
-
- As mentioned multiple times throughout this guide, successful build of any OpenPOWER Foundation
- document requires two things:
-
- The cloning of the Docs-Master project.
- The cloning of the specific documentation project into the same parent directory as the
- Docs-Master project.
-
- To begin to understand why, let us use a picture. The following graphic illustrates
- the directory structure of three projects: two existing OpenPOWER Foundation GitHub projects,
- Docs-Master and Docs-Template, and a
- hypothetical new project named my_project.
-
-
- Directory structure and key files in the OpenPOWER Foundation Docbook projects
-
-
-
-
-
-
-
- To create this structure, one would clone the Docs-Master project to
- get the Docs-Master directory and all its contents (shown above in green),
- clone the Docs-Template project to get the Docs-Template directory
- and all its contents (shown in blue), and clone my_project project to get the
- my_project directory and all its contents (shown in red).
-
- Among these projects, the most important directory and project is Docs-Master. Without this project
- and associated directory, no document will build. As depicted in the above figure, the Docs-Master directory
- must sit at a level equal to all other project directories. Details on how to install this project can be found in the
- section.
-
- Inside the Docs-Masterproject directory, the two most important pieces are a
- commmon directory
- and a pom.xml file. The directory contains common files used by all projects such as the common preface
- (ch_preface.xml) and the common appendix (app_foundation.xml). The pom.xml file
- in this directory serves as the "Master POM" (POM stands for Program Object Model and serves as the main configuration file)
- for all builds. This file references the OpenPOWER Maven Plugin JAR
- (found in the OpenPOWER Foundation Repository at
- http://openpowerfoundation.org/repo.openpowerfoundation.org/)
- used to control the OpenPOWER
- Foundation document builds where all other dependencies, supporting tools, and document build rules are defined.
-
- The Docs-Template project and directory are depicted in blue in the above figure. The top level of the
- project Docs-Template must be cloned into the same parent directory as the Docs-Master
- for Maven builds to complete successfully.
- At the top level of the Docs-Template project
- are a pom.xml referred to as the "Workgroup POM" and a single document directory (template).
- The "Workgroup POM" is a minimal POM file that locates the parent, "Master POM" in the Docs-Masterproject directory
- with a <relativePath> definition of ../Docs-Master/pom.xml.
- The document directory contains the unique files used to create the document. The two most important files in the
- Docs-Template/doc_dev_guide directory (and in any project) are the pom.xml or "Document POM" which describes
- how to build the document and which points to the main document file, the bk_main.xml file. This book file
- contains all the Docbook source, directly or through include statements (<xi:include href="..."),
- to build the document.
-
- For completeness of understanding, a hypothetical project my_project is also depicted in red. Like all
- OpenPOWER Foundation projects, it is cloned at the correct level, equal to Docs-Master. Like the
- Docs-Template project, it has a "Workgroup POM" which will differ only in the <modules>
- section where it will describe two document projects, my_doc_1 and my_doc_2. But, each
- document directory has similar contents to Docs-Template/template -- a "Document POM" (pom.xml)
- and a "Main book file" (bk_main.xml).
-
-
diff --git a/doc_template/app_template.xml b/doc_template/app_template.xml
deleted file mode 100644
index f4b7ae4..0000000
--- a/doc_template/app_template.xml
+++ /dev/null
@@ -1,30 +0,0 @@
-
-
-
-
- Appendix template
- This is the first paragraph of a new appendix...
-
- Section title
- Section text...
-
-
diff --git a/doc_template/bk_main.xml b/doc_template/bk_main.xml
deleted file mode 100644
index c656c15..0000000
--- a/doc_template/bk_main.xml
+++ /dev/null
@@ -1,109 +0,0 @@
-
-
-
-
-
-]>
-
-
-
-
- Title
-
- Sub-title
-
-
-
-
-
- TBD Work Group Name
-
- tbd-chair@openpowerfoundation.org
-
- OpenPower Foundation
-
-
-
- 2018
- OpenPOWER Foundation
-
-
- Revision 1.0_pre1
- OpenPOWER
-
-
-
-
-
-
- Copyright details are filled in by the template.
-
-
-
-
-
-
- The purpose of this document is to ...TBD describe the document
- This document is a Standard Track, Workgroup Specification work product owned by the
- TBD Workgroup and handled in compliance with the requirements outlined in the
- OpenPOWER Foundation Work Group (WG) Process document. It was
- created using the Master Template Guide version &template_version;.
- Comments, questions, etc. can be submitted to the
- public mailing list for the parent specification at
- tbd@mailinglist.openpowerfoundation.org.
-
-
-
-
-
- 2018-08-29
-
-
-
- TODO: Describe your initial draft, e.g. from where it came if not created from scratch
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/doc_template/ch_example.xml b/doc_template/ch_example.xml
deleted file mode 100644
index 2f81fb1..0000000
--- a/doc_template/ch_example.xml
+++ /dev/null
@@ -1,323 +0,0 @@
-
-
-
-
- Documentation examples
-
-
-
- Section Title goes here
- This Section covers something of interest to a limited number of people and shows a 1st level section
-
-
- Example Itemized List
-
- Here is an example of an itemized list
-
- A list title is completely optional
-
-
- Item you don't care about
-
-
- Perhaps you'd like a sub-list
-
-
- Oooh, here's about another
-
-
-
-
-
-
-
- Item you might care about
-
-
-
- Item you do care about
-
-
-
-
- Example ordered list
-
- All good documents need ordered lists.
-
- Another purely optional title
-
- First item
-
-
- Second item
-
-
- first indented item
-
-
- second indented item
-
-
-
-
- Third item
-
-
-
-
-
- Example figure with embedded graphic
-
- Here is how you embed a graphic.
-
- Example figure
-
-
-
-
-
-
- Raw images such as the bitmap (bmp) file above may become blurry as they are scaled.
- Scalable graphic formats like SVG (Scalable Vector Graphics) embed and scale the best.
-
-
-
- Example table
- Of course all good documents need tables. Here's how you build a basic table.
-
-
- Example Table Title
-
-
-
-
-
-
-
-
-
- 1st Column Heading
-
-
-
-
- 2nd Column Heading
-
-
-
-
- 3rd Column Heading
-
-
-
-
- 4th Column Heading
-
-
-
-
-
-
-
- Yes
-
-
- Red
- Green
- Blue
- Custom (Amber)
-
-
- MAIN_Junk
-
-
- More_Junk
-
-
-
-
- merged cells horizontal
-
-
- cell_stuff
-
-
-
-
- Merge cells vertical
-
-
- filler
-
-
- merge cells both ways
-
-
-
-
- filler 2
-
-
-
-
- How about we put a list in the table cell
-
-
- item 1
-
-
- item 2
-
-
- item 2
-
-
-
-
- Another Cell
-
-
- Yet Another Cell
-
-
- Finally the last cell
-
-
-
-
-
-
-
- Example of crossreferences and footnotes
- To reference another section or table is pretty easy. For example: see for how tables look.
- Lists are shown in and if you need to make a footnote
- The footnote text goes here and can reference something like for additional explanation.
- For clarification that is easy. Of course you might want an additional reference to the footnote which can also be done easily.
- Lastly you probably want to mark text by making it italic text example or Bold Text Example.
-
-
- Example of code citations and user input
- When showing user input, you want a nice sceen-looking layout, a prompt, monospace text, and a way to differentiate input from output. Here's an example:
- $ echo "Hello world"
-Hello world
-$
-
- Docbook also allows for formatting and display of common languages, allowing for whitespace
- and line returns just as they are written. Here's a sample snippet of C code with line numbering enabled:
-main()
-{
- printf("Hello world\n");
-}]]>
- If code formatting is not quite what you need, simply displaying text "literally" may suffice as follows: This is my literal
-text. It ignores whitespace.
-
-
- Example of special characters in text
- Sometimes in text you need special characters. These can be provided using their UNICODE values such as ≠ (≠),
- Ω (Ω), and ∆ (∆).
- These can be "coded" using the form &#ddddd; where ddddd is
- the up to five digit decimal representation of the character. The form &#xhhhh; where
- hhhh is the up to 4 digit hexidecimal representation of the character.
- This formatting works well as long as the symbol to which you are referring is contained in the font set
- used for the document -- Arimo for standard text and Cousine for monospace. If when building a document, you see a message like
- "WARNING, Glyph...not available in font 'Arimo',"
- see in for details on using the provided symbol fonts explicitly.
-
-
-
-
-
- Examples of OpenPOWER Foundation Docbook extensions
-
- The OpenPOWER Foundation Maven Plugin supports a number of extensions that are not pure Docbook. These are:
-
-
- Setting text color explicitly
-
- Text color can be controlled using <phrase role="color:color_name">
- tag where color_name contains the color setting. For example, this
- text:A red sentence contains a blue word.]]> produces this sentence:
- A red sentence contains a blue word.
- Valid colors include either a keyword color name or a numerical RGB specification. Keyword names are common with the HTML 4 specificiation:
- aqua, black, blue, fuchsia, gray,
- green, lime, maroon, navy, olive,
- purple, red, silver, teal, white,
- and yellow. Additionally, RGB values can be #nnnnnn where nnnnnn is a hexidecimal color value or
- rgb(n1, n2, n3) where n1, n2, and n3 are integers 0-255.
- This tag has also been implemented on the following tags: <thead>,
- <tbody>, and <tfoot>.
- This parameter should only be used for tags listed above.
-
-
-
- Inserting line breaks
- Line breaks can be introduced using <?linebreak?> tags. For example, this
- text:A line break in the middle of text]]> produces this sentence:
- A line break in the middle of text
- This tag becomes useful in table text spacing.
-
-
-
- Inserting page breaks
- Page breaks can be introduced using <?hard-pagebreak?> tags. For example, this
- text:A page breakBetween two paragraphs]]> produces this output:
- A page breakBetween two paragraphs
- This tag becomes useful in placing tables on page. Placing this statement before a large table may prevent it from spanning a page.
- Because the XSL template behind the Processing Instruction generates
- a ]]> in
- the book FO output, this instruction should be used in the outer most blocks of a section to work effectively. Use inside lists and other structural
- components may result in the text after the break being dropped. User beware!.
-
-
-
- Varying the font size
- Font sizes can also be set using the
- <phrase role="font-size:size">
- tag where size contains a size value such as "6pt" or "50%" or "1.5em".
- For example, a paragraph can be made to be 6 point as follows:A sentence that contains some 6pt font,
-50% font, and
-1.5em font in it.]]> produces this output:
- A sentence that contains some 6pt font,
- 50% font, and 1.5em font in it.
- This tag has also been implemented on the following tags: <para>,
- <thead>, <tbody>, and <tfoot>.
- This parameter should only be used for tags listed above.
-
-
-
- Using additional symbols
- If you find that the Arimo and Cousine fonts do not contain the special symbol you need
- for your document, you may use the additional symbol font provided for document (STIX Two Math).
- Due to an unimplemented feature in the Apach FO Processor, selection of this
- font needs to be explicitly performed using the
- <symbol role="symbolfont"> wrapper around your symbol value.
-
- For example, the symbol coding of should produce
- a circle with a cross in here "⨁", but instead creates a "Glyph...not available in font 'Arimo'" error
- on document build and the PDF renders as a "#".
-
- Re-coding this to use ⨁]]> produces
- the correct symbole here "⨁".
- If this still does not provide the symbol you expected, double check the code and the font maps found at
- http://www.stixfonts.org/charactertable.html.
-
-
-
-
-
diff --git a/doc_template/figures/example_graphic.bmp b/doc_template/figures/example_graphic.bmp
deleted file mode 100644
index 296b4ea..0000000
Binary files a/doc_template/figures/example_graphic.bmp and /dev/null differ
diff --git a/doc_template/pom.xml b/doc_template/pom.xml
deleted file mode 100644
index d601a92..0000000
--- a/doc_template/pom.xml
+++ /dev/null
@@ -1,161 +0,0 @@
-
-
-
-
-
- org.openpowerfoundation.docs
- workgroup-pom
- 1.0.0-SNAPSHOT
- ../pom.xml
-
- 4.0.0
-
-
- todo-artifact_id
-
- jar
-
-
- todo-name
-
-
-
-
- 0
-
-
-
-
-
-
-
-
- org.openpowerfoundation.docs
-
- openpowerdocs-maven-plugin
-
-
-
- generate-webhelp
-
- generate-webhelp
-
- generate-sources
-
-
- ${comments.enabled}
- openpower-template-guide
- 1
- UA-17511903-1
-
- appendix toc,title
- article/appendix nop
- article toc,title
- book toc,title,figure,table,example,equation
- book/appendix nop
- book/chapter nop
- chapter toc,title
- chapter/section nop
- section toc
- part toc,title
- reference toc,title
- set toc,title
-
-
- 1
- 1
- 1
-
-
- todo-builddir-name
-
-
- todo-pdfFile-name
-
-
-
- workgroupSpecification
-
-
-
-
- workgroupConfidential
-
-
-
-
- draft
-
-
-
-
-
-
-
-
- true
- .
-
-
- bk_main.xml
-
-
-
-
- ${basedir}/../glossary/glossary-terms.xml
- 1
- www.openpowerfoundation.org
-
-
-
-
-
diff --git a/doc_template/sec_example.xml b/doc_template/sec_example.xml
deleted file mode 100644
index 8bd05dd..0000000
--- a/doc_template/sec_example.xml
+++ /dev/null
@@ -1,25 +0,0 @@
-
-
-
- Sample section include
- This section was developed in a separate file but included in the document by using the following
- text:]]>
- where sec_example.xml is the source file name.
-
-
diff --git a/errata_template/bk_main.xml b/errata_template/bk_main.xml
deleted file mode 100644
index 2fa45e5..0000000
--- a/errata_template/bk_main.xml
+++ /dev/null
@@ -1,117 +0,0 @@
-
-
-
-
-
-]>
-
-
-
-
- <TBD Base Document Name> Errata
- For <TBD Base Document Name and version>
-
-
-
-
-
-
- TBD Work Group Name
-
- tbd-chair@openpowerfoundation.org
-
- OpenPower Foundation
-
-
-
- 2018
- OpenPOWER Foundation
-
- Revision 1.0
- OpenPOWER
-
-
-
-
-
-
-
-
-
-
- Copyright details are filled in by the template.
-
-
-
-
-
- This document provides errata against version
- #.#.# of the
- Base Document Title
- specification. These errata should be considered part of said specification until such
- time as a newer version of the full specification is published.
- This document is a Non-standard Track, Work Group Note work
- product owned by the
- TBD Workgroup
- and handled in compliance with the requirements outlined in the
- OpenPOWER Foundation Work Group (WG) Process document. It was
- created using the Master Template Guide version &template_version;.
- Comments, questions, etc. can be submitted to the
- public mailing list for the parent specification at
-
-
- tbd@mailinglist.openpowerfoundation.org.
-
-
-
-
-
- 2018-08-29
-
-
-
- TODO: Describe your initial draft, e.g. from where it came if not created from scratch
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/errata_template/ch_errata.xml b/errata_template/ch_errata.xml
deleted file mode 100644
index 36088d6..0000000
--- a/errata_template/ch_errata.xml
+++ /dev/null
@@ -1,78 +0,0 @@
-
-
-
-Errata
-
-
-The following statements in version
- #.#.#
- of the
- Base Document Title
- specification are incorrect, and should be considered corrected as specified.
-
-
-
-
- Section <#.#>, <Section Name>
-
- Problem:
-
- TBD: Describe the problem here. For example,
- "Paragraph 2 contains a statement that makes use of undefined behavior according to the C standard."
- Then, cite the offending text in the next paragraph block.
-
-
-
-
-
-
- Regardless of the alignment rules for the allocation of data types,
- pointers to both aligned and unaligned data of each data type shall
- return the value corresponding to a data type starting at the specified
- address when accessed with either the pointer dereference operator * or
- the array reference operator [ ].
-
-
-
-
-
-
- Resolution:
- TBD: Describe resolution. For example,
- "Paragraph 2 is stricken from the text." If needed, add a block quote of the
- updated text like below.
-
-
-
-
-
-
-
- C pointer types have an emperical and undefined behavior which applications
- should simply tolerate. Therefore and regardless of the alignment rules for
- the allocation of data types, pointers to both aligned and unaligned data of
- each data type shall return the value corresponding to a data type starting at the specified
- address when accessed with either the pointer dereference operator * or
- the array reference operator [ ]. Anything that doesn't work is somebody else's
- problem.
-
-
-
-
-
-
-
diff --git a/errata_template/pom.xml b/errata_template/pom.xml
deleted file mode 100644
index bf8f71f..0000000
--- a/errata_template/pom.xml
+++ /dev/null
@@ -1,159 +0,0 @@
-
-
-
-
-
- org.openpowerfoundation.docs
- workgroup-pom
- 1.0.0-SNAPSHOT
- ../pom.xml
-
- 4.0.0
-
-
- todo-errata
-
- jar
-
-
- todo-errata
-
-
-
-
- 0
-
-
-
-
-
-
-
-
- org.openpowerfoundation.docs
-
- openpowerdocs-maven-plugin
-
-
-
- generate-webhelp
-
- generate-webhelp
-
- generate-sources
-
-
- ${comments.enabled}
- openpower-template-guide
- 1
- UA-17511903-1
-
- appendix toc,title
- article/appendix nop
- article toc,title
- book toc,title,figure,table,example,equation
- book/appendix nop
- book/chapter nop
- chapter toc,title
- chapter/section nop
- section toc
- part toc,title
- reference toc,title
- set toc,title
-
-
- 1
- 3
- 1
-
-
- todo-errata
-
-
- todo-pdfFile-errata
-
-
- workgroupNotes
-
-
-
-
-
- workgroupConfidential
-
-
-
-
- draft
-
-
-
-
-
-
-
- true
- .
-
- bk_main.xml
-
-
-
-
- ${basedir}/../glossary/glossary-terms.xml
- 1
- www.openpowerfoundation.org
-
-
-
-
-
diff --git a/rst_template/bk_main.xml b/rst_template/bk_main.xml
deleted file mode 100644
index b792d5b..0000000
--- a/rst_template/bk_main.xml
+++ /dev/null
@@ -1,82 +0,0 @@
-
-
-
-
-
-]>
-
-
-
-
- TBD
- TBD
-
-
-
- TBD
- TBD
-
- OpenPower Foundation
-
-
-
- TBD
- TBD
-
- TBD
- OpenPOWER
-
-
-
-
-
-
-
- Copyright details are filled in by the template.
-
-
-
- TBD
-
-
- TBD
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/rst_template/opf_docbook.py b/rst_template/opf_docbook.py
deleted file mode 100644
index adb92e7..0000000
--- a/rst_template/opf_docbook.py
+++ /dev/null
@@ -1,292 +0,0 @@
-#!/usr/bin/python
-# -*- coding: utf-8 -*-
-#
-# Builds OpenPOWER Foundation documentation using standard template.
-#
-# Assumes rst2db has been used to convert rst to docbook.
-#
-import os, sys, getopt, shutil, errno
-from git import Repo
-from lxml import etree
-from conf import opf_docbook_settings, master_doc
-from subprocess import Popen, PIPE
-
-
-def copy_xml_to_template(src_dir, tgt_dir):
- # Copy XML files
- src_files = os.listdir(src_dir)
- for filename in src_files:
- full_file = os.path.join (src_dir, filename)
- if (os.path.isfile(full_file)):
- shutil.copy(full_file, tgt_dir)
- elif (os.path.isdir(full_file)):
- try:
- os.makedirs(os.path.join(tgt_dir,filename))
- except OSError as exception:
- if exception.errno != errno.EEXIST:
- raise
- copy_xml_to_template( os.path.join(src_dir,filename), os.path.join(tgt_dir,filename) )
-
-def update_file(filename, old_str, new_str):
- # Verify tag exists
- with open(filename) as f:
- s = f.read()
- if old_str not in s:
- print 'Error: "{old_str}" not found in {filename}.'.format(**locals())
- sys.exit(-2)
-
- # Safely write the changed content, if found in the file
- with open(filename, 'w') as f:
- s = s.replace(old_str, new_str)
- f.write(s)
-
-def print_tree(element, level):
- # Print current element
- num_children = element.__len__()
- indent = ' '.ljust(level+1)
- print indent, 'Tag: ', element.tag, ' Attrib: ', element.attrib, ' Num children: ', num_children
-
- for i in range(num_children):
- child = element.__getitem__(i)
- print_tree(child, level+1)
-
-def convert_top_level_sections(head, file):
- path = os.path.dirname(file)
- if 'sect' in head.tag:
- head.tag = 'book'
-
- # Clear attributes
- for attrib in head.attrib.keys():
- head.attrib.pop(attrib, None)
- if head.attrib.items() != []:
- print 'Error: Section attributes not removed. ', head.attrib.items(), ' items remain -- ', head.attrib.keys()
- sys.exit(-5)
-
- # Walk children to remove title
- num_children = head.__len__()
- for i in range(num_children):
- child = head.__getitem__(i)
- if 'title' in child.tag:
- head.__delitem__(i)
- break
-
- # Walk children looking for next set of tags, opening include files if necessary
- num_children = head.__len__()
- num_chapter = 0
- for i in range(num_children):
- child = head.__getitem__(i)
-
- # check for section tag
- if 'section' in child.tag:
- # Convert tag to
- child.tag = child.tag.replace('section','chapter')
- num_chapter = num_chapter+1
-
- # check for include tag
- if 'include' in child.tag:
- # Open and parse include file
- # NOTE: We will only check one level deep
- include_file = child.attrib['href']
- full_include_file = os.path.join(path,include_file)
- parser = etree.XMLParser(remove_comments=False)
- tree = etree.parse(full_include_file, parser=parser)
- #print_tree( tree.getroot(), 0 )
-
- # Check for sections
- include_head = tree.getroot()
- if 'sect' in include_head.tag:
- # Convert tag to
- include_head.tag = include_head.tag.replace('section','chapter')
- num_chapter = num_chapter+1
-
- # Create backup file
- shutil.copy2(full_include_file, full_include_file+'.bak')
-
- # Write out changed file
- tree.write(full_include_file)
- if num_chapter == 0:
- print 'Error: No chapters found in document'
- sys.exit(-6)
- else:
- print 'Toc file contains ', head.tag, 'tag, not '
- sys.exit(-4)
-
-def remove_book_tags(old_file, new_file):
- with open(old_file, 'r') as input:
- with open(new_file, 'wb') as output:
- for line in input:
- if '' not in line:
- output.write(line)
-
-def insert_toc_into_book(toc_file, book_file):
- book_file_bak = book_file+'.bak'
- shutil.copy2(book_file, book_file_bak)
- key_string = ''
- inserted_toc = False
-
- with open(book_file_bak, 'r') as input:
- with open(book_file, 'wb') as output:
- for line in input:
- if key_string not in line:
- output.write(line)
- else:
- inserted_toc = True
- # Write toc_file contents
- with open(toc_file, 'r') as input_toc:
- for line_toc in input_toc:
- output.write(line_toc)
-
- if not inserted_toc:
- print 'Error: key string of "', key_string, '" not found in ', book_file
- sys.exit(-7)
-
-def build_revhistory(book_file):
- # Variables for formating git log
- log_format = '%h%x01%an%x01%ad%x01%s%x02'
- log_fields = ['id', 'author', 'date', 'subject']
-
- # Retrieve log
- pipe = Popen('git log --date=iso --format="%s" -- . .' % log_format, shell=True, stdout=PIPE)
- log, _ = pipe.communicate()
-
- # Substitute for problem characters: &, <, >
- log = log.replace('&','&').replace('<','<').replace('>','>')
-
- # Remove newlines, trailing end-of-record (0x02), and then split at end-of-record
- log = log.replace('\n','').strip('\x02').split('\x02')
-
- # Split records into individual fields
- log = [row.split('\01') for row in log]
-
- # Create dictionary using field names
- log = [dict(zip(log_fields, row)) for row in log]
-
- # Format log into revision history
- revision = '\n'
- for entry in log:
- revision = revision + '' + entry['date'].split(' ')[0] + '' +\
- entry['subject'] + ' (' + entry['id'] + ')\n'
- revision = revision + '\n'
-
- # Update file
- rev_str = 'TBD'
- update_file(book_file, rev_str, revision)
-
-
-def main(argv):
- master_git_url = 'https://github.com/OpenPOWERFoundation/Docs-Master.git'
- template_git_url = 'https://github.com/OpenPOWERFoundation/Docs-Template.git'
- build_dir = ''
- db_dir = ''
- master_dir = ''
- template_dir = ''
- toc_file = master_doc+'.xml'
-
- try:
- opts, args = getopt.getopt(argv,"hb:d:m:t:",["builddir=","docbookdir=","masterdir=","templatedir="])
- except getopt.GetoptError:
- print 'Invalid option specified. Usage:'
- print ' opf_docbook.py -b -d -m -t '
- sys.exit(-1)
- for opt, arg in opts:
- if opt == '-h':
- print 'opf_docbook.py -b -d -m -t '
- sys.exit(0)
- elif opt in ("-b", "--builddir"):
- build_dir = arg
- elif opt in ("-d", "--docbookdir"):
- db_dir = arg
- elif opt in ("-m", "--masterdir"):
- master_dir = arg
- elif opt in ("-t", "--templatedir"):
- template_dir = arg
-
- # Clone a new Master Directory
- print 'Cloning new Docs-Master directory...'
- if os.path.exists(master_dir):
- shutil.rmtree(master_dir)
- Repo.clone_from(master_git_url, master_dir)
-
- # Clone a new Template Directory
- print 'Cloning new Docs-Template directory...'
- if os.path.exists(template_dir):
- shutil.rmtree(template_dir)
- Repo.clone_from(template_git_url, template_dir)
-
- # Locate the TOC file
- rst_template_dir = os.path.join(template_dir, 'rst_template')
- full_toc_file = os.path.join(rst_template_dir, toc_file)
- book_file = os.path.join(rst_template_dir, 'bk_main.xml')
-
- # Copy all files and directories in docbook dir into rst_template recursively
- print 'Copying docbook files into template build directory...'
- copy_xml_to_template( db_dir, rst_template_dir)
-
- # Update all file in opf_docbook_settings with tag/value combinations specified
- print 'Updating Docbook files with settings from conf.py...'
- for f in opf_docbook_settings.keys():
- filename = os.path.join(rst_template_dir, f)
- tags = opf_docbook_settings[f]
-
- for tag in tags:
- value = opf_docbook_settings[f][tag]
-
- if value != '':
- new_str = '<'+tag+'>'+value+''
- else:
- new_str = ''
-
- old_str = '<'+tag+'>TBD'
- update_file(filename, old_str, new_str)
-
- # Parse TOC file, convert high level tag to "book" and write back out to .tmp1 file
- print 'Cleaning up Docbook file structure...'
- parser = etree.XMLParser(remove_comments=False)
- tree = etree.parse(full_toc_file, parser=parser)
- # print_tree( tree.getroot(), 0 )
- convert_top_level_sections( tree.getroot(), full_toc_file )
- full_toc_file_tmp1 = full_toc_file+'.tmp1'
- tree.write(full_toc_file_tmp1)
-
- # Eliminate and tags in .tmp1 and write to .tmp2 file
- full_toc_file_tmp2 = full_toc_file+'.tmp2'
- remove_book_tags(full_toc_file_tmp1, full_toc_file_tmp2)
-
- # Update link to first file
- insert_toc_into_book(full_toc_file_tmp2, book_file)
-
- # Create revision history from Git Log
- print 'Building document revision history from git log...'
- build_revhistory(book_file)
-
- # Perform build of Docbook
- print 'Building Docbook PDF and HTML output in Maven...'
- maven_log_file = 'build.log'
- maven_build = 'cd ' + rst_template_dir + '; mvn generate-sources 2>&1 | tee ' + maven_log_file + ''
- pipe = Popen(maven_build, shell=True)
- log, err = pipe.communicate()
-
- if pipe.returncode != 0:
- print "Build failed with return code:%s" % pipe.returncode
- print "See %s/build.log for more details" & rst_template_dir
-
- # Copy output to better location
- print 'Copying build output...'
- bld_out_dir = os.path.join(rst_template_dir, 'target/docbkx/webhelp')
- html_head = os.path.join(bld_out_dir, opf_docbook_settings['pom.xml']['webhelpDirname'] + '/index.html')
- if os.path.exists(bld_out_dir) and os.path.exists(html_head):
- doc_dir = os.path.join(build_dir, 'docbook/opf_docbook')
-
- if os.path.exists(doc_dir):
- shutil.rmtree(doc_dir)
- shutil.copytree(bld_out_dir, doc_dir)
- print "Build successful. Output files located in %s" % os.path.join(doc_dir, opf_docbook_settings['pom.xml']['webhelpDirname'])
-
- sys.exit(0)
-
- else:
- print "Docbook build failed. Check logfile %s for details." % os.path.join(rst_template_dir, maven_log_file)
- sys.exit(-10)
-
-if __name__ == "__main__":
- main(sys.argv[1:])
diff --git a/rst_template/opf_html2db.py b/rst_template/opf_html2db.py
deleted file mode 100644
index 79f1c33..0000000
--- a/rst_template/opf_html2db.py
+++ /dev/null
@@ -1,692 +0,0 @@
-#!/usr/bin/python
-# -*- coding: utf-8 -*-
-#
-# Builds OpenPOWER Foundation documentation using standard template.
-#
-# Assumes rst2db has been used to convert rst to docbook.
-#
-import os, sys, getopt, shutil, errno, subprocess, copy, re
-from os import fdopen, remove
-from shutil import move
-from git import Repo
-from lxml import etree
-from conf import opf_docbook_settings, master_doc, project
-from subprocess import Popen, PIPE
-
-
-def copy_xml_to_template(src_dir, tgt_dir):
- # Copy XML files
- src_files = os.listdir(src_dir)
- for filename in src_files:
- full_file = os.path.join (src_dir, filename)
- if (os.path.isfile(full_file)):
- shutil.copy(full_file, tgt_dir)
- elif (os.path.isdir(full_file)):
- try:
- os.makedirs(os.path.join(tgt_dir,filename))
- except OSError as exception:
- if exception.errno != errno.EEXIST:
- raise
- copy_xml_to_template( os.path.join(src_dir,filename), os.path.join(tgt_dir,filename) )
-
-def update_file(filename, old_str, new_str):
- # Verify tag exists
- with open(filename) as f:
- s = f.read()
- if old_str not in s:
- print 'Error: "{old_str}" not found in {filename}.'.format(**locals())
- sys.exit(-2)
-
- # Safely write the changed content, if found in the file
- with open(filename, 'w') as f:
- s = s.replace(old_str, new_str)
- f.write(s)
-
-def traverse_clean_html_source_examples(filename):
- temp_file = filename + '.tmp'
- code_found = False
- html_source_start_regex = '^<div class="highlight-default"><div class="highlight"><pre>'
- html_source_stop_regex = '^</pre></div>'
- span_regex = '\<span(\sclass="[a-z]+")?>'
-
- print filename
-
- # Walk file by line
- with open(temp_file, 'w') as new_file:
- with open(filename) as old_file:
- for line in old_file:
- if re.match(html_source_start_regex,line):
- # print 'DEBUG: Code block start found'
- code_found = True
- elif re.match(html_source_stop_regex,line):
- # print 'DEBUG: Code block stop found'
- code_found = False
-
- if code_found:
- oldline = line
- # Remove </span> references
- line = line.replace('</span>', '')
- # Remove <span class=...> references
- line = re.sub(span_regex, '', line)
- # print 'DEBUG: line changed.\n Old: >' + oldline + '<\n New: >' + line + '<'
- new_file.write(line)
-
- # Preserve old file
- move(filename, filename + '.bak')
-
- # Move new file into old
- move(temp_file, filename)
-
-def traverse_clean_html_nodes(element):
-
- if 'ul' in element.tag and element.attrib:
- key = element.attrib.keys()[0]
- value = element.attrib[key]
- if 'id' in key:
- first_child = element.__getitem__(0);
- if first_child.__len__() == 0:
- print 'Error: Bad assumption. <ul> tag is empty.'
-
- # Add attribute to first_child and remove from element
- first_child.attrib[ key ] = value;
- del element.attrib[ key ]
-
- # print 'DEBUG: <ul> attributes: ', element.attrib
- # print 'DEBUG: child attributes: ', first_child.attrib
- sys.stderr.write( '**Information: id attribute on <ul> tag to first sub-element, <' + element.tag + '> for ' + key + ' = ' + value + '\n' )
-
- for child in element.getchildren():
- traverse_clean_html_nodes(child)
-
-def cleanup_html(infile, outfile):
-
- # Create internal representation of document from infile
- parser = etree.XMLParser(remove_comments=False)
- tree = etree.parse(infile, parser=parser)
- head = tree.getroot()
-
- # print_tree( head, 0, 2 )
-
- # Walk nodes doing any cleanup
- traverse_clean_html_nodes(head)
-
- # Persist updates to output file
- tree.write(outfile)
-
- # Note: This invocation needs to occur post tree-write because
- # it will update file
- traverse_clean_html_source_examples(outfile)
-
-def find_match(reference, anchor_node, relationship):
-
- if not anchor_node is None and 'anchor' in anchor_node.tag:
- # Try this, verify matching ids
- key = anchor_node.attrib.keys()[0]
- value = anchor_node.attrib[key]
- regex = '^' + reference + '(\.\d+)?$'
-
- # print 'DEBUG: ' + relationship + ' anchor check. Reference: ' + reference + ' Regex: ' + regex + ' Value: ' + value
-
- if re.match(regex,value):
- return anchor_node
-
- else:
- # print 'DEBUG: Anchor in ' + relationship + ' tag does not match. Expected: ', reference, ' Found: ', value, ' Looking further...'
- node = anchor_node
- while not node.getprevious() is None:
- node = node.getprevious()
- if 'anchor' in node.tag:
- key = node.attrib.keys()[0]
- value = node.attrib[ key ]
- if re.match(regex,value):
- # print 'DEBUG: Anchor in ' + relationship + ' tag finally match!!!'
- return node
- # else
- # print 'DEBUG: Anchor in ' + relationship + ' tag does not match. Expected: ', reference, ' Found: ', value, ' Looking further...'
-
- else:
- # print 'DEBUG: Anchor in ' + relationship + ' tag does not match. Expected: ', reference, ' Found: ', value, ' Anchor node: ', node
- return None
-
- else:
- # print 'Error: find_match called with non-anchor element. Reference: ' + reference + ' Node: ' + anchor_node + ' Relationship: ' + relationship
- return None
-
-def traverse_clean_links(element):
-
- if 'link' in element.tag:
- # Note: Terminal tag, no need to recurse
-
- # Gather link details
- text = element.text
- num_attributes = element.attrib.__len__()
- reference = element.attrib.get('linkend',None)
-
- if num_attributes is 1 and not reference is None and text == u'¶':
- # Erroneous link message, find related anchor, could be "uncle" or "cousin" (of various degrees)
- anchor = None
- parent = element.getparent()
- grandparent = parent.getparent()
- greatuncle = grandparent.getprevious()
-
- # Check Great Uncle for match
- anchor = find_match(reference, greatuncle, 'Great Uncle')
-
- # If no match, locate "cousin" and if found, check it
- if anchor is None:
- cousin = None
- if not greatuncle is None:
- node = greatuncle
- while node.__len__() > 0 and cousin is None:
- node = node.__getitem__(node.__len__() -1)
- if 'anchor' in node.tag:
- cousin = node
-
- if not cousin is None:
- anchor = find_match(reference, cousin, 'Cousin')
-
- # If no match, try uncle
- if anchor is None:
- uncle = parent.getprevious()
- anchor = find_match(reference, uncle, 'Uncle')
-
- # Always delete <link> tag of this type (contains only u'¶' for text)
- parent.__delitem__(parent.index(element))
-
- if not anchor is None:
- # print 'MATCH FOUND: ', reference
-
- # Retrieve attribute key from anchor
- # Note: The <link> key is always correctly set by herold in the case of duplicate keys.
- # The <anchor> tag may have a "dot" and a number appended to value in <link>.
- key = anchor.attrib.keys()[0]
- value = anchor.get(key)
- if 'title' in parent.tag:
- # Add id attribute to Grandparent
- grandparent.set(key,value)
- else:
- # Add id attribute to Parent
- parent.set(key,value)
-
- sys.stderr.write( '**Information: removed dummy link and for ' + reference + ' and added proper xml:id as ' + value + '\n' )
-
- # Delete <anchor> tag
- anchor_parent = anchor.getparent()
- anchor_parent.__delitem__(anchor_parent.index(anchor))
- else:
- # Nothing more to do
- sys.stderr.write( '**Information: Matching <anchor> element not found for reference = ' + reference + '. Link removed.' + '\n' )
-
-
- else:
- for child in element.getchildren():
- traverse_clean_links(child)
-
-def traverse_clean_other(element):
- if 'informalexample' in element.tag:
- # Get key elements around this one
- parent = element.getparent()
- grandparent = parent.getparent()
-
- # Create new elements -- section and title (use text from informal example element)
- new_section = parent.makeelement(grandparent.tag)
- new_title = parent.makeelement('title')
- title = element.text
- new_title.text = title
-
- # Add title to new section
- new_section.append(new_title)
-
- # Copy over children from <informalexample> to new <section>
- for child in element.getchildren():
- element.remove(child)
- new_section.append(child)
-
- # print 'DEBUG: old tree...'
- # print_tree(parent, 0, 2)
-
- # Add new <section> as next sibling of parent and remove <informalexample> from parent
- parent.addnext(new_section)
- parent.remove(element)
-
- # print 'DEBUG: new tree...'
- # print_tree(parent.getparent(), 0, 3)
-
- sys.stderr.write( '**Information: <informalexample> ' + element.text + ' removed and promoted as <section> with title: ' + title + '\n' )
-
- elif 'note' in element.tag:
- # Get key elements around this one
- parent = element.getparent()
- grandparent = parent.getparent()
-
- # print 'DEBUG: old tree...'
- # print_tree(parent, 0, 4)
-
- # Create new elements -- section and title (use text from bridgehead subelement)
- new_section = parent.makeelement(parent.tag)
- bridgehead = element.__getitem__(0).__getitem__(0)
-
- if not 'bridgehead' in bridgehead.tag:
- print 'Error: Bad assumption about <note> structure. Bridgehead not found as expected.'
- sys.exit(-20)
-
- title = bridgehead.text
- new_title = parent.makeelement('title')
- new_title.text = title
-
- # Add title to new section
- new_section.append(new_title)
-
- # Remove <bridgehead> from <note>
- bridgehead.getparent().remove(bridgehead)
-
- # Copy over remaining items in <note> to new <section>
- for child in element.getchildren():
- element.remove(child)
- new_section.append(child)
-
- # Add new <section> as next sibling of parent and remove <note> from parent
- parent.addnext(new_section)
- parent.remove(element)
-
- # print 'DEBUG: New tree...'
- # print_tree(grandparent, 0, 3)
-
- sys.stderr.write( '**Information: <note> removed and promoted as <section> with title: ' + title + '\n' )
-
- elif 'anchor' in element.tag:
- # Get key elements around this one
- parent = element.getparent()
-
- # Retrieve anchor details
- key = element.attrib.keys()[0]
- value = element.attrib[ key ]
-
- # Remove node
- parent.remove( element );
-
- sys.stderr.write( '**Information: removed <anchor> with id: ' + value + '\n' )
-
- elif 'section' in element.tag:
- #Ensure at least one child beyond <title>
- if element.__len__() == 1:
- title = element.__getitem__(0).text
- parent = element.getparent()
-
- # Make and add empty paragraph to section, just behind title
- new_para = parent.makeelement('para')
- new_para.text = ' '
- element.append(new_para)
-
- sys.stderr.write( '**Information: <para> tag added to empty section with title: ' + title + '\n' )
-
- for child in element.getchildren():
- traverse_clean_other(child)
-
-def cleanup_xml(infile, outfile):
- # Create internal representation of document from infile
- parser = etree.XMLParser(remove_comments=False)
- tree = etree.parse(infile, parser=parser)
- head = tree.getroot()
-
- # print_tree( head, 0, 2 )
-
- # Note: because link cleanup involves relative location of multiple tags, it must be separate and first
- traverse_clean_links(head)
- traverse_clean_other(head)
-
- # Persist updates to output file
- tree.write(outfile)
-
-def print_tree(element, level, max_depth):
- # Print current element
- num_children = element.__len__()
- indent = ' '.ljust(level+1)
-
- if level < max_depth:
- print indent, 'Tag: ', element.tag, ' Attrib: ', element.attrib, ' Text: >', element.text, '< Num children: ', num_children
-
- for i in range(num_children):
- child = element.__getitem__(i)
- print_tree(child, level+1, max_depth)
-
-def traverse_clean_sections(element):
- section_blacklist = ['Navigation', 'Table Of Contents']
-
- # Walk children looking for next set of <section> tags, opening include files if necessary
- num_children = element.__len__()
- i = 0;
- while i < num_children:
- child = element.__getitem__(i)
- parent = element
-
- # print 'DEBUG: clean sections, visiting node with tag: ' + child.tag
-
- # Walk first level of tags, deleting info and any "blacklist" sections
- if 'section' in child.tag:
- num_sec_children = child.__len__()
-
- title = ''
- if num_sec_children > 0:
- first_grandchild = child.__getitem__(0)
- if first_grandchild.__len__() == 0:
- title = child.__getitem__(0).text
- else:
- # This makes me nervous, not sure how well it will work...
- title = first_grandchild.__getitem__(0).text
- # print 'Section title found: ' + title
-
- if title in section_blacklist:
- # Delete section
- # print 'DEBUG: Deleted blacklist section ' + title
- parent.remove(child)
- num_children = num_children-1
- else:
- traverse_clean_sections(child)
- i = i+1
- else:
- i=i+1
-
-def eliminate_top_section(head):
-
- # Remove <info> and <index> sections
- for child in head.getchildren():
- if 'info' in child.tag or 'index' in child.tag:
- # print 'DEBUG: unneeded top level tag: ' + child.tag
- head.remove(child)
-
- # Eliminate head section which really is title
- if head.__len__() == 1:
- first_section = head.__getitem__(0)
-
- if not 'section' in first_section.tag:
- print 'Error: Bad assumption. Top tag in document is not a section.'
- sys.exit(-36)
-
- # print 'DEBUG: first section -- tag: ' + first_section.tag + ' num children: ' + str(first_section.__len__())
-
- for child in first_section.getchildren():
- # print 'DEBUG: child -- tag: ' + child.tag + ' num children: ' + str(child.__len__())
-
- # Promote sections
- if 'section' in child.tag:
- first_section.remove(child);
- head.append(child);
- # print 'DEBUG: Promoting child -- tag: ' + child.tag
-
- head.remove(first_section)
-
- else:
- print 'Error: Bad assumption. Too many sections (' + str(head.__len__()) + ') found in base document.'
- sys.exit(-13)
-
-
-def transform_head_sections(head):
-
- num_chapter = 0
-
- for child in head.getchildren():
- if 'section' in child.tag:
- child.tag = child.tag.replace('section','chapter')
- num_chapter = num_chapter+1
-
- if num_chapter == 0:
- print 'Error: No chapters found in document'
- sys.exit(-6)
-
-
-def convert_structure(infile, outfile):
-
- # Create internal representation of document from infile
- parser = etree.XMLParser(remove_comments=False)
- tree = etree.parse(infile, parser=parser)
- head = tree.getroot()
-
- # print 'DEBUG: Pre tree structure cleanup...'
- # print_tree(head, 0, 3)
-
- if 'article' in head.tag:
- head.tag = 'book'
-
- # Clear attributes
- for attrib in head.attrib.keys():
- head.attrib.pop(attrib, None)
- if head.attrib.items() != []:
- print 'Error: Section attributes not removed. ', head.attrib.items(), ' items remain -- ', head.attrib.keys()
- sys.exit(-5)
- else:
- print 'Toc file contains ', head.tag, 'tag, not <article>'
- sys.exit(-4)
-
- # Traverse tree sections, removing nodes as needed
- traverse_clean_sections(head)
-
- # Eliminate first section, placeholder for document title
- eliminate_top_section(head)
-
- # Traverse remaining top level <section> and convert to <chapter>
- transform_head_sections(head)
-
- # print 'DEBUG: Post tree structure cleanup...'
- # print_tree(head, 0, 2)
-
- # Persist updates to output file
- tree.write(outfile)
-
-
-def remove_book_tags(old_file, new_file):
- with open(old_file, 'r') as input:
- with open(new_file, 'wb') as output:
- for line in input:
- if '<book' not in line and '</book>' not in line:
- output.write(line)
-
-def insert_toc_into_book(toc_file, book_file):
- book_file_bak = book_file+'.bak'
- shutil.copy2(book_file, book_file_bak)
- key_string = '<!--TBD-->'
- inserted_toc = False
-
- with open(book_file_bak, 'r') as input:
- with open(book_file, 'wb') as output:
- for line in input:
- if key_string not in line:
- output.write(line)
- else:
- inserted_toc = True
- # Write toc_file contents
- with open(toc_file, 'r') as input_toc:
- for line_toc in input_toc:
- output.write(line_toc)
-
- if not inserted_toc:
- print 'Error: key string of "', key_string, '" not found in ', book_file
- sys.exit(-7)
-
-def build_revhistory(book_file):
- # Variables for formating git log
- log_format = '%h%x01%an%x01%ad%x01%s%x02'
- log_fields = ['id', 'author', 'date', 'subject']
-
- # Retrieve log
- pipe = Popen('git log --date=iso --format="%s" -- . .' % log_format, shell=True, stdout=PIPE)
- log, _ = pipe.communicate()
-
- # Substitute for problem characters: &, <, >
- log = log.replace('&','&').replace('<','<').replace('>','>')
-
- # Remove newlines, trailing end-of-record (0x02), and then split at end-of-record
- log = log.replace('\n','').strip('\x02').split('\x02')
-
- # Split records into individual fields
- log = [row.split('\01') for row in log]
-
- # Create dictionary using field names
- log = [dict(zip(log_fields, row)) for row in log]
-
- # Format log into revision history
- revision = '<revhistory>\n'
- for entry in log:
- revision = revision + '<revision><date>' + entry['date'].split(' ')[0] + '</date><revdescription><para>' +\
- entry['subject'] + ' (' + entry['id'] + ')</para></revdescription></revision>\n'
- revision = revision + '</revhistory>\n'
-
- # Update file
- rev_str = '<revhistory>TBD</revhistory>'
- update_file(book_file, rev_str, revision)
-
-
-def main(argv):
- master_git_url = 'https://github.com/OpenPOWERFoundation/Docs-Master.git'
- template_git_url = 'https://github.com/OpenPOWERFoundation/Docs-Template.git'
- html_dir = ''
- build_dir = ''
- db_dir = ''
- master_dir = ''
- template_dir = ''
- toc_file = master_doc+'.xml'
-
- try:
- opts, args = getopt.getopt(argv,"hs:b:d:m:t:",["htmldir","builddir=","docbookdir=","masterdir=","templatedir="])
- except getopt.GetoptError:
- print 'Invalid option specified. Usage:'
- print ' opf_html2db.py -s <htmldir> -b <builddir> -d <docbookdir> -m <masterdir> -t <templatedir>'
- sys.exit(-1)
- for opt, arg in opts:
- if opt == '-h':
- print 'opf_hmtl2db.py -s <htmldir> -b <builddir> -d <docbookdir> -m <masterdir> -t <templatedir>'
- sys.exit(0)
- elif opt in ("-s", "--htmldir"):
- html_dir = arg
- elif opt in ("-b", "--builddir"):
- build_dir = arg
- elif opt in ("-d", "--docbookdir"):
- db_dir = arg
- elif opt in ("-m", "--masterdir"):
- master_dir = arg
- elif opt in ("-t", "--templatedir"):
- template_dir = arg
-
- # Verify html directory, error if not found
- if not os.path.exists(html_dir):
- print 'ERROR: ' + html_dir + ' does not exist. Please specify path to directory containing single html file.'
- sys.exit(-11)
-
- # Generate path to single file
- # NOTE: assumption is that file name is always "index.html" (master_doc). If this doesn't prove true, may need to use variable.
- html_file_src = os.path.join(html_dir, master_doc + '.html')
-
- if not os.path.isfile(html_file_src):
- print 'ERROR: ' + html_file_src + ' does not exist. Please verify path to single html file and file name.'
- sys.exit(-12)
-
- # Convert html file to xml and place in db directory
- if not os.path.exists(db_dir):
- print 'Making docbook build directory ' + db_dir
- os.path.makedirs(db_dir)
-
- db_file = os.path.join(db_dir, project + '.xml')
- if os.path.exists(db_file):
- os.remove(db_file)
-
- # Clean up herold html output
- print 'Cleaning up html file before processing'
- html_file = os.path.join(db_dir, master_doc + '.html')
- html_file_tmp1 = html_file + '.tmp1'
- shutil.copy2(html_file_src, html_file)
- cleanup_html(html_file, html_file_tmp1)
-
- print 'Converting html file to XML...'
- print subprocess.check_output(['herold', '-i', html_file_tmp1, '-o', db_file])
-
- # Clone a new Master Directory
- print 'Cloning new Docs-Master directory...'
- if os.path.exists(master_dir):
- shutil.rmtree(master_dir)
- Repo.clone_from(master_git_url, master_dir)
-
- # Clone a new Template Directory
- print 'Cloning new Docs-Template directory...'
- if os.path.exists(template_dir):
- shutil.rmtree(template_dir)
- Repo.clone_from(template_git_url, template_dir)
-
- # Create the new XML file *****
- rst_template_dir = os.path.join(template_dir, 'rst_template')
- full_toc_file = os.path.join(rst_template_dir, toc_file)
- shutil.copy2(db_file, full_toc_file)
- book_file = os.path.join(rst_template_dir, 'bk_main.xml')
-
- # Update all file in opf_docbook_settings with tag/value combinations specified
- print 'Updating Docbook files with settings from conf.py...'
- for f in opf_docbook_settings.keys():
- filename = os.path.join(rst_template_dir, f)
- tags = opf_docbook_settings[f]
-
- for tag in tags:
- value = opf_docbook_settings[f][tag]
-
- if value != '':
- new_str = '<'+tag+'>'+value+'</'+tag+'>'
- else:
- new_str = ''
-
- old_str = '<'+tag+'>TBD</'+tag+'>'
- update_file(filename, old_str, new_str)
-
- # Parse TOC file, convert high level tag to "book" and write back out to .tmp1 file
- print 'Cleaning up Docbook file structure...'
- full_toc_file_tmp1 = full_toc_file+'.tmp1'
- full_toc_file_tmp2 = full_toc_file+'.tmp2'
- full_toc_file_tmp3 = full_toc_file+'.tmp3'
-
- # Walk document correcting XML errors
- cleanup_xml( full_toc_file, full_toc_file_tmp1 )
-
- # Remove extraneous sections
- convert_structure( full_toc_file_tmp1, full_toc_file_tmp2 )
-
- # Eliminate <book> and <title> tags in .tmp1 and write to .tmp2 file
- remove_book_tags(full_toc_file_tmp2, full_toc_file_tmp3)
-
- # Update link to first file
- insert_toc_into_book(full_toc_file_tmp3, book_file)
-
- # Create revision history from Git Log
- print 'Building document revision history from git log...'
- build_revhistory(book_file)
-
- # TODO: Remove this hack after rst_template bk_main gets updated
- update_file(book_file, 'xmlns:xlink', 'xmlns:xl')
-
- # Perform build of Docbook
- print 'Building Docbook PDF and HTML output in Maven...'
- maven_log_file = 'build.log'
- maven_build = 'cd ' + rst_template_dir + '; mvn generate-sources 2>&1 | tee ' + maven_log_file + ''
- pipe = Popen(maven_build, shell=True)
- log, err = pipe.communicate()
-
- if pipe.returncode != 0:
- print "Build failed with return code:%s" % pipe.returncode
- print "See %s/build.log for more details" & rst_template_dir
-
- # Copy output to better location
- print 'Copying build output...'
- bld_out_dir = os.path.join(rst_template_dir, 'target/docbkx/webhelp')
- html_head = os.path.join(bld_out_dir, opf_docbook_settings['pom.xml']['webhelpDirname'] + '/index.html')
- if os.path.exists(bld_out_dir) and os.path.exists(html_head):
- doc_dir = os.path.join(build_dir, 'docbook/opf_docbook')
-
- if os.path.exists(doc_dir):
- shutil.rmtree(doc_dir)
- shutil.copytree(bld_out_dir, doc_dir)
- print "Build successful. Output files located in %s" % os.path.join(doc_dir, opf_docbook_settings['pom.xml']['webhelpDirname'])
-
- sys.exit(0)
-
- else:
- print "Docbook build failed. Check logfile %s for details." % os.path.join(rst_template_dir, maven_log_file)
- sys.exit(-10)
-
-if __name__ == "__main__":
- main(sys.argv[1:])
diff --git a/rst_template/pom.xml b/rst_template/pom.xml
deleted file mode 100644
index d54f271..0000000
--- a/rst_template/pom.xml
+++ /dev/null
@@ -1,162 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- 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.
-
--->
-<project xmlns="http://maven.apache.org/POM/4.0.0"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
-
- <!-- All TBD values are assumed by the XXX.py package to be contained in the conf.py
- opf_docbook_documents[] hash by tag name -->
-
- <parent>
-
- <groupId>org.openpowerfoundation.docs</groupId>
- <artifactId>workgroup-pom</artifactId>
- <version>1.0.0-SNAPSHOT</version>
- <relativePath>../pom.xml</relativePath>
- </parent>
- <modelVersion>4.0.0</modelVersion>
-
- <artifactId>TBD</artifactId>
-
- <packaging>jar</packaging>
-
- <name>TBD</name>
-
- <properties>
- <!-- This is set by Jenkins according to the branch. -->
- <release.path.name></release.path.name>
- <comments.enabled>0</comments.enabled>
- </properties>
- <!-- ################################################ -->
- <!-- USE "mvn clean generate-sources" to run this POM -->
- <!-- ################################################ -->
- <build>
- <plugins>
- <plugin>
-
- <groupId>org.openpowerfoundation.docs</groupId>
-
- <artifactId>openpowerdocs-maven-plugin</artifactId>
- <!-- version set in ../pom.xml -->
- <executions>
- <execution>
- <id>generate-webhelp</id>
- <goals>
- <goal>generate-webhelp</goal>
- </goals>
- <phase>generate-sources</phase>
- <configuration>
- <!-- These parameters only apply to webhelp -->
- <enableDisqus>${comments.enabled}</enableDisqus>
- <disqusShortname>TBD</disqusShortname>
- <enableGoogleAnalytics>1</enableGoogleAnalytics>
- <googleAnalyticsId>UA-17511903-1</googleAnalyticsId>
- <generateToc>
- appendix toc,title
- article/appendix nop
- article toc,title
- book toc,title,figure,table,example,equation
- book/appendix nop
- book/chapter nop
- chapter toc,title
- chapter/section nop
- section toc
- part toc,title
- reference toc,title
- set toc,title
- </generateToc>
- <!-- The following elements sets the autonumbering of sections in output for chapter numbers but no numbered sections-->
- <sectionAutolabel>1</sectionAutolabel>
- <tocSectionDepth>3</tocSectionDepth>
- <sectionLabelIncludesComponentLabel>1</sectionLabelIncludesComponentLabel>
-
- <webhelpDirname>TBD</webhelpDirname>
- <pdfFilenameBase>TBD</pdfFilenameBase>
-
- <!-- TODO: Define the appropriate work product type. These values are defined by the IPR Policy.
- Consult with the Work Group Chair or a Technical Steering Committee member if you have
- questions about which value to select.
-
- If no value is provided below, the document will default to "Work Group Notes".-->
- <!--workProduct>workgroupNotes</workProduct-->
- <!-- workProduct>workgroupSpecification</workProduct -->
- <!-- workProduct>candidateStandard</workProduct -->
- <!-- workProduct>openpowerStandard</workProduct -->
- <workProduct>TBD</workProduct>
-
- <!-- TODO: Set the appropriate security policy for the document. For documents
- which are not "public" this will affect the document title page and
- create a vertical running ribbon on the internal margin of the
- security status in all CAPS. Values and definitions are formally
- defined by the IPR policy. A layman's definition follows:
-
- public = this document may be shared outside the
- foundation and thus this setting must be
- used only when completely sure it allowed
- foundationConfidential = this document may be shared freely with
- OpenPOWER Foundation members but may not be
- shared publicly
- workgroupConfidential = this document may only be shared within the
- work group and should not be shared with
- other Foundation members or the public
-
- The appropriate starting security for a new document is "workgroupConfidential". -->
- <!-- security>workgroupConfidential</security -->
- <!-- security>foundationConfidential</security -->
- <!-- security>public</security-->
- <security>TBD</security>
-
- <!-- TODO: Set the appropriate work flow status for the document. For documents
- which are not "published" this will affect the document title page
- and create a vertical running ribbon on the internal margin of the
- security status in all CAPS. Values and definitions are formally
- defined by the IPR policy. A layman's definition follows:
-
- published = this document has completed all reviews and has
- been published
- draft = this document is actively being updated and has
- not yet been reviewed
- review = this document is presently being reviewed
-
- The appropriate starting security for a new document is "draft". -->
- <!-- documentStatus>draft</documentStatus -->
- <!-- documentStatus>review</documentStatus -->
- <!-- documentStatus>published</documentStatus -->
- <documentStatus>TBD</documentStatus>
-
- </configuration>
- </execution>
- </executions>
- <configuration>
- <!-- These parameters apply to pdf and webhelp -->
- <xincludeSupported>true</xincludeSupported>
- <sourceDirectory>.</sourceDirectory>
- <includes>
- bk_main.xml
- </includes>
-
- <!-- **TODO: Set to the correct project URL. This likely needs input from the TSC. -->
- <!-- canonicalUrlBase>http://openpowerfoundation.org/docs/template-guide/content</canonicalUrlBase -->
- <glossaryCollection>${basedir}/../glossary/glossary-terms.xml</glossaryCollection>
- <includeCoverLogo>1</includeCoverLogo>
- <coverUrl>www.openpowerfoundation.org</coverUrl>
- </configuration>
- </plugin>
- </plugins>
- </build>
-</project>