User:Jr/WikiDocGen2 - Revision history

Jr: wording, and "grammar"

2026-06-05T14:05:50Z

wording, and "grammar" </sigh>

Jr: minor re-wording, better (I hope :-)) punctuation.

2026-05-31T20:02:29Z

minor re-wording, better (I hope :-)) punctuation.

Jr: added last "new" content.

2026-05-31T10:14:50Z

added last "new" content.

Jr: more adding ...

2026-05-30T14:56:42Z

more adding ...

Jr: added content.

2026-05-28T19:21:47Z

added content.

Jr: adding content..

2026-05-27T13:19:42Z

adding content..

Jr: wip, adding & revising content.

2026-05-25T17:59:49Z

wip, adding & revising content.

Jr: created with partial content and screenshot.

2026-05-25T11:59:19Z

created with partial content and screenshot.

New page

this page details the new generating POV-Ray documentation procedure,
revised since the server's crash in the early 20s.

the page is based on J Holsenback's [[User:Jholsenback/WikiDocGen|private notes]] page,
which although now mostly obsolete, I have copied "freely" from.

as JH points out, all work happens on the wiki server, so I assume
you will be logged (have 'ssh'd) into the account which has been set up
by Chris for the purpose.

== layout, manifest, setup ==

[[File:docgen2tree.png]]

the screenshot shows the "work area", a dedicated directory, containing
the following when clean:

<code>archives/</code>
contains the files generated by a given './makeDocs all' run.
it will be empty, usually.

<code>common.php</code>
frequently used functions associated with the wikidocgen process.

<code>getStyleSheet.php</code>
gets the 'povray37.css' style sheet and copies it to a given doc set
directory.

<code>getWikiPages.php</code>
gets the files from the POV-Wiki and processes them.

<code>makeDocs</code>
a BASH script, the "driver". generates either a single document set for
preview/checking, or all (three) of them.

<code>makedocs.pl</code>
a Perl script which post-processes the Windows documentation in preparation
of generating the compiled help file, 'povray.chm'.

<code>mkContentsPages.php</code>
builds the various table of contents files and an 'index.html' file for
a given doc set.

<code>mkImagePackage.php</code>
builds the'images' directory structure and copies files from the POV-Wiki.

<code>mkWikiTOC.php</code>
rebuilds the '[[Documentation:Contents]]' listing if any of the 'contents'
pages gets changed.

<code>resources/</code>
this directory is "static" essentially, that is, its contents will not
change.

<code>resources/Arrow{Down,Up}.png</code>
these navigation icons/images are copied into the 'documentation' tree.

<code>resources/favicon.ico</code>
as is our icon/image.

<code>resources/povray.{hhp,js,stp}</code>
these files get copied to the 'output' directory, they're used by the
Windows HTML Help Compiler.

<code>scrubGeneratedFiles</code>
this simple BASH script removes the generated, temporary directories and
their contents.

<code>utilities.php</code>
frequently used functions associated with the wikidocgen process,
an attempt to organize.

the "setup" below, discussed by JH, still exists, but no longer permanently;
the whole of the 'documentation' directory tree now is created and populated
at run-time.

: <code>documentation</code>
::<code>mac</code>
:::<code>images</code>
::<code>unx</code>
:::<code>images</code>
::<code>win</code>
:::<code>images</code>

== the procedure ==

intro, step-by-step, "afterwards".
use 'script'.

@@ Line 6: / Line 6: @@
 as JH points out, all work happens on the wiki server, so I assume
-you will be logged (have 'ssh'd) into the account which has been set up
+you will be logged (have 'ssh'd) into the account set up by Chris for the purpose.
 == layout, manifest, setup ==
@@ Line 21: / Line 20: @@
 <code>common.php</code>
-frequently used functions associated with the wikidocgen process.
+frequently used functions associated with the documentation generating processes.
 <code>getStyleSheet.php</code>
@@ Line 57: / Line 56: @@
 <code>scrubGeneratedFiles</code>
-this simple BASH script removes the generated, temporary directories and their contents.
+a BASH script, it removes the generated, temporary directories and their contents.
 <code>utilities.php</code>
@@ Line 81: / Line 80: @@
 note, the work area '''must''' be clean, that is, not contain files generated in a previous run; a dedicated command is provided for the purpose.
-typically you will need to re-generate the docs after some detail or other in the online POV-Ray documentation was edited or updated.
+typically you will need to re-generate the docs after some detail or other in the online POV-Ray documentation was edited/updated.
 at this point, only make one platform-specific set of the docs, the one you are most familiar with; ie 'mac' or 'unx' or 'win'.
 double-check, visually, your edit(s) in the generated set, in a browser of choice.
@@ Line 107: / Line 106: @@
 updating the table of contents, while not "onerous", requires a quiet moment and due care.
 also bear in mind that you will, to quote JH, "need to edit the ''entire page'' (top most edit button)".
-the contents of the <code>newWikiTOC</code> file (prefixed by date, stored in 'archives', 1100+ lines) need to be transferred/copied ''as is'' to the wiki's '[[Documentation:Contents]]' page, replacing the existing lines between the two identifier comment lines shown below.
+the content of the <code>newWikiTOC</code> file (prefixed by date, stored in 'archives', 1100+ lines) needs to be transferred/copied ''as is'' to the wiki's '[[Documentation:Contents]]' page, replacing the existing lines between the two identifier comment lines shown below.
 <pre>

@@ Line 79: / Line 79: @@
 whereas the previous method required several manual steps to update the POV-Ray documentation, there are basically just two now: generate the archives and update the wiki's docs table of contents.
-note, the work area '''must''' be clean, that is, not contain files generated in a previous run.
+note, the work area '''must''' be clean, that is, not contain files generated in a previous run; a dedicated command is provided for the purpose.
 typically you will need to re-generate the docs after some detail or other in the online POV-Ray documentation was edited or updated.
@@ Line 95: / Line 94: @@
 </pre>
-after generating the 'unix' version assess the results under 'documentation/unx/', and in the "log" file created;
+after generating the Unix version assess the results under 'documentation/unx/' and in the "log" file created;
-if making the 'win' version look in the 'output' directory, as this contains the post-processed HTML.
+if making the 'win' version, look in the 'output' directory instead, as it contains the post-processed HTML.
 when all "looks good", do a:
@@ Line 104: / Line 103: @@
 to create the three documentation sets, plus the corresponding archives and the updated TOC.
-using the script utility as suggested above ensures the same name prefix is given to the recording as is used for the archives.
+using the script utility as suggested above ensures the same prefix is given to the recording as to the archives.
 updating the table of contents, while not "onerous", requires a quiet moment and due care.
 also bear in mind that you will, to quote JH, "need to edit the ''entire page'' (top most edit button)".
-the contents of the <code>newWikiTOC</code> file (prefixed by the date, stored in 'archives', 1100+ lines) need to be transferred/copied '''as is''' to the wiki's '[[Documentation:Contents]]' page, replacing the existing lines between the two identifier comment lines shown below.
+the contents of the <code>newWikiTOC</code> file (prefixed by date, stored in 'archives', 1100+ lines) need to be transferred/copied ''as is'' to the wiki's '[[Documentation:Contents]]' page, replacing the existing lines between the two identifier comment lines shown below.
 <pre>
@@ Line 115: / Line 114: @@
 </pre>
-after that, all that remains is to contact/notify Chris regarding the update and new archives; currently there "is talk" of possible git pull requests being placed instead.
+after that, all that remains is to contact/notify Chris regarding the update and new archives; currently there "is talk" of (perhaps) git pull requests being placed instead.
 == the future ==
-the PHP could do with another "attempt to organize"..  any such work should be carried out in a copy of the 'docgen2' directory, suitably renamed.
+the PHP could do with another "attempt to organize"...  any such work should be carried out in a copy of the 'docgen2' directory, suitably renamed.
-either remove the <code>.git*</code> directory and files, or start a new branch ?  the only change required is updating the 'workdir' variable in 'makeDocs' line 30, to its new value.
+either remove the <code>.git*</code> directory and files, or start a new branch ?  the only change required is updating the 'workdir' variable, in 'makeDocs' line 30, to its new value.

@@ Line 83: / Line 83: @@
 typically you will need to re-generate the docs after some detail or other in the online POV-Ray documentation was edited or updated.
-at this point, only make one platform-specific set of the docs, the one you are most familiar with, that is 'mac' or 'unx' or 'win'.
+at this point, only make one platform-specific set of the docs, the one you are most familiar with; ie 'mac' or 'unx' or 'win'.
-(double-)check, visually, your edit(s) in the generated set, in a browser of choice.
+double-check, visually, your edit(s) in the generated set, in a browser of choice.
-generating even one set of the docs will output a fair amount of progress information, hence the use of the 'script' utility is recommended.
+generating even a single set of the docs outputs a fair amount of progress information, hence the use of the 'script' utility is recommended.
 typically:
@@ Line 103: / Line 103: @@
 </pre>
-to generate the three documentation sets, the corresponding archives, and the updated TOC.
+to create the three documentation sets, plus the corresponding archives and the updated TOC.
 using the script utility as suggested above ensures the same name prefix is given to the recording as is used for the archives.
-toc ...
+updating the table of contents, while not "onerous", requires a quiet moment and due care.
 <pre>
 <!--BEGIN CHANGES BETWEEN HERE--->
@@ Line 112: / Line 115: @@
 </pre>
-- notify CC re update/archives.
+== the future ==
-<pre>
+the PHP could do with another "attempt to organize"..  any such work should be carried out in a copy of the 'docgen2' directory, suitably renamed.
-</pre>
+either remove the <code>.git*</code> directory and files, or start a new branch ?  the only change required is updating the 'workdir' variable in 'makeDocs' line 30, to its new value.

@@ Line 78: / Line 78: @@
 == the procedure ==
-whereas the previous method required several manual steps to update the POV-Ray documentation, there are basically just two now: generate the archives, and update the wiki's docs table of contents.
+whereas the previous method required several manual steps to update the POV-Ray documentation, there are basically just two now: generate the archives and update the wiki's docs table of contents.
 note, the work area '''must''' be clean, that is, not contain files generated in a previous run.
 a dedicated command is provided for the purpose.
@@ Line 86: / Line 86: @@
 (double-)check, visually, your edit(s) in the generated set, in a browser of choice.
-generating "stuff" will output a fair amount of progress information, hence the use of the 'script' utility is recommended.
+generating even one set of the docs will output a fair amount of progress information, hence the use of the 'script' utility is recommended.
-typical:
+typically:
 <pre>
    $ cd ~/docgen2
-   $ script ~/tmp/$(date +%d%b%Y)script ./makeDocs unx
+   $ script ~/tmp/unixscript ./makeDocs unx
    $ ./scrubGeneratedFiles
 </pre>
-after generating the 'unix' version, assess the results under 'documentation/unx/';
+after generating the 'unix' version assess the results under 'documentation/unx/', and in the "log" file created;
-for the 'win' version look in 'output', as this directory contains the post-processed HTML.
+if making the 'win' version look in the 'output' directory, as this contains the post-processed HTML.
 using the script utility as suggested above ensures the same name prefix is given to the recording as is used for the archives.
-when "happy", do a:
+toc ...
 <pre>
-  $ ./makeDocs all
+<!--BEGIN CHANGES BETWEEN HERE--->
 </pre>
 - notify CC re update/archives.
@@ Line 113: / Line 118: @@
 <pre>
 </pre>

@@ Line 33: / Line 33: @@
 <code>makedocs.pl</code>
-a Perl script which post-processes the Windows documentation in preparation of generating the compiled help file, 'povray.chm'.
+a Perl script, it post-processes the Microsoft Windows version of the documentation in preparation of generating the compiled help file, 'povray.chm'.
 <code>mkContentsPages.php</code>
@@ Line 62: / Line 62: @@
 frequently used functions associated with the wikidocgen process, an attempt to organize.
-not shown are '.git*' files and directory.
+not shown are the <code>.git*</code> files and directory.
-the "setup" discussed by JH, and replicated below, still exists, but no longer permanently;
+the "setup" discussed by JH and replicated below still exists, but no longer permanently;
 the whole of the 'documentation' directory tree now is created and populated at run-time.
@@ Line 78: / Line 78: @@
 == the procedure ==
-whereas the previous method required several manual steps to update the POV-Ray documentation, there are basically just two now: generate the archives, and update the wiki's docs table of contents.  step one:
+whereas the previous method required several manual steps to update the POV-Ray documentation, there are basically just two now: generate the archives, and update the wiki's docs table of contents.
 <pre>
    $ cd ~/docgen2
-   $ ./makeDocs all
+   $ script ~/tmp/$(date +%d%b%Y)script ./makeDocs unx
 </pre>
-note, the work area '''must''' be clean, that is, not contain files generated in a previous run.
+after generating the 'unix' version, assess the results under 'documentation/unx/';
-a dedicated "command", ie shell script, is provided for the purpose:
+for the 'win' version look in 'output', as this directory contains the post-processed HTML.
 <pre>
-   $ ./scrubGeneratedFiles
+   $ ./makeDocs all
 </pre>
-typically you will need to re-generate the docs after some detail or other in the online POV-Ray documentation was edited or updated.
+to create the lot.
-at this point, simply make one platform-specific set of the docs, the one you are most familiar with, that is 'mac' or 'unx' or 'win'.
-(double-)check, visually, your edit(s) in the generated set, in a browser of choice.
+- wiki TOC
 <pre>
 </pre>

@@ Line 11: / Line 11: @@
 == layout, manifest, setup ==
-the screenshot shows the "work area", a dedicated directory, containing
+the screenshot shows the layout of <code>docgen2</code>, aka the "work area",
-the following when clean:
+a dedicated directory containing the following when clean:
 [[File:docgen2tree.png||right]]
@@ Line 61: / Line 61: @@
 <code>utilities.php</code>
 frequently used functions associated with the wikidocgen process, an attempt to organize.
 the "setup" discussed by JH, and replicated below, still exists, but no longer permanently;
@@ Line 76: / Line 78: @@
 == the procedure ==
-typically you will need to (re-)generate the docs after some detail or other in the POV-Ray documentation needed editing or updating.
+whereas the previous method required several manual steps to update the POV-Ray documentation, there are basically just two now: generate the archives, and update the wiki's docs table of contents.  step one:
 the process is split into two "stages".  first make a set for the platform you use, you are most familiar with.
 use a browser to verify that all looks "kosher" following that edit/update.
 second, assuming all is ok, clean out the work area and generate the sets for all platforms.

@@ Line 1: / Line 1: @@
-this page details the new generating POV-Ray documentation procedure,
+this page details the new procedure for generating the POV-Ray documentation,
 revised since the server's crash in the early 20s.
@@ Line 8: / Line 8: @@
 you will be logged (have 'ssh'd) into the account which has been set up
 by Chris for the purpose.
 == layout, manifest, setup ==
 the screenshot shows the "work area", a dedicated directory, containing
 the following when clean:
 <code>archives/</code>
-contains the files generated by a given './makeDocs all' run.
+this directory contains the files generated by a given './makeDocs all' run.
 it will be empty, usually.
@@ Line 25: / Line 24: @@
 <code>getStyleSheet.php</code>
-gets the 'povray37.css' style sheet and copies it to a given doc set
+gets the 'povray.css' style sheet from the wiki and copies it to a given doc set directory.
 <code>getWikiPages.php</code>
@@ Line 32: / Line 30: @@
 <code>makeDocs</code>
-a BASH script, the "driver".  generates either a single document set for
+a BASH script, the "driver".  it generates either a single document set for preview/checking, or all (three) of them.
 <code>makedocs.pl</code>
-a Perl script which post-processes the Windows documentation in preparation
+a Perl script which post-processes the Windows documentation in preparation of generating the compiled help file, 'povray.chm'.
 <code>mkContentsPages.php</code>
-builds the various table of contents files and an 'index.html' file for
+builds the various table of contents files, and an 'index.html' file, for a given doc set.
 <code>mkImagePackage.php</code>
@@ Line 47: / Line 42: @@
 <code>mkWikiTOC.php</code>
-rebuilds the '[[Documentation:Contents]]' listing if any of the 'contents'
+rebuilds the '[[Documentation:Contents]]' listing, if any of the 'contents' pages were changed.
 <code>resources/</code>
-this directory is "static" essentially, that is, its contents will not
+this directory is "static" essentially, that is, its contents will not change.
 <code>resources/Arrow{Down,Up}.png</code>
@@ Line 58: / Line 51: @@
 <code>resources/favicon.ico</code>
-as is our icon/image.
+as is the POV-Ray icon/image.
 <code>resources/povray.{hhp,js,stp}</code>
-these files get copied to the 'output' directory, they're used by the
+these files get copied to the 'output' directory, they're used by the Windows HTML Help Compiler.
 <code>scrubGeneratedFiles</code>
-this simple BASH script removes the generated, temporary directories and
+this simple BASH script removes the generated, temporary directories and their contents.
 <code>utilities.php</code>
-frequently used functions associated with the wikidocgen process,
+frequently used functions associated with the wikidocgen process, an attempt to organize.
+the "setup" discussed by JH, and replicated below, still exists, but no longer permanently;
-the "setup" below, discussed by JH, still exists, but no longer permanently;
+the whole of the 'documentation' directory tree now is created and populated at run-time.
 : <code>documentation</code>
@@ Line 88: / Line 76: @@
 == the procedure ==
-intro, step-by-step, "afterwards".
+typically you will need to (re-)generate the docs after some detail or other in the POV-Ray documentation needed editing or updating.
-use 'script'.