Open Source Documentation, Again

I had a whole blog entry written, but sadly the new and "improved" Blogger application appears to have eaten it. Personally I don't think they have improved the application, as ^Z after setting something to a block quote now appears to delete the complete entry contents, the preview is way less friendly in the new popup format, and the editor icons don't seem as intuitive as they used to. Overall I think I'd rather go back to the previous version, but there doesn't seem to be any way to do that.

Anyway, to cut a long story boring, I just wanted to point out that when I went to update my Cygwin installation (hoping that Python 2.6 and/or 3.1 would now be available, which sadly they aren't - where's Jason Tischler when you need him?) I got a parse error on the setup configuration file. No biggie, the setup program even pointed out that I probably needed to download a new copy, and when I did so the updated copy told me to read the Cygwin documentation to find out what I needed to know to update from 1.5 to 1.71 (I presume 1.6 was omitted for some reason).

Sadly when I went to the Cygwin home page the only relevant information I see is "PLEASE read the new User's Guide before upgrading your Cygwin installation to 1.7. You're avoiding trouble."

This is OK, but when I follow the link to the users' guide I get a list of three different possible formats plus links to two different quick start guides and another link to Setting Up Cygwin. It's only by clicking one of the users' guide links that I finally discover the link, in the table of contents, to What's new and what changed in Cygwin 1.7. Guess what? None of the information in there relates to upgrading from an earlier version, so I am left with the only hint being the note at the start of the home page that says

Please note that the update from Cygwin 1.5.x to Cygwin 1.7.x might require some manual changes afterwards. Most notably the mount point storage has been moved out of the registry into files. User mount points are NOT copied into the new user-specific /etc/fstab.d/$USER file. Rather, every user has to call the /bin/copy-user-registry-fstab shell script once after the update.

Now I don't want you to think that Cygwin's documentation is lousy. In fact the situation might seem less problematical if the documentation were worse, but generally Cygwin is up there with Python and Django in terms of the quality of its documentation. All of which only makes it seem more jarring that there is no specific advice to use migrators, even though the project home page seems to imply a) that there is, and b) that it's important to read it.

Anyway, I am going to finish this post now, before Blogger decides it's time to delete all my typing again. Happy New Year!

EDIT: Interestingly the original entry came through on Feedburner, but I decided to leave the revised entry as it was, modulo this edit. As is so often the case, a re-work improved the quality of the work.

For the Want of a Nail

We've all done it. One step forward, two steps back. I just thought I'd try to relieve my current frustrations by writing this particular sequence up. It's amazing the diversions and byroads you can end up taking to achieve an apparently simple goal (as I learned yet again last week in trying to accommodate Outlook on my SMTP server). This one started at PyCon, now four weeks in the past. So, bear in mind the goal: submit a Django documentation change.

At the Django sprint (of which, due to a family illness, I was only able to attend a truncated first day) I was struggling with an unstable laptop, so I managed to assign myself a documentation ticket, and that turned out to be pretty much it what with PSF responsibilities and needing to go home early. I have been working on the ticket since: it isn't a difficult issue, but I needed to learn a little more about how the Django database layers worked.

Having finally decided on the required change, during entry in the Django tracker I decided it would be much more developer-friendly if I were to provide the change in the form of a patch. This isn't really necessary but I figured it couldn't hurt, and that I should really be able to rebuild the documentation locally to be sure that any future changes were stylistically correct and didn't mangle what is, after all, quite good documentation.

This is where things started to get a little rough. Descending into the documentation directory I discover that it's driven by a Makefile. "No problem", I think, "I have Cygwin, I can build under that". So I type "make html" and discover I don't have make installed. This is quite normal, I like to keep Cygwin fairly lean, and I haven't previously done any Cygwin building on the new laptop.

So, I run the usually very cooperative Cygwin installation utility, and discover that my usual mirror site is providing very slow response. So slow, in fact [minor pause here to repair cable retraction mechanism on traveling mouse: this really is not my day] that several attempts to update my installation have to be abandoned, though it notes that several of my other installed applications should also be upgraded and has even managed to pull down some of the installers.

Eventually the fifth or sixth attempt gives me the dread message from Vista (how I hate this operating system, yet despite my best efforts there are tasks I currently still need it for) that the Cygwin installer "is not working correctly".

After a reboot and several further repeats, I eventually track this down to a corrupted /etc/setup/openshh.lst.gz file, and delete it. I establish contact with a different mirror and lo! The Cygwin installer now runs to completion, and I can run make. So I confidently re-enter "make html" and see the message

make: sphinx-build: Command not found

Fair enough, it shouldn't (I foolishly think, despite all the evidence that should by now have convinced me to set the computer aside for the day) take me long to get that up. As a first stab, before doing anything else, I type "easy_install sphinx-build". Hello, another even more interesting error message:

bash: /c/Python25/Scripts/easy_install: Permission denied

What? ls -l gives me the following rather unsavory news:

----------+ 1 sholden None 6656 Apr 2 10:33 /c/Python25/Scripts/easy_install

Damn, that can't be right? How did that happen? Well by this time I am past caring how it happened. I own the file, so I'll just reassert the correct permission, right? Wrong:

$ chmod 755 /c/Python25/Scripts/easy_install chmod: changing permissions of `/c/Python25/Scripts/easy_install': Permission denied

Now this is getting really annoying. Note how my problem has subtly changed from "how do I submit a Django documentation change" to "how do I get Cygwin to allow me to change the permissions on this file", and that I am now several steps further away from my original goal than I appeared to be at that happy moment when I set out to submit the change. Note also the assumption that running easy_install is actually necessary to solve my problem. If this had turned out to be wrong I would probably have shot myself, thereby relieving you of the task of reading this post.

Fortunately I quickly realize that this is the easy_setup from my Windows Python that I am trying to run, and that the solution is to run ez_setup.py with my Cygwin Python. [There are some who doubt the wisdom of doing this to a Python installation, but I am blasé beyond belief about such things]. So I run ez_setup.py, which installs setuptools. There is the minor annoyance that Cygwin refuses to recognize the correct version of easy_install and continues to run the Windows copy, but I solve that by opening a new Cygwin terminal window. Another final false start: the package required isn't called sphinx-build, so easy_setup can't load it. So I take another reasonable guess.

Now, finally, I run easy_install sphinx followed by make html, and in less time than it take to write a blog entry I have a local copy of the documentation that I can patch to my heart's content. Wonderful things, computers. When they do what you want.

Cygwin ssh-agent Control

[Edited: 10/6/08 Remove temporary files before starting a new agent]

Another little annoyance gone: all Cygwin processes now share a single ssh-agent instance, which is started up automatically as required. I picked this tip up from a now-forgotten blog. the only change required to that recipe being to re-order the redirections for the ssh-agent command. Since it took me a while to find (low Google-fu today?) I take the liberty of repeating it here so I don't forget it.

In your ~/.bashrc file add the following:

export SSH_AUTH_SOCK=/tmp/.ssh-socket

ssh-add -l >/dev/null 2>&1
if [ $? = 2 ]; then
# Exit status 2 means couldn't connect to ssh-agent; start one now
rm -rf /tmp/.ssh-*
ssh-agent -a $SSH_AUTH_SOCK >/tmp/.ssh-script
. /tmp/.ssh-script
echo $SSH_AGENT_PID >/tmp/.ssh-agent-pid
fi


function kill-agent {
pid=`cat /tmp/.ssh-agent-pid`
kill $pid
}


You can use Start | My Computer | Properties | Advanced | Environment Variables to add an environment variable called SSH_AUTH_SOCK whose value is /tmp/.ssh-socket to make the agent available to other Cygwin-aware processes you run under Windows.

That's better!

For some reason a number of posts were stuck in the blog as drafts. This one is from October last year.