Well, some about the handbook. This note is intended to be sufficient for anyone faced with a request to check, and edit if necessary, a bit of the handbook. It isn't technical documentation. Indeed, there isn't much firm technical documentation, though there are several notes which I've written down to summarise my experiences. ( These are listed down below somewhere. )
The handbook is really three handbooks : the undergraduate printed handbook, the graduate printed handbook, and the www handbook. My major accomplishment so far has been to integrate these into a single operation with some sort of standardisation throughout; that means that I can automate parts of the task of constructing the handbooks, which both saves work ( except that at the moment it makes far more than it saves, but in the long run ... ) and is a good deal more reliable. And eventually, I hope, faster.
The theory is that you give me the raw information about yourself, your courses, and such other handbook material as you control because of the various responsibilities you have in the department, and I look after the formatting and presentation in the three forms. I shouldn't need to point out to experienced computists such as yourselves that unless you give me your garbage to put in, I can't get my garbage out, but years of experience suggests that not everyone has absorbed this axiom.
The first year with the new organisation ( 1997 ) was frankly experimental; nevertheless, it went not too badly. Since then, things have improved a bit every year - from my point of view if not from yours, but I think everyone has won a bit. The system is now very complex ( for good reasons, I think, but I continue to work at it ), but almost all automatic at the low level. I still push things along at a higher level, but most of the sordid details are done by scripts for awk and shell, and stuff like that.
It follows that the material you send is now untouched by any vestige of intelligence as it works through the system. ( "What has changed ?", you might say. ) If anything you send requires intelligent handling, don't send it to inco; I'll return to this point later, but if in doubt ask me in person. Whether that will guarantee intelligent handling remains to be seen, but it's a step in the right direction.
As the handbook material has to be formatted in different ways in the different editions, and to make it useful as a reasonably general database for other purposes, the raw information is kept in a set of simple text mark-up files. I use a mark-up language of my invention, simply to make sure that I'm in a semblance of control. This marks different sorts of information, and things like local type styles where necessary. ( Styles are only necessary if they come in the middle of text; in most other cases, the type style used is implied by the document format. )
The mark-up files with which you might be concerned are :
Some other files have some relevance to the operation, but real people don't see them. Examples are :
All that gives me enough information in principle to automate the whole handbook procedure. Once I've collected the information, it's organised by large quantities of awk. Final formatting for the text handbooks is handled by Word macros, but the HTML files are completely done by awk.
Then there's some proof-reading. This is tackled by a set of experts chosen without favouritism from whoever the HoD thinks looks likely. It is supposed to include the HoD ( who is officially the editor, for what that's worth ), and has so far included the information coordinator for no better reason than that he's there and tediously literate. This is mainly to look for wide range coherence and completeness, and last year resulted in one or two twiddles and some reordering.
And that's it. All over bar the printing, and HTMLing, should there be such a word.
So now you see how your valued contributions fit into the system. Your chance to contribute begins when I send you by E-mail a request for information. Perhaps you will receive several requests, depending on your responsibilities in the department; if you work here, you should certainly receive one, in connection with your entry in the people file. ( If you don't receive that one, perhaps you should check with the registry that you do work here. )
Each such request will ( well, should ) be accompanied by either last year's material for editing, or some sort of indication of what's expected in case of a new item of some sort. The material you receive might include objects of several sorts :
It is possible to have double-semester courses, which - curiously enough - last for two semesters. These used to have names like 415.380DC, which made sense. ( All our double-semester courses are projects, at the moment. ) We should now therefore call them COMPSCI380DC, shouldn't we ? But we don't. Someone somewhere in the university has contrived to saddle us with software which can't cope with it, and is cast in high-tensile steel so can't be changed. Therefore, instead of writing COMPSCI 380 DC we are expected to write COMPSCI 380A FC and COMPSCI 380B SC. By this ingenious stratagem, someone somewhere has not only destroyed a reasonably sensible systematic notation, but has also significantly complicated the task of dealing with course numbers automatically.
Therefore PLEASE STICK TO THE ORIGINAL D NOTATION. It is far easier for inco to deal with courses if they are sensibly described, and then to rewrite the numbers in the stupid new way just before printing.
For each request, the intention is that you EDIT it and reply. I have tried to make this as easy for you as I can, and and the system is designed so that if you simply REPLY to the message as it appears, make any changes you think fit, or none if that's what you want, then QUEUE the result, it will all work.
That seems to work with most E-mail software. I assume that the Subject line of the reply is much the same as that of the original - the critical bit is the part between "|+" and "+|", which should not be changed; I can cope with minor changes ( "Re :", etc. ). I can also cope with line prefixes ( ">", etc. ) which the mail software inserts in the body of the reply.
I can also cope if you reply in HTML, but I hope you won't, because I'm not so confident about my awk that supposedly does the automatic conversion. I put it in last year because several people seemed to delight in messing up the simple model of text, and it seems to work ....
If you want to reply in any other way, please do your best to make it look like a straight reply to the original message - in particular, get the message's Subject right, and keep to the formatting pattern as marked by the mark-up symbols and lines of ====== in the message, and keep it machine-readable in simple text with no significant styles. So the easy thing to just to reply to the E-mail .....
| If you don't, it is true that the world will not come to an end. You will feel little or no pain. But I shall feel pain, because I have to sort out the mess. It has cost me many hours over the years sorting out the havoc wrought by well-meaning colleagues who evidently thought that they knew better than I did how my system worked. For the record, they were all wrong. ( Naturally, I reject absolutely any suggestion that they just didn't care that they were making me a lot of work. My colleagues aren't like that. ) |
.... but when I say "reply" I mean "REPLY". Use the automatic reply on your mail software to make sure that I get it all back again. I want it all back even if you made no change. Look, it's easier than deleting it. PLEASE DO NOT :
Last year's entry will NOT miraculously reappear; I don't edit the old file, I make a new one from your reply. ( Because : it's safer ( I'm much less likely to mess up the original file ); it ensures that items which should be omitted from last year's collection are omitted; and it guarantees that everything that appears in the new edition really has been vetted by the expert concerned. )
If you really can't see how to do something, talk to me - Alan, not inco - and we can work something out. I do want to produce helpful material, and if my strange devices get in the way of that, then let's do something about it.
|
"Why does he go on so ?", they ask themselves. "Because",
I reply, patiently, "I don't know any other way to get the message across". ( Experience shows that that sentence still works without the "other". ) Of
course, you do it right, but many of your highly intelligent colleagues
do not read the messages attached to the mail I send them.
|
| The original point of all this was not merely to bully you, but to get you trained for the eventual change to the more automatic system, which would be even less intelligent than I am. Now the more automatic system is here, and nothing has changed. Heigh ho. |
That's all general information. There's some more specific information about a subset of the files. It's supposed to help you to compose your replies to my importunate electronic mail messages. The size of the subset will increase as I get round to writing the stuff. So far, it is { the people file; the courses file; the other stuff }.
Need I say more ? Probably, but I don't know what it is. If you have difficulty, please tell me.
Happy handbooks !
These are my other writings on the handbook exercise. They're not formal, as befits a project still very much in the throes of development, but they record my state of mind at about the time when they were written. You're welcome to look, and comments and suggestions are invited.
| WN111 | Information structures | May, 1997 |
| WN115 | Background for a document generator | September, 1997 |
| WN117 | Designing the document factory | November, 1997 |
| WN118 | Making the HTML version of the handbooks | December, 1997 |
| WN119 | Going back again | December, 1997 |
| WN120 | Handbook preparation : the future ( perhaps ) | December, 1997 |
| WN127 | Lessons from the 1998 handbook exercise | February, 1999 |
Alan Creak,
2000 October.
Go to me;
Go to information central;
Go to Computer Science.