POV-Ray : Newsgroups : povray.object-collection : Contribution Questions : Re: Contribution Questions Server Time
1 Jun 2023 14:52:36 EDT (-0400)
  Re: Contribution Questions  
From: Chris B
Date: 1 Feb 2008 10:47:26
Message: <47a33f0e$1@news.povray.org>
"Blue Herring" <bhe### [at] tinfoilcatcom> wrote in message 
> Hello,
>  I was wondering if there was any guidance available on a couple points 
> when
> contributing to the object collection.  I've got a lot of things that I'd 
> like
> to potentially contribute.  However many of the include files I've created 
> for
> myself are interdependent.  I'm a big fan of modularity and reusability, 
> so if
> a piece of an object or macro can be generalized I'll usually split it out 
> and
> put it into a separate include file (generally organized by category).  So 
> what
> would be a suggested "best practice" for adapting these to the object
> collection?


There are no hard and fast rules because, as you've identified, there are 
natural conflicts that arise, so each case requires a degree of judgement. 
Also, as the collection grows, I expect thinking on this subject to evolve.

My current thoughts are as follows:

1. You can submit a set of objects that are usually used together as a 
single bundle. If you do you should add keywords for all the objects and 
summarise that fact in the description. I don't think that downloading a 
bundle of 10 objects to use only 3 of them is so bad. If you wish you can 
also submit an HTML page with images to describe how the objects are grouped 
and used.

2. If objects can readily be split out and used completely independently 
then it probably makes sense to make separate submissions. You can add notes 
to the description or to an accompanying HTML page to describe how to use 
the objects in combination with other objects from the collection. e.g. I've 
started referencing the ScaleConvert macro from my documentation rather than 
incorporating anything fancy to handle different units.

3. It's also possible to do both and to live with a degree of duplication. 
For example, I've recently been working on a bottle with a label. The label 
turned out more complicated than the bottle, with multiple overlayed 
pigments containing text and images, so I plan to work further on that and 
to also submit a separate label generation macro.

The licensing enables anyone in the future to rearrange the grouping of 
objects to meet the evolving needs of the community. It is possible that, as 
the collection grows, people will combine existing objects into packages, 
potentially with changes to make them work better together. Alternatively a 
single part of a bundle of objects could be split out and developed 

> I don't think just bundling all the dependent files into a big
> lump would be good, when they could easily each be their own submission.
> However, the collection site makes it clear that prerequisites are 
> undesirable,
> so would it be best to duplicate the needed pieces of code for each object
> submitted?  This would lead to much more redundancy, but perhaps that 
> isn't the
> end of the world.

At this stage I'd argue that ease of use is more important than worrying 
about a degree of redundancy. Although the site permits prereqs to be 
listed, I believe that building lists of prereq chains is undesirable 
because it makes it more complicated for people to use stuff.

>  In a similar vein, is there a preference in groupings of objects vs 
> single
> objects?  For example I have (as I'm sure most POVers do) an include with 
> a
> number of basic shapes.  Would it be better to split out each shape into 
> its
> own include, or keep them together as a collection?

A smaller number of files is easier to submit and to maintain, though it's 
logical to split out and group some things separately. If you've got 
something that takes a long time or lots of memory to parse and that isn't 
needed every time, then it's good to split that out. On the other hand, if 
your basic shapes file only takes a tiny fraction of a second to parse then 
it's probably better to include it in a single file rather than have POV-Ray 
open a succession of files when you do want to use more than one shape.

You might also choose to split something out to make it easier to replace or 
to support alternatives.

>  Thanks for any input.
> -The Mildly Infamous Blue Herring

The main things to worry about when preparing objects are the naming 
standards. These are intended to enable people to download different objects 
and use them together without running into naming conflicts which can be a 
devil to sort out in code you've not written.

That's been a bit of a wordy response I'm afraid. Has it been any help?

Chris B.

p.s. It is possible to use the file_exists function to check whether another 
object has also been downloaded and to skip it, or incorporate a simplified 
shape if it hasn't. This is a good way of removing hard-wired 
interdependencies, while enabling people to use objects in combination if 
they already have a copy.

Post a reply to this message

Copyright 2003-2023 Persistence of Vision Raytracer Pty. Ltd.