User:Jr/WikiDocGen2

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 layout of docgen2, aka 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, 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 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.

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 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'. (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.

typical:

  $ cd ~/docgen2
  $ script ~/tmp/$(date +%d%b%Y)script ./makeDocs unx
  $ ./scrubGeneratedFiles

after generating the 'unix' version, assess the results under 'documentation/unx/'; for the 'win' version look in 'output', as this directory 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:

  $ ./makeDocs all

to create the lot.

- wiki TOC - notify CC re update/archives.

win "special", check under 'output'.

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.