Difference between revisions of "User:Jr/WikiDocGen2"
(created with partial content and screenshot.) |
(wip, adding & revising content.) |
||
| Line 1: | Line 1: | ||
| − | this page details the new generating POV-Ray documentation | + | 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 8: | Line 8: | ||
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 which has been set up | ||
by Chris for the purpose. | by Chris for the purpose. | ||
| − | |||
== layout, manifest, setup == | == layout, manifest, setup == | ||
| − | |||
| − | |||
the screenshot shows the "work area", a dedicated directory, containing | the screenshot shows the "work area", a dedicated directory, containing | ||
the following when clean: | the following when clean: | ||
| + | |||
| + | [[File:docgen2tree.png||right]] | ||
<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. | ||
| Line 25: | Line 24: | ||
<code>getStyleSheet.php</code> | <code>getStyleSheet.php</code> | ||
| − | gets the ' | + | 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 30: | ||
<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 which post-processes the Windows 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 42: | ||
<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 | ||
<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 51: | ||
<code>resources/favicon.ico</code> | <code>resources/favicon.ico</code> | ||
| − | as is | + | 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 | + | this simple BASH script 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. | ||
| − | + | the "setup" discussed by JH, and replicated below, still exists, but no longer permanently; | |
| − | the "setup" | + | the whole of the 'documentation' directory tree now is created and populated at run-time. |
| − | the whole of the 'documentation' directory tree now is created and populated | ||
| − | at run-time. | ||
: <code>documentation</code> | : <code>documentation</code> | ||
| Line 88: | Line 76: | ||
== the procedure == | == 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. | |
| − | + | ||
| + | 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. | ||
| + | |||
| + | |||
| + | creating the documentation for all three platforms as detailed in JH's page used to require a series of manual steps for each, and must have been correspondingly "brittle". | ||
Revision as of 17:59, 25 May 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 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:
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 wikidocgen process.
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 which post-processes the Windows 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
this simple BASH script removes the generated, temporary directories and their contents.
utilities.php
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 whole of the 'documentation' directory tree now is created and populated at run-time.
documentationmacimages
unximages
winimages
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.
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.
creating the documentation for all three platforms as detailed in JH's page used to require a series of manual steps for each, and must have been correspondingly "brittle".