Difference between revisions of "Documentation Talk:Contents"

From POV-Wiki
Jump to navigation Jump to search
(New page: = Planning needed = We need a list of the wiki page names that every documentation section will have. There are duplicate names, like in [http://www.povray.org/documentation/view/3.6.1/73/...)
 
m (follow up)
 
(16 intermediate revisions by 7 users not shown)
Line 1: Line 1:
−
= Planning needed =
 
−
We need a list of the wiki page names that every documentation section will have. There are duplicate names, like in [http://www.povray.org/documentation/view/3.6.1/73/ Tutorial: Isosurface Object], [http://www.povray.org/documentation/view/3.6.1/300/ Reference: Isosurface Object], and [http://www.povray.org/documentation/view/3.6.1/531/ Quick reference: Isosurface]. What should the wiki pages for those be called?
 
  
−
Making them links also helps see which pages are missing.
+
==Introduction==
 +
This is the talk page for the project front door. Registered users can edit this page, so let's try to stay organized.
 +
==Announcements==
 +
"New" news and stuff like that ...
 +
==Guidelines==
 +
Besides the site editing [[Help:Editing Guidelines|guidelines]], we need to establish a few style and programming rules of our own.
 +
==Suggestion Box==
 +
Suggestions go here.
 +
 
 +
 
 +
 
 +
These are somewhere between suggestions/questions.
 +
 
 +
With the official documentation in wiki format, it seems like it would be appropriate to embed images of the example code right along with the appropriate section.  This is really more of a style question, both for options for the scene when rendering the example (should probably be standardized as much as possible) and the image should fit in the wiki (size, thumbnails, etc.)
 +
<p>
 +
:Thanks for the feedback, however I think you may have misunderstood. Have a look at the opening [[Documentation:Contents#An Introduction|paragraph]]. Additionally the [[Documentation:Developers Notes|Developers Notes]] page might also lend some clarity to the intent.
 +
</p>
 +
Also, how closely are the other sections going to be associated with the documentation?  For instance, if the docs cover some topic, and there is a HowTo: guide for related aspects, would it be appropriate for the documentation to link to that?  I think some sort of collapsible "See related HowTo articles" might be a good fit.
 +
<p>
 +
:At this time I hadn't planned to do anything along those lines. Since [[HowTo:Contents|HowTo]] articles aren't part of the official distribution documentation sets, I didn't see a need.
 +
</p>
 +
What should be done to aid searching?  For instance, if I search for "disc", the very first result returned should be the disc section of the official docs.  A series of redirect pages that link to the official docs would work, but I suspect there would be a smarter way.
 +
-[[User:Reactor|Reactor]] 18:33, 7 August 2009 (UTC)
 +
<p>
 +
:The search comes embedded with the Wiki application. I tried several searches (disc, plane, cylinder, box) and got mixed results. '''disc''' was the only one that hit it's mark '''plane''' and '''cylinder''' were a scroll away while '''box''' missed it altogether. Near the top of the search results page, I ended up [[Help:External_searches|here]]. Just for the heck of it I tried this search ''POV+Reference+box'' with somewhat better but mixed results (the top hit wasn't even a POV site). I think it is what it is. I'm going to follow up, but have to call this a low priority item. --[[User:Jholsenback|jholsenback]] 10:38, 8 August 2009 (UTC)
 +
</p>
 +
 
 +
==Rants==
 +
Complaints are valid too, please keep it civil.
 +
==Archives==
 +
I didn't want to delete these discussions, so I created this section. --[[User:Jholsenback|ash]] 20:04, 12 March 2009 (UTC)
 +
===Planning Needed===
 +
We need a list of the wiki page names that every documentation section will have. There are duplicate names, like in [http://www.povray.org/documentation/view/3.6.1/73/ Tutorial: Isosurface Object], [http://www.povray.org/documentation/view/3.6.1/300/ Reference: Isosurface Object], and [http://www.povray.org/documentation/view/3.6.1/531/ Quick reference: Isosurface]. What should the wiki pages for those be called? Making them links also helps see which pages are missing.
 +
 
 
[[User:Nicolas|Nicolas]] 19:21, 5 November 2007 (UTC)
 
[[User:Nicolas|Nicolas]] 19:21, 5 November 2007 (UTC)
 +
 +
:I intend to import the official POV-Ray documentation into this namespace at some point; I didn't link to this part of the wiki from the navigation bar because it's not really ready for content. Once the docs are imported then folks will be free to offer changes and updates. Note that this will require that the docs in this portion of the wiki be licensed according to the existing POV license (and thus edits must also be).
 +
 +
:If there is strong enough interest by folks willing to re-write the docs under a free license such as the Creative Commons ones, for example, then I'll split the doc area accordingly.
 +
:[[User:WikiSysop|WikiSysop]] 21:24, 5 November 2007 (UTC)
 +
:: Damn, I totally forgot about licensing issues. So, either existing docs get imported and we're stuck with the POV doc license, or they get rewritten to make them CC... That would need some discussion on the ng's.
 +
:: [[User:Nicolas|Nicolas]] 21:40, 5 November 2007 (UTC)
 +
 +
===Documentation Content===
 +
In the absence of movement in this area I have created the skeleton of (most of) the documentation as it is laid out in the official documentation. It won't be much longer before the skeleton is complete.<BR>However, I have also started to add [[Documentation:Contents/POV-Ray Reference/Introduction/Notation and Basic Assumptions|content]] and am asking the administrators to please add some classes to (one of) the wiki stylesheets for use in the documentation. So far I have used:
 +
*"keyword" for styling keywords
 +
*"syntax" for styling syntax items
 +
*"location" for styling paths.
 +
Please feel free to create whatever classes you want according to your standards, I will use them as you specify. The above are just preliminary examples and can easily be changed. Also please set the properties as you see fit. I used properties that mimic the original documentation except in color, so as to differentiate between wiki links and documentation items. Again, these are just examples and can easily be changed.<BR><BR>Once you have created the classes, please document them in the [[Help:Editing_Guidelines|Editing Guidelines]] so that people adding documentation  will know how to format the content.<BR><BR>Note that I am rewording the content such that it falls under the license of this wiki but retains the original meaning.<BR>[[User:Eddie|Eddie]] 19:07, 6 January 2008 (UTC)
 +
 +
:Thanks Chris. (You're fast!). I don't see any color, so I'm not sure if it is what you intended or if my browser has a caching issue. Since I cannot see the stylesheet to troubleshoot I will continue in the hopes that things appear as you want them to. [[User:Eddie|Eddie]] 01:40, 8 January 2008 (UTC)
 +
 +
::Check the [[Documentation:Contents/POV-Ray Reference/Introduction/Notation and Basic Assumptions|content]] page; at least for me it's displaying the colors (and I'm using a different system than I made the changes on). If you still don't see them, make sure the source for the page shows something like <code>@import "/content?title=MediaWiki:Common.css</code>. [[User:Chrisc|chrisc]] 01:49, 8 January 2008 (UTC)
 +
::One thing I've just noticed is that the wiki doesn't allow non-logged-in users to access common.css. Not sure why, but the net result is that folks reading the wiki without logging in won't get the enhanced CSS markup mentioned above. I'll have to fix this, once I've worked out why it's happening. [[User:Chrisc|chrisc]] 00:51, 9 January 2008 (UTC)
 +
 +
:::It appears to be a permissions issue. Even though I'm logged in I cannot access that style sheet. I'm not familiar with the inner workings of MediaWiki, but it seems there is a problem distinguishing between letting someone view the style sheet as opposed to edit it. I understand that you don't want us regular users to edit it, but without being able to view it, it can't take effect. Thanks for looking into it. [[User:Eddie|Eddie]] 17:40, 12 January 2008 (UTC)
 +
 +
::::It should be fixed now. [[User:Chrisc|chrisc]] 16:20, 19 January 2008 (UTC)
 +
 +
:::::Thanks Chris. Good work. [[User:Eddie|Eddie]] 17:37, 20 January 2008 (UTC)
 +
 +
== Patterns entries not in the right section ==
 +
Hexagon & square pattern should be in the discontinuous pattern sub-chapter, not the general pattern sub-chapter.
 +
 +
* OK ... updated the [[Documentation:Reference Table of Contents#Scene File Elements|table of contents]] --[[User:Jholsenback|jholsenback]] 15:53, 23 August 2012 (UTC)
 +
 +
Caveat: when Hexagon, Brick, and checker are named together, they should often also be in company of square, object and triangle (such as in http://wiki.povray.org/content/Reference:Media#Density_with_color_map ), or an ellipsis should be used.
 +
(for instance: using object pattern in density is supported, despite the sentence not naming it)
 +
I did not test if square & triangle can have a list in density block of media (instinctively, they should support it too).
 +
 +
* Not sure what you mean by <em>despite the sentence not naming it</em> are you talking about in the [[Reference:Discontinuous Patterns|discontinuous patterns]] narrative, or in the [[Reference:Media#Density with color map|media density]] topic? --[[User:Jholsenback|jholsenback]] 15:53, 23 August 2012 (UTC)
 +
 +
=== New discontinuous ? ===
 +
Cells and crackle are somehow mixed cases: they are discontinuous at boundary of cell, but there is no limit to the different number of values they can generate. (all in range 0 to 1)
 +
Notice that the tiling pattern is also in the same situation, for the tiling numbers that have more than one kind of tile:
 +
(i.e. : 1, 2, 4 & 10 are the only tiling variants which are "continuous"; all others (up to 27) are discontinuous on the map)
 +
 +
On the opposite, hexagon, brick, checker, object, square and triangle are all patterns which are discontinuous but whose number of value are finite (and small, from 2 up to 6).
 +
I do not know the English to qualify these subtleties.
 +
 +
--[[User:Le Forgeron|Le Forgeron]] 12:37, 23 August 2012 (UTC)
 +
 +
* Rather than adding another sub-section, does the note I added in [[Reference:Discontinuous Patterns|Discontinuous Patterns]] clear up your concern? --[[User:Jholsenback|jholsenback]] 15:53, 23 August 2012 (UTC)
 +
 +
<br>
 +
<table width=100% border=0 cellspacing=0 cellpadding=5>
 +
<tr><td width=50% bgcolor=#EEEEEF>
 +
[[Documentation:Contents|Main Table of Contents]]</td>
 +
<td width=50% bgcolor=#EEEEEF align=right>
 +
[[Main Page|The POV-Wiki Main Page]]</td></tr>
 +
</table>

Latest revision as of 15:53, 23 August 2012

Introduction

This is the talk page for the project front door. Registered users can edit this page, so let's try to stay organized.

Announcements

"New" news and stuff like that ...

Guidelines

Besides the site editing guidelines, we need to establish a few style and programming rules of our own.

Suggestion Box

Suggestions go here.


These are somewhere between suggestions/questions.

With the official documentation in wiki format, it seems like it would be appropriate to embed images of the example code right along with the appropriate section. This is really more of a style question, both for options for the scene when rendering the example (should probably be standardized as much as possible) and the image should fit in the wiki (size, thumbnails, etc.)

Thanks for the feedback, however I think you may have misunderstood. Have a look at the opening paragraph. Additionally the Developers Notes page might also lend some clarity to the intent.

Also, how closely are the other sections going to be associated with the documentation? For instance, if the docs cover some topic, and there is a HowTo: guide for related aspects, would it be appropriate for the documentation to link to that? I think some sort of collapsible "See related HowTo articles" might be a good fit.

At this time I hadn't planned to do anything along those lines. Since HowTo articles aren't part of the official distribution documentation sets, I didn't see a need.

What should be done to aid searching? For instance, if I search for "disc", the very first result returned should be the disc section of the official docs. A series of redirect pages that link to the official docs would work, but I suspect there would be a smarter way. -Reactor 18:33, 7 August 2009 (UTC)

The search comes embedded with the Wiki application. I tried several searches (disc, plane, cylinder, box) and got mixed results. disc was the only one that hit it's mark plane and cylinder were a scroll away while box missed it altogether. Near the top of the search results page, I ended up here. Just for the heck of it I tried this search POV+Reference+box with somewhat better but mixed results (the top hit wasn't even a POV site). I think it is what it is. I'm going to follow up, but have to call this a low priority item. --jholsenback 10:38, 8 August 2009 (UTC)

Rants

Complaints are valid too, please keep it civil.

Archives

I didn't want to delete these discussions, so I created this section. --ash 20:04, 12 March 2009 (UTC)

Planning Needed

We need a list of the wiki page names that every documentation section will have. There are duplicate names, like in Tutorial: Isosurface Object, Reference: Isosurface Object, and Quick reference: Isosurface. What should the wiki pages for those be called? Making them links also helps see which pages are missing.

Nicolas 19:21, 5 November 2007 (UTC)

I intend to import the official POV-Ray documentation into this namespace at some point; I didn't link to this part of the wiki from the navigation bar because it's not really ready for content. Once the docs are imported then folks will be free to offer changes and updates. Note that this will require that the docs in this portion of the wiki be licensed according to the existing POV license (and thus edits must also be).
If there is strong enough interest by folks willing to re-write the docs under a free license such as the Creative Commons ones, for example, then I'll split the doc area accordingly.
WikiSysop 21:24, 5 November 2007 (UTC)
Damn, I totally forgot about licensing issues. So, either existing docs get imported and we're stuck with the POV doc license, or they get rewritten to make them CC... That would need some discussion on the ng's.
Nicolas 21:40, 5 November 2007 (UTC)

Documentation Content

In the absence of movement in this area I have created the skeleton of (most of) the documentation as it is laid out in the official documentation. It won't be much longer before the skeleton is complete.
However, I have also started to add content and am asking the administrators to please add some classes to (one of) the wiki stylesheets for use in the documentation. So far I have used:

  • "keyword" for styling keywords
  • "syntax" for styling syntax items
  • "location" for styling paths.

Please feel free to create whatever classes you want according to your standards, I will use them as you specify. The above are just preliminary examples and can easily be changed. Also please set the properties as you see fit. I used properties that mimic the original documentation except in color, so as to differentiate between wiki links and documentation items. Again, these are just examples and can easily be changed.

Once you have created the classes, please document them in the Editing Guidelines so that people adding documentation will know how to format the content.

Note that I am rewording the content such that it falls under the license of this wiki but retains the original meaning.
Eddie 19:07, 6 January 2008 (UTC)

Thanks Chris. (You're fast!). I don't see any color, so I'm not sure if it is what you intended or if my browser has a caching issue. Since I cannot see the stylesheet to troubleshoot I will continue in the hopes that things appear as you want them to. Eddie 01:40, 8 January 2008 (UTC)
Check the content page; at least for me it's displaying the colors (and I'm using a different system than I made the changes on). If you still don't see them, make sure the source for the page shows something like @import "/content?title=MediaWiki:Common.css. chrisc 01:49, 8 January 2008 (UTC)
One thing I've just noticed is that the wiki doesn't allow non-logged-in users to access common.css. Not sure why, but the net result is that folks reading the wiki without logging in won't get the enhanced CSS markup mentioned above. I'll have to fix this, once I've worked out why it's happening. chrisc 00:51, 9 January 2008 (UTC)
It appears to be a permissions issue. Even though I'm logged in I cannot access that style sheet. I'm not familiar with the inner workings of MediaWiki, but it seems there is a problem distinguishing between letting someone view the style sheet as opposed to edit it. I understand that you don't want us regular users to edit it, but without being able to view it, it can't take effect. Thanks for looking into it. Eddie 17:40, 12 January 2008 (UTC)
It should be fixed now. chrisc 16:20, 19 January 2008 (UTC)
Thanks Chris. Good work. Eddie 17:37, 20 January 2008 (UTC)

Patterns entries not in the right section

Hexagon & square pattern should be in the discontinuous pattern sub-chapter, not the general pattern sub-chapter.

Caveat: when Hexagon, Brick, and checker are named together, they should often also be in company of square, object and triangle (such as in http://wiki.povray.org/content/Reference:Media#Density_with_color_map ), or an ellipsis should be used. (for instance: using object pattern in density is supported, despite the sentence not naming it) I did not test if square & triangle can have a list in density block of media (instinctively, they should support it too).

New discontinuous ?

Cells and crackle are somehow mixed cases: they are discontinuous at boundary of cell, but there is no limit to the different number of values they can generate. (all in range 0 to 1) Notice that the tiling pattern is also in the same situation, for the tiling numbers that have more than one kind of tile: 

(i.e. : 1, 2, 4 & 10 are the only tiling variants which are "continuous"; all others (up to 27) are discontinuous on the map)

On the opposite, hexagon, brick, checker, object, square and triangle are all patterns which are discontinuous but whose number of value are finite (and small, from 2 up to 6). I do not know the English to qualify these subtleties.

--Le Forgeron 12:37, 23 August 2012 (UTC)


Main Table of Contents The POV-Wiki Main Page
Retrieved from "https://wiki.povray.org/content?title=Documentation_Talk:Contents&oldid=7536"