Difference between revisions of "HowTo Talk:Contents"

From POV-Wiki
Jump to navigation Jump to search
(→‎Basic article suggestions: coding: best practices)
Line 29: Line 29:
 
* Common PoVRay coding errors (such as the fact that variable and colour names are case sensitive, the fact that rotatation always works around the origin, and the fact that the order in which you rotate things matters and other things that commonly trip people up.) Debugging tips for tracking these errors down.
 
* Common PoVRay coding errors (such as the fact that variable and colour names are case sensitive, the fact that rotatation always works around the origin, and the fact that the order in which you rotate things matters and other things that commonly trip people up.) Debugging tips for tracking these errors down.
 
* Coding and scene development tips (such as: when laying out a scene, use simple placeholder objects in distinctive colours to ensure you have the layout right, and only then start using complex objects.)
 
* Coding and scene development tips (such as: when laying out a scene, use simple placeholder objects in distinctive colours to ensure you have the layout right, and only then start using complex objects.)
 +
::I suggest sub sections about coding containing best practices for keeping complex PoV scripts not only readable, but as well manageable, safe and reusable. Like good use of variables, scopes, functions, macros and inline files. The PovDoc is a bit brief on that. It's so important especially for larger projects and for beginners, because the current version of the language allows terribly hard to debug constructions, that look perfectly ok. I volunteer to contribute to that.--[[User:Wound|Wound]] 19:28, 21 November 2007 (UTC)
 
* Documentation Errata – the PovDocs contain a scattering of typos, and probably other mistakes as well. I believe these are corrected reasonably promptly when reported, but compiling outstanding errors in one place would allow them to be fixed in batches rather than piecemeal. Should this one be part of the Knowledge Base?
 
* Documentation Errata – the PovDocs contain a scattering of typos, and probably other mistakes as well. I believe these are corrected reasonably promptly when reported, but compiling outstanding errors in one place would allow them to be fixed in batches rather than piecemeal. Should this one be part of the Knowledge Base?
 
::Yes. I don't see why not. Problems will probably be reported all over the place and regulars will need to consolidate them according to policy guidelines, but that's par for the course with a Wiki. :) [[User:Eddie|Eddie]] 21:21, 17 November 2007 (UTC)
 
::Yes. I don't see why not. Problems will probably be reported all over the place and regulars will need to consolidate them according to policy guidelines, but that's par for the course with a Wiki. :) [[User:Eddie|Eddie]] 21:21, 17 November 2007 (UTC)

Revision as of 19:28, 21 November 2007

Please hold discussions regarding content of the HowTo:Contents page here.

When starting a new topic, use the '+' button (on the right of the edit button) rather than edit. '+' starts a new section.

Also, please sign your contributions. This can be done by adding ~~~~ (four tildes) at the bottom of your comment.

chrisc 14:48, 10 November 2007 (UTC)

Also, when replying to a comment, add a colon at the beginning of your text. That will indent it, making a threaded conversation like on newsgroups. Nicolas 17:50, 10 November 2007 (UTC)
Indeed, and adding multiple colons will form an indented hierarchy. ;) Eddie 21:40, 10 November 2007 (UTC)

Manually maintained lists

Personally I think it is a better idea to use Wiki categories than have a page that requires a manually maintained list of other pages. I will try to get some examples in place to show what I mean. I just need to make some time... :)

Eddie 15:55, 10 November 2007 (UTC)

Actually, the Help category is a good example of what I mentioned above. All pages added to a category automatically appear on the category page which alleviates the need to have a page where you manually maintain a list of other pages. Do the admins agree with this policy?
Eddie 17:25, 11 November 2007 (UTC)
I don't have a problem with it as such, though a contents page would always be around I think (it for example allows us to highlight particular articles, or to otherwise serve as a 'front end' to the namespace).
chrisc 17:42, 11 November 2007 (UTC)

Basic article suggestions

  • A writing style guide for the Wiki. This external example Wiki style guide covers many of the areas we might care about, but there will certainly be some extra PoV-specific ones as well. I think this one may be well worth adding as a high priority, because it will help establish a high level of quality right from the start.
  • How to cite – "When citing the PoV-Wiki, please include the date and time of the revision to which you refer. This information remains static even when the page is updated, which means others can find the information you were referring to even if it is later edited or vandalised. To provide a link to a specific historical version of a page …"
  • Common PoVRay coding errors (such as the fact that variable and colour names are case sensitive, the fact that rotatation always works around the origin, and the fact that the order in which you rotate things matters and other things that commonly trip people up.) Debugging tips for tracking these errors down.
  • Coding and scene development tips (such as: when laying out a scene, use simple placeholder objects in distinctive colours to ensure you have the layout right, and only then start using complex objects.)
I suggest sub sections about coding containing best practices for keeping complex PoV scripts not only readable, but as well manageable, safe and reusable. Like good use of variables, scopes, functions, macros and inline files. The PovDoc is a bit brief on that. It's so important especially for larger projects and for beginners, because the current version of the language allows terribly hard to debug constructions, that look perfectly ok. I volunteer to contribute to that.--Wound 19:28, 21 November 2007 (UTC)
  • Documentation Errata – the PovDocs contain a scattering of typos, and probably other mistakes as well. I believe these are corrected reasonably promptly when reported, but compiling outstanding errors in one place would allow them to be fixed in batches rather than piecemeal. Should this one be part of the Knowledge Base?
Yes. I don't see why not. Problems will probably be reported all over the place and regulars will need to consolidate them according to policy guidelines, but that's par for the course with a Wiki. :) Eddie 21:21, 17 November 2007 (UTC)
  • How-tos can be divided into technical how-tos, and artistic how-tos. Technical: How to animate; move an object; use CSG; use macros; use blobs; how to plan a complex scene, … Artistic: choosing good colours, choosing the right lighting, using the right camera settings, …
  • Program coding style guide - that is, how PoVRay itself is coded. Compiling tips. ? Not so sure about these ones. Probably less vital.

Simon Smith 21:08, 17 November 2007 (UTC) (updated, errata idea added)

POV-Ray coding style and most importantly some documentation on how the existing code is structured will be totally vital during 4.0 rewrite. Nicolas 03:33, 11 November 2007 (UTC)