Coping with the local shell is a perennial issue. It processes whatever is typed at the shell prompt before G’MIC even sees the command line string. Tutorial Land has a Custom Cheat which attempts to address this issue. Since shell prepossessing is a source of frustration for many a beginning script writer, I am thinking of moving some form of this cautionary way up front: to Start Here. Since the Technical Reference links to this page, its readers can benefit from such an early warning — so long as they follow the link.
Possibly, before offering such a link, the Technical Reference should have a terse warning of its own. Something to the effect of:
Be advised that the examples in this Reference are subject to shell preprocessing; successfully executing many examples calls for being familiar with your shell’s special characters and escaping them accordingly.
Alternatively, consider writing a small Custom Command to encapsulate the example. This bypasses most shell interaction. The tutorial outlines the basic approach.
Perhaps this is too verbose for the Technical Reference. But something like this could live in the more verbose tutorial guide, and the Reference can link to it.
will work as expected.
These examples are examples of use of the G’MIC language, not examples of shell commands.
There’s no point in giving examples of command lines running in a terminal if you don’t say which terminal it is (there are dozens of different terminals, each with its own specific features).
For a reference documentation, it is just not possible to give example that are working with all possible terminals. It’s not a question of ‘it should be working’, or not. It is just not possible to have this.
The examples accompanying The List of Commands illustrate the use of the G’MIC language and are written as they would appear in a custom command. While some examples may work if entered directly at a shell prompt, there is no guarantee. No attempt has been made to escape special characters in these examples, which many shells reserve… _
The “Start Here” page, which one lands upon by following the Tutorial link, will be so modified to explicitly present a template for a “finger exercise”. This template is drawn directly from what @David_Tschumperle illustrated with custom command foo in Post 129 and the accompanying advice would suggest that a “finger exercise” is the easiest way to bypass most shell peculiarities. When the beginner lights upon a Technical Reference command description, they would be guided in how to turn that example into a finger exercise.
I’ll set about to do this at the next Tutorial upgrade, probably just after the Ides of June.
Ah me. With my suggestion, I have induced @David_Tschumperle to open a can of worms:
this ‘List of Commands’ illustrate the use of the G’MIC language and are written as they would appear in a custom command.
Except, with $ gmic preceding most of the examples, there is the decided indication of a command line being in use, and not the interior of a custom command. So much for consistency in aims…
Suggesting to adjust nine hundred or so commands is just my quaint little way of celebrating the 79th anniversary of the Invasion of Normandy, which is today, and marking one of the largest logistic exercises taken up in modern times. So, patching 900 or so commands? Pfft! Nothing compared to other kerfuffles that have taken place in and around Caen.
I think I shall be experimenting with some Emacs macros tonight, some of which have turned similar format automation tricks for me in times past, including line wraps for A4 paper. And yes, gmic_stdlib.gmic also underlies the -help command entries, as well as the Technical Reference, so a bit of care is in order. Might offer up trial patches along these lines this coming weekend. Cheers!
I guess a solution regarding syntax difference per shell is to write a Python script that would address those limitations when it comes, and have user select shell example choices. I could do a bit of that via Python and regex as now I know how to use Python to automate G’MIC coding. But, I think that’s just way too much regardless. Maybe later I could help on that, but between G’MIC things and other things I like doing, consider me out on that.
One simple trick for Linux :
If your G’MIC command line does not use the single quote character ', then using command run is a good way to execute commands :
$ gmic run 'sp , repeat 9 +rotate[0] {$>*36},1,0,50%,50% done add div 10'
The idea behind presenting examples in the Technical Reference as custom commands — rather than as shell command lines — is to place to one side issues arising from the transformations that shell preprocessing performs on command line strings before G’MIC even sees the string. As you all know, the two processors collide over many special characters: $, {, }, and so forth, that they share compete over.
At the top of this discussion @samj observed that many of the of the Technical Reference examples as written fail to work. Well, yes, that when the example is tried, whatever shell is in the mix has first rights on processing command lines and gets to do its substitutions and transformations first, then the transformed string is given over to gmic. As is often the case, that transformed string is no longer the example as written and failures arise because the transformations that the outer shell has done do not accommodate G’MIC syntax.
It is certainly the case that that the G’MIC run command, given a single-quote verbatim string that happens to be a pipeline, lays to rest many shell-conflict issues, so long as the shell in question recognizes the single-quote verbatim notation as a string to be passed — untransformed — to the application. Windows PowerShell does, and on Linux, so does the bash shell. The nice aspect of the run command is that it rather creates a temporary custom command on-the-fly. (use gmic debug… to see the show), so it is not so much different from the scheme of writing a Technical Reference example as a small custom command. Using run may be the way to go if I could convince myself that the vast majority of shells support verbatim strings and that the convention of introducing them with single quotes is de rigueur. Alas, there may be shells out there… That uncertainty keeps me in the camp of illustrating examples with small custom commands.
Note that I used single quotes here to delimitate the single run argument, but double quotes work also most of the time (except when I have to use the devil ! character that is still substituted by something, at least with bash).
@David_Tschumperle :
Feature request. Would it be possible to modify the (undocumented) G’MIC reference command so that it renders the specially formatted comment string:
#@cli : $ <example command>
more-or-less in the same manner across all the supported output modes: (help command ascii, HTML, PDF)? Currently, PDF renders in an outlier fashion:
in that the PDF renderer is inserting a $ gmic in front of <example command>, suggesting to readers of the PDF document that the given examples are to typed onto a shell command line, thereby subjecting themselves to all the command line issues that have been aired on this thread thus far.
$ gmic help blur
blur (+):
std_deviation>=0[%],_boundary_conditions,_kernel |
axes,std_deviation>=0[%],_boundary_conditions,_kernel
Blur selected images by a deriche or gaussian filter (recursive
implementation).
(equivalent to shortcut command 'b').
'boundary_conditions' can be { 0=dirichlet | 1=neumann | 2=periodic |
3=mirror }.
'kernel' can be { 0=deriche | 1=gaussian }.
When specified, argument 'axes' is a sequence of { x | y | z | c }.
Specifying one axis multiple times apply also the blur multiple times.
Default values: 'boundary_conditions=1' and 'kernel=1'.
Example:
[#1] image.jpg +blur 5,0 +blur[0] 5,1
[#2] image.jpg +blur y,10%
Tutorial: https://gmic.eu/oldtutorial/_blur
Do not insert $ gmic in front of <example command>, so those venues are agnostic about the larger context. In so far as HTML or ASCII rendering goes, the <example command> may very well be in a command definition module or embedded in the verbatim string of a run command. If PDF rendering can be bought into alignment with this, then we will not be unintentionally leading the PDF readers astray regarding the shell command line.
As for the formatting issue that @samj raised, that some examples are overly long and are clipped on the right hand side in the PDF document, I do not see any straightforward fixes. PDF is the least forgiving on right-hand-margin overruns; the issue is not that apparent in help ASCII or HTML rendering.