Re: [Gimp-web] Proposed gimp tutorial

[Stephen Kiel <snick kiel gmail com>]

Saul,

First of all, thanks for the input and feedback.

Second, I AM CONFUSED. The link I sent to Pat was for a tutorial titled 
"Automate Editing in Gimp", whose examples were exclusively written in 
Python. The Automated Jpg to XCF tutorial was published several months ago.

*   If I caused or contributed to confusion and caused extra work, I am 
DEEPLY SORRY.

*   Roman wrote an email mentioning discussions on two mailing lists.  
For several days prior I did not receive any emails from gimp-docs-list 
or gimp-web-list, so I have been in the dark for a few days. (Suddenly 
it has become apparent why the DIR-SEPARATOR comment came up)

*   Are we talking about pulling the AutomatedJpgToXcf tutorial? I would 
prefer to work on one tutorial at a time if possible. Preferably I would 
like to get through the tutorial that I just submitted before going back 
to look at this one. I find that looking at code that I wrote 6 months 
ago is at times like looking at code written by a stranger (old guy).

Third, I appreciate the honest criticism and did not feel like it was at 
all negative. The objective is a good tutorial.  I will respond back 
with my reasons & opinions, with no offense intended as well.  I am 
pretty sure we can get to a consensus.

You made several comments, let me respond to them one by one:

1)"presented in the AutomatedJpgToXcf tutorial on wgo[1]"

*   I don't actually know what wgo is or how I would determine what is 
there.

2) "The first requirement ("The script needs to be available and run 
when there is no image open" is only half correct. While it is true that 
the script needs to be available when no image is open, there is no need 
-- or benefit -- "

*   I disagree with the -- or benefit -- assertion.

*   While the script might run with an image open, I feel like you are 
assuming an unnecessary risk running a script that is opening and 
closing files if you don't start from a known starting point. Will the 
script always behave the same w.r.t. the open image, will it always 
close it, leave it open, act the same way on a Windows host OS as Linux, 
will it behave the same if the image was open from a Jpeg or xcf (opened 
vs imported)? While you could run test cases for all of these 
permutations, the next time there is a major Gimp release will all it 
all still work?

*   I do not feel that a requirement to close open images prior to 
running the script is all that burdensome.

3) "The script could be simplified by using the Script-fu constant 
DIR-SEPARATOR".

*   It is true that the code would be a couple of lines shorter, but it 
is not clear that there is any performance difference.  I guess you 
could write the code either way, I did not use DIR-SEPARATOR because I 
did not know it existed. I would be *inclined* to stick with the code 
the way it is particularly for a tutorial because:
      a. DIR-SEPARATOR isn't mentioned in any real documentation, 
search engines bring you to a couple of discussion forums but nothing 
that looks official. strbreakup on the other hand  is at least mentioned 
on an old scheme site as being part of the language. In a tutorial it is 
a good idea to avoid obscure (although the entire scheme language seems 
to be getting a bit obscure these days).
      b. Changes in the code need to be reflected in changes to the 
documentation, can't let them get out of sync.
      c. The change does not make the purpose more clear or enhance the 
performance.
      d. I tend to favor features built into a language over the same 
feature built into an application. The features with the wider user base 
are more likely to keep on working on all supported platforms. Changing 
the code to use DIR-SEPARATOR doesn't seem like a big deal, but it 
doesn't seem like a real improvement either.

4) "The script uses 'file-glob' to build a list of the names of 
pre-existing files in the target directory, then checks whether the 
filename of the file being saved is in that list before saving. Since 
GIMP 2.4 there has been a 'file-exists?' procedure ..."

*   Using a scheme predicate sounds like a good solution.  The part that 
is troubling is "Since GIMP 2.4". There isn't really a lot said about 
what works and what does not work in the scheme that gimp uses.

*   file-glob is documented in the procedure browser, which seems like a 
real plus for keeping it.

*   Again, I don't see any performance issues with the code as written, 
so I am wondering if we are changing things for the sake of changing them.

5) "With regard to the description supplied in the 'script-fu-register' 
block,  while it is true that this description appears in the Procedural 
DataBase browser, more importantly it appears in the status line and 
infobox popup when the mouse is hovered over the menu command. For this 
reason it has been decided that this description should be limited to a 
single line of text[2]."

*  Will have to take your word for it, I was not aware of this decision, 
and could not get the referenced web sight to come up.

6) "The remainder of my critique addresses the issue of stylistic choices"

*   I am not a programmer, so some of my stylistic choices are more than 
likely non - conventional, but they were choices that I put some thought 
into before I made them.  I do feel that readability is important in 
particular Human Readability outside of an editor. When you are reading 
text from a web sited rather than in an editor that highlight matches 
parenthesis, to my eyes at least the extra white space is more 
readable.  I find that a parenthesis cluster of 4 or more jammed 
together is pretty unreadable. While I acknowledge that you are most 
likely 100% correct where you point out that my code is not 
conventional, I don't really buy the readability argument. I guess that 
I haven't seen much scheme that seemed particularly readable. I would 
tend to value clarity over being conventional in a tutorial.

*   About the variable names in CamelCase - cute name - vs hyphen 
separated names. The tutorial is somewhat bi-lingual python and scheme.  
I wanted to use variable names that were consistent throughout the 
article. The hyphen separated names is simply a convention and in and of 
itself it brings nothing to the table in the case of a scheme script, 
and it is not used at all in python. The idea that names like 
"the-image" in one language and "the_image" in another language makes 
more sense than "theImage" that works in both seems odd.  There is 
nothing about using hyphens or underscores that actually improves the 
code, it is just a custom.

Having said all of that, as I mentioned when I started this email, I AM 
CONFUSED about why we are talking about a tutorial that was published 
months ago.  I would rather work on the tutorial that I just submitted 
and is fresh in my mind first.  We don't have to worry about the scheme 
code in the new tutorial, there is none.

I would welcome the opportunity to improve the quality of the existing 
tutorial. My focus as I mentioned always has been a method for 
automating common tasks.  I appreciate your re-write of the code.  It 
did seem a little sparse from the perspective of explanatory comments, 
but that is just additional detail.  In expressing my opinions above my 
heels aren't dug in, I can compromise on a consensus view of the way it 
should be.  In fact if you are interested, I would welcome you as a 
co-author.

Thanks again for the feedback,

Stephen




On 2/25/2014 5:40 AM, Saul Goode wrote:
> On Mon, Feb 24, 2014 at 9:36 PM, Pat David <patdavid gmail com> wrote:
> Could someone with a better grasp of the material chime in to help iron
> this out so that we can possibly include it as either a tutorial or wiki
> material?
> I should like to offer some comments on the Script-fu material presented in the AutomatedJpgToXcf tutorial on 
> wgo[1].
>
>
> The first requirement ("The script needs to be available and run when there is no image open" is only half 
> correct. While it is true that the script needs to be available when no image is open, there is no need -- or benefit 
> -- to prevent the script from running when an image is open.
>
>
> The script could be simplified by using the Script-fu constant DIR-SEPARATOR when constructing the pathnames. 
> There is no need to determine the host operating system.
>
> The script uses 'file-glob' to build a list of the names of pre-existing files in the target directory, then 
> checks whether the filename of the file being saved is in that list before saving. Since GIMP 2.4 there has 
> been a 'file-exists?' procedure available that obviates the need for this code.
>
> With regard to the description supplied in the 'script-fu-register' block,  while it is true that this description 
> appears in the Procedural DataBase browser, more importantly it appears in the status line and infobox popup when the 
> mouse is hovered over the menu command. For this reason it has been decided that this description should be limited to 
> a single line of text[2]. By convention, this text should describe what the command will do when executed ("Copy 
> all JPEG files in a directory as XCF files").
>
> The remainder of my critique addresses the issue of stylistic choices and some areas where the example script 
> deviates from conventional Scheme programming style.
>
> 1) Boolean procedures and variables should end with a question mark (e.g., "linux?", not "isLinux").
>
>
> 2) As a general rule, white spaces should not appear after an open parethesis or before a closing one.
>
>
> 3) The first part of a compound expression should rarely be followed by a newline; when it is, the remainder 
> of the expression should be indented from the start of that compound expression.
>
>    For example:
>      (if (zero? (length string))
>    or:
>      (if (zero?
>            (length string))
>
>    but not:
>      (if (zero?
>        (length string))
>
>
> 4) The closing parenthesis of a multi-line expression should appear either on the same line as the last 
> subexpression or nested to the same level as the subexpressions. It should never appear directly beneath the 
> opening parenthesis of the expression.
>
>
>    For example:
>      (begin
>        (display "Hello, world")
>        (newline))
>    or:
>
>      (begin
>        (display "Hello, world")
>        (newline)
>        )
>    not:
>
>      (begin
>        (display "Hello, world")
>        (newline)
>      )
>
> 5) The convention in Scheme is to use hyphens to separate words within the names of constants and variables, 
> as opposed to CamelCase or the use of under_scores. This practice is re-enforced in Script-fu by virtue of 
> all Script-fu constants and PDB procedures following this naming convention (despite the actual names in the 
> database employing underscores).
>
>
>
> While all of these points might to some degree be considered mere stylistic preferences, following the idiomatic 
> conventions of a particular programming language makes the program easier to read and understand. While some of 
> the scripts that ship with GIMP may deviate from some of these conventions, official GIMP tutorials should avoid 
> making the same mistake. To quote Kernighan and Pike, "The purpose of style is to make the code
> easy to read for yourself and others, and good style is crucial to good
> programming."
>
> I apologize if this all seems overly negative and critical. It just seems to me that in order to address a 
> lack of good documentation about scripting in GIMP, it is necessary for the documentation that is provided 
> itself be of a high caliber.
>
>
>
> Finally, I am inclosing my own version of the same procedure (I omitted the registration block), 
> incorporating some of the above commentary:
>
> (define (script-fu-example-jpg-to-xcf source-directory target-directory)
>    (let ((pattern (string-append source-directory
>                                  DIR-SEPARATOR
>                                  "*.[jJ][pP][gG]" )))
>      (let loop ((source-files (cadr (file-glob pattern 1))))
>        (unless (null? source-files)
>          (let* ((source-name (car source-files))
>                 (basename (car (last (strbreakup source-name DIR-SEPARATOR))))
>                 (basename-without-extension
>                   (unbreakupstr (butlast (strbreakup basename "."))
>                                 "." ))
>                 (target-name (string-append target-directory
>                                             DIR-SEPARATOR
>                                             basename-without-extension
>                                             ".xcf")) )
>            (unless (file-exists? target-name)
>              (let ((image (catch #f (car (file-jpeg-load RUN-NONINTERACTIVE
>                                                          source-name
>                                                          source-name )))))
>                (if image
>                  (begin
>                    (gimp-xcf-save RUN-NONINTERACTIVE image -1 target-name target-name)
>                    (gimp-image-delete image) ))))
>            (loop (cdr source-files))))))
>
>
>
>
> [1] http://www.gimp.org/tutorials/AutomatedJpgToXcf/
>
> [2] http://www.gimpusers.com/forums/gimp-developer/5624-script-fu-procedure-blurb-review
>
> _______________________________________________
> gimp-web-list mailing list
> gimp-web-list gnome org
> https://mail.gnome.org/mailman/listinfo/gimp-web-list

--
Stephen Kiel
26602 Strafford
Mission Viejo, CA 92692
Mobile/SMS (949) 702-1993
Home (949) 367-2915
snick kiel gmail com
http://stephenkiel.blogspot.com/