November 2002

jds:

Woah. Chill.

You're missing the point. It's "HOWTO Encourage Women In Linux". Not "HOWTO Make Linux a Feminist Battleground" or "HOWTO Use Linux to Overthrow the Patriarchy". Val's HOWTO isn't there because Linux is meant to be about gender issues. It's there because there's less women involved in Linux than there could be. Don't misrepresent the message or intent of the HOWTO -- that wouldn't be truth, would it?

And you've got it backwards, anyway. The problem isn't a HOWTO that you fear will "Make Linux about gender." Of course gender should be irrelevant to Linux -- so why does the HOWTO exist?

It's because some people in the Linux, unwittingly or not, do make gender an issue. They treat women differently, make them feel uncomfortable, unwelcomed or even threatened. That, I think, is why Val wrote the HOWTO: to point out this problem and give ideas on how to correct it, so that gender isn't an issue for Linux. I think you, me and Val all agree that this is the way it should be.

Hacking:

Twisted 1.0 has been out for a while and no show-stoppers have been found... in fact the response has been quite positive. It's great to see the mailing-list become more active -- we're obviously getting more users.

1.0.1 is slowly arriving, with lots of nice little bits and pieces: the UDP API is better and will probably be marked stable soon, and the documentation is much better, in quantity, quality and presentation. It's been fun working with moshez on the doc generation stuff (which will be in the twisted.lore package of 1.0.1).

Oh! -- and z3p's ssh implementation, twisted.conch, is rocking. The client works beautifully -- running terminal programs, or doing CVS checkouts, or whatever. I still find it to be amazingly cool.

robilad:

Seems like I need to have a look at a reasonable documentation system that will let me generate man pages, info files, HTML and pdf docs all from one source.

I recommend Twisted's Lore package, which will be part of the imminent 1.0.1. Lore can output HTML and LaTeX (and thus ps and pdf) from XHTML source. Actually, it's a subset of XHTML, and it uses the class attribute alot to provide semantic rather than presentational markup, e.g:

... will return a <code class="API" base="twisted.internet.defer">Deferred</code>.

or:

You can footnote<span class="footnote">This is a footnote.</span> text.

It's currently geared towards Python docs, i.e. it can pretty-print python code and automatically link API references to epydoc's output, but is easily extensible. Docbook output is in the works (which in turn provides for info pages), and we have a man2lore utility, which is simple but sufficient for Twisted's manpages.

It does nice things like turn relative links to other HTML files into LaTeX cross-references, and so forth. It automatically creates a table of contents for the HTML output based on your H1, H2, etc tags. And a nice side-effect of using XHTML as source means that the unprocessed source document is directly viewable (although occasionally ugly, such as with footnotes (but stylesheets can help)), which is handy.

It's also quite small; there's only about 600 lines of source that does all this, and it includes a lint utility! So, it shouldn't be too scary to work with, even if you don't know Python. Feel free to ask about it on #twisted (on freenode) or the mailing list if you're interested, we'd be happy to help.

Hacking:

I was going to talk about the fun I've been having working on Lore, but I think I've probably covered that quite well already for this entry :)