Lars Wirzenius: February, 2005
Contents
- February 23: 1978 perspective on programmer office space
- February 20: Free software at last!
- February 19: Tools for converting DocBook to manual pages
- February 17: SoundConverter - new developer?
- February 15: Sheety music, BTS layout and typography
- February 09: Bologna
- February 08: I like windows, Huge release management discussion coming up?
- February 04: Electronic lab notebooks
- February 01: Phone books - just say no
Wednesday, February 23, 2005
Review: 1978 perspective on programmer office space
I just read IBM's Santa Teresa Laboratory — Architectural design for program development by Gerald McCue, from IBM Systems Journal, Volume 17, Number 1, 1978. It describes the design process and some of the design decisions made when IBM built its Santa Teresa facility. It is remarkable in two ways: firstly in the extreme care they took to make sure programmers were happy and productive, resulting in things that many later building projects have failed to achieve. Primary among these is private rooms for programmers, with most of them having windows with nice views. I have worked in open offices, with tens of people in the same hall, and they suck. Totally. Yet they are common and new ones are still being built.
Secondly, it is remarkable to see how much the details of the programming profession have changed in 25 years. No longer is it necessary to choose a table based on the size of line printer fanfold paper. Having lots of space for storing printouts, punch card stacks, and other form of data storage, is not a high priority anymore.
A most interesting read, therefore. Recommended.
Sunday, February 20, 2005
Hedgehog Lisp: Free software at last!
We have finally released Hedgehog as free software. We meant to do this a year ago, but there was always something else to do.
Hedgehog is a tiny Lisp implementation meant for embedded devices. It is its own dialect of Lisp, not Common Lisp or Scheme. I designed it, Kenneth Oksanen re-implemented it, and Oliotalo used to employ me to hack on this.
See http://hedgehog.oliotalo.fi/ for more details, including source code and an i386 Debian package. I may eventually upload Hedgehog to Debian proper, probably after sarge is released.
Saturday, February 19, 2005
Review: Tools for converting DocBook to manual pages
I decided recently that writing manual pages directly in roff markup is too tedious for me. I wrote my first manual page in 1989 or 1990, and have been producing them ever since. I still can't remember all the details, and getting all the formatting correct every time is still boring. So I'd like an alternative; others disagree, preferring to write in raw roff -man, and that's all right.
One of the alternatives is to use DocBook markup instead,
specifically the refentry element and its
children. I looked at docbook-to-man and
saw that it does, indeed, produce manual pages. Writing
DocBook markup is still slightly tedious, since elements
have such long names, but it is a lot easier than roff.
However, I was not happy with the output docbook-to-man
produces. So I wrote my own tool.
After I'd written about 380 lines of Python code, I figured that maybe someone else had also written something better than docbook-to-man. I found docbook2man and docbook2x-man. The following is a brief comparative review of the three.
I used a very simple file as input, evince.xml. It is short, and has only the minimal amount of content to actually be useful, but this is good for comparison purposes. Some results:
- Using the XML version instead of the SGML version works fine. I didn't use anything XML specific, like empty elements, however.
- Getting the DOCTYPE right is important. I'm not sure what I did is kosher, but at least it shuts the tools up.
- docbook-to-man and docbook2man copy spaces in the input file directly to the output file. In XML, using many spaces should in most cases be equivalent to using one, so the tools should compress them. docbook2x-man gets this right.
- docbook-to-man and docbook2x-man do not convert the name of the manual page to upper case.
- docbook-to-man requires dashes to be escaped in the input file. That is, it requires \- to be typed instead of - to get a dash instead of a hyphen. For pure ASCII output this doesn't matter, but for high quality typesetting or Unicode output it does. However, using roff escapes in XML source is the wrong way to do this. It is better for the tool to do the escaping. There needs to be a way in the XML source to specify a hyphen, however.
- docbook2man produces some spurious empty lines in the output. Some of them result in empty lines in the formatted manual page (as it comes out from the man command). This is ugly.
- docbook2x-man does not fully follow the font conventions described in (Debian's) man(7). For example, in the synopsis, replaceable parts should be in italics (which becomes underlined in terminal output). Also, when referring to the command, boldface is best practice.
- docbook2man puts extra spaces inside the brackets indicating an optional argument in synopsis.
- docbook-to-man and docbook2man format alternative names for an option on separate lines and with empty lines in between. docbook2x-man follows the more common style of putting them on the same line, separated by a comma. Separate lines would be reasonable, but the empty line is ugly.
- docbook-to-man and docbook2man render a ulink element so that both the url attribute and the contents of the element are in the output. If the url is duplicated in both in anticipation of a non-hypertext output format, which is fairly common, the output is quite ugly. The way docbook2man renders this also results in a line that groff has trouble rendering, resulting in a warning. docbook2x-man is more reasonable here, producing the url only once.
- docbook2man invents the date for the page footer. The input file has a date, but docbook2man replaces it with the date when the program is run, and, worse, outputs it in the locale it is run in. In my case, this resulted in a Finnish language date in an English language manual page. Not pretty, and potentially problematic with character sets.
- docbook-to-man(1) does not follow manual page conventions. It uses shell redirections in the synopsis, indicates that command line arguments are optional (they are not), does not capitalize a non-standard section (should arguably use a subsection) nor the "SEE ALSO" section, formats references to other manual pages incorrectly, etc.
- docbook2man produces not only the output file (into a named file, not the standard input) but also the files manpages.links and manpages.refs. This is ugly, to say the least.
- docbook2x-man(1) lacks descriptions of the options it uses, and instead only refers to programs it runs during the conversion. The synopsis uses braces to indicate non-optionality of command line arguments, and uses bulleted lists weirdly.
- docbook-to-man is implemented generic SGML tools and a custom 7000 line C program. docbook2man is shell and Perl scripts, mostly. docbook2x-man is XSLT, mostly.
My conclusion, based on this very small test: none of these three tools are perfect, but docbook2x-man is fairly good, and should be easy to tweak into near-perfection. The other two are clearly less good. In fact, I think they are so bad that they should be removed from Debian, unless further tests show that they can deal with input files that docbook2x-man can't.
I'm shelving my Python program, since there is no point in having a fourth program to do this. I may make some patches to tweak docbook2x-man, however.
Thursday, February 17, 2005
Random hacks: SoundConverter - new developer?
My SoundConverter program has not seen any development for some time now. Particularly MP3 encoding support would be nice, plus various tweaks to the user interface to make it follow the GNOME Human Interface Guidelines better. I'm sure there are other things as well that could be improved. I don't seem to find interest in it, however, since the program works quite well enough for me and I am quite busy enough with other projects.
Would someone like to take over it? It is a simple thing, written in Python, using PyGTK, libglade, and GStreamer. Mail me, if you're interested.
Tuesday, February 15, 2005
Random thought: Sheety music
I don't understand music, except in a very shallow listening-only sense. I don't understand musical notation. When I was put into piano school, after five weeks the teacher said it would be best if I stopped. However, I like typography, and if for no other reason, the Mutopia project is cool. They have sheet music, mostly classical. A bit like Project Gutenberg. Some people I've asked who understand something about music also say it looks cool.
Debian: BTS layout and typography
There was some discussion on IRC about ways to make the Debian bug tracking system's web interface nicer to use. I think it would be possible to achieve quite a bit with only small changes to the backend, by fixing some of the markup that is generated to be valid and to add a class attribute here and there. Then a CSS file can do the rest. I played around with this for a bit and created some samples of what an index page for a package could look like: the original, and my first, second, and third versions.
I did not have the time to do any major changes, like try table based approaches. It might be good for someone to write up or collect a few sample users and use cases and then start a redesign of the web interface.
Wednesday, February 09, 2005
Debian: Bologna
LocalGroups on wiki.debian.net lists various local Debian groups. Among them is this:
The Secret "Fetch Every DD Passing Thru Bologna and Take 'em To Dinner" Group
Location: Bologna, Italy
Description: Thou Shalt Not Pass For Bologna Without Gaining An Extra Kilo
I'd like to visit Italy some year. Now I have one more reason.
Tuesday, February 08, 2005
Random thought: I like windows
I really like windows. They are quite a practical way of allowing natural light to reach the inside of a house. Natural light looks better than flash light when you're photographing.
Debian: Huge release management discussion coming up?
For some time now, I've avoided talking about Debian release management except in very small gatherings of people. This is one of the topics that has a tendency to explode, resulting in very large and long discussions. Such discussions aren't useful right now, when we're working on getting sarge released. Large discussions distract from that.
I have today drawn a further conclusion about the issue: I don't know enough about Debian release management to talk usefully about it. I'm not sure anyone else does, either. I expect, however, that very soon after sarge is released, several Debian mailing lists will explode in volume with discussion about how to do release management better for etch. Those discussions are likely to last quite a while, and even if they happen not to degenerate into flame wars, the sheer volume will mean that they aren't going to be very productive. I have an idea for maybe avoiding that.
We could have free discussion about the topic for, say, one or two weeks. After this, the release management team will draft a proposal for how they intend to make the etch release happen, using any inputs from the discussion they like. This draft will then be discussed a further one or two weeks, and then the release management team will publish their final plan. This plan will be adhered to, to the letter, and without exception, and disobedience will be punished by expulsion from the ...
Er, sorry, I went into control freak mode there for a moment.
Let me try again: I think it would be good to at least try to put some structure into some of the more controversial discussions we have. In the case of release management, where we have a clearly identified team in charge, the structure might be that they make a draft and that is discussed, then they make a decision of how to proceed. That ends the discussion, until there is a need to change the plans.
This way, perhaps we could have more productive discussion than several weeks of open-ended flooding of debian-devel.
Friday, February 04, 2005
Random thought: Electronic lab notebooks
Researchers in academia or companies are usually required to keep a "lab journal" or "lab notebook", where they write down everything they do while they work. Every experiment, its method and results, regardless of whether it turned out to be a good idea or not. This is useful for, among other things, proving that you invented something or that you didn't.
Lab notebooks are kept on paper, preferably in bound books with numbered pages, so that it is clear that no pages are missing. Writing should be from one edge of a page to the next, so that nothing can be added. Each page should be signed daily or weekly by the researcher and someone else to prove dates. And so on; there are lots of things done to make it as likely as possible that the notebooks will be accepted as proof in a court of law.
For various reasons, I've been thinking about ways of doing this elecronically. What I've ended up with is this: the text for each day (or maybe week) is written in its own file, and that file is signed by the author, and then by someone else. In order to keep things secret, the other signer might sign only a detached signature of the original file, or its encrypted version. Files are named with consecutive numbers so that it is clear that nothing is missing (one might not work every day).
This might even be automated, to some degree. I think it would work, but it is anyone's guess whether it would hold up in court. Depends on the court, I assume.
Tuesday, February 01, 2005
Rant: Phone books - just say no
The main phone company in Helsinki, the one that publishes the phone book (there are a couple of competitors now), has decided to distribute it to every household in the area. In former days, it was only distributed to households that had a landline from them, but since they essentially had a monopoly, that included everyone with a phone. Mobile phones changed that. These days, many people have only a mobile phone and no landline at allt; I'm one of these people. I have never used the phone book much, and have not regretted not having it since I gave up my landline. I rarely need to find a phone number and when I do, the Internet works fine. So I wouldn't accept the phone book when the distributors rang my door bell. This rather surprised the distributors, but they got the message in the end.
On the whole, I rather think the phone book needs to go away. It is published only once per year, which means that a fair amount of its data goes out of date before the next one appears. Since the same data can already be found via Internet services or the (old!) number information service (via voice calls or SMS), making books of several kilograms per household in the greater Helsinki area is a real waste of natural resources.
The phone book is a relic. Its proper place is the museum.