I see that there is interest in the Object Collection among new users
and old timers who have returned.  You may or may not know that the
Object Collection is a formal repository that was hosted on an entire
subdomain of povray.org, namely lib.povray.org.  Early in 2021 there was
a site-wide server crash, and while most of the site was quickly
restored (mostly), lib.povray.org remains offline.

Most of the user contributions have been mirrored at
  https://github.com/LeForgeron/PovContributions
but the infrastructure of lib.povray.org, which included user
registration, upload, search, and general instructions, is not
duplicated there.

As a formal repository, the Object Collection has certain rules.  If you
wish to submit your objects to lib.povray.org when it comes back online,
you'll need to be familiar with these rules to make whatever edits are
necessary to prepare your files for submission.  I will summarize them here.

The main considerations are the license, namespace compliance, and what
files should be bundled.

TL;DR
-----
- All modules must be licensed under the LGPL.
- All modules have a unique name and an optional unique prefix.
- All filenames and most identifiers must be prefixed with the module
  name or prefix to avoid namespace collisions with other Object
  Collection modules.
- Scene files and include files may contain ASCII only.
- Your submission should include a sample image and a 160x120 thumbnail.

LICENSE
-------
All contributions must be licensed under the GNU Lesser General Public
License (LGPL).  To that effect, every .inc and .pov file must contain a
comment with this text:

  This file is licensed under the terms of the CC-LGPL

This exact wording is required by the upload software; you will not be
allowed to upload your module without it.  The "CC" is due to Creative
Commons having once provided an online deed for the GNU licenses.

If you borrow someone else's work, you will need to certify that you
have the legal right to republish it under the LGPL.

You will note that the above required text does not specify a license
version.  However, the link in the Object Collection documentation
(currently offline) does point specifically to version 2.1 of the LGPL.
No formal decision has been made about upgrading to version 3.0.

MODULE NAMES
------------
Every module has a unique name and, optionally, an additional unique
prefix, which are registered with the upload software.  The names and
prefixes must begin with a Latin letter and comprise only letters and
digits--the same rules as for POV-Ray identifiers, except underscores
are not allowed.  The name and prefix are not case sensitive; for
example, if there is a module called "NetBall," it is not allowed to
create a new module called "NETball."

NAMESPACE COMPLIANCE
--------------------
One of the goals of the Object Collection is interoperability.  The
Collection has naming standards to avoid namespace conflicts between
modules.  Modules are rated for compliance on a scale of 0 (not at all
compliant) to 3 (fully compliant).  By default, only level 3 modules
appeared in search results.

For compliance level 3:

 1. All filenames must begin with the module name or prefix, followed
    by either a dot or an underscore.  This allows all level 3 modules
    to share the same directory, so your Library_Path list doesn't grow
    out of hand.  Filenames should be all lowercase for operating
    system portability.

    For example, if the name and prefix are NetBall and NB,
    respectively, then netball.inc and nb_example.pov are acceptable
    filenames.  netball1.pov and nb-example would not be accepted, as
    the name or prefix is followed by a character other than a dot or
    an underscore.

 2. All identifiers introduced in the main library files must be the
    module name or prefix, or must be prefixed with the module name or
    prefix followed by an underscore.  Due to namespace scope leakage
    within POV-Ray, this rule must also apply to #local identifiers and
    any function formal parameters other than u, v, x, y, and z.  Macro
    formal parameter names are exempt from this rule, as are any demo
    scene description files you may bundle to demonstrate how to use
    your module.

    Using the above example, Netball and NB_BallRadius are acceptable
    identifier names, but NBRadius is not.

 3. A third rule that has been proposed, but not formally adopted, is
    to require all identifiers to have at least one uppercase letter.

The modules are currently self-rated by the author.  If the author rates
their module at compliance level 3, the upload software will reject
filenames that are out of compliance.  Identifiers are not scanned for
compliance at this time.

No detailed guidance has been provided for self-rating your module at
compliance level 1 or 2.

FILES TO BUNDLE WITH YOUR SUBMISSION
------------------------------------
These are not hard and fast rules, but are typical of Object Collection
contributions.

- A .inc file containing the necessary macros and other features.

- An example .pov scene description file demonstrating how to use your
  module.

- A 160 by 120 pixel thumbnail image to be displayed on the Object
  Collection search page and index page.  The name of this file must be
  the module name or prefix, followed immediately by _thumbnail, dot,
  and the image type extension; for example, netball_thumbnail.jpg or
  nb_thumbnail.png.

- A main image file to be linked to the thumbnail.  The name of this
  file must be the module name or prefix, followed immediately by dot
  and the image type extension; for example, netball.jpg or nb.png.

- HTML documentation.  In order to be automatically linked to the Object
  Collection search page and index page, the name of the file must be
  the module name or prefix, followed immediately by .html; for example,
  netball.html or nb.html.

  HTML documentation is optional; many existing contributions just have
  the documentation as a block comment within the main include file.

Files are limited to the following types: .bmp, .css, .csv, .gif, .htm,
.html, .inc, .ini, .jpeg, .jpg, .js, .mac, .mcr, .mdl, .pgm, .png, .pov,
.ppm, .tga, .tif, .tiff, .txt

CONTENTS OF SDL FILES
---------------------
As of the time of the crash, the upload software allowed only 7-bit
ASCII characters in .inc and .pov files.  Greek, Cyrillic, special
characters, etc. could only be used via the "\u" notation.  For an
example of this, see:
  https://github.com/CousinRicky/POV-BrightStar5/blob/main/brightstar5.inc
and find bsc5__s_Gr_chars.

OTHER CONSIDERATIONS
--------------------
There are other considerations, such as keyword list and topic
categories, but these will not be important to detail until the Object
Collection site comes back online.  If you are interested, the upload
instruction page is archived at:

https://web.archive.org/web/20150923194204/http://lib.povray.org/usersguide/04contributing.html

Note that these instructions have an incorrect name for the license.
The name has been corrected since that page was last archived.

ADMINISTRATION
--------------
The initial administrator of the Object Collection has not been heard
from since 2009, and there has been no successor.  So far as I can see,
there is no formal process in place for overseeing the collection.  See
the thread "License reassessment and other matters" for my thoughts on
this situation.

Post a reply to this message

I have additional comments on these rules.

On 2023 21:37 (-4), Cousin Ricky wrote:
> 
> LICENSE
> [snip]
>   This file is licensed under the terms of the CC-LGPL
> 
> This exact wording is required by the upload software; you will not be
> allowed to upload your module without it.  The "CC" is due to Creative
> Commons having once provided an online deed for the GNU licenses.

Creative Commons has since removed the deed from their website, and the
link now redirects to gnu.org.  It has been proposed that the "CC" be
removed, but the upload software had not been updated to accept this as
of the time of the crash.

> NAMESPACE COMPLIANCE
> [snip]
> 
>  2. [snip]  Due to namespace scope leakage
>     within POV-Ray, this rule must also apply to #local identifiers and
>     any function formal parameters other than u, v, x, y, and z.
> [snip]
> 
> The modules are currently self-rated by the author.  If the author rates
> their module at compliance level 3, the upload software will reject
> filenames that are out of compliance.  Identifiers are not scanned for
> compliance at this time.

Note that identifier name collisions are possible even with modules
self-rated at level 3.  There was some sort of process for verifying
compliance, the details of which I do not know, but the only modules so
"verified" happen to have been submitted by the administrator
himself--in other words, *none* of the modules can be considered
verified.  As my father once told me, "A priest does not hear his own
confession."

I am very careful about keeping my own contributions level 3 compliant,
yet I have discovered noncompliance in my own code.  To my knowledge, no
one has independently verified my modules, so there could still be some
stray violations.  And I know for a fact that some other contributors
have been less diligent than I.  Caveat emptor.

Add to this, that the scope leakage of #local variables was not
discovered until about 50 modules had already been contributed, so many
of those were rendered de facto non-compliant when the rule was changed.
 Thus far, function formal parameters are not specifically addressed in
the Object Collection rules, but these newsgroups are scattered with
POVers who have been burned by using an identifier that just *happened*
to share a name with a function parameter in some include file.  Caveat
emptor.

LeForgeron's mirror does not record the compliance level of the modules,
but from the information I had collected previously, all of the
contributions were self-rated at level 3 except for the following:
ConvexLens, TextureGen, and TextureGen4.  These 3 modules should *not*
share a directory with other Object Collection downloads.  Two other
modules were once self-rated as non-compliant, but they have since been
edited into full compliance.  All remaining modules are fully filename
compliant, and may share a single directory, even if their identifiers
are not compliant.  All this is to say that you'll probably want to make
your contributions namespace compliant as well.

> CONTENTS OF SDL FILES
> ---------------------
> As of the time of the crash, the upload software allowed only 7-bit
> ASCII characters in .inc and .pov files.

I hope this will change.

Post a reply to this message

hi,

Cousin Ricky <ric### [at] yahoocom> wrote:
> ...
> a site-wide server crash, and while most of the site was quickly
> restored (mostly), lib.povray.org remains offline.
> ...

for now, yes.  however, it "is being looked at".


> The initial administrator of the Object Collection has not been heard
> from since 2009, and there has been no successor.  So far as I can see,
> there is no formal process in place for overseeing the collection.  See
? the thread "License reassessment and other matters" for my thoughts on
> this situation.

I share the impression that the OC has been handled without such a laid down
procedure/process.  quick scan in 200 most recent threads did not find the
above, will try find/read it.  thoughts on how (future) administration
can/should be made more "robust" will be useful/appreciated (but see below).


> LeForgeron's mirror does not record the compliance level of the modules,
> but from the information I had collected previously, all of the
>  contributions were self-rated at level 3 except for the following:
> ConvexLens, TextureGen, and TextureGen4.  These 3 modules should *not*
> share a directory with other Object Collection downloads.

thank you.  will look at the "self-rated" vs confirmed.


> As of the time of the crash, the upload software allowed only 7-bit
> ASCII characters in .inc and .pov files.

ok, thanks.  will add some utf8 to the "mock" object I use while working on
submission.

fyi.  since the crash, no one had (apparently) offered help restoring it (Chris
is .. running at capacity much of the time, aiui), so late last year I jumped
in.  fwiw, it (site code) is an excellent example of why code ought not be
"intertwined" with global variables.  anyway, there were[*] other, real problems
regarding the database, it seems that at least one of those with admin access
missed their calling as comedian. :-(  it seemed opportune to move the OC db
from the server-based implementation to a file-backed one, without changes to
the UI as such (except fewer admin options).  the current state of things: a
fair few things done, but more still to do.  (sorry to be so .. oblique)

[*] and, to an extent, continue to be.  would, personally, prefer the db schema
fully normalised, but cannot afford to break the Javascript + stuff.

admin changes - little from the web UI, only suspending versions/users/feedback
and "health check", for all else person will have to log in to an admin account,
and use utility(-ies) provided.


regards, jr.

Post a reply to this message

On 03/03/2023 04:37, Cousin Ricky wrote:
> I see that there is interest in the Object Collection among new users
> and old timers who have returned.  You may or may not know that the
> Object Collection is a formal repository that was hosted on an entire
> subdomain of povray.org, namely lib.povray.org.

Hi,
Thank you for this review, I really didn't know about the formal side of
this group. Now I see that this is the wrong place for my previous
posts, sorry for the inconvenience.
--
YB

Post a reply to this message

hi,

Cousin Ricky <ric### [at] yahoocom> wrote:
> I have additional comments on these rules.
>
> On 2023 21:37 (-4), Cousin Ricky wrote:
> >
> > LICENSE
> > [snip]
> >   This file is licensed under the terms of the CC-LGPL
> >
> > This exact wording is required by the upload software; you will not be
> > allowed to upload your module without it.  The "CC" is due to Creative
> > Commons having once provided an online deed for the GNU licenses.
>
> Creative Commons has since removed the deed from their website, and the
> link now redirects to gnu.org.  It has been proposed that the "CC" be
> removed, but the upload software had not been updated to accept this as
> of the time of the crash.

so what, exactly, are/ought-to-be the implications?  the submission as such, and
aiui, would still require some form of (permissive) licensing by the author(s).
what, ideally, would the check upon upload look for?


regards, jr.

Post a reply to this message

On 2023-03-05 03:31 (-4), jr wrote:
> Cousin Ricky <ric### [at] yahoocom> wrote:
>> I have additional comments on these rules.
>>
>> On 2023 21:37 (-4), Cousin Ricky wrote:
>>>
>>> LICENSE
>>> [snip]
>>>   This file is licensed under the terms of the CC-LGPL
>>>
>>> This exact wording is required by the upload software; you will not be
>>> allowed to upload your module without it.  The "CC" is due to Creative
>>> Commons having once provided an online deed for the GNU licenses.
>>
>> Creative Commons has since removed the deed from their website, and the
>> link now redirects to gnu.org.  It has been proposed that the "CC" be
>> removed, but the upload software had not been updated to accept this as
>> of the time of the crash.
> 
> so what, exactly, are/ought-to-be the implications?  the submission as such, and
> aiui, would still require some form of (permissive) licensing by the author(s).
> what, ideally, would the check upon upload look for?

I am not proposing that we move away from the LGPL.  I'm thinking that
the upload software could accept "GNU-LGPL" as well as "CC-LGPL," that
the phrase "Creative Commons" be dropped from the documentation on
lib.povray.org, and that the documentation link directly to gnu.org.
But as long as the Creative Commons link redirects to gnu.org, this is
not a major issue.

Post a reply to this message

On 2023-03-02 21:37 (-4), Cousin Ricky wrote:
> 
> There are other considerations, such as keyword list and topic
> categories, but these will not be important to detail until the Object
> Collection site comes back online.  If you are interested, the upload
> instruction page is archived at:
> 
>
https://web.archive.org/web/20150923194204/http://lib.povray.org/usersguide/04contributing.html
> 
> Note that these instructions have an incorrect name for the license.
> The name has been corrected since that page was last archived.

I got some files mixed up in my mind.  The README file that comes with
each download has been updated.  I cannot tell if the instructions have
been updated.

Post a reply to this message

hi,

Cousin Ricky <ric### [at] yahoocom> wrote:
> >>> LICENSE
> >>>
> I am not proposing that we move away from the LGPL.  I'm thinking that
> the upload software could accept "GNU-LGPL" as well as "CC-LGPL," that
> the phrase "Creative Commons" be dropped from the documentation on
> lib.povray.org, and that the documentation link directly to gnu.org.
> But as long as the Creative Commons link redirects to gnu.org, this is
> not a major issue.

after a cursory look at the code, I think the upload could be modified to accept
either with little work.  re the whole issue, decisions are for Chris, will
bring it up at the earliest opportunity.


regards, jr.

Post a reply to this message

hi,

Cousin Ricky <ric### [at] yahoocom> wrote:
> ...
> The main considerations are the license, namespace compliance, and what
> files should be bundled.
>
> TL;DR
> -----
> - All modules must be licensed under the LGPL.
> - All modules have a unique name and an optional unique prefix.
> - All filenames and most identifiers must be prefixed with the module
>   name or prefix to avoid namespace collisions with other Object
>   Collection modules.
> - Scene files and include files may contain ASCII only.
> - Your submission should include a sample image and a 160x120 thumbnail.

the GNU/CC licensing and the ASCII only issues have been mentioned, and, final
decision pending, will be acted on.  there is one new, added requirement now:
the descriptive text, ideally including documentation and scene/.inc file
comments, is expected to be in English.

the reason is a legacy of several dozen objects submitted in Spanish, only.
those will likely remain unavailable until translated.  (any native speakers, or
fluent + conversant with Central American cultures, with a little time on their
hands ?  ;-))


> ConvexLens, TextureGen, and TextureGen4.  These 3 modules should *not*
> share a directory with other Object Collection downloads.  Two other
> modules were once self-rated as non-compliant, but they have since been
> edited into full compliance.  ...

so, in the "legacy" data for TextureGen I see three versions, with the following
'standardsconformance:status' values recorded (in order): 3:2, 0:1, 1:1.  :-(

seems to me that when an administrator assesses an object / version for
compliance, all versions need taking into account, and there should only be "one
score", per object ?

(if you have a "private" list of assessments of various contributions, that
could (perhaps) serve as base going forward (o/wise most of the db's content
will remain "self-assessed"))


regards, jr.

Post a reply to this message

hi,

"jr" <cre### [at] gmailcom> wrote:
> Cousin Ricky <ric### [at] yahoocom> wrote:
> > ...
> > The main considerations are the license, namespace compliance, and what
> > files should be bundled.
> > ...
> the GNU/CC licensing and the ASCII only issues have been mentioned, and, final
> decision pending, will be acted on.  ...

the licensing mention/requirements have been updated, the text only uses 'GNU',
and files can be submitted with either 'GNU-LGPL' or 'CC-LGPL.'

the remaining item (another request for help :-)) is replacing the
'cc-LGPL-a.png'; would appreciate if you could suggest (locate! :-)) a suitable
file; same  WxH, and ideally monochrome (the latter just a personal preference).
 tia.

elsewhere you wrote:
> I have updated the procedural wood texture I used for my hand plane,
> prepared it for the Object Collection when it comes back online ...

currently faced with .pov etc files having different mimetypes/'signatures' if
they include utf-8.  to (mis)use Leroy's phrase: 'Have Fun!' </grin>


regards, jr.

Post a reply to this message