Re: [Gimp-web] Proposed gimp tutorial

[Saul Goode <saul crazyauntgail com>]

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