Charles C wrote:
> pressed to find a single standard that won't turn most people away.  So,
> I'd lean more towards guidelines, and tutorials on how to make #includes
> "nice," kinda like what Chris B was talking about.

Here's an option:

Have two sections of the library: the 'standard', and the 'ad-hoc' one.
Everything goes into 'ad-hoc' to start with, until an administrator checks
it. If it meets the standard, it goes into the standard area. If it doesn't,
it either (a) stays in ad-hoc, (b) gets wrapped (see below) and moved into
standard, or (c) gets deleted.

Given a license that permits modifications or derivative works, if a macro is
good enough that it really should be in the standard area, but the author
didn't do it for some reason, a volunteer could encapsulate it within a
standards-compliant wrapper. Presuming support for some sort of private
namespace (or the equivalent thereof) is available, this would not always
require going though the entire file line by line.

Also I will mention that it is possible we could have a parser that reads SDL
and re-writes it according to a set of rules. I'm not about to volunteer to
do this but consider it as one possible means of handling issues that might
otherwise require run-time support within the distributed POV-Ray.

-- Chris

Post a reply to this message

FWIW I'd suggest some of you investigate how the Perl folks have handled
this, since they've gone through some of the same issues. While it is for
example possible to include a file into a perl program just like we do with
#include, they have another concept called 'modules' which covers some of the
issues here, plus some others that we haven't covered yet (e.g. modules can
be self-documenting). See:

  http://en.wikipedia.org/wiki/Perl_module.
  http://stein.cshl.org/genome_informatics/chervitz/perl-modules/

-- Chris

Post a reply to this message

"Charles C" <nomail@nomail> wrote:
> I think it all depends on what we're building here.  Something like a
> professonal product containing the best of the best, or a community effort
> containing some things that might not be as up-to-snuff as others.
> ...
> I'd lean more towards guidelines, and tutorials on how to make #includes
> "nice," kinda like what Chris B was talking about.

Chris Cason <del### [at] deletethistoopovrayorg> wrote:
> Have two sections of the library: the 'standard', and the 'ad-hoc' one.
> Everything goes into 'ad-hoc' to start with, until an administrator checks
> it. If it meets the standard, it goes into the standard area.

I like the direction in which this discussion is heading.

My personal preference is for #macro includes with a parameter each for size
or texture-density where appropriate.  I just got done rewriting my personal
includes, eliminating all #declares.  My headers now have two new lines:

// Manifest: #macro_1, #macro_2, ...
// Dependencies: "file_1.inc", "file_2.inc", ...

BTW: I'm more of a hands-on learner.  So, this exercise served to inform me
better in participating in this discussion.  It is not my intention to
promote my personal standard.  I share it only as an example.

I would still like to promote my "scene ruler" #macro-generated objects for
use by the 'ad-hoccers' who want to make their textures and such available
via #declares (assuming we do end up with an 'ad-hoc' area).

Also, I'd be happy to help with the tutorials.

-Randall

Post a reply to this message

Chris Cason <del### [at] deletethistoopovrayorg> wrote:
> FWIW I'd suggest some of you investigate how the Perl folks have handled
> this, since they've gone through some of the same issues. While it is for
> example possible to include a file into a perl program just like we do with
> #include, they have another concept called 'modules' which covers some of the
> issues here

Chris, i guess having proper lexical scoping helps a lot in getting true
module/package/unit/namespace...

The SDL right now just has global variables and per-file local variables.
Macro "local variables" seem like they are really just copied verbatim to
the location where the macro was followed, thus becoming local to the
callee file.  Macros are indeed a strange mix of C preprocessing macros and
procedures/functions...

Still, i guess its too costly for a change right now, so i think we'd better
deal with it for a while -- hey, C is still around! -- and see what we can
do with this limitation in mind.

>, plus some others that we haven't covered yet (e.g. modules can
> be self-documenting). See:

talking about it, code is the best document there is! :)

Post a reply to this message

Chris Cason wrote:

> [Chris B]
> 
>>>For example, using #local in include files wherever you don't need to expose
>>>them externally.
> 
> 
> Overall I am strongly in favor of some system whereby the only things exposed
> from a specialized object or macro include file are those things the author
> intends to expose, that is, by explicit declaration. C++ uses namespaces,
> perl uses modules, other languages have their own ways; whatever, the point
> is intelligent management of exposed symbols.
> 
> [nemesis]
> 
>>i just wish #local would also be local to macros.  oh well...
> 
> 
> Recall I mentioned changes to SDL are possible. Not necessarily the above,
> perhaps, but something that gives us the same effect. Basically if enough of
> you think it's needed, tell me and we'll give it some thought. Some things
> might not be possible with the current parser but we'll at least consider it.

Keeping it simple is a must.

Namespaces are probably the best way.  Ideas:

* #namespace LABEL creates the namespace LABEL if it doesn't already 
exist.  Whether new or not, namespace LABEL becomes the active namespace 
(the former namespace is saved on a stack).

* #namespace undef pops the current namespace off of the stack, and the 
former namespace becomes active.

* All #declare and #local statements affect the variable in the current 
namespace.  Other variables of the same name in other namespaces are not 
affected.

* #declared variables live from one invocation of the namespace to the 
next, but #labeled variables die when the namespace passes out of scope 
(end of macro, end of file, popped by #namepsace undef statement).

* The arguments of a macro are, within a macro, always in scope, 
regardless of the active namespace.

This way if I write a set of macros for simulating physics (called the 
Phony Physics Pholio), I can put

   #namespace Phony_Physics_Pholio

at the start of every macro, and thereby minimize conflicts with other 
macros sets by other authors.

Regards,
John

Post a reply to this message

John VanSickle wrote:

> Chris B wrote:
>
>> As Sabrina has mentioned, there are certain standard ways of doing 
>> things that can help us to construct #include files that will work 
>> together and also minimise compatibility issues with future versions 
>> of POV-Ray. For example, using #local in include files wherever you 
>> don't need to expose them externally. Also starting variable names, 
>> macro names etc. that are exposed with an upper case letter to avoid 
>> potential conflicts with future POV-Ray keywords.
>
>
> This is something that C/C++ programmers (and others as well) know: 
> Don't use globals unless you really, really have to.
>
>> I think Sabrina's idea of using a unique prefix for names is a good 
>> one and I've used this in the past, for example, all POV-Stairs 
>> variables exposed externally start with SC (for StairCase). 
>> Interestingly I started using PS but found that someone elses include 
>> file used PS. Nevertheless, because it was standard I could do a case 
>> sensitive global change and was able to quickly change all my PS's to 
>> SC's. The lesson here is that using a standard makes life easier than 
>> not using a standard, even if the detail needs to change.
>
>
> I already do this with my Subdivision Surface macros; everything 
> starts with SSS or sss.


Just some ideas from my personal coding standards...

I make all #declared items uppercase with a three-letter descriptive 
suffix; anything in an #include file gets a two- or three-letter prefix 
as well.  For example, a weathered oak texture in the hypothetical 
Outhouse.inc file would become OH_WEATHERED_OAK_TEX, a corncob would be 
called OH_CORNCOB_OBJ, and so on.  #local items are similar, but with 
upper- and lower-case:  BoardShapeObj, CorncobLength, and so on.  A 
#macro would be named something like macOH_MakeCorncob.

Any macro is preceded by a nice comment box, along the lines of...

////////////////////////////////////////////////////////////////////////
//  macOH_MakeCorncob--Creates a corncob to be placed in the corncob box
//    in the "Outhouse" project.
//
//  Parameters:
//    CorncobLength   = Float; length of corncob.
//    CorncobDiameter = Float; diameter of corncob.
//    TrimEnds        = Boolean; true  = ends of corncob are trimmed
//                               false = ends are untrimmed
//                               default = false
////////////////////////////////////////////////////////////////////////

...and gets an  "// end macOH_MakeCorncob" comment at the end.

(Yes, I know it's a silly example  ;)  I also tend to do things like 
naming a function to create a pink pigment PinkPigFun.  And so on.  I 
just can't help myself.)


>
>> Florian raised the point that having a standard for sizes and names 
>> can make it less likely that someone put's his 
>> objects/textures/whatever in the collection, because it's too much 
>> hassle. Maybe a solution to this is that we document a standard, but 
>> don't insist people use it. We could have an indicator on the web 
>> site to show whether a particular submission adheres to the standard. 
>> This would also enable older and non-compliant files to still be 
>> published, but users would be forewarned about maybe having to sort 
>> out conflicts. From time to time we could drive campaigns to help 
>> standardise the most popular and well-used materials.
>
>
> Probably the biggest issue is that while many people around here use 1 
> unit = 1 meter, others (such as I) use 1 unit = 1 cm for most scenes.
>
> This is probably best addressed with a simple line at the start of the 
> macro or scene file:
>
> // -- uses centimeter scaling
>

I wonder if some sort of generic unit conversion code might be posted on 
the site, to allow coders to use the units they find most appropriate, 
while simplifying end-users' ability to mix-and-match #include files...?


>> On the subject of Object Diversity I think we could probably come up 
>> with some best practices that would help people to write #include 
>> files in a parametrised way that permits people using the file to 
>> readily adjust as much as possible. For example, using #ifdef() 
>> before #declare inside the #include file helps someone to override 
>> default settings within their scene file. Rather than writing that 
>> sort of thing into our standards, I would propose that we assemble 
>> (or reference if some already exist) a few tutorials that illustrate 
>> how to build include files that enable a diverse range of objects to 
>> be generated.
>
>
> Well, I use an #ifndef-#local-#end block, and it works fine.  My robot 
> models have a default texture for different things; in fact, there is 
> also a BotGender variable that specifies which of two defaults gets used.
>
> And we can put code in the #ifndef-#local-#end block to detect if any 
> of the defaults are changed, and print out "Use some imagination!" if 
> none of them are changed :-)
>
> Regards,
> John


I use a block like...

#ifndef "_MyInclude"
  #include "MyInclude.inc"
  #declare _MyInclude = 1 ;
#end

...to avoid re-#including files in big projects with lots of #includes, 
and things like...

#ifndef "_TestMode"
  #declare _TestMode" = false ;
#end

...to set global parameters.  I imagine everybody has a collection of 
these code snippets to share.

--Sherry Shaw

-- 
#macro T(E,N)sphere{x,.4rotate z*E*60translate y*N pigment{wrinkles scale
.3}finish{ambient 1}}#end#local I=0;#while(I<5)T(I,1)T(1-I,-1)#local I=I+
1;#end camera{location-5*z}plane{z,37 pigment{granite color_map{[.7rgb 0]
[1rgb 1]}}finish{ambient 2}}//                                   TenMoons

Post a reply to this message

John VanSickle wrote:
> Namespaces are probably the best way.  Ideas:
> 
> * #namespace LABEL creates the namespace LABEL if it doesn't already 
> exist.  Whether new or not, namespace LABEL becomes the active namespace 
> (the former namespace is saved on a stack).
> 
> * #namespace undef pops the current namespace off of the stack, and the 
> former namespace becomes active.

Rather than that, why not just utilize
#namespace
with no arguments, to return to the global namespace?

> * All #declare and #local statements affect the variable in the current 
> namespace.  Other variables of the same name in other namespaces are not 
> affected.
> 
> * #declared variables live from one invocation of the namespace to the 
> next, but #labeled variables die when the namespace passes out of scope 
> (end of macro, end of file, popped by #namepsace undef statement).

You mean #local items, right?

I think namespaces are the perfect way to go, especially as the 
community using POV-Ray matures in their code-writing efforts.

...Chambers

Post a reply to this message

Sherry Shaw <tenmoonsPutAtCharacterHereaol-dot-com> wrote:
> John VanSickle wrote:

> > Probably the biggest issue is that while many people around here use 1
> > unit = 1 meter, others (such as I) use 1 unit = 1 cm for most scenes.
> >
> > This is probably best addressed with a simple line at the start of the
> > macro or scene file:
> >
> > // -- uses centimeter scaling
> >
>
> I wonder if some sort of generic unit conversion code might be posted on
> the site, to allow coders to use the units they find most appropriate,
> while simplifying end-users' ability to mix-and-match #include files...?


If anybody's interested, Sherry your comment inspired me to make a little
macro which is expandable, but currently can convert any combination of
"mm", "cm", "m", "km", "in", "ft", "mi". I posted it here, and then as
usual found a minor error in a #debug statement & then re-posted.  I
wouldn't mind contributing this, realising it may need modification to fit
the standard we come up with. Any comments for improvement?

http://news.povray.org/povray.binaries.scene-files/thread/%3Cweb.4570c25ad5e52cf5e451c5d90%40news.povray.org%3E/

Charles

Post a reply to this message

Re: CSG fonts

I have an interest in developing and exchanging CSG fonts and CSG
font-formatting tools.  I have proposed adopting a standard for such
objects and macros in this thread:

http://news.povray.org/povray.binaries.scene-files/thread/%3Cweb.456ff0468ffcc40c7cac52a50%40news.povray.org%3E/

{ Please pardon my newbiisms and my footprints on a well-worn path, but
take seriously my proposal to adopt some sort of CSG font standard. }

In a nutshell:  I think it would be wise for default CSG font objects to
emulate default 'text{}'-generated objects.  And, I think it would be wise
to adopt a standard array structure to contain CSG fonts to allow for
portability among formatting tools.

-Randall

Post a reply to this message

Ben Chambers wrote:

> John VanSickle wrote:
> 
>> Namespaces are probably the best way.  Ideas:
>>
>> * #namespace LABEL creates the namespace LABEL if it doesn't already 
>> exist.  Whether new or not, namespace LABEL becomes the active 
>> namespace (the former namespace is saved on a stack).

By this stack thing I mean that the fact of being active is kept saved 
on a stack.

>> * #namespace undef pops the current namespace off of the stack, and 
>> the former namespace becomes active.
> 
> Rather than that, why not just utilize
> #namespace
> with no arguments, to return to the global namespace?

But there file or macro may return to code that had a different 
namespace active; returning to the global may mess that up.

To go to the global, there should probably be a keyword for it so that 
the scene coder gets a chance to know what he's doing.

>> * All #declare and #local statements affect the variable in the 
>> current namespace.  Other variables of the same name in other 
>> namespaces are not affected.
>>
>> * #declared variables live from one invocation of the namespace to the 
>> next, but #labeled variables die when the namespace passes out of 
>> scope (end of macro, end of file, popped by #namepsace undef statement).
> 
> You mean #local items, right?

Yeah, I meant #localed instead of #labeled.

> I think namespaces are the perfect way to go, especially as the 
> community using POV-Ray matures in their code-writing efforts.

I was trying to come up with something that is easy for the SDL user to 
understand (which means something far less complex that C++ namespaces), 
and which seems to be relatively simple to implement.

Regards,
John

Post a reply to this message