Documentation:Developers Notes
|
This document is protected, so submissions, corrections and discussions should be held on this documents talk page. |
Introduction
On this page you will find information about the repository content, were it came from, and why it dosen't appear exactly like the documentation that is currently being distributed with the POV-Ray application, as well as information for contributors that wish to get involved with this project.
The Source
The images and html files used to generate this repository came from the POV-Ray revision control depot. They are representative of the current state (version 3.5/3.6) documentation that is currently being distributed with the POV-Ray application.
The Content
Introduction
If you've already had a look at the contents then you've noticed that it only vaguely looks like the distribution documentation. Let me explain. In order to facilitate the concurrent activities of converting this content to version 3.7 and the developement of the PHP script(s) that will produce the final documentation sets, it was decided go with a pretty basic content and navigation scheme for the first phase of this project. Getting the user community involved as soon as possible is essential to the timely completion of this project.
The Translation
The repository documents were produced by a perl script. It converted the html files into MediaWiki markup language preserving POV-centric tags that are critical to the final creation of distribution documentation sets, produced The Chapters table of contents files, and resolved section to section links that tie the documentation together. MediaWiki markup understands many standard html tags, so by in large most things get passed on as-is, however there are some exceptions that are covered in the tag summary below.
Tag Summary
This section is a list of the tags with a brief synopsis of how it was handled and why.
MUST Preserve
These tags are for indexing and searching purposes. They are critical to down stream processes.
These have no end user viewable information so they are commented out.
<!--<sectiondesc desc="Unix specific">--->
<!--<indexentry "average, tutorial">--->
The end user sees this tag as an Intra-Wiki navigational link, so ....
<linkto "Introduction">Introduction</linkto>
becomes
<!--<linkto "Introduction">Introduction</linkto>---> [[Documentation:SomePage#Introduction|Introduction]]
Must Hide
Some tags for various reasons were hidden from end user view with the comments notation. See the examples given above.
ANYTHING enclosed in the comments notation should not be changed in ANY way.
There will be some cleanup opportunities at some point in this project.
Appearance
In order to come a bit closer to resembling the distribution some class identifiers from the povray35.css style sheet have been added to the Wiki site file. Classes added here affect ALL skins, so not all the definitions were added.
Left Justified
There were a number of html tags that just didn't work as you'd expect, until the became the first character of a new line. There are also certain wiki tags that have the same requirement, so it was necessary to get rid of leading tabs and spaces in some places.
Help Wanted
Introduction
There has already been an initial audit of the content done on the developement Wiki before it was posted on this site, however one set of eyes can't possibly catch everything. The translation process is admittedly not perfect, so in addition to branding the content version 3.7, there are additional quality assurance measures that should be considered. See the summarized list below.
Version Issues
Some sections can be changed others deleted. New sections will need to be added for new version 3.7 features.
Link Integrity
Make sure all links resolve properly. Not all links were programmaticly resolved.
Technical Correctness
News group discussions have mentioned several issues. There is a need to investigate and follow up accordingly.
Spelling and Grammar
Awkwardly worded passages and spelling errors.
More Details
Have a look at this more detailed to do list.
A Change Example
Consider this example of identifying a needed change. Only users with Sysop privileges can directly edit the repository documents, however any registered user can create a talk page, to identify the needed change and offer a correction.
Take Me Back
To the main Table of Contents
|
This document is protected, so submissions, corrections and discussions should be held on this documents talk page. |