[ts-gen] A look behind the curtain; was: create & modify orders

[R P Herrold]

On Tue, 1 Apr 2008, Paul C wrote:

> Is it fair to say that the sctipts in exs/ and bin/includes 
> are the best guide to the latest command syntax? or is there 
> a simple way of extracting this from the source code (e.g. I 
> get the impression that 'open' has evolved to 'select open', 
> but throwing around a few greps in the src/ dir didn't get 
> me very far).

./bin/ and ./exs/ are the most end user friendly.  grepping 
through the source code would not turn up examples in 
comments, as that would be a place for 'rot'; the concept of 
'test-driven development' which Bill uses in the locus he is 
focusing on, and my use of test scripts in broad stroke 
really and truly are how we develop and test the shim.

My documentation building scripts, and Bills's as well, pull 
information out of the sources, or in my case, a running shim 
instance, to populate secondary source documents, but this is 
fragile.  Probably not a good place to start.

Bill's older post about using grep to drill down into 
headers, and the sources to follow data flows is quite 
technical, and is more for a person interested in the shim 
internals (which are really fascinating), but are so laden 
with detail, that they are not a practical way to discern the 
commands compared to studying the scripts.   Also the scripts 
are designed to be copied, tweaked, and used.


> So are you moving towards ruby instead of korn-shell for scripts, or
> does ksh have some significant advantage (e.g. coprocesses?) for
> interacting with the shim?
>
> It would be interesting to know how other list users interact with the
> shim.

Actually Bill wanted to use the korn shell because of its (to 
him) better support for co-processes; I use a mixture of bash, 
php, and perl scripts and the 'nix pipes and shell 
redirects, for lashed together 'throwaways'

>>   The mailing list archives
>> are the natural place that Bill and I can first present
>> examples of usage of the shim, and we hope the archives are
>> useful to members of the list
>
> Yes, I've found a number of useful posts in the archive and can see
> the value of some dialogue between list users.

As part of the writing process, I went through all list posts 
and all bugs, open and closed, in building flesh to hang on 
the outline of my writeup, bringing it up to date to reflect 
the then current syntax.

> I can appreciate the difficulty of documenting something that is
> changing.  Now that I know _what_ has changed, I find the docs quite
> useful.  I haven't yet gone as far as using the .tex files (did I read
> somewhere there is more info in the tex that doesn't make it to the
> pdf/html?).

Yes for Bill's content.  a trivial define restores the 
'missing' parts.  I don't think it is worth too much effort to 
do so, because that text will have rotted.

We try to turn around answers to questions from either Bill of 
me within a day on the mailing list, as an informal goal.

-- Russ herrold