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 Wiki extension 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 hyper-links that tie the documentation togeather. 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 is 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.

Assigning Tasks

This project will make use of the POV-Ray bug track system. When contributors have been recruited and spoken up for one of the five chapters the project coordinator will enter a new task and assign ownership so redundant efforts can be avoided and progress can easily be tracked.

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.