AMK's Journal

I've been away on two weekend trips, and checking in on the progress of the Privacy Handbook re-licensing. I am not optimistic; the FSF doesn't seem impressed by the need to change the document's license.

I was pointed to an old repository of the Handbook that may pre-date the copyright transfer to the FSF, but this is starting to get increasingly archaic -- do I want to assess the even-more-outdated SGML in this old repository and re-convert it?

Frankly, if I'd just started writing a new GnuPG tutorial back in September, I would probably have finished a first draft at this point. So I'm going to start thinking about the outline for a new GnuPG introduction.

Ideas:

• Limit conceptual explanation of cryptography to the high-level; don't bother explaining hash functions, symmetric ciphers, etc.
  
• Try to avoid suggesting overrides to GnuPG's config; instead, we should trust that GnuPG has sensible defaults.
  
• Encourage people to use mailer integration. Don't try to document the various GUIs; just link to them.
  

Possible outline:

1. Cryptography and GnuPG concepts.
2. Generating a key.
3. Using GnuPG in your e-mail program.
4. Using GnuPG from the command line. (Possibly make this an appendix?)
5. Managing your keys.

Sunday I worked on translating the Docbook form of the GNU Privacy Handbook to Emacs org-mode. I didn't try to script it or parse the SGML at all, but just copied the original manual.sgml file to manual.org and began whacking
away at it in Emacs, doing search-and-replaces and manual editing to translate between the two markups.

Docbook provides minutely detailed markup. In a code example, you can mark the system prompt by <prompt></prompt> and the user's typing by <userinput>. All these details are discarded by the translation to org-mode, which only offers the basic formatting of emphasis, italic, monospace, and a few other styles.

I'm working on a branch called akuchling-modernize in my new gph repository on github. The next step will be to apply a patch to make various small updates that's been sent to me. The patch is probably old enough that it's slightly out of date, so then I'll start reading through the document
and consider what revisions I want to make. I also need to figure out what to do for a glossary; the Docbook has a <firstterm> element marking the first use of a term. For now I've left them in. I don't know if I should add a glossary section or just link to the new FAQ.

The existing GnuPG FAQ is very outdated, referring to versions such as 1.0.4 that were released around 2001. Rob Hansen is working on a new FAQ. Today I read through the XML source for the new FAQ, made a bunch of edits and fixes, and filed a pull request. Once that's accepted, the next step will be to write some of the entries that currently only have FIXME.