On Jan 12, 2010, at 8:11 AM, Bryan Larsen wrote:
The Hobo project already uses two excellent mechanisms for document
creation.
1) agility uses a combination of git and markdown
2) many of the manual pages use rubydoctest, which uses markdown
The key advantage of both of these approaches is that the code
snippets contained within are executable code, and can be easily
verified or pulled out.
This does mean that it takes longer to create the document, but you
get most of it back while verifying and bug-fixing the document, and
it pays for itself in spades when updating the document for a new
version of Hobo or new features, et cetera.
I've not tried this, but it would be even better to have a mechanism
to directly include a chunk of code from another file, ie specify
"give me lines 24-40 from some/path/foo.rb, starts with 'class
Something'" - the last bit in the same spirit that diff/patch use
context to warn when things don't match up. That would be the ultimate
"make the examples match the book" technique.
Another advantage is that you don't need to learn another editor --
you need an editor with a good markdown mode. Luckily, the editor
you currently use for programming will probably work. Both emacs
and TextMate have good markdown modes, as will any popular ruby
programmer's editor.
I can't think of any reason that the same editors couldn't be used to
handle LaTeX - TextMate's got a sizable mode for it, and I remember
editing TeX code in emacs on a vt220... Certainly, Markdown is easier
for inexperienced users, but I doubt anybody who's afraid of
structured markup is hanging around here... :)
Luckily, it is not difficult to transcode between markdown and
LaTeX. It's easy to transcode from markdown to LaTeX, and is easy to
transcode from LaTeX to markdown if you agree on an appropriate
subset of LaTeX.
The biggest issue I could see in transcoding between the two is
getting the right figure / chapter markings in. Automatic figure
numbering, tables of contents and back/forward refs are some of the
major wins for TeX - no more stray references to "Figure XX" floating
around.
My other peeve with Markdown is the silly "internal emphasis" rule,
which tends to munge Ruby variable names. We've run into it on the
cookbook, and Github got so tired of tripping over it that they
dropped it in "GitHub-flavored Markdown". Maybe there's a workaround
for that?
Anyway, good to see some discussion about future book markup - I'm all
for anything that's *not* Word! :)
--Matt Jones
--
You received this message because you are subscribed to the Google Groups "Hobo
Users" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/hobousers?hl=en.
