Difference between revisions of "User:Jholsenback/WikiDocGen"

From POV-Wiki
Jump to navigation Jump to search
m (initial page creation)
 
m (added new section)
 
(9 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
===The Directories===
+
===The Setup===
−
In the directory <code>/a/home/jholsenback/testbed</code> this is the expected structure:
+
In the directory<code>&nbsp;&nbsp;/a/home/jholsenback/testbed&nbsp;&nbsp;</code>this is the expected directory structure:
 
: <code>documentation</code>
 
: <code>documentation</code>
 
::<code>mac</code>
 
::<code>mac</code>
Line 8: Line 8:
 
::<code>win</code>
 
::<code>win</code>
 
:::<code>images</code>
 
:::<code>images</code>
 +
You should be in the above mentioned directory to run the scripts, however, the batch-files wander a bit but always end up back home.
  
 
===The Files===
 
===The Files===
−
These are the files that make up the povdocgen process:
+
These are the files that make up the wikidocgen process:
 
<ol>
 
<ol>
 
   <li><code>batchMacFiles</code></li>
 
   <li><code>batchMacFiles</code></li>
Line 32: Line 33:
 
       <li>builds the various table of contents files and an <em>index.html</em> file for a given doc set</li>
 
       <li>builds the various table of contents files and an <em>index.html</em> file for a given doc set</li>
 
     </ul>
 
     </ul>
−
  <li><code>mkImagePackage.php</code></li>
+
  <li><code>mkWikiTOC.php</code></li>
−
      <ul>
+
    <ul>
−
        <li>builds the <em>images</em> directory structure and copies files from the POV-Wiki</li>
+
      <li>rebuilds [[Documentation:Contents|this]] listing if any of these <em>contents</em> pages below gets changed.<br>See additional notes at bottom for more about this!</li>
−
      </ul>
+
    </ul>
−
  <li><code>common.php</code></li>
+
  <li><code>mkImagePackage.php</code></li>
−
      <ul>
+
    <ul>
−
        <li>some common functions associated in the povdocgen process</li>
+
      <li>builds the <em>images</em> directory structure and copies files from the POV-Wiki</li>
−
      </ul>
+
    </ul>
−
  <li><code>utilities.php</code></li>
+
  <li><code>getStyleSheet.php</code></li>
−
      <ul>
+
    <ul>
−
        <li>some common utilities associated in the povdocgen process</li>
+
      <li>gets the <em>povray37.css</em> style sheet and copies it to a given doc set directory</li>
−
      </ul>
+
    </ul>
−
    <li><code>documentation/WikiImages</code>
+
  <li><code>common.php</code></li>
−
      <ul>
+
    <ul>
−
        <li>a symbolic link to the POV-Wiki images directory</li>
+
      <li>frequently used functions associated with the wikidocgen process</li>
−
      </ul>
+
    </ul>
−
    <li><code>documentation/favicon.ico</code>
+
  <li><code>utilities.php</code></li>
−
      <ul>
+
    <ul>
−
        <li>copied to a given doc set directory</li>
+
      <li>frequently used functions associated with the wikidocgen process, an attempt to organize</li>
−
      </ul>
+
    </ul>
−
    <li><code>documentation/povray37.css</code>
+
  <li><code>documentation/WikiImages</code></li>
−
      <ul>
+
    <ul>
−
        <li>copied to a given doc set directory</li>
+
      <li>a symbolic link to the POV-Wiki images directory</li>
−
      </ul>
+
    </ul>
 +
  <li><code>documentation/favicon.ico</code></li>
 +
    <ul>
 +
      <li>copied to a given doc set directory</li>
 +
    </ul>
 
</ol>
 
</ol>
 
Besides the <em>content</em> files on the POV-Wiki these files are also part of the process:
 
Besides the <em>content</em> files on the POV-Wiki these files are also part of the process:
Line 61: Line 66:
 
   <li>[[Documentation:Page Header|Page Header]]</li>
 
   <li>[[Documentation:Page Header|Page Header]]</li>
 
   <li>[[Documentation:Content Header Footer|Content Header Footer]]</li>
 
   <li>[[Documentation:Content Header Footer|Content Header Footer]]</li>
 +
  <li>[[Documentation:Povray37css|Style Sheet]]</li>
 
   <li>[[Documentation:Index Page|Index Page]]</li>
 
   <li>[[Documentation:Index Page|Index Page]]</li>
 
</ol>
 
</ol>
 +
 +
===Running The Process===
 +
<p>ssh access to lib.povray.org is required, so is this [[User:Jholsenback/WikiDocGen#The Setup|directory structure]]. All the shell and PHP scripts that make up the process are available revision control under povray&nbsp;&gt;&nbsp;tools&nbsp;&gt;&nbsp;wiki-docgen. Once you're logged and all setup has been done, do the following:</p>
 +
<p class="Note"><strong>Note:</strong> This example deals with generating the Unix/Linux doc set, but the other platforms (MacOs and Windows) are the similar, they are just processed into different directories.</p>
 +
<ol>
 +
  <li><code>cd testbed</code></li>
 +
  <li><code>./batchUnxFiles</code></li>
 +
  <li><code>cd documentation/unx/</code></li>
 +
  <li><code>find . -type f -exec chmod 444 '{}' \;</code></li>
 +
  <li><code>tar -cvvf 24Oct2011unx.tar Arrow*.* favicon.ico images/* povray37.css *.html</code></li>
 +
  <li><code>gzip 24Oct2011unx.tar</code></li>
 +
  <li><code>find . -type f -exec chmod 644 '{}' \;</code></li>
 +
  <li><code>chmod 444 *.tar.gz</code></li>
 +
  <li><code>cd ..</code></li>
 +
  <li><code>vi docsets.html</code></li>
 +
</ol>
 +
<p>Typically it's okay to run each platforms batch scripts one right after another, then the individual platform directories get bundled into a tar file. Lastly they get compressed using gzip.</p>
 +
<p class="Note"><strong>Note:</strong> If you've previously run the process make sure that the file permissions are correctly set before running the process again. See step 7 above.</p>
  
 
===Notes===
 
===Notes===
−
Some process notes will go here ....
+
The <em>most</em> important part of this process is that it is driven off these files:
 +
<ul>
 +
  <li>[[Documentation:Windows Table of Contents|Windows Table of Contents]]</li>
 +
  <li>[[Documentation:Mac OS Table of Contents|Mac OS Table of Contents]]</li>
 +
  <li>[[Documentation:Unix Table of Contents|Unix Table of Contents]]</li>
 +
  <li>[[Documentation:Tutorial Table of Contents|Tutorial Table of Contents]]</li>
 +
  <li>[[Documentation:Reference Table of Contents|Reference Table of Contents]]</li>
 +
</li>
 +
</ul>
 +
The <code>GatherTOCfiles</code> and <code>BuildDocMap</code> functions reads and processes those files. They are located in <code>utilities</code> and <code>common</code> respectively, they depend on the <code>class DocumentMap</code> definition located in <code>common</code>. During batch processing if an <em>exception</em> message is seen, most likely something isn't correct with an associated table of contents entry and how it appears in the content body. The title portion of the toc entry and the heading entry in the content body <em>MUST</em> be and exact match. Batch processing will continue and the offender will appear in the content body as wiki markup.
 +
<p class="Hint"><strong>Hint:</strong> look for the wiki tag&nbsp;&nbsp;Documentation:</p>
 +
The content on the Wiki is organized such that a given section can span more than one file, the script <code>getWikiPages.php</code> effectively concatenates the files together, so look near the bottom of that script to find a place to tap into the <em>stream</em> as it were!
 +
 
 +
The file that <code>mkWikiTOC.php</code> produces needs to be copied into the [[Documentation:Contents|table of contents]] file. Since this file spans several sections, you need to edit the <em>entire</em> page (top most edit button). Look for these comments embedding in the file delimiting where the changes should go.
 +
<pre>
 +
<!--BEGIN CHANGES BETWEEN HERE--->
 +
<!--END CHANGES BETWEEN HERE--->
 +
</pre>

Latest revision as of 21:08, 24 October 2011

The Setup

In the directory  /a/home/jholsenback/testbed  this is the expected directory structure:

documentation
mac
images
unx
images
win
images

You should be in the above mentioned directory to run the scripts, however, the batch-files wander a bit but always end up back home.

The Files

These are the files that make up the wikidocgen process:

  1. batchMacFiles
    • a bash script that processes the Mac OS documentation set
  2. batchWinFiles
    • a bash script that processes the Windows documentation set
  3. batchUnxFiles
    • a bash script that processes the Unix documentation set
  4. getWikiPages.php
    • gets the files from the POV-Wiki and processes them
  5. mkContentsPages.php
    • builds the various table of contents files and an index.html file for a given doc set
  6. mkWikiTOC.php
    • rebuilds this listing if any of these contents pages below gets changed.
      See additional notes at bottom for more about this!
  7. mkImagePackage.php
    • builds the images directory structure and copies files from the POV-Wiki
  8. getStyleSheet.php
    • gets the povray37.css style sheet and copies it to a given doc set directory
  9. common.php
    • frequently used functions associated with the wikidocgen process
  10. utilities.php
    • frequently used functions associated with the wikidocgen process, an attempt to organize
  11. documentation/WikiImages
    • a symbolic link to the POV-Wiki images directory
  12. documentation/favicon.ico
    • copied to a given doc set directory

Besides the content files on the POV-Wiki these files are also part of the process:

  1. Page Header
  2. Content Header Footer
  3. Style Sheet
  4. Index Page

Running The Process

ssh access to lib.povray.org is required, so is this directory structure. All the shell and PHP scripts that make up the process are available revision control under povray > tools > wiki-docgen. Once you're logged and all setup has been done, do the following:

Note: This example deals with generating the Unix/Linux doc set, but the other platforms (MacOs and Windows) are the similar, they are just processed into different directories.

  1. cd testbed
  2. ./batchUnxFiles
  3. cd documentation/unx/
  4. find . -type f -exec chmod 444 '{}' \;
  5. tar -cvvf 24Oct2011unx.tar Arrow*.* favicon.ico images/* povray37.css *.html
  6. gzip 24Oct2011unx.tar
  7. find . -type f -exec chmod 644 '{}' \;
  8. chmod 444 *.tar.gz
  9. cd ..
  10. vi docsets.html

Typically it's okay to run each platforms batch scripts one right after another, then the individual platform directories get bundled into a tar file. Lastly they get compressed using gzip.

Note: If you've previously run the process make sure that the file permissions are correctly set before running the process again. See step 7 above.

Notes

The most important part of this process is that it is driven off these files:

The GatherTOCfiles and BuildDocMap functions reads and processes those files. They are located in utilities and common respectively, they depend on the class DocumentMap definition located in common. During batch processing if an exception message is seen, most likely something isn't correct with an associated table of contents entry and how it appears in the content body. The title portion of the toc entry and the heading entry in the content body MUST be and exact match. Batch processing will continue and the offender will appear in the content body as wiki markup.

Hint: look for the wiki tag  Documentation:

The content on the Wiki is organized such that a given section can span more than one file, the script getWikiPages.php effectively concatenates the files together, so look near the bottom of that script to find a place to tap into the stream as it were!

The file that mkWikiTOC.php produces needs to be copied into the table of contents file. Since this file spans several sections, you need to edit the entire page (top most edit button). Look for these comments embedding in the file delimiting where the changes should go. 

<!--BEGIN CHANGES BETWEEN HERE--->
<!--END CHANGES BETWEEN HERE--->
Retrieved from "https://wiki.povray.org/content?title=User:Jholsenback/WikiDocGen&oldid=4718"