Difference between revisions of "User:Jr/WikiDocGen2"

From POV-Wiki
Jump to navigation Jump to search
(created with partial content and screenshot.)
 
m (wording, and "grammar" </sigh>)
 
(6 intermediate revisions by the same user not shown)
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.
 
revised since the server's crash in the early 20s.
  
Line 6: Line 6:
  
 
as JH points out, all work happens on the wiki server, so I assume
 
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.
−
by Chris for the purpose.
 
−
 
 
  
 
== layout, manifest, setup ==
 
== layout, manifest, setup ==
  
−
[[File:docgen2tree.png]]
+
the screenshot shows the layout of <code>docgen2</code>, aka the "work area",
 +
a dedicated directory containing the following when clean:
  
−
the screenshot shows the "work area", a dedicated directory, containing
+
[[File:docgen2tree.png||right]]
−
the following when clean:
 
  
 
<code>archives/</code>
 
<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.
 
it will be empty, usually.
  
 
<code>common.php</code>
 
<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>
 
<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.
−
directory.
 
  
 
<code>getWikiPages.php</code>
 
<code>getWikiPages.php</code>
Line 32: Line 29:
  
 
<code>makeDocs</code>
 
<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.
−
preview/checking, or all (three) of them.
 
  
 
<code>makedocs.pl</code>
 
<code>makedocs.pl</code>
−
a Perl script which post-processes the Windows documentation in preparation
+
a Perl script, it post-processes the Microsoft Windows version of the documentation in preparation of generating the compiled help file, 'povray.chm'.
−
of generating the compiled help file, 'povray.chm'.
 
  
 
<code>mkContentsPages.php</code>
 
<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.
−
a given doc set.
 
  
 
<code>mkImagePackage.php</code>
 
<code>mkImagePackage.php</code>
Line 47: Line 41:
  
 
<code>mkWikiTOC.php</code>
 
<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.
−
pages gets changed.
 
  
 
<code>resources/</code>
 
<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.
−
change.
 
  
 
<code>resources/Arrow{Down,Up}.png</code>
 
<code>resources/Arrow{Down,Up}.png</code>
Line 58: Line 50:
  
 
<code>resources/favicon.ico</code>
 
<code>resources/favicon.ico</code>
−
as is our icon/image.
+
as is the POV-Ray icon/image.
  
 
<code>resources/povray.{hhp,js,stp}</code>
 
<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.
−
Windows HTML Help Compiler.
 
  
 
<code>scrubGeneratedFiles</code>
 
<code>scrubGeneratedFiles</code>
−
this simple BASH script removes the generated, temporary directories and
+
a BASH script, it removes the generated, temporary directories and their contents.
−
their contents.
 
  
 
<code>utilities.php</code>
 
<code>utilities.php</code>
−
frequently used functions associated with the wikidocgen process,
+
frequently used functions associated with the wikidocgen process, an attempt to organize.
−
an attempt to organize.
 
  
 +
not shown are the <code>.git*</code> files and directory.
  
−
the "setup" below, discussed by JH, 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
+
the whole of the 'documentation' directory tree now is created and populated at run-time.
−
at run-time.
 
  
 
: <code>documentation</code>
 
: <code>documentation</code>
Line 88: Line 77:
 
== the procedure ==
 
== the procedure ==
  
−
intro, step-by-step, "afterwards".
+
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.
−
use 'script'.
+
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/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.
 +
 
 +
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:
 +
<pre>
 +
  $ cd ~/docgen2
 +
  $ script ~/tmp/unixscript ./makeDocs unx
 +
  $ ./scrubGeneratedFiles
 +
</pre>
 +
 
 +
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 instead, as it contains the post-processed HTML.
 +
 
 +
when all "looks good", do a:
 +
<pre>
 +
  $ script ~/tmp/$(date +%d%b%Y)script ./makeDocs all
 +
</pre>
 +
 
 +
to create the three documentation sets, plus the corresponding archives and the updated TOC.
 +
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 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>
 +
<!--BEGIN CHANGES BETWEEN HERE--->
 +
<!--END CHANGES BETWEEN HERE--->
 +
</pre>
 +
 
 +
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.
 +
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.

Latest revision as of 14:05, 5 June 2026

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

the page is based on J Holsenback's 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 set up by Chris for the purpose.

layout, manifest, setup

the screenshot shows the layout of docgen2, aka the "work area", a dedicated directory containing the following when clean:

docgen2tree.png

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

common.php frequently used functions associated with the documentation generating processes.

getStyleSheet.php gets the 'povray.css' style sheet from the wiki and copies it to a given doc set directory.

getWikiPages.php gets the files from the POV-Wiki and processes them.

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

makedocs.pl a Perl script, it post-processes the Microsoft Windows version of the documentation in preparation of generating the compiled help file, 'povray.chm'.

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

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

mkWikiTOC.php rebuilds the 'Documentation:Contents' listing, if any of the 'contents' pages were changed.

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

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

resources/favicon.ico as is the POV-Ray icon/image.

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

scrubGeneratedFiles a BASH script, it removes the generated, temporary directories and their contents.

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

not shown are the .git* files and directory.

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.

documentation
mac
images
unx
images
win
images


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. 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/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.

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: 

  $ cd ~/docgen2
  $ script ~/tmp/unixscript ./makeDocs unx
  $ ./scrubGeneratedFiles

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 instead, as it contains the post-processed HTML.

when all "looks good", do a: 

  $ script ~/tmp/$(date +%d%b%Y)script ./makeDocs all

to create the three documentation sets, plus the corresponding archives and the updated TOC. 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 content of the newWikiTOC 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. 

<!--BEGIN CHANGES BETWEEN HERE--->
<!--END CHANGES BETWEEN HERE--->

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. either remove the .git* 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.

Retrieved from "https://wiki.povray.org/content?title=User:Jr/WikiDocGen2&oldid=11502"