On a programming manual for Lout

[Graham Douglas]

Hi All

This is a loooong post based on my
experiences to date with Lout. My
basic point is that Lout needs a proper 
programming manual. I will preface the 
following with by stating that I have great 
respect for the time + effort Jeff has put into 
*giving* us Lout and really appreciate the 
energy + time Uwe devotes to providing
free online help/support. 

OK...

Well, I just downloaded the entire Lout mailing list
archive using Adobe Acrobat -- it is a 23MB PDF file --
with all the hyperlinks working etc. Firstly, I
hope you don't mind me doing this Uwe, Jeff et al -- I
have a reason...

Over the next few months I am going to
*try* to edit together something which could
act as a *starting point* for a programming
manual. I hope to do this by structuring the posts 
to indicate what is needed (which topics keep 
coming up) and, hopefully, integrating some of 
Jeff's and Uwe's (and others) posts as well. 
Whether this is a really dumb thing to
do will become apparent as I get into the job...

My goal is to produce a printable book in PDF 
format, not a HTML-type FAQ thing (we need
decent graphics). This is *not* a disguised attempt 
to produce something I can make money from; 
by trying to do this I hope to get a better understanding 
of Lout, that's all -- and to make it available 
IF I GET IT DONE. Input from
others would be a huge encouragement.

There is obviously a copyright issue here, let
me address that. I will not identify ANYBODY
in the text (except by explicit request) and I will not 
make ANYTHING available (assuming I ever get it 
done, that is...) until it has been approved by expert eyes 
(hopefully, Jeff and Uwe will help here). 
If anyone has objections, please e-mail 
me at address@hidden and I will do my best
not include anything you have written.

I, personally, cannot write a programming manual 
because I simply don't know enough. But I do 
firmly believe that a programming book (tutorial-based) 
is an *absolute necessity* if this great piece of software
is to grow in popularity -- and be easier to use. Lout is 
just too good to ignore because of the frustrations 
encountered when trying to learn it. No disrespect 
meant at all Jeff, but it is frustrating.

Jeff has given us a great tool (+ documentation)
and Uwe gives freely of his time to answer questions; 
I'm extremely grateful to both of them
as I'm sure are many others. Expecting either
to give even more of their time to write a programming 
manual is asking too much -- despite the 
fact that it would be a *great thing* if  this were to happen
(and a saleable product would result).

For me, Lout seems to offer such potential but is,
in my personal opinion, severely hampered by the
lack of a full programming resource -- the need 
for such documentation is witnessed with TeX. 
Knuth wrote such a programming guide to TeX 
(whether one actually likes The TeXBook is 
another matter) and sold it, no doubt making a 
quite a few bucks -- AND WELL DESERVED 
TOO!

It is, I guess, unlikely (as I've said before) that 
commercial publishers will invest in books
about Lout because, obviously, the market
is so tiny. Lout deserves to achieve far greater
visibility and publishers might take note if
their authors actually start using Lout
to prepare their books. But, I would suggest, for 
more authors to do that Lout needs some extra 
documentation -- Catch 22!

If anyone has notes, examples, ideas for
topics to be covered, indeed ANYTHING 
that could contribute to eventually producing
a programming guide, please e-mail it to me
(as text please). Please don't send executable 
attachments, I simply delete ANY unknown 
attachment. Drop me a mail if you want to send
something sizeable (>50k, say), thanks. 

If anyone reading this has grasped a particular 
aspect of Lout (no matter how trivial you *think* 
it may be) and could spare a bit of time to
write it up ***I beg you to do so*** and 
send it to me. You never know how the tiny pieces
of this jigsaw could be completed by your input.
If in doubt, write it and send it. 

If you have Lout source code, please write some notes
explaining how it works and -- any problems you had; 
in particular, those aspects of Lout which initially confused 
you and the "Eureka moment" you had when you finally 
understood it (as I experienced with @Filter). 
I will identify you, **if requested**, in a general
list at the front of whatever I actually produce.

If I don't get any input/feedback at all, I will 
probably not do any more than prepare 
something for my own use because I'd tend 
to think "Why bother?"

Well, that's all. Please, please contribute
if you can. Pointless negative criticism is not
appreciated...

Cheers

Graham

===========================
The above reflects the opinions
of my employer because my 
employer is me ;-).
===========================