[Detail of the nymphs on folio 78r of the Voynich Manuscript Beinecke Rare Book & Manuscript Library, Yale University, New Haven, Connecticut, USA.
And so July is done, and the dog days of August are upon us, here on the Eastern Seaboard of North America. July was not as steamy as she could be, the latter two weeks being rather mild, and for some days with dew points in the mid to low 60°s Fahrenheit, ‘Fahrenheit,’ children, one of the many measures from the days of yore that we Americans still treasure.
I have been more sketching and planning than writing: getting grist for the mill. Thus, little came out through the door in July:
*do…while was unearthed from the 1.6x antiquities; I retained, but updated, its extended example on lightning bolts.
*for…done slipped past the door in the waning hours of 31 July. It freights a sidebar on Variance. One might notice a pattern in these workaday control flow commands: they are a good setting to slip in a little image theory. Not much, but a little. G’MIC does not operate in a vacuum; where possible, making home for an interesting or vital concept is intent on connecting the language with its world. Hopefully, this is not too painful.
@KaRo made an interesting remark on documenting when a document comes into being. Still uncomfortably aware of how much 1.6x documentation is still being taken seriously, I felt it responsible for me to begin dating these tutorials, now that Git so nicely records their development histories. Going forward, I will date the new and retrodate the older in the 2.9x series. There’s little to be done about the 1.6x series but rewrite them out of existence, for they are pure HTML with no backing originals.
It may not have been his intention, but in post 60 of this thread @Reptorian bought to the fore a responsibility where I have been remiss, so it seems worth my while to address that shortcoming now in these lackadaisical dog days of August, before the quickening press of September is upon us: by what principles am I guided to write these tutorials, in particular, a script coding style that I term “Tutorial writing?”
In fact, I have quite strong opinions on the matter, ones that favor redundancy over reduction, and I don’t want the vigour to which I hold these principles to translate in anyway to a seeming rebuff of the good @Reptorian, who is going about around here as he often does by being helpful. First and foremost, I want to make clear that I appreciate his helpfulness, hope to benefit more from it, and generally celebrate his being around.
That said, I should like to express my intent that explicit -input notation, hyphen-and-all, will be part of G’MIC tutorials so long as I have any part in the endeavor. The reasons, I think, are unassailable — but I have made no effort to advance what those reasons are, for which I have been remiss. So thank you @Reptorian, for bringing the matter to the fore, and what better place to do it than here in Tutorial Fragments?
To the rest of you developing twitches in the face of exciting discussions on Documentation Standards, I bid you a fair adieu, but before you drop entirely from the thread allow me to leave you with this: Clarity matters. In writing code, it is bearing in mind that someone will be reading it. Presuming you’ve done anything useful at all, it will be read, and if it is to serve as an agent to advance this particular craft, then it should be as readable as your skills can make it. That may entail coding in a style not quite so reduced as personal habit leads. That’s it. Drop now, and fair thee well.
One or two still here. Gee. Must be a slow day at the Krusty Krab. Very well then. Last March I went to some length about the process of tutorial writing Post 28, Instructions to help writing reference documentation, somewhat centered on how hard it is to get out of bed and find the bathroom, let alone write anything useful. What I didn’t address over there, but will here, is G’MIC’s recondite coding style, at once its strength and encroaching weakness. Fortunately, G’MIC’s design has a great deal of influence on coding style, such that one can, with deliberation and foresight, code in a way that avoids the allure of reduction in favor of redundancy. The trick, I think, turns on the realization that code can be read. Realizing that, one can then proceed to have her code deliberately read. It is a sociable thing to do, which is more than being pleasant. As I noted last month, those who have an initial success in steering G’MIC to do something useful enjoy a rewarding sense of accomplishment — and so they set out to do more. Conversely, those who hit brick walls are just motivated to use something else. G’MIC’s survival in the Darwinist world of open source depends on lots of little successes just like that. The key then, is engineering successes just like that.
Some time ago, @David_Tschumperle made clear his design goals for the G’MIC command line interpreter. See Looking back at 10 years of development. The two design goals were conciseness and coherence. By implementing highly consistent parsing rules, the G’MIC team in the days of yore achieved coherence, which furnishes a foundation for conciseness. With conciseness, we may routinely omit -input, say, and, given the coherent parsing rules that underlie command line parsing, nothing untoward happens: the command line parser quietly infers -input where it could have been and, if the pipeline is not too infested with typos, misconstructions or malapropisms, proceeds on its merry way. Through its substitution rules, G’MIC consolidates at levels approaching Forth: normalize → n, set → =, input → , among others, and if the out-of-the-box syncopations do not suffice, one may write <shortname> : <long form> substitutions — Adding Custom Commands in a nutshell — reducing, say, turbulence to mxup via a mxup : turbulence $* customization or some such.
In very short order, many sense the Game: consolidating code as a kind of solitaire, one that engenders enormous satisfaction in puzzling out how little one may write to do a lot.
This Game is not peculiar to G’MIC. It may be played with any language, computer or natural, and to serve pragmatic ends. I am sure many of you have heard the writers’ lament: “I am sorry I wrote you such a long letter; I did not have time to write a short one.” There is much time consumed in clarifying ideas so that words don’t get in the way: pouring through dictionaries to find that one nugget which dissolves a phrase, crafting apt transitions to burn down bridging paragraphs, sifting through similes and metaphores for just those that crystalize ideas shimmering on the edge of perception. It is a labor writers must do in the service of their readers, who, like all souls, live with time-and-space constraints and cannot spend forever reading a ramble. But it is also a labor in which writers take a great deal of pleasure, for it is again just the Game, and the Game’s condense-and-consolidate puzzles exercise our intellects and provide the thrill of the chase. Truth be told, I wouldn’t have it any other way. It would be churlish of me, therefore, to lodge any sort of complaint against the reduced-form of G’MIC coding, especially since I practice it myself, with all the childish delight of a chimpanzee in a poo fight. But — Alas! — The road to Hell is paved with good intentions. For all the good intentions behind the sophisticated and varied substitution rules underlying the most abbreviated, yet effective, G’MIC command, these very rules raise not an inconsiderable barrier to newcomers, whose oft-time response is this:
[quote=“punchcard, post:29, topic:9966”]
Did you ever create a filter or other GMic method to create these tilings? I’m having trouble figuring out the GMic commands because everyone uses single letter commands and no comments.[/quote]
The flip side of Reduction is Redundancy — pehaps the Anti-Game. Those who train themselves on writing a little to do a lot look upon Redundancy with not a little displeasure. Among cognoscenti conversing in the cloister there is indeed an ingrained resistance to perceived excess. However, the Hubble Space Telescope is still useful as of this writing because of triply-redundant systems. Commercial twin-engine aircraft can still get to an airport with just one engine. No one is suggesting, however, that this one engine suffices, because getting to an airport with no engines is hard.
The triply-redunant regimen taught to me is in pyramid form: “Tell 'em what you’re going to tell them. Tell 'em. Then, tell 'em what you told 'em.” The first part, the pinnacle, is a very concise précis about ‘Foo’, calibrated at just below the TL;DR tripwire. For semi-seasoned readers needing reminders, the first part triggers: “Ah! Foo! I remember Foo. I just need to get the Bar piece and then I’m good to go.” So the semi-seasoned peel away, leaving those still at sea with the middle part of the pyramid. In the middle part, we unpack Foo, present its relation to Bar, go over why Foo needs Bar while Bar may not need Foo, but heaven help you if you try to go through life without Foo, only Bar. At this juncture we hope to have cleared the hall but there are still stragglers in the cheap seats, way up in God’s Country, and the blank expressions on their faces tell you they Just Don’t Get It. Knowledge has a chiral character and a right-handed unpacking of Foo only works for some. So in the bottom part of the pyramid we unpack Foo again, only left-handedly: different words, new similes, slower unwindings and at a finer grain, and we leave Determinants to the last: the folk with left-handed brains always seem to struggle with Determinants.
There are more than a few Darwinists around perfectly willing to tell those at the bottom of the pyramid to just bugger off; pay people to give you the basics and come back here when you know how to ask a question. There is an economic side to how much time one can invest in walking people up a curve and it is a question with which I constantly struggle, for it has no clean resolution. My judgements in this matter tend to be provisional and are case-specific. For G’MIC, from which I took about a five year hiatus, my provisional judgement is grounded upon sobering observations when I came back: a community that has grown not that much in the intervening years — maybe it has shrunk! — and that withall suffers from the stress assailing many open-source projects: the participants are highly skilled and, for the talented, the commercial world has plenty of money. That, and the tendency of more experienced participants for acquiring greater responsibilities as their careers progress. So @David_Tschumperle’s cautionaries in Some news from the G’MIC developers’ corner! are unsettling but not surprising. These, too, are Darwinist pressures: a project either takes up new people to assume the load from those being drawn away — or it doesn’t. Full stop.
These issues are far larger than I am, so it comes to the piece that I can manage. It is this: technical communication, harnessed to draw in newcomers. It is what I do best and I can be at it as long as my health holds up and the City of New York doesn’t roll off the Eastern Seaboard. I find it quite remarkable, and very much to the credit of G’MIC development, that the language can be written at a variety of compression levels, from verbose to terse. Its curse is its salvation, the twain in ways depends upon intent. Any mature and intelligent practitioner of a craft knows when it is time to pick the right kit for the job.
For private experimentation, and perhaps communication with fellow cognoscenti, terse is fine, and, in fact, is the proper and polite way to go. One does not bore friends with redundancy. But in a more public sphere, with the aim to establish and advance acceptance for a craft, then clarity matters, and clarity is necessary for any active intent to communicate. Lacking that, the work becomes a latter day Voynich Manuscript, its somber mystery of little practical use in the advance of craft. So in the Tutorial sphere, I shall be the curmudgeonly guardian for the verbose Tutorial style, insistent on hyphens, full command spellings, named images and descriptive variable names, for all these offer clues of intent and engender readability. In time, perhaps, the student discovers the allure of syncopation, senses the Game, sees how little she can get away in typing and still pull off the trick. I will pretend not to notice. And if I think no one is looking, may hazard a smile.
).
since '15a.