Difference between revisions of "Documentation:Developers Notes"
Jholsenback (talk | contribs) |
Jholsenback (talk | contribs) m (numerous adds and deletes) |
||
| Line 6: | Line 6: | ||
<br> | <br> | ||
==Introduction== | ==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 | + | ==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== | ==The Content== | ||
| − | The repository documents were produced by a perl script | + | ===Introduction=== |
| − | + | If you've already had a look at the [[Documentation:Contents|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. | |
| − | + | ||
| − | ==Tag Summary== | + | ===The Translation=== |
| − | This section is a list of the tags | + | 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 [[Documentation:Contents#The Chapters|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==== | ====MUST Preserve==== | ||
These tags are for indexing and searching purposes. They are ''critical'' to down stream processes. | 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. | |
| − | + | <pre><!--<sectiondesc desc="Unix specific">---></pre> | |
| − | + | <pre><!--<indexentry "average, tutorial">---></pre> | |
| + | |||
| + | The end user sees this tag as an Intra-Wiki navigational link, so ....<br> | ||
| + | <pre><linkto "Introduction">Introduction</linkto></pre> | ||
| + | ''becomes'' | ||
| + | <pre><!--<linkto "Introduction">Introduction</linkto>---> | ||
| + | [[Documentation:SomePage#Introduction|Introduction]]</pre> | ||
| + | |||
| + | ====Must Hide==== | ||
| + | Some tags for various reasons were hidden from end user view with the comments notation. See the examples given above. | ||
| + | <p class="BeAware"> | ||
| + | ANYTHING enclosed in the comments notation should not be changed in ANY way. | ||
| + | </p> | ||
| + | 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 <code>povray35.css</code> style sheet have been added to the [[MediaWiki:Common.css|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 [[Documentation:Developers Notes#The Translation|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===== |
| − | There | + | 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 [http://bugs.povray.org/task/3?project=2|_new <span title="Opens A New Window!">project</span>] will make use of the POV-Ray bug track system. When contributors have been recruited and spoken up for one of the five [[Documentation:Contents#The Chapters|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 [[Documentation Talk:Tutorial Section 1.1|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== | ==Take Me Back== | ||
| − | To the | + | To the main [[Documentation:Contents|Table of Contents]] |
<br> | <br> | ||
<table width=100% border=1 cellspacing=0 cellpadding=5> | <table width=100% border=1 cellspacing=0 cellpadding=5> | ||
Revision as of 16:02, 18 May 2009
|
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. |