Gimp Doc Guys,

One of the listed methods to contribute to the Gimp project, listed on the website, is to write a tutorial. I tried sending in a tutorial for basic scripting (it was probably too long) about a year and a half ago. I did not hear back, but since the scripting tutorial did make some improvements I hope that it did have some positive contribution.

I did have another area where I thought that a few tutorials might be of interest and helpful to others, and that is in the area of Automation. This is an area that is nearer to my interests anyway (closer to my career interests). I think Gimp is unique in its capability as a platform for automating the image editing process. I am talking about Automating the process of custom edits not just using an "I feel lucky" button on a photo manager.

I think there is room in the area of automation for a couple of tutorials, I wrote up an example for one (importing a directory of images / jpg -> xcf). I think other tutorials could cover reading & writing parasites, parasites as flow control variables, how to build & execute a recipe / process / flow. I touched on these possibilities in the included file "Introduction".

Anyway, here is my dilemma. I would be happy to write a draft for tutorials on some or all of these topics, or better yet, co-author them with a member(s) of the gimp-doc team. I have no where to publish a tutorial, and it seems pointless to write something that no one will read.

Take a look at the attached documents and scripts. Let me know if this idea is something that sounds interesting. The *.odt format files are open office writer format.

Thanks,

Stephen Kiel

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/

Andrew,

Thanks for your reply and feedback. The answer to your first question is yes, I would like to to be able to post a tutorial or tutorials on the site http://www.gimp.org/tutorials/ or somewhere like it. I understand that the gimp-doc group might not want to post every tutorial the general public might submit, there might be a lot of repetition and the quality might not be sufficient. On the other hand, I think there are many areas where expanding the range of topics covered with tutorials or other forms of documentation could benefit Gimp.

I would be happy to write a couple of tutorials or if someone wanted to co-author the tutorials that would be fine as well. Sometimes when two people are working on documentation one person can spot what is not clear in the other person's explanation. Going back and forth can make a better end product.

The dilemma is there is no point in writing a tutorial if you don't have a venue to publish it. I do not have access to a website where I can post tutorials, and if I did I would imagine it would be so obscure no one would see it. I suspect there are other Gimp users who would be willing to share ideas but don't have a venue to publish them.

About your comments on the text, the way you specify the image type is more of a means of control rather than an issue. The attached jpegs are small shots of the menu from my automation scripts with and without an image open. The scripts that are intended to run on a directory of images are on all of the time, the scripts that are intended to run on a single file / image are grayed out (image type "*") unless an image is opened.

The four items I identified in the tutorial were things that I had to do more research on and work harder at when I wrote the scripts to automate my flow. I thought they might be good things to point out in a more advanced tutorial. The script is pretty handy, saves time, and when you get past the less commonly understood aspects it is pretty straightforward. It seemed that if the four little "tricks" were widely understood, something like this script should have been written 10 years ago (maybe it was I I just could not find it).

Anyway, thanks for the feedback.

Sincerely,

Stephen Kiel

On Thu, Jun 20, 2013 at 2:59 PM, Andrew Douglas Pitonyak < andrew@pitonyak.org> wrote:

Hello Stephen,

Disclaimer: I have no particular ability myself to integrate these..

Having read these, I see that you have much that is useful to say. In other words, I found automated-jpg-to-xcf.odt to be informative.

That said, are you saying that you would like to create content that is published here:

http://www.gimp.org/tutorials/

It looks like you chose the correct lists (doc, web, and developer) to obtain appropriate feed back.

I recommend (and other feedback may negate what I say) that you identify what you would like to have as topics in the tutorial; for example:

"How to write a script that is available when an image is not open"

I was not aware that this was an issue until I read your document.

I expect that this tutorial would be "Change all JPG files in a directory to XCF".

On 06/20/2013 02:29 PM, Stephen Kiel wrote:

Gimp Doc Guys,

One of the listed methods to contribute to the Gimp project, listed on the website, is to write a tutorial. I tried sending in a tutorial for basic scripting (it was probably too long) about a year and a half ago. I did not hear back, but since the scripting tutorial did make some improvements I hope that it did have some positive contribution.

I did have another area where I thought that a few tutorials might be of interest and helpful to others, and that is in the area of Automation. This is an area that is nearer to my interests anyway (closer to my career interests). I think Gimp is unique in its capability as a platform for automating the image editing process. I am talking about Automating the process of custom edits not just using an "I feel lucky" button on a photo manager.

I think there is room in the area of automation for a couple of tutorials, I wrote up an example for one (importing a directory of images / jpg -> xcf). I think other tutorials could cover reading & writing parasites, parasites as flow control variables, how to build & execute a recipe / process / flow. I touched on these possibilities in the included file "Introduction".

Anyway, here is my dilemma. I would be happy to write a draft for tutorials on some or all of these topics, or better yet, co-author them with a member(s) of the gimp-doc team. I have no where to publish a tutorial, and it seems pointless to write something that no one will read.

Take a look at the attached documents and scripts. Let me know if this idea is something that sounds interesting. The *.odt format files are open office writer format.

Thanks,

Stephen Kiel

-- 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/

_______________________________________________ gimp-docs-list mailing listgimp-docs-list@gnome.orghttps://mail.gnome.org/mailman/listinfo/gimp-docs-list

-- Andrew Pitonyak
My Macro Document: http://www.pitonyak.org/AndrewMacro.odt Info: http://www.pitonyak.org/oo.php

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/

Roman,

Thanks for getting back to me, your feedback wasn't discouraging, I just didn't really know how to proceed (so no worries).

I completely understand peoples limited time, I am in the same boat, I did not want to invest hours in writing, learning the nuances of a particular markup language, only to have a barrier thrown up at the end. This is the reason for my questions.

I would be happy to format and maintain my own tutorial, as this is my first contribution of any kind, I am completely unfamiliar with the procedures, customs, and requirements for doing this on the gimp project. It sounds like the barriers that you mentioned are more technical than administrative, so that is actually pretty encouraging.

I am not quite ready to checkout a module and add my own tutorial just yet, I need to read up on using Git for a collaborative project. I have used older CMS S/W (RCS, CVS) for collaborative projects, but that was a while ago. I will follow the link and do some reading.

I did browse through some of the tutorials & looked at they way they were marked up. I don't think porting my tutorials into a markup language will be any problem. The part that I don't really understand yet is whether there are tags that will or won't work right. In other words, if the XHTLM is well formed and presents in a web browser is there any downstream processing that looks at or uses particular tags? e.g. some of the xhtml that I looked at used the older tags for bold instead of . Both work, one is more contemporary, but what I am wondering is whether there is a reason to use the older tag format.

Once I do get ready to check out the module and add my tutorial, is there any kind of an approval process, or do I just stage the changes and commit them?

Thanks for the feedback & help.

On Mon, Jul 1, 2013 at 12:35 AM, Roman Joost wrote:

On Fri, Jun 28, 2013 at 05:09:49PM -0700, Stephen Kiel wrote:

Pat,

Sorry for the delay in getting back to you. I would really appreciate

your

help. While all of Roman's suggestions sounded positive and a great

idea,

they left me wondering how I would go about accomplishing them. Having someone that has gone through a few of these steps or is going through

them

would be a great help.

Sorry if I sounded discouraging. The problem for most of the GIMP people is to take care of your contributions since there is only a limited amount of spare time available for all of us. At the moment, the file format you're using is incompatible at what is being used for the homepage and/or the manual. That means, someone would need to incorporate it.

What you could do is, checkout the gimp-web module from:

https://git.gnome.org/browse/gimp-web

and try to add your tutorial. That should be something you can't export from libre office.

As you can see, the barrier has already risen from simply contributing something you can write in an office application towards something where you need to write markup and perhaps even source code. Even more, you need to figure out how to incorporate your contributions instead of just making them available.

Hope that makes things more clear on where to start, but feel free to follow your own ideas.

Kind Regards, --
Roman Joost
www: http://www.romanofski.de
email: romanofski@gimp.org

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/

Roman and Pat,

I have made some progress toward getting my tutorial ready for release, but I am at a point now where I have hit a wall, and I would like to ask for some advice on how to proceed.

I did do a final edit of the tutorial, format it into xhtml, and add a couple of pictures. I downloaded a copy of Bluefish and used it to format the material into an xhtml file adding the boilerplate provided in the tutorial template by hand. It seemed to render well in the Firefox browser.

I did find a procedure for adding content through git web at https://wiki.gnome.org/Git/Developers and followed it as best as I could. I was able to clone the gimp-web, check out a branch, make local changes and commit them, but then my progress stopped. My questions are:

1) when I performed a 'git branch -r' several branches were listed. I guessed and picked HEAD as it appeared to link to origin/master. When I did a 'git status' and 'git commit -a' I got a warning message that “refname 'HEAD' is ambiguous”. Did I pick the wrong branch? Is there another problem, or is this warning normal?

2) The guidelines I was looking at seemed to be saying I could either use 'git-bz' or 'git push' to get my changes back to the main repository. Neither worked, so I was wondering which technique I should focus on. Would rather not debug them both at this time (could use quite a bit of time, since I don't know what either is trying to do).

The error message that I go with git-bz was:

bash: git-bz: command not found...

The error message from git push –dry-run was:

fatal: Could not read from remote repository.

Please make sure you have the correct access rights

and the repository exists.

A git pull –rebase right before trying the push seemed to find the repository and verify that my current branch is up to date.

I would appreciate any pointers you could give me. I am attaching a copy of the transcript from my shell session. I am also attaching a copy of the files I was trying to add & modify in case it is relevant or you would like to take a look at them.

In the mean time, I will start looking at git-bz in case that is the write way to go. It looks like there may be some setup issues, even though the error message make it look like it is an installation issue. The options for the bz command were not clear to me. The wiki page indicated the syntax should be:

git-bz file product/component HEAD

I am guessing the product should be 'gimp-web', but when I look at https://bugzilla.gnome.org/buglist.cgi?quicksearch=gimp-web I see the component listed as both gimp-web and www.gimp.org. Do you know which it should be, or whether it matters? When it asks for 'file' I am assuming it is looking for the results of the local 'commit'. In my case the feedback was

[HEAD a97ce5a] Added tutorial Automate Creation fo XCF from JPG"

Are they looking for a97ce5a as the file?

Thanks,

Stephen Kiel

On Wed, Jul 10, 2013 at 10:49 PM, Roman Joost wrote:

Dear Stephen,

On Tue, Jul 02, 2013 at 12:37:33PM -0700, Stephen Kiel wrote:

Roman,

I did browse through some of the tutorials & looked at they way they were marked up. I don't think porting my tutorials into a markup language

will

be any problem. The part that I don't really understand yet is whether there are tags that will or won't work right. In other words, if the

XHTLM

is well formed and presents in a web browser is there any downstream processing that looks at or uses particular tags? e.g. some of the xhtml that I looked at used the older tags for bold instead of . Both work, one is more contemporary, but what I am wondering is whether there is a reason to use the older tag format.

Not sure. I think these are remnants of old edits which have simply been updated for a new version of the website.

Once I do get ready to check out the module and add my tutorial, is there any kind of an approval process, or do I just stage the changes and

commit

them?

Usually you can send in your patches and they're been reviewed by people who have access to the module. The more you contribute, the more likely maintainers see to getting you commit (read: push) rights.

Thanks for the feedback & help.

Happy to help!

Kind Regards, --
Roman Joost
www: http://www.romanofski.de
email: romanofski@gimp.org

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/

Roman & Pat,

I spent quite a bit of time fiddling round with git-bz and after downloading it, configuring it, and trying to use it to send in the differences from checking my tutorial into git (local check out / check in *seems* OK), I have come to the conclusion that this is probably not what you guys are using because it sure seems to be - broken. After trying to send in a patch with git-bz it told me that I did not seem to be logged into bugzilla.gnome.org in firefox - I am. It does not seem to be able to read the cookies (Firefox V22 on Fedora).

Is there a set of instructions written down anywhere that indicates what format and method someone should use to send in changes, updates and new content like a tutorial? I did format the tutorial into web format and do a checkout / check in into the repository, but not being able to get any farther with it is beginning to take a lot of time.

The files I am trying to check in are in a share (should be easy to download) at:

https://spideroak.com/browse/share/Stephen_Kiel_Pictures/Stephen_Kiel_Gimp_Tutorial

I would appreciate any help you could give me. I will be on the road for about a week, so I may be slow getting back to you.

Thanks,

Stephen

On Mon, Jul 22, 2013 at 7:22 AM, Stephen Kiel wrote:

Roman and Pat,

I have made some progress toward getting my tutorial ready for release, but I am at a point now where I have hit a wall, and I would like to ask for some advice on how to proceed.

I did do a final edit of the tutorial, format it into xhtml, and add a couple of pictures. I downloaded a copy of Bluefish and used it to format the material into an xhtml file adding the boilerplate provided in the tutorial template by hand. It seemed to render well in the Firefox browser.

I did find a procedure for adding content through git web at https://wiki.gnome.org/Git/Developers and followed it as best as I could. I was able to clone the gimp-web, check out a branch, make local changes and commit them, but then my progress stopped. My questions are:

1) when I performed a 'git branch -r' several branches were listed. I guessed and picked HEAD as it appeared to link to origin/master. When I did a 'git status' and 'git commit -a' I got a warning message that refname 'HEAD' is ambiguous. Did I pick the wrong branch? Is there another problem, or is this warning normal?

2) The guidelines I was looking at seemed to be saying I could either use 'git-bz' or 'git push' to get my changes back to the main repository. Neither worked, so I was wondering which technique I should focus on. Would rather not debug them both at this time (could use quite a bit of time, since I don't know what either is trying to do).

The error message that I go with git-bz was:

bash: git-bz: command not found...

The error message from git push dry-run was:

fatal: Could not read from remote repository.

Please make sure you have the correct access rights

and the repository exists.

A git pull rebase right before trying the push seemed to find the repository and verify that my current branch is up to date.

I would appreciate any pointers you could give me. I am attaching a copy of the transcript from my shell session. I am also attaching a copy of the files I was trying to add & modify in case it is relevant or you would like to take a look at them.

In the mean time, I will start looking at git-bz in case that is the write way to go. It looks like there may be some setup issues, even though the error message make it look like it is an installation issue. The options for the bz command were not clear to me. The wiki page indicated the syntax should be:

git-bz file product/component HEAD

I am guessing the product should be 'gimp-web', but when I look at https://bugzilla.gnome.org/buglist.cgi?quicksearch=gimp-web I see the component listed as both gimp-web and www.gimp.org. Do you know which it should be, or whether it matters? When it asks for 'file' I am assuming it is looking for the results of the local 'commit'. In my case the feedback was

[HEAD a97ce5a] Added tutorial Automate Creation fo XCF from JPG"

Are they looking for a97ce5a as the file?

Thanks,

Stephen Kiel

On Wed, Jul 10, 2013 at 10:49 PM, Roman Joost wrote:

Dear Stephen,

On Tue, Jul 02, 2013 at 12:37:33PM -0700, Stephen Kiel wrote:

Roman,

I did browse through some of the tutorials & looked at they way they

were

marked up. I don't think porting my tutorials into a markup language

will

be any problem. The part that I don't really understand yet is whether there are tags that will or won't work right. In other words, if the

XHTLM

is well formed and presents in a web browser is there any downstream processing that looks at or uses particular tags? e.g. some of the xhtml that I looked at used the older tags for bold instead of . Both work, one is more contemporary, but what I am wondering is whether there is a reason to use the older tag format.

Not sure. I think these are remnants of old edits which have simply been updated for a new version of the website.

Once I do get ready to check out the module and add my tutorial, is

there

any kind of an approval process, or do I just stage the changes and

commit

them?

Usually you can send in your patches and they're been reviewed by people who have access to the module. The more you contribute, the more likely maintainers see to getting you commit (read: push) rights.

Thanks for the feedback & help.

Happy to help!

Kind Regards, --
Roman Joost
www: http://www.romanofski.de
email: romanofski@gimp.org

--
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/

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/

Marco,

Thanks for all of the help! I don't really have any direct suggestions for why there would be a problem with the git clone. There is a limitation that I ran into with testing which was the index.htrw files work almost like an index.html file would except it did not seem to follow the links completely. For example the 'index.htrw' file under tutorial references the directories that hold all of the tutorials: GIMP Script-Fu Write Scheme for GIMP. GIMP Script-Fu 2 Write More Scheme for GIMP. Automated Jpg to Xcf Import Xcf Images a Directory at a Time.
All of these links simply showed a directory of files in the index.htrw, I just followed the same pattern as the existing tutorials. I concluded that there is a downstream process that defines the styles, fonts, colors, and how to follow the links. My conclusion could be wrong, but I did not see how to display any of the gimp web with the same 'look' as I see on the gimp web site.

Just to be sure I was clear with my intent, there should have been the following in the share export_to_gimp_web

[stephen@localhost export_to_gimp_web]$ ls -R .:
AutomatedJpgToXcf index.htrw

./AutomatedJpgToXcf: example-jpeg-to-xcf.py gimp_jpg_to_xcf_popup.jpg gimp_menu_compare.jpg index.htrw script-fu-example-jpg-to-xcf.scm

The directory AutomatedJpgToXcf and file index.htrw should go into gimp-web/tutorials. The index.htrw would replace the older index.htrw and has a link to the new tutorial in AutomatedJpgToXcf. There are index.htrw files in several places, just wanted to be clear about which I was trying to modify.

I am not sure if I addressed your questions or issues or not. As I said there are some limitations to what I was able to test, I did try to stitch my tutorial into the tutorials section following in the same technique as the existing tutorials. I do appreciate your testing the changes, I would hate to be know as the guy who broke everything.

I am going to be leaving in a few minutes and will be on the road for about a week. I will have very limited access to the internet, so perhaps if there is something that I need to fix, I can look at it next week.

Thanks for the help and suggestions.

Stephen Kiel

On Wed, Jul 24, 2013 at 2:59 AM, Marco Ciampa wrote:

On Tue, Jul 23, 2013 at 07:32:57PM -0700, Stephen Kiel wrote:

I did format the tutorial into web format

Here you can help me a lot. I have tried to test your tutorial before committing it to the git-web repo but I was unable to test it.

I have started with trying to test the actual web site without any additions directly from a git clone command. I have tried both with makefile and with Apache SSI directly.

Same results: it keeps to create into the git dir a bunch of html files and install just a few of them into the right installation dir.

There must be something wrong here.

I use Linux Ubuntu 13.04 wich comes with python-2.7 (could be a problem the python version?)

Any hint?

--

Marco Ciampa

+--------------------+ | Linux User #78271 |
| FSFE fellow #364 |
+--------------------+
_______________________________________________ gimp-docs-list mailing list
gimp-docs-list@gnome.org
https://mail.gnome.org/mailman/listinfo/gimp-docs-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/

Marco,

Thanks for the feedback, & don't worry , I think that people who ask for feedback and want to shoot the messenger are pretty ridiculous.

It is interesting that the code was the one that you had trouble with. I used the "bluefish" editor (open source) to format the HTML. I noticed that their tag for preformatted text was simpler than that used on previously published tutorials. I tried editing those tags to make them like the published tutorials, apparently I missed the quotes. It would be interesting to see if the code right out of an editor like bluefish would work, it would be nice to be able to use an editor that would produce code that is essentially correct by construction.

About the scheme code & style, I guess I would say that I am not a programmer, so the criticism does not hurt my feelings. My goal was to write code that is clear and avoid writing bad code (to have it called kind of 'C' like actually seems like kind of a compliment). I think it is better to avoid opening up a debate on coding style, I have seen them consume a lot of energy and often fail to resolve much. If I do write another tutorial, the one that I am thinking about be just gimp-python anyway (it would be harder to write in scheme).

Anyway thanks again for all of the help and feedback,

Stephen

On Mon, Oct 14, 2013 at 3:59 AM, Marco Ciampa wrote:

On Fri, Oct 11, 2013 at 08:59:04PM -0700, Stephen Kiel wrote:

Marco,

Thanks for all of your help! Getting the tutorial published was more complicated than I originally anticipated, but it was definitely worth

it.

I do have a question for you:

If I were to write another tutorial, is there anything that I could do to make the release or publication process easier? I am not sure if there were things that you had to fix in order to publish the tutorial. If I made some mistakes, it would be a good time for me to take note of them

so

I don't repeat them.

Stephen Kiel

Right question, I do not really know the answer(s).

I myself have had some difficoulties to have your tutorial published.

I asked help to a friend of mine for testing in local the gimp site pages before publication.
I successfully tested your tutorial using the nginx web server instead of Apache.
I was NOT able to test it under Apache btw... Even when local testing went well (without errors) the publication went wrong.
Automatic compilation was blocked by a couple of errors in the tutorial pages.
It seems that my version of python is less picky about small errors in the htrw pages so it was not so easy to find the errors in the first place. Specifically the code into the web pages, the text in MUST BE QUOTED since there are a couple of "" inside it that confuse it a bit. Once quoted compilation and consequently site update went well.

Some developers complained about the scheme code. They say that it is a bit "C like" and not really "scheme/lisp like" and since it should be a teaching example, it should be rewritten to be a better code for beginners and students.

Please forgive my bad english and ... don't shoot the messenger! :-)

bye

--

Marco Ciampa

+--------------------+ | Linux User #78271 |
| FSFE fellow #364 |
+--------------------+

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/

Pat,

I will definitely contact you for testing if I do another tutorial, I have one in mind and a first draft started, just have to get it all together.

I mentioned in an email to Marco that I used the bluefish editor to create the HTML, if that or another editor creates code that works, it would make the authoring process a lot easier (in case others wish to write as well).

I am fine with the licensing that Marco suggested and changed on my behalf, I will be happy to use which ever one is the current favorite.

About the images, I only use my own photos for editing examples & I will try to stick to inanimate objects & if I have to use a face it will be mine. I guess the only question about rights is if I capture a screenshot of a Gimp window or menu, I assume that I have the rights to that image as well. Do you know if that is true?

Anyway,

Thanks for the help & feedback,

Stephen

On Mon, Oct 14, 2013 at 7:28 AM, Pat David wrote:

Stephen,

I had finally gotten my build environment setup for gimp-web, and was intending to integrate your tutorial into the site, but Marco beat me to it. :)

Unlike him, I do have an apache environment setup that mirrors gimp-web, so can test these things as well (this goes for Marco as well - if you need me to check if things are working just ask).

I'm not sure what might have happened with the 's, as spurious "" shouldn't cause a problem (down the path of regex'ing html leads madness).

In the future, if you can stick to standard html tags, we can handle translation to gimp-web for you. don't worry about anything other than the raw tutorial stuff (heading tags , , , , , ). Just write it normally, and we'll handle the rest.

If you do use strange things, just notify us ahead of time, and we can sort it out.

Also, if you wouldn't mind, consider the licensing moving forward (I'm sure Marco already spoke with you about this). We'd prefer something permissive like cc-by-(sa), cc0, gfdl (I think). If you use any images in your tutorial, make sure the rights are cleared for use, and if there is anyone recognizable in the images, please have model releases for them as well.

-- pat david
http://blog.patdavid.net
_______________________________________________ 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/

Pat,

That sounds great. I will plan to write in a word processor (with a spell checker) & then dump it into bluefish to add the html tags. If that works it should make the whole authoring process pretty straightforward. I would prefer to stay in a word processor form rough to final draft & minimize editing of the html for of the document in order to avoid accidentally goofing up the closures.

I am on my way out of town for a couple of days as well, I will touch base again when I get closer to a finished tutorial.

Thanks,

Stephen

On Wed, Oct 16, 2013 at 7:20 AM, Pat David wrote:

Just stick to clean, plain HTML and you should be fine. Style inline if you want, I'll move it to an external style sheet anyway.

You can publish screen grabs if gimp non problem I believe. Someone may correct me.

I'll be out of town for a few days, but just hit me up when you're ready for testing.

--
pat david
http://blog.patdavid.net

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/

Pat,

I finally finished the tutorial that I was talking about with you a couple of months ago. You mentioned then that I could either send it in Word Processor format or take attempt to convert it to HTML.

Which of the two methods would be easiest for you? I am not sure if it is easier to fix a document that I might get partially 'right' or just start from scratch. Maybe you could take a look at it and give me your opinion on the best way to proceed.

I have it on a Box.net share at https://app.box.com/s/mbd93d12ha6t1gvzgbhy

You should see the file AutomateEditingInGimp.odt and the corresponding .pdf file. It was written using LibreOffice Writer. The jpeg pictures in the same directory. The code examples are in the directories plug-ins and myXml.

I was able to get html directly out of Writer that looked real good in Firefox, I just don't know if some of the tags might cause problems within the help system. If not, the job could be easy! One problem that I did notice with the automatically generated html was that the images were no longer centered, but other than this issue, it looked good, and the links seemed to work. If you want me to generate a copy of the html, let me know.

The tutorial is kind of long, wish I could have made it shorter, but since it uses some Gimp features that aren't documented elsewhere, I had to expand on them.

Anyway, let me know if there are issues or feedback and whether you think it would be better for you to format the tutorial or if you want me to take a first pass at it.

Thanks,

Stephen Kiel

On Wed, Oct 16, 2013 at 12:21 PM, Pat David wrote:

If you want to keep it in a word processor, I can just translate it from there.

You can also use google docs if you want to share it with my acct through there.

On Wednesday, October 16, 2013, Stephen Kiel wrote:

Pat,

That sounds great. I will plan to write in a word processor (with a spell checker) & then dump it into bluefish to add the html tags. If that works it should make the whole authoring process pretty straightforward. I would prefer to stay in a word processor form rough to final draft & minimize editing of the html for of the document in order to avoid accidentally goofing up the closures.

I am on my way out of town for a couple of days as well, I will touch base again when I get closer to a finished tutorial.

Thanks,

Stephen

On Wed, Oct 16, 2013 at 7:20 AM, Pat David wrote:

Just stick to clean, plain HTML and you should be fine. Style inline if you want, I'll move it to an external style sheet anyway.

You can publish screen grabs if gimp non problem I believe. Someone may correct me.

I'll be out of town for a few days, but just hit me up when you're ready for testing.

--
pat david
http://blog.patdavid.net

--
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/

--
pat david
http://blog.patdavid.net

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/

Pat,

I finally finished the tutorial that I was talking about with you a couple of months ago. You mentioned then that I could either send it in Word Processor format or take attempt to convert it to HTML.

Which of the two methods would be easiest for you? I am not sure if it is easier to fix a document that I might get partially 'right' or just start from scratch. Maybe you could take a look at it and give me your opinion on the best way to proceed.

I have it on a Box.net share at https://app.box.com/s/mbd93d12ha6t1gvzgbhy

You should see the file AutomateEditingInGimp.odt and the corresponding .pdf file. It was written using LibreOffice Writer. The jpeg pictures in the same directory. The code examples are in the directories plug-ins and myXml.

I was able to get html directly out of Writer that looked real good in Firefox, I just don't know if some of the tags might cause problems within the help system. If not, the job could be easy! One problem that I did notice with the automatically generated html was that the images were no longer centered, but other than this issue, it looked good, and the links seemed to work. If you want me to generate a copy of the html, let me know.

The tutorial is kind of long, wish I could have made it shorter, but since it uses some Gimp features that aren't documented elsewhere, I had to expand on them.

Anyway, let me know if there are issues or feedback and whether you think it would be better for you to format the tutorial or if you want me to take a first pass at it.

Thanks,

Stephen Kiel

On Wed, Oct 16, 2013 at 12:21 PM, Pat David wrote:

If you want to keep it in a word processor, I can just translate it from there.

You can also use google docs if you want to share it with my acct through there.

On Wednesday, October 16, 2013, Stephen Kiel wrote:

Pat,

That sounds great. I will plan to write in a word processor (with a spell checker) & then dump it into bluefish to add the html tags. If that works it should make the whole authoring process pretty straightforward. I would prefer to stay in a word processor form rough to final draft & minimize editing of the html for of the document in order to avoid accidentally goofing up the closures.

I am on my way out of town for a couple of days as well, I will touch base again when I get closer to a finished tutorial.

Thanks,

Stephen

On Wed, Oct 16, 2013 at 7:20 AM, Pat David wrote:

Just stick to clean, plain HTML and you should be fine. Style inline if you want, I'll move it to an external style sheet anyway.

You can publish screen grabs if gimp non problem I believe. Someone may correct me.

I'll be out of town for a few days, but just hit me up when you're ready for testing.

--
pat david
http://blog.patdavid.net

--
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/

--
pat david
http://blog.patdavid.net

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/

Pat,

The conversion to compatible HTML went much faster than I imagined. It looks like getting everybody comfortable with the tutorial is going to be the longer part of the process.

I looked at the notes, if we need to make some changes we can, I would rather not make a lot of changes if they aren't really necessary though. Let me comment back about the notes, I am not sure what to do about them at this point.

1. 'the term "macro" in the tutorial' - Where in the tutorial was it a problem, and what was the suggested alternative? The term seemed pretty descriptive and non-proprietary, so I don't know where the problem lies. Part of the wikipedia description of macro is - "Macros are used to make a sequence of computing instructions available to the programmer as a single program statement, making the programming task less tedious and less error-prone." I am not stuck on using the term but would need to know what a better suggestion would be.
2. 'have him look into the DIR-SEPARATOR constant' - Again I really don't know what problem we are try to fix, the suggestion isn't very specific. I would say that it is the usual case that you can write a more efficient program - 2nd version - using a 1st version as a working model. I would actually be kind of surprised if there weren't several places where reviewing the code and productizing it produced code that is better from an aesthetic and maintenance point of view. But, that is kind of missing the point: * This is an Automation Tutorial. The efficiency from being able to edit 20 images in the time that it takes to edit one by hand. * It is not a programming tutorial nor is a rolled out change to Gimp. As I pointed out in the text - I am not a programmer. The gimp - python environment is not great for debugging and in the past it was not robust. If the code is working I would not be inclined to mess with it. You could waste a lot of time by trying to get too cute with 'enhancements'. * If there is a real desire to productize the automation tools, I would be happy to work on that effort, but I am not really that interested in beautifying working code for a tutorial. 3. I think all of the Gimp Documentation should move to a Wiki. The biggest hole in the documentation is topics not being covered and coverage that is out of date. Lowering the threshold for people to contribute would be a great way to address this. A Wiki seems like it would allow for a larger amount of participation than the current method of converting things to HTML by hand. * My concern about moving the tutorial to a Wiki site, is whether it would get buried in a corner of the internet that no one can find. I certainly have no idea where this wiki is. It would be a shame to do the work of writing a tutorial and then put it where no one sees it.
* I think a Wiki format is great in that it can be kept current and follow the changes of Gimp. As I said, I think all of the documentation should be ported to a Wiki.

Anyway, if there are some specific things that need to be fixed, let me know and we can address them. I can be fairly flexible with changes, I just don't want to get into a loop - modifying code until someone like it. That has no real / specific goal.

If there is a documenation Wiki, let me know where to look, I would like to see what is there so far.

Thanks for all of your help!

Stephen

On 2/20/2014 1:03 PM, Pat David wrote:

Stephen,

Just a couple of notes. There are some concerns about the introduction of the term "macro" in the tutorial and the sense with which it's used.

Also, saul has asked me to relay to you: "have him look into the DIR-SEPARATOR constant. Using it would obviate about half of his code."

If you can take a look at DIR-SEPARATOR to see if perhaps it can help streamline things a bit, that would be great. I'm also hoping others might be able to chime in with other suggestions as well.

There is a consideration of moving this to the wiki as opposed to wgo as well.

On Thu, Feb 20, 2014 at 1:37 PM, Pat David > wrote:

Stephen,

I've converted the tutorial to HTML to fit the website. I've pushed it up along with the assets, and am now just waiting on someone to poke wgo for it to show up. Keep an eye on the tutorials page.

On Thu, Feb 20, 2014 at 1:29 PM, Stephen Kiel > wrote:

Pat,
Thanks. Let me know if there are any issues. Stephen

On Feb 20, 2014 7:27 AM, "Pat David" > wrote:

Hi Stephen!

You can just leave it as an ODT file. I'll make the stylistic changes required to fit the website HTML.

Give me a little time and I'll make the conversion and get it up to test.

Thanks for the contribution!

-- pat david
http://blog.patdavid.net

-- pat david
http://blog.patdavid.net

-- pat david
http://blog.patdavid.net

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/

Pat,

The conversion to compatible HTML went much faster than I imagined. It looks like getting everybody comfortable with the tutorial is going to be the longer part of the process.

I looked at the notes, if we need to make some changes we can, I would rather not make a lot of changes if they aren't really necessary though. Let me comment back about the notes, I am not sure what to do about them at this point.

1. 'the term "macro" in the tutorial' - Where in the tutorial was it a problem, and what was the suggested alternative? The term seemed pretty descriptive and non-proprietary, so I don't know where the problem lies. Part of the wikipedia description of macro is - "Macros are used to make a sequence of computing instructions available to the programmer as a single program statement, making the programming task less tedious and less error-prone." I am not stuck on using the term but would need to know what a better suggestion would be.
2. 'have him look into the DIR-SEPARATOR constant' - Again I really don't know what problem we are try to fix, the suggestion isn't very specific. I would say that it is the usual case that you can write a more efficient program - 2nd version - using a 1st version as a working model. I would actually be kind of surprised if there weren't several places where reviewing the code and productizing it produced code that is better from an aesthetic and maintenance point of view. But, that is kind of missing the point: * This is an Automation Tutorial. The efficiency from being able to edit 20 images in the time that it takes to edit one by hand. * It is not a programming tutorial nor is a rolled out change to Gimp. As I pointed out in the text - I am not a programmer. The gimp - python environment is not great for debugging and in the past it was not robust. If the code is working I would not be inclined to mess with it. You could waste a lot of time by trying to get too cute with 'enhancements'. * If there is a real desire to productize the automation tools, I would be happy to work on that effort, but I am not really that interested in beautifying working code for a tutorial. 3. I think all of the Gimp Documentation should move to a Wiki. The biggest hole in the documentation is topics not being covered and coverage that is out of date. Lowering the threshold for people to contribute would be a great way to address this. A Wiki seems like it would allow for a larger amount of participation than the current method of converting things to HTML by hand. * My concern about moving the tutorial to a Wiki site, is whether it would get buried in a corner of the internet that no one can find. I certainly have no idea where this wiki is. It would be a shame to do the work of writing a tutorial and then put it where no one sees it.
* I think a Wiki format is great in that it can be kept current and follow the changes of Gimp. As I said, I think all of the documentation should be ported to a Wiki.

Anyway, if there are some specific things that need to be fixed, let me know and we can address them. I can be fairly flexible with changes, I just don't want to get into a loop - modifying code until someone like it. That has no real / specific goal.

If there is a documenation Wiki, let me know where to look, I would like to see what is there so far.

Thanks for all of your help!

Stephen

On 2/20/2014 1:03 PM, Pat David wrote:

Stephen,

Just a couple of notes. There are some concerns about the introduction of the term "macro" in the tutorial and the sense with which it's used.

Also, saul has asked me to relay to you: "have him look into the DIR-SEPARATOR constant. Using it would obviate about half of his code."

If you can take a look at DIR-SEPARATOR to see if perhaps it can help streamline things a bit, that would be great. I'm also hoping others might be able to chime in with other suggestions as well.

There is a consideration of moving this to the wiki as opposed to wgo as well.

On Thu, Feb 20, 2014 at 1:37 PM, Pat David > wrote:

Stephen,

I've converted the tutorial to HTML to fit the website. I've pushed it up along with the assets, and am now just waiting on someone to poke wgo for it to show up. Keep an eye on the tutorials page.

On Thu, Feb 20, 2014 at 1:29 PM, Stephen Kiel > wrote:

Pat,
Thanks. Let me know if there are any issues. Stephen

On Feb 20, 2014 7:27 AM, "Pat David" > wrote:

Hi Stephen!

You can just leave it as an ODT file. I'll make the stylistic changes required to fit the website HTML.

Give me a little time and I'll make the conversion and get it up to test.

Thanks for the contribution!

-- pat david
http://blog.patdavid.net

-- pat david
http://blog.patdavid.net

-- pat david
http://blog.patdavid.net

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/

Pat,

I did look into the DIR-SEPARATOR (DIR_SEPARATOR on python?) constant. It did not appear to be documented anywhere in the gimp docs that I could find with a search engine. From an old scheme script I found posted I was able to find the following:

The DIR-SEPARATOR constant appears to be just a "/" on platforms where the OS is Linux and "\" on platforms where the OS is Windows. The following is pasted from a Script-Fu Console and a Python-Fu Console (Linux).

**** Script-Fu Console*

Welcome to TinyScheme Copyright (c) Dimitrios Souflis
Script-Fu Console - Interactive Scheme Development

> (string-append "Yaba" DIR-SEPARATOR "Daba" DIR-SEPARATOR "Doo") "Yaba/Daba/Doo"

**** PYTHON CONSOLE*

GIMP 2.8.10 Python Console Python 2.7.5 (default, Feb 11 2014, 10:29:30) [GCC 4.8.2 20131212 (Red Hat 4.8.2-7)] >>> import os
>>> print os.sep
/
>>> from gimpfu import *
>>> print DIR_SEPARATOR
Traceback (most recent call last):
File "", line 1, in
NameError: name 'DIR_SEPARATOR' is not defined >>> print DIR-SEPARATOR
Traceback (most recent call last):
File "", line 1, in
NameError: name 'DIR' is not defined >>> if DIR_SEPARATOR == "/":
... print "YES"
...
Traceback (most recent call last):
File "", line 1, in
NameError: name 'DIR_SEPARATOR' is not defined >>>

In python, os.sep does the same job that we would expect from what we see in the scheme example except it has the following advantages:

1. It is documented 2. It has a wide user base, so it should be robust 3. It works in any python shell, so you can debug programs using wide range of tools.
4. It works.

It seems like os.sep would be a much better design choice **IF** we actually needed to determine a platform portable directory separator. As far as I can tell, we don't.

In the code I use python functions that take care of the separator. e.g.
srcFile = os.path.join(srcPath, srcFile) Python sticks in the right separator for the host OS.

From my point of view, it seems like using the DIR_SEPARATOR and manually concatenating strings would make the code clumsy. I did not see anywhere where knowing what the separator character was would be an advantage.

I wanted to keep the focus of the tutorial on Automation and not get sidetracked too much on design and architecture. It is worth while to note that if you can design a block of code (like autoBase.py) that does not use the gimpfu library, you can run it on any python shell and use any debugging tools at your disposal. This is a real advantage over debugging in Gimp. So I view using a gimp constant instead of a python library function (os.sep) as kind of a mistake.

Please let me know if I missed something.

Stephen

On 2/20/2014 1:03 PM, Pat David wrote:

Stephen,

Just a couple of notes. There are some concerns about the introduction of the term "macro" in the tutorial and the sense with which it's used.

Also, saul has asked me to relay to you: "have him look into the DIR-SEPARATOR constant. Using it would obviate about half of his code."

If you can take a look at DIR-SEPARATOR to see if perhaps it can help streamline things a bit, that would be great. I'm also hoping others might be able to chime in with other suggestions as well.

There is a consideration of moving this to the wiki as opposed to wgo as well.

On Thu, Feb 20, 2014 at 1:37 PM, Pat David > wrote:

Stephen,

I've converted the tutorial to HTML to fit the website. I've pushed it up along with the assets, and am now just waiting on someone to poke wgo for it to show up. Keep an eye on the tutorials page.

On Thu, Feb 20, 2014 at 1:29 PM, Stephen Kiel > wrote:

Pat,
Thanks. Let me know if there are any issues. Stephen

On Feb 20, 2014 7:27 AM, "Pat David" > wrote:

Hi Stephen!

You can just leave it as an ODT file. I'll make the stylistic changes required to fit the website HTML.

Give me a little time and I'll make the conversion and get it up to test.

Thanks for the contribution!

-- pat david
http://blog.patdavid.net

-- pat david
http://blog.patdavid.net

-- pat david
http://blog.patdavid.net

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/

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 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/

Saul,

Just a couple of quick additional comments on your feedback:

I would like to refer you to http://docs.gimp.org/2.8/en/gimp-using-script-fu-tutorial-identifier.htmland the examples in sections 3.2.1 and 3.2.6 with respect to your stylistic
comments #2 and #4 about parenthesis placement. The coding style in these sections looks more like mine.

You made a comment about the script-fu-register block "... For this reason it has been decided that this description should be limited to a single line of text[2]. ..." . The site
http://www.gimp.org/tutorials/Basic_Scheme/section 5 would have been a much more effective place to reflect that decision.

I did try again and was able to get the web site you mentioned to come up and found a long 7 year old discussion thread about blurbs. The thing is, no one would think to read through this to see if a decision or standard was ever reached. If the decision is important enough to matter, it needs to be documented on a web site that people are likely to find based on getting there with a search engine.

Thanks,

Stephen

On Tue, Feb 25, 2014 at 5:40 AM, Saul Goode wrote:

On Mon, Feb 24, 2014 at 9:36 PM, Pat David 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/