Thomas de Groot <tho### [at] degrootorg> wrote:

> Aha! This again, addresses imo the fundamental question, also mentioned
> by BaldEagle, if we should not take leave of (some) of the "backward
> compatibility" rule. These cloud scenes were great a couple of decades
> ago but hardly anyone nowadays would use them without serious changes;
> even newbies would probably not find them acceptable given the
> development in the field of cgi.

I think, at this point, if we are going to move forward toward "4.0", then WE
must move _forward_ TO 4.0.

I have been writing some macros for use in (new) include files as well, and I
think it would be good to periodically collect and summarize ALL of the broadly
useful macros and formulas that we have - to see where we are, and so people can
review, fiddle, critique, error and performance check, etc.

> ...over the years, we have
> acquired a huge amount of creative power condensation and deposition! :-)

Going through a lot of what we have, I would say that if we're in the process of
updating and changing things, we should make a clean break, and even start
renaming some of the macros as well.

For instance, in the recent example of clarifying and modifying Point_At_Trans,
I have always thought that the name was terrible, due to vagueness.  Point
_what_ at _what_?  I think that maybe it should be renamed to something that
more clearly and concisely describes what it actually does.  "Tilt Y to new
position" "Rotate Y vector" or something like that.  Because that's what we're
going to have to remember when we type it into the scene.
It's easy enough to have the old macro name just call the macro with the new
name.

#macro OldName (Argument)
     //#warning "macro OldName has been deprecated, consider using NewName"
     #macro NewName (Argument)
#end

It's always difficult for me to know where to strike a balance with comments,
but in general, as Bill Pokorny pointed out, comments in macros and loops need
to be parsed - character by character - and so perhaps comments should reside
exclusively outside of the macros, perhaps in a nice, boxed header section, or
at least use a // 1   // 2   // 3 short notation to refer to line-specific
comments in the header.

//########################################
// This is my macro that does cool stuff #
// 1. actually it does literally nothing #
//########################################
// Author                                #
// Revised by                            #
// Version                               #
// Dependencies: math.inc, stuff2.inc    #
//########################################
#macro CoolStuff ()
     #if (true)
          #break // note 1
     #else
     #end
#end
//########################################

Since over the course of time, various include files have been improved,
updated, and have had errors corrected, I would like to see a semantic
versioning system somehow implemented.  Otherwise we're talking about one
filename, rather than a specific version of the file.  Just like we have POV-Ray
3.5, 3.6, 3.7, 3.8...
How do we accomplish that, yet keep the same simple naming scheme?
Maybe skies.inc has a single functional line: #include "skies_2_1_1.inc"
Sure, we can have a revision history, with #include "skies_1_1_1.inc" commented
out above that.

Perhaps, if there is a need for extensive documentation, it would be wise to
supplement the official docs with a .txt file with the same parent filename.
So, skies,inc would have a skies.txt file that tags along in the include
directory, and can be as verbose as the situation warrants.

Things like eval_pigment(), now(), trace() and the orthographic camera are
things that I have to re-learn to use Every Single Time.
There are also things about the orthographic camera that I still don't really
understand.


Everyone has their own programming style, and naming conventions, and toleration
for "clutter" or absence of guiding commentary.

So while there will be a certain level of unavoidable preference clashes, I
think that now is a good time to set the tone for how things will be structured,
and maybe even the content and placement of macros in the include files might
get rearranged, if it makes more sense to do so.

I mean we have shapes, and shapes1 and shapes2 and maybe even a shapes3
and there are necessary dependencies in some of those shape files that aren't
explicitly indicated or automatically included.

stones metals granites golds, ....
textures.inc ---- textures of WHAT?

It's a lot to slog through, but I think that hammering out a single include file
that illustrates a lot of the ideology and format we might want would be a great
way to guide work on successive efforts.

Post a reply to this message