World: r3wp

OK, since nobody objected, I shall proceed with the preprocessing 
directives user-poll:


- in the current INCLUDE, the PREBOL directives are made standard, 
while other directives, like COMMENT are made "user-defined", which 
means, that they are defined "on-demand" only


Since in RMA, we actually used the COMMENT directive as "standard" 
for quite some time, there is a suggestion (by Cyphre) to make it 
standard as well. Any other opinions on which preprocessing directives 
should be made "standard" and which ones should be "user-definable"?


Just a note - switching this in the code is trivial, it is more of 
a standardization issue, than a problem of work in my side.

Also, once the directives are defined, there is no difference between 
"standard" and "user-defined" as far as the speed or other issues 
are compared.

(that is because all directives use the same way how they are defined, 
using the SET-INCLUDE-DIRECTIVES function, the only difference is 
*when* the directives are defined, and whether it is by default, 
or whether additional action is needed)

Thanks for the update, including the great docs Ladislav. I will 
try to give it more thought, and incorporate the new version in my 
work. In the meantime, here are some quick comments.


Have a naming convention for scripts that define include directives. 
e.g. %localize.r could be %#localize.r or %incl-directive-localize.r. 
Short is good, but special characters may affect portability.


If a directive doesn't require per-script or environment specific 
changes, like #comment, make it standard. And the way you designed 
#localize is very nice, in that it gives you control. Do you have 
helper functions for updating 'translate-list? I might call it translation-list, 
since 'translate sounds like an action.

A note to "%incl-directive-localize.r" - you may not have noticed 
yet, but %localize.r defines four localization directives, and string 
handling, not just one directive.

But, certainly, naming convention may be important, although, in 
this specific case, we do not have any alternative for localization. 
Certainly, if Robert agrees, we can easily change the name to a more 
descriptive one.

The COMMENT directive really looks general enough, so it is meaningful 
to make it standard. Funnily enough, its spelling is:

    COMMENT


, i.e. it is the old word, Robert just wanted to be able to strip-out 
the COMMENTs from the code, that is why I made it an INCLUDE directive 
as well. This shows, that currently you can make anything an INCLUDE 
directive, not just issues.

Making the COMMENT and INCLUDE directive, we actually keep compatibility 
with old code, being able to strip-out the COMMENTs from it when 
wished.

Of course, I can imagine a case when the COMMENT directive would 
be incompatible with the COMMENT function. See e.g. the following:

    COMMENT 1 + 1


if it is a function (not being stripped out), the expression *is* 
evaluated as a COMMENT argument. If handled as a directive, and stripped 
out, it ends up like this:

    + 1


(the COMMENT 1 part being stripped out), which looks unexpected. 
But, I was not afraid of such strange things, since nobody uses the 
COMMENT function like that.

Regarding the translation functions: yes, the directives do not suffice 
to supply all the necessary functionality. Other code is needed to 
handle the run-time translation of "marked" strings. That code was 
written by Cyphre and is influencing the behaviour of RebGUI widgets 
to show the currently required language version of the text.

err: "Making the COMMENT *an* INCLUDE directive..." is what it should 
have been in the text above

Aha, actually, forget about it, my definition of the COMMENT directive 
would handle the 1 + 1 expression as well. The only difference being, 
that it would be handled during link-time, not run-time of the code, 
which may still cause some incompatibilities

But, as said, I am not afraid of such "stangenesses", since they 
do not exist in the actual code base

What I mean, regarding %localize.r, is that any script that defines 
directives (one or more) could use the naming convention. And it 
makes perfect sense to group related directives in a script.

I'm using COMMENT in cases where I want to persist it in my code 
after building process - as a COMMENT. If I just want to temporaly 
remove some code, I one or multiple semicolons, which would be exactly 
the case with 1 + 1

I'm using COMMENT in cases where I want to persist it in my code 
after building process - as a COMMENT.
 - the COMMENT directive supports that mode as well

There iis a problem with comment, if you use it in an any block
>> print [
[    ; 2
[    1]
1
but 

>> print [
[    comment  2
[    1]
?unset? 1

sorry, I forgot the any
 
>> print any [
[    ; 2
[    1]
1
>> print any [
[    comment 2
[    1
[    ]
** Script Error: print is missing its value argument
** Near: print any [
    comment 2 1
]

No problem, it was clear what you were after, and yes, that problem 
exists

As suggested by some people, I am making the COMMENT directive standard, 
improving all the directives, and enhancing the way how INCLUDE generates/uses 
errors. When INCLUDE is traversing a large set of files, I feel it 
convenient not only to get an error, but also the file, where the 
error occurred.

That is possible by either


- enhancing the error to contain the information about the file, 
where it occurred

- storing the name of the culprit file somewhere else, not into the 
error itself

The former situation (the information about the "culprit file" is 
stored in the error) looks as follows, currently:

performing localization
** User Error: INCLUDE
** Near: do last-error: make error! spec


The trouble is, that the present error-forming code does not show 
all the attributes. If you examine the error on your own, you get:

print mold disarm last-error

make object! [
    code: 802
    type: 'user
    id: 'message
    arg1: 'syntax
    arg2: %gui/include.r
    arg3: [
        id: missing
        arg1: "end-of-block"
        arg2: "["
        arg3: none
        near: "(line 949) ]"
    ]
    near: [do last-error: make error! spec]
    where: none
]


, which shows all the data as "stored" in the error, which is referred 
(for convenience) by the LAST-ERROR variable

aha, correction, the current look of the error is as follows:

>>print mold disarm last-error

make object! [
    code: 802
    type: 'user
    id: 'message
    arg1: "INCLUDE"
    arg2: 'syntax
    arg3: [
        file: %actions/tabs/data.r
        id: missing
        arg1: "end-of-block"
        arg2: "["
        arg3: none
        near: "(line 949) ]"
    ]
    near: [do last-error: make error! spec]
    where: none
]

The second option would be to not "enhance" the error, in which case 
it might look like:

** Syntax Error: Missing [ at end-of-script
** Near: (line 949) [

, and examining the error we would get:

make object! [
 id: missing
        arg1: "end-of-block"
        arg2: "["
        arg3: none
        near: "(line 949) ]"
]


here, clearly, the information that it was an error in the %actions/tabs/data.r 
file is missing, but the "standard" error message is more informative. 
The missing CULPRIT-FILE information could be supplied by defining 
a CULPRIT-FILE variable for that purpose. Any preference(s) which 
alternative you might prefer?

Summary of the advantages of the first approach:

+ the file information is present in the error itself

Disadvantages:


- the error is "too complicated" for the interpreter to display the 
important informations

- the error has to be "intercepted" by TRY for the INCLUDE to be 
able to "enhance" it.

- also, since the INCLUDE works recursively, the TRY is used many 
times, and the code needs to take care, that the "enhancement" occurs 
only once

The second approach has got the following advantages:


+ no need to "intercept" the error, since no "error enhancement" 
needs to be done

+ the error is displayed by the interpreter in a standard way, the 
user needs just to get the CULPRIT-FILE name elsewhere

Disadvantages:


- the error does not contain the CULPRIT-FILE information, which 
is important, thus, the user needs to look for it elsewhere

Ladislav, it is possible to add new error kinds to system/error, 
then the "error display" can be made to show what you want as well.

eg. see http://www.rebol.it/power-mezz/schemes/hardball.html#section-7.1

and http://www.rebol.it/power-mezz/mezz/messages.html#section-9

Ladislav, it is possible to add new error kinds to system/error, 
then the 

error display" can be made to show what you want as well." - yes, 
in R2, but INCLUDE is written to be compatible with R3

(I used such a method when INCLUDE was meant just for R2, but, with 
R3 I am not sure)

Brian, don't you happen to know a similar "mechanism" for R3?

; the arguments have to be strings: substitute [

%1" 12] ; triggers an error" - Why does the STRING! constraint exist? 
IMO every aregument should be reduced and than formed into a string.

The FORM can be implicit if the argument is not string.

Why does the STRING! constraint exist?

 - Cyphre and I thought, that it may be of help for the programmer 
 to tell him that he "forgot" to put in strings. Even the numbers 
 are unlikely to be put in unformatted.

IMO every aregument should be reduced and than formed into a string.

 - yes, but that should be done when a substitution is made, not when 
 it is translated, e.g.

I think that it may help to think of substitutions as "a different 
kind of string". A substitution as "a different kind of string" does 
not need to contain any expressions or code.

Certainly, this restriction can be removed, but it does not look 
like worth doing it.

Substitutions are meant to separate:


- the time when the substition was created (using e.g. the REDUCE 
function)

- the time when the substitution was translated and displayed (using 
e.g. the combination of the TRANSLATE SUBSTITUTE and SHOW functions)

Note: it may make sense to put some of the Q&A to the

http://www.rebol.net/wiki/Replacement#SUBSTITUTE

section

We can also think of the SUBSTITUTE function as being written using 
the KISS strategy. REDUCE can be performed separately, that is why 
it is not needed in the definition of the SUBSTITUTE function.

substitute ["a%0"] ; == "aa%0"
but there is no argument string?

Isn't this just a special case of printf ..  so why not implement 
printf instead?

I agree with Robert .. why would you want to perform an extra reduce 
?  Is the added efficiency worthwhile making the program reduce in 
those instances where non string values are being passed?

KISS in this instance means default reduce, and use a refinement 
if you don't want this behaviour

Isn't this just a special case of printf ..  so why not implement 
printf instead? - it does not have anything in common with printf, 
except for the superficial similarity

I agree with Robert .. why would you want to perform an extra reduce 
?
 - exactly because the REDUCE is performed at a different time

The substitution has to be performed always at the translation time, 
while REDUCE just when you need to create the substitution

Not to mention, that it is safer to have substitutions as data files, 
than to allow code

err. susbstitutions as data values is what I mean

there is no argument string?

 - the %0 is the substitution string (the first one), just as a curiosity, 
 it may not be needed