The 'Contribution' screen guides you through the submission process step-by-step. As you move the cursor from field to field a short piece of context-sensitive help is displayed at the top of the screen. In addition, most of the fields have an individual help button (a question mark '?' in a circle) that takes you straight to the relevant section of this manual. Mandatory fields are marked with an 'M' in a circle and change from Red to Green once you've filled them in. If you do anything wrong an error should immediately display in Red at the bottom of the screen and it won't let you hit the 'Submit Contribution' button until you've fixed such errors.
There are some easy-to-implement standards that help people to use different objects together in a single scene. There's an option that allows you to submit a non-compliant contribution (better than not submitting anything), but it helps people a lot if you can make your work compliant. The standards are mostly about naming things so that file names and identifier names don't clash. This can easily be achieved by prefixing your file names, variable names (both global and local), macro names etc. with a common prefix that consists of the name of your contribution, followed by the underscore '_'. Examples are given below.
All file names are converted to lowercase when they are uploaded onto the server to try to cope better with operating system differences with respect to case sensitivity in file names. Any references to file names within your POV scene and include files (and within any HTML documentation) should therefore consistently use lowercase.
You should test the files that you intend to submit before submitting them. Make sure that the set of files works together and doesn't require anything else. To subsequently update a submission with enhancements or fixes you'll need to create a new version, so that anyone who has downloaded it in between times can tell it's been updated.
Hopefully you will find the submission process pretty clear. If you do get stuck you can display the more detailed descriptions of the fields in the 'Submission Form' section of this document below. There's also a POV-Ray newsgroup dedicated to this collection at http://news.povray.org/povray.object-collection/ where you can ask questions or propose improvements.
Before submitting any files to this collection you must:
|The POV-Ray Team reserve the right to change the licensing conditions for the collection in the future, in which case anyone who has downloaded files under the CC-GNU LGPL will continue to be covered by that license or may choose to use the new license.|
In the following examples it is assumed that you have an object called 'Netball' and have elected to use a unique prefix of 'NB'.
|Main Contribution Files Most contributions will contain at least one scene file (a '.pov' file) and/or an include file (a '.inc' file). If your submission is really just an example of how to do something, you may choose to put it all in a single scene file. However, it is preferred that you submit Object/Macro/Texture/Function definitions as include files and provide a sample scene file to illustrate how the include file should be used. It is recommended that you use the full object name for the main files, but you can use the unique Prefix if you wish.||netball.inc||The main file in the contribution, this contains the principal Objects, Textures, Macros, Functions etc.|
|netball.pov||A sample scene file illustrating how the include file can be used.|
|Other Scene/Include Files You can provide as many other scene files and/or include files as you wish. You could, for example have a macro in the main include file that assembles components from a variety of other include files. You can also provide a range of different scene files illustrating different features of your contribution.||netball_valve.inc||May be a component of the ball|
|netball_bag.inc||Could be an accessory to the main file|
|netball_withlogo.pov||Could illustrate how to apply an image file to the ball.|
|nb_example1.pov||You can use the unique prefix in place of the contribution name.|
|Main Image Files
You should provide a thumbnail image file with a Height of 120 pixels and a width of 160 pixels that will be displayed on the search results screen.
You should also provide a larger sized image file ideally with a resolution of 800x600 or 640x480.
Both images should be in a common compressed format (extensions jpg, jpe, jpeg, gif or png). These images are optional, but strongly encouraged.
The rule for getting the thumbnail to appear on the search page is that the file name must be just the contribution name/prefix name followed by '_thumbnail' and the file type for the thumbnail image file.
The rule for getting the thumbnail to hyperlink to a larger image is that the file name of the larger image must be just the contribution name/prefix name followed by the file type for the larger image file.
See the examples to the right.
|netball_thumbnail.jpg or nb_thumbnail.jpg||The thumbnail image to display on the search screen|
|netball.jpg or nb.jpg||The full-sized image linked to from the thumbnail on the search screen|
|Other Image Files You can provide additional image files but they won't be displayed on the collection website unless you create an HTML document file to display them (see below).||netball_withlogo.jpg or nb_example7.jpg||Could be an additional images referenced in your documentation.|
You can provide an HTML file containing additional information about your contribution. If you do (and you name it correctly) the search results
for your contribution will incorporate a 'More Detail' link to enable the user to display that page. Your page can incorporate images and hyperlinks
to other HTML pages that you submit or to other web sites.
If your HTML skills are not very good you can write plain text into an HTML file and it will still be displayed (you can use the '<P>' tag to throw a new paragraph here and there).
|netball.html||An optional HTML documentation file.|
The desciption of your object is very important as it enables people looking for things to determine whether or not your contribution meets their needs.
You should attempt to write a short but detailed English language description. Remembering that English may not be the first language of people
reading your description, so structure your sentences properly and make sure that what you write is not ambiguous or otherwise confusing.
For further information about how to use this file see the decription field below.
|netball_description.txt||A plain text file containing the description of the contribution.|
Keywords and Key Phrases provide an important means by which people can find the files you are submitting when they search the collection.
Althouth not visible on the collection web site, careful selection of appropriate words and phrases will significantly increase the likelihood that people
will be able to find and use your submission.
As you prepare your contribution for submission, think of different keywords that will be appropriate and jot them down in this file as you go.
For further information about how to use this file see the keywords field below.
|netball_keywords.txt||A plain text file containing the search keywords and key phrases that will result in this contribution being found.|
You should avoid prerequisites and dependencies wherever possible, but you may find that your contribution is dependant upon
specific software, a specific operating system, a specific version of POV-Ray or that it relies upon other contributions or
files available from other Internet sites. You should keep a note of such dependencies in this file so that you can record them as
prerequirsites on the submissions page when you submit your contribution.
For further information about how to use this file see the prerequisites field below.
|netball_prereqs.txt||A plain text file containing the prerequisites for this contribution.|
|Readme, Script, Licence Logo These files are automatically copied into each download. You don't need to copy them back up to the server at all when you submit a contribution.||
Readme for this download.
Script file for this download.
The following sections describe the information that needs to be entered into the contribution form field by field.
One of the aims of this collection is to encourage the evolution of objects.
The licensing permits the use, modification and redistribution of objects from the collection so that, if you find an object useful,
you can develop it further and resubmit it to the collection. To keep track of this the server implements a versioning mechanism, so that previous
versions are still held unaltered when an altered version of an object is submitted.
If you are submitting a brand new object to the collection that is not based on an earlier contribution, or if it is sufficiently distinct that it should be classed as a separate object, then select 'New' from the New/Existing pull-down.
If you are submitting an altered version of an object that already exists in the collection then select 'Existing' from the New/Existing pull-down.
There may well be times when it's difficult to decide whether to classify a contribution as a new object or whether it should be classed as an updated version of an existing object. Don't forget that you can discuss it with others on the POV-Ray newsgroups.
When submitting a new object you should pick a new name. If you find an object with that name exists, then, unless you wish to put in the work to make it compatible with the existing object, you should pick a different name. If you, for example, create a netball object that is not based on the object already called Netball, then you could choose a different name e.g. Netball_pgd, or you could look at what the existing object does and combine the best of both to develop something with all of the capabilities of both your Netball and the existing netball, in which case you could upload it using the existing name 'Netball', recording it with a different version number.
|Unique Prefix (Optional)||
You can choose to use the full object name as a prefix or you can optionally reserve a separate unique prefix. For example, the Netball contribution uses the full contribution name 'Netball' to prefix all files, but uses the letters 'NB' as a prefix internally, with NB_BallRadius being used to control the radius of the Netball and NB_BallTexture being used to control its surface texture.
Optional Unique Prefixes must be unique across the collection and must not be the same as any contribution name. The name check ignores case (so NB=nb=nB=Nb). If you find that the prefix you would really like to use is already being used for another contribution, consider appending a number to the prefix e.g. NB2.
Using an underscore between the prefix and the rest of the name is require as it makes it possible for abbreviations of existing names to be used for other objects. For example, the name 'Net' could still be used for an object even when 'Netball' is already being used for a different object. Hint - this also makes it very easy to do a global change throughout one or more files.
You are asked to make a reasonable assessment as to how closely your contribution follows the standards.
When searching the collection, anything that is less than a '3', doesn't come up in the results by default.
The person doing the search needs to conciously select the 'Search for both standards compliant and non-compliant files' option to display less-compliant files so
that they don't accidentally download files that could interfere with files they already have.
If you submit non-compliant files then a lot of people may never bother looking at them. On the other hand, saying they're compliant if they're not is likely to hack people off pretty quickly.
Providing the option to submit non-compliant files is intended to encourage contributions even from those who don't have the time to invest in making it compliant. At least if you do submit a non-compliant file and someone finds it useful then there's always the hope that they'll tidy it up and submit a compliant version.
Once you have submitted a contribution it will always be referred to along with your contributor tag name and will usually have the submission date appended to it. You therefore enter only the version number itself. You should not identify yourself in the version number and should not add the date into the number as this is liable to mess up the version number displays and make it more difficult for people to easily find what they want.
|Previous Version||If you are submitting an updated version of an existing submission you will need to indicate which previous version your updates are based on. This would most normally be the most recent previous submission, which is the default version selected in the pull-down list of previous versions. This information is currently only used by administrators. You should not assume that the person downloading your contribution will already have any files from any previous version of the contribution. You should submit all files that are required to work with the version of the contribution that you are submitting.|
The description you enter here should therefore cover all you need to say. Make it as clear and concise as you possibly can.
Avoid using unnecessary abbreviations that may confuse people and structure your text to assist anyone considering whether to download the item to decide whether
it's what they're looking for.
Use full english sentences to ensure that the description is clear, remembering that english may not be the first language of many of the people reading it.
|Keywords or Key Phrases||
Enter each word or short phrase on each line.
Try to think of words or phrases that people looking for this sort of object are likely to enter into the search field on the search screen.
This can include words describing both what the object represents and the techniques used to implement it.
For example, the 'TheEarth' entry includes the keyphrase 'The Earth' and keywords such as 'Earth', 'Globe', 'Planet', 'Sphere' and 'Image Map'.
You don't need to enter the name or the unique prefix of the object as a keyword. These will be automatically added by the server.
It may however be worth adding variants of the name (plurals or abbreviations/acronymns).
The categories you select from the 'Categories' list will help people to find the files you are submitting when they search the collection.
By carefully selecting the most appropriate categories you can help save other people a lot of time.
You can select multiple categories by Ctrl-Clicking items in the list, but you don't need to select successive categories leading down to a lower-level category because inclusion at a lower level automatically implies inclusion in levels above. For example, adding an object into the 'Computers' category automatically implies inclusion in the 'Household/Office Objects' category.
Note: Occasionally with IE6 in Windows the 'Categories' control freezes and it fails to scroll properly. The cause of this is currently unknown, but minimising the browser window and reactivating it from the Windows taskbar seems to fix the problem without losing information entered into the window.
This is a free text field that will be displayed to those searching the collection. To record any prerequisites you can type into this input field, cut and paste from another application, or use the 'widget' controls next to the text area to load text into the field:
If there are prerequisites that your contribution needs in order to work, please list them, or point to the location of a file identifying those prequequisites (It is best to avoid pre-reqs if possible).
Use the Browse button in the 'Files' input area to select the files that you want to contribute. Clicking the Browse button opens the standard 'Choose File'
dialogue box enabling you to select a single file. Once you've selected a file you will see it appear in the list of files (with a 'Remove' button next to
it. You can repeat this as many times as you like to identify all of the files that constitute your contribution. If you add one by mistake, clicking the 'Remove'
button simply removes it from the list of files to upload.
All file names are converted to lowercase when they are uploaded onto the server to try to cope with operating system differences with respect to case sensitivity in file names.
If you have identified your contribution as being 'Fully Compliant' in the 'Standards Compliance' pull-down, then certain restrictions apply to the file names that you use. All file names for a 'Fully Compliant' submission must be prefixed with either the contribution name or, if you have specified a unique prefix, with that prefix name. This must then be followed either by an underscore ('_') or by a dot/period ('.').
The names XXX_description.txt, XXX_keywords.txt and XXX_prereqs.txt (where XXX is the contribution name or unique prefix) cannot be used for files submitted in the 'Files' input area. These file names are used by the server to generate files based on the description, keywords and prerequisites that you provide in the appropriate input fields. You can however use the 'Browse' buttons next to each of those fields to load text from files with those names into the appropriate input fields.
The following table provides some examples of both valid, standards compliant and invalid or non-standards compliant file names for a contribution called 'Netball' where the optional unique prefix of 'NB' has been specified.
When you submit the contribution, all of the files that you have identified in the list will be sent to the server.
Unfortunately, if your contribution contains errors you will have to select the contribution files again before resubmitting because the file input areas will be cleared by the browser when the page gets re-displayed. There is one exception to this where the only error is that you've forgotten to add the licensing statement to your .pov or .inc files. In this case you can update your files then hit the browser Refresh button, electing to resubmit the form values when prompted by the browser.
|Checklist||The purpose of this collection is to build a set of POV-Ray files that can be freely used, modified and redistributed. In order to be able to achieve this it is necessary that the provenance of anything contributed to the collection is clearly understood and that the person submitting the contribution has the rights necessary to authorise the contribution to be used, modified and redistributed.|
Many errors are picked up in the submission form before it allows you to submi the form. However, if the submission contains errors when you submit it to the server, the server returns you to the submission form and displays the errors at the top of the screen. Most of your responses will still be there, but, unfortunately, once you have corrected the erroneous field, you will need to reselect your files because the browser won't retain the fileIDs in the file input fields. If the only error reported by the server is that you've forgotten to include the licensing statement in your '.pov' or '.inc' files there's a little trick that works in many browsers to avoid having to re-enter the fileIDs. Once you've updated your '.pov' or '.inc' files you should be able to hit the 'Refresh' or 'Reload Current Page' button on your browser tool bar and it will ask you if you wish to resubmit the field values.
If successful the server will display a list of the files you have submitted along with the entry as it will appear on the search panel. Note: If you have provided a thumbnail and a larger image to illustrate your contribution, the thumbnail will provide a hyperlink to the full-sized image. For reasons as yet unknown, from time to time in IE6 under Windows, following this hyperlink opens an empty window. Simply refreshing this window in the browser usually displays the image correctly.