Darren New wrote:
> When I did this sort of thing, I allowed "keywords" and "topics". 
> "Topics" were chosen from a list the administrators created, while 

I'd go with both too. The main criteria however is that a good search
function enables users to find what they want more or less instantly, and
that would require good keyword selection. Inevitably there will be the need
for some admin work to clean up/add keywords and arrange categories.

-- Chris

Post a reply to this message

Randall Sawyer wrote:
> What if the contents of each include file be strictly limited to ONE
> macro/object or ONE class of macros/objects/textures/etc?  Furthermore,
[snip]

I'm inclined to go along with this, at least for macros/objects.

If the macro/object requires any other includes, they would be listed as
dependencies. If it doesn't want to depend on another include for some other
macro that the author already has but doesn't want to go to the trouble of
releasing separately, then that macro (or declarations, or whatever) must be
local to the file and not visible from outside, so as to not pollute the
namespace and potentially cause collisions.

-- Chris

Post a reply to this message

Charles C wrote:
> I want to verify what we're doing here...  What will be downloadable?  I
> thought we were laying the groundwork for a future single(yet
> versionable/growable) package containing the entire library of things
> people contribute.  If I have that right, the website can/could be

My ten cents: things are downloadable separately. Perhaps in groups as well.

The site could be smart enough to provide you links to dependencies of
something you download, too, and possibly (if we hook it up to the POV-Ray
user registration system) keep track of what you download and only offer the
downloads of dependencies you don't already have.

If this collection gets to be quite useful we need to consider the
possibility that at some point, integration with some POV platform user
interfaces could happen; for that, it definitely needs to support retrieval
of individual files.

-- Chris

Post a reply to this message

Chris, thank you for your enthusiastic support for the idea.  I think indeed
exciting bright times are ahead for povray and the povray community! :)

Post a reply to this message

Chris Cason wrote:
> If the macro/object requires any other includes, they would be listed as
> dependencies. If it doesn't want to depend on another include for some other

Come to think of it, tracking dependencies would probably be important for
versioning too - e.g. if 'abc.inc' only works with version 1.1 of 'def.inc'
then we either need to provide links to the older version of 'def.inc', mark
'abc.inc' as broken, or attempt to have some sort of backward-compatibility
standard.

Personally, I feel that apart from the case of bug fixes, if an include file
in the standard portion of the library needs to be changed in such a way that
it would adversely affect other files that use it (where such use is done
according to the documented interface), there should be some attempt made to
keep the old behaviour and provide the new behaviour only to files that
expect it (i.e. have been written to use the new feature).

-- Chris

Post a reply to this message

Randall Sawyer <sra### [at] yahoocom> wrote:
> What if the contents of each include file be strictly limited to ONE
> macro/object or ONE class of macros/objects/textures/etc?

  I would say that if the feature is prominent and quite stand-alone
(such as eg. a lens-flare effect) then it should be in its own file,
but some files can contain a collection of similar features (math.inc
and functions.inc are good examples of this).

-- 
                                                          - Warp

Post a reply to this message

in news:456ec72e@news.povray.org Chris Cason wrote:

> Randall Sawyer wrote:
>> What if the contents of each include file be strictly limited to ONE
>> macro/object or ONE class of macros/objects/textures/etc? 
>> Furthermore, 
> [snip]
> 
> I'm inclined to go along with this, at least for macros/objects.

I think it will be restrictive quite soon when working on complex 
includes.

>[...] If it doesn't want to depend on another include for
> some other macro that the author already has but doesn't want to go
> to the trouble of releasing separately, then that macro (or
> declarations, or whatever) must be local to the file and not visible
> from outside, so as to not pollute the namespace and potentially
> cause collisions. 

how about the possibility of including 'packages' of includefiles. Think 
for example of Jaime's lightsys. It consists of several files and lots 
of macros and data. Now if we could just '#include lightsys' and in one 
go include all files in the directory /lightsys and put them all in the 
lightsys namespace, the potential of collisions gets a lot less. I'm not 
good at explaining this so maybe have a look at how Python deals with 
standard and third party libraries and namespaces. It's done very user 
friendly.

#include MMMM  (a library (directory) consisting of 7 includefile 
sharing a lot of code)

object { 
   MMMM.Parametric (
     function(u,v){R*sin(v)*cos(u)},
     function(u,v){R*cos(v)},
     function(u,v){R*sin(v)*sin(u)}
     <0, FromV(0)>, <pi, 2*pi>,
     20, 10, ""
   )
   pigment {rgb 1}
   finish{specular 0.3}
 }

Ingo

Post a reply to this message

ingo <ing### [at] tagpovrayorg> wrote:
> #include MMMM  (a library (directory) consisting of 7 includefile
> sharing a lot of code)
>
> object {
>    MMMM.Parametric (
>      function(u,v){R*sin(v)*cos(u)},
>      function(u,v){R*cos(v)},
>      function(u,v){R*sin(v)*sin(u)}
>      <0, FromV(0)>, <pi, 2*pi>,
>      20, 10, ""
>    )
>    pigment {rgb 1}
>    finish{specular 0.3}
>  }


oh!  I'd certainly love proper foo.bar style of accessing containers member
rather than the one in my proposed alias:

#include "foo.inc" #as MMM

object { MMM_Parametric(...) }...

Except i feel the latter should be simpler to implement in the povray parser
with a few rewriting rules...

Post a reply to this message

This thread contained quite a diverse range of ideas and has been quite 
difficult to summarize. This is a first attempt to summarize it, so feel 
free to chip in if you think I've overlooked something or made mistakes.

I've tried to incorporate the ideas raised into a description of how the 
collection could potentially work (a sort of specification). It's a bit 
long, so I've tried to break it up to enable you to focus in on the bits 
that most interest you.

Please comment on whether you think the following scenarios seem reasonable:

The Plan is to create a collection of  objects, textures and include files 
contributed by the POV-Ray community on povray.org.

Organisation
-------------
The site would be split into two main parts with (1) an 'ad-hoc' area for 
new submissions and (2) a 'standard' area where contributions adhere to 
certain standards and to a common licensing structure. There would be no 
visible hard-wired hierarchy of directories within these areas, but there 
would be (potentially multiple) logical categorisations available alongside 
indexing information (Keywords) supplied by the contributor. One form of 
categorisation could potentially cover topics like 'Space Hardware' and 
'Landscapes' whereas an alternative form of categorisation could cover 
contribution types, such as 'Component', 'Finished Object', 'Texture', 
'Utility Macro' etc.

The povray.org server may use an internal directory structure to manage 
versioning or other aspects of the collection, but this structure would not 
be visible to users and would not be present on the user's local machine 
once the files have been downloaded.

Submitting Contributions
------------------------
Contribution Name - To submit a contribution through the povray.org web 
site, you would first enter a name or a unique ID for your contribution.
Povray.org would search its index for that identifier.
If it's a new submission and the name is already being used, you will need 
to pick a different one.
If you intend to supersede an existing contribution you will need confirm 
that and will need to 'version' your contribution - See 'Provenance' below.

Keywords - You will need to associate keywords with the contribution so that 
people can find it through the search facility. You could be given the 
option of either submitting a file containing keywords or typing them into a 
list on the submission page, in which case the server would create the file. 
In both cases povray.org would incorporate the keywords into a machine 
readable index for use by the search facility.

Categories - You will be prompted to select one or more categories for the 
contribution. For example, a chair object could go into the Topic-based 
categories 'Household Objects' and 'Business Furnishings' and into the 
'Completed Objects' category within the Contribution-Type-based categories.

Standards Compliance - You would also indicate whether you believe your 
contribution conforms to the standards necessary to become eligible for 
promotion into the 'standard' area.

Dependencies - If the contribution has dependencies (is dependant upon 
another contribution already in the collection), you will also needs to 
identify those dependencies. As was alluded to earlier in this thread, if we 
build large lists of dependencies it becomes difficult to keep them up to 
date and to retain forward and backward compatibility as new versions of a 
contribution are added. If you write a macro that works with your objects, 
it may be safer to bundle it all together in a single contribution and 
accept that if someone wants to use it elsewhere that they'll copy it. I 
think this is one of those issues we can most appropriately handle in a 
'best-practices' tutorial once we see how this all works out.

Pre-Requisites - If your contribution has any pre-requisites you'll need to 
describe them, for example, if the contribution requires a certain version 
of POV-Ray or if there are operating system or other software dependencies 
(e.g. Use of Windows bmp format, Perl scripts, Modellers).

Description/Comments - For new contributions, you should provide a brief 
description of the contribution. If updating the contribution, you could 
optionally modify the existing description and potentially add update notes.

Server-Side Checks - The server would check that all of the file names in a 
submission are prefixed with the contribution name or some form of 
standardised prefix.
The server checks that any required files are present and accepts the 
submission, adding indexing and category information into the search 
facility and storing the files in the 'ad-hoc' area. A submission may be 
required to include a rendered image of the object at a standard size, 
documentation etc. but we'll cover that in detail in the standards thread. 
The server may perform tasks such as generating a thumbnail image from the 
submission, either from the larger image or using some sort of standard for 
rendering the contribution.

Collaborative Developments
----------------------------
Although many of the contributions could be objects contributed by a single 
author, it is also possible to foresee more collaborative developments where 
many people are updating a set of files. I think that groups working on such 
projects will need to coordinate themselves and to establish who will manage 
releases of the contribution into the collection. Such projects could 
involve development using a check-out/check-in strategy, but this would be 
managed outside of the collection using a code repository such as CVS, a 
service such as Sourceforge or some other mechanism selected by that team.

Provenance (Origin)
------------
The intention is to encourage the evolution of contributions by future 
contributors, so we need a way of accepting new versions of a contribution. 
However, we run into an issue of divergency, where two separate modification 
streams could be taking place at the same time.

I would suggest that the easiest way of dealing with this is to incorporate 
the a contributor prefix (the authors initials or tag) into the version 
number and have a place on the submissions page where the contributor can 
indicate the version that the changes are based on. If the contributor is 
registered and logged in they can use their ID in the version number. If the 
contributor is not logged in they would need to add a number each time to 
make their tag unique.

If contribution hierarchies get overly complex for a contribution then 
someone would need to sort it out. This is most likely to occur with a 
contribution where many people from the POV-Ray community have shown an 
interest, so hopefully, getting someone to put in the time to sort it out 
should be a viable option.

Finding and Downloading Contributions
----------------------------------------
The collection would be available to anyone with an Internet connection 
using a standard browser by accessing the appropriate page on the povray.org 
web site. If you have chosen to register as a POV-Ray community member you 
could have the option of logging in, which will enable the povray.org server 
to provide you with a couple of extra features (previous download lists 
etc).

Searching - You would be able to search for contributions by some 
combination of contribution name, author name, one or more category 
structures or by keyword. Multiple versions of a contribution could 
potentially be present in the collection. The most recent version would 
normally be displayed, but you could go into a 'detail' page that would list 
the version hierarchy and enable you to select an alternative version of the 
contribution.

Standards Compliance - Some means will be used to indicate whether a given 
version has been accepted into the 'standard' area. If it hasn't, the server 
could indicate whether the contributor considered that it conforms to the 
standards and has accepted the common license. Otherwise the server could 
indicate that it's an 'ad-hoc' contribution. Maybe we could use a sort of 
'traffic lights' type system.

Dependencies - An indication will be given to show dependencies on other 
contributions within the collection and an option could be provided to 
either link through to those items, or some mechanism could be provided to 
follow dependency chains and add the contribution and all of its 
dependencies to the 'download list' (see next paragraph).

Download Lists - When you find a contribution you like, you can either 
download it from the list or add it to a 'download list' similar to a 
shopping basket concept for online shops. A button on the page would enable 
you to add all items from the current selection to your 'download list'. If 
building a 'download list' you could go to your list and remove items. Once 
happy with your list you can download a zipped archive containing the files 
selected.

Value Added Features - If you register with povray.org and choose to log-in, 
the server may be smart enough to keep track of what you have previously 
downloaded so that it can indicate which contributions you already have and 
could list any contributions that have been updated since you last 
downloaded them (would require some hooks into the POV-Ray registration 
system).

Future enhancements could include downloadable indexes that could be used to 
link into platform specific user interfaces to support retrieval from the 
editor (e.g. from the 'insert' menu).

Promotion into the 'standard' area
----------------------------------
If the contributor has accepted the common licensing terms and has complied 
with the required standards, their work will be eligible for inclusion in 
the 'standard' area.

Depending upon the complexity of the standards agreed upon, it may be 
possible to automatically verify that some or all of the standards are 
satisfied. For more complex standards or for more complex contributions it 
may be necessary for a group of volunteers to go through and verify 
conformance to the required standards before registering the contributions 
for inclusion in the 'standard' area. I think we're agreed that we would 
like to keep manual maintenance tasks to a minimum.

Once a contribution has been accepted into the 'standard' area, users will 
be able to identify that fact when they come across that contribution in the 
collection (a special icon or something).

Other Stuff
-----------
There was a discussion on the subject of whether we have one file per 
object/macro or whether we support more sophisticated bundles/packages. I 
believe the conclusion was that prominent and quite stand-alone items should 
be in their own file, collections of similar features could be in a single 
file and more complex packages of files could be bundled together. Imposing 
some over restrictive rule on this could reduce the potential for the 
collection.

My view is that supporting archives of files that work together would be a 
good thing. Given the licensing conditions the exchange of  ideas could go 
both ways. Someone could take individual contributions and build them into a 
package using a standardised scale, standardised parameters and consistent 
documentation etc. Someone else could picking macros and other pieces out of 
packages and create more generic, standalone utilities out of them. I would 
foresee a smaller number of the larger packages, so it might be possible for 
those to be expanded into separate directories on the user's machine without 
hitting the 20 library path limit mentioned in the help (Charles indicated 
25, is this OS dependant?). This could maybe permit naming conventions 
within the archive to be relaxed avoiding large amounts of rework on 
existing packages.

There was a discussion about automatic renaming of contributions. I 
personally use some animation features to build the names of include files 
dynamically and I'm not sure whether we could do anything that could 
reliably update everyone's file references without risking breaking them 
beyond repair.

'Value-Added' features like "most downloaded", ratings, etc. could be added 
as time permits.
We could also implement the features described above in two phases, getting 
started with the 'ad-hoc' area and initially relying on contributors to 
assess their own contributions. We could potentially introduce the more 
formal 'standard' mark of approval at a later stage, once we can assess how 
much work/interest is generated.

Ben suggested the following categories as a starting point for a 'type' 
based categorisation:
- Textures
 o Pigments
 o Finishes
 o Normals
- Interiors
 o Media
- Shapes
 o Solid (CSG-able)
 o Non-solid (Non-CSG-able)
- Functions
 o Isosurface
 o Positioning
 o Other

I'll propose the following starting point for a 'topic' based 
categorisation:
- Household/Office Objects
- Buildings
- Landscapes
- Vehicles
- Space
- Organic Forms
- Abstract Forms


Regards,
Chris B.

Post a reply to this message

457d907f@news.povray.org...

> Ben suggested the following categories as a starting point for a 'type' 
> based categorisation:
> - Textures

(These threads are long so please ignore the following if already discussed)

IMHO it should be possible to add resource materials that are not made of 
POV-Ray SDL.

Bitmaps textures (simple or HDRI) are the more obvious case - bitmaps are 
often part of packaged scenes or objects -, but other stuff could go there 
too, including non-SDL models (think Wings or Blender models), packaged 
tutorials, BVH files, little software utilities etc. I realise that this 
opens another can of worms, but this is done in other 3D communities, and 
lots of people have non-SDL material to offer.

The fact that non-SDL goodies could be used by users of other software may 
be a good thing (more public exposure for POV-Ray and its community) or not 
(extra server load, more potential license troubles since non-SDL goodies 
are likely to have a higher commercial value than SDL ones).

G.

Post a reply to this message