How BibDesk generates Apple Help and a web manual
Tuesday 16 February 2010 - Filed under Uncategorized
This is something that had been on my old blog in 2006 and went away, so I’m reposting something I wrote to the macsb list a few years ago:
For the BibDesk open source project, we wanted to have legit in-app apple help, as well as a web page (and PDF), without maintaining separate sources, since we were all working out of spare time.
We tried a few free options, and eventually worked out something decent with Texinfo, a latex-like markup language that can be processed into latex (and then PDF) or HTML.
I wrote a custom init file to have the (standard) texi2html script print out apple help compatible HTML. One post-processing script and a simple xcode script build phase later, and we get apple help.
We also get a version a little more suitable for the web (more content per page) from the same source: http://bibdesk.sf.net/manual/
It’s worked well for a couple of years, and it’s a good choice if you don’t mind learning texinfo (it’s pretty nice compared to writing in Docbook or HTML, IMO), and very good for version-controlled collaboration, since it’s just text.
For an example, here’s what the help source text looks like:
http://bibdesk.svn.sourceforge.net/viewvc/bibdesk/trunk/bibdesk/English.lproj/BibDesk%20Help/bibdesk.texi?view=markup
The init file and other stuff is here: http://bibdesk.svn.sourceforge.net/viewvc/bibdesk/trunk/bibdesk/BibDesk%20Help/
If anyone’s curious about it, feel free to ask me questions here. I’ll try to remember how it works.
2010-02-16 » mike
21 February 2010 @ 8:21 pm
I had a similar problem in my project (also creating Apple Help pages), although I was mostly just looking for something that was more compact to maintain than HTML.
I found Textile: http://en.wikipedia.org/wiki/Textile_(markup_language)
Specifically, the pytextile tool: http://code.google.com/p/pytextile/
Like in your case, I still felt that I needed a processing script and build step to make the most complete web pages.
But in terms of input, the Textile format is pretty trivial; the most common page elements are reduced to one or two prefix characters most of the time, e.g. a list bullet is a “*”, a heading might be “h1.”. And raw HTML can be directly embedded for corner cases.
The other neat thing about the language is that it interprets intent pretty well, e.g. if you were to type “2 x 3″, it would assume that the “x” should become the Unicode multiplication sign in the HTML output; similarly, it handles curly quotes and other conversions implicitly from a raw ASCII line.