About three weeks ago I wrote that one of my goals was to make it easy to generate versions of my book using custom colors, in part because approximately 10% of the male population suffers from some kind of color blindness. Since that time, I find that achieving this goal has become increasingly important to me. Most of the world's problems are beyond my control, but this I can do something about. I concluded before that wanting to offer color customization on a per-copy basis pretty much commits me to markup-based authoring, a commitment I don't have much enthusiasm for, but the inconveniences associated with markup-based authoring can't compare with the inconveniences associated with color blindness, so I'm in no position to whine. (Not that it means I won't.) I suspect that the use of markup will ultimately allow me to do other things I'll find useful, but at the end of the day, I find that I can't get away from the idea that if I can make it possible for color blind people to see things in a way that works for them and isn't too onerous for me, I have a moral obligation to do it. I guess it's my way of adapting the ADA's "reasonable accommodation" rule to publishing.
As I wrote before, the choices in MarkupLand seem to boil down to XML+DocBook and LaTeX. I was leaning towards DocBook, but then two things happened. The first is that I went to my local technical bookstore to get a book on DocBook, and it didn't have any. Bad sign, very bad, especially since my local technical bookstore is Powell's, which is not a small store. That Powell's didn't have any books on DocBook gave me the kind of "you're in this alone" feeling that's anything but warm and fuzzy. (Yes, there are lots of online resources, and yes, the two big books on DocBook are online, but (1) I like physical books and (2) I can't shake the feeling that the availability of physical books tends to bear a correlation to the size of the user community.)
The second thing that happened is that a friend of mine who's been pushing me to choose LaTeX agreed to act as my personal LaTeX consultant. That's key. Having a person I know agree to help me is much more reassuring than having only the faceless masses of the Internet to turn to. I have a lot of respect for those faceless masses, and I've found them tremendously helpful on many occasions, but I find that the more specialized my interests, the less likely I am to get help online. When I was working with OpenOffice Writer, for example, it didn't take much time for me to go beyond what I was able to find online, and it didn't take much longer than that for me to start stumping the consultant I was working with. "Huh, nobody has ever wanted to do that before..." is not really the kind of feedback I want to start getting on a regular basis.
And then there's this one silly thing: because DocBook is XML, every paragraph has to be started with <para> and ended with </para>. This is inhuman. Literally. It's fine for machines, but not for humans. LaTeX, in contrast, while not without its own syntactic ideosyncracies, interprets a blank line as a paragraph separator. That's vastly more natural for a writer. Working with XML requires that I be aware that I'm building a tree structure that happens to have nodes of text in it. Judging from the online demos for WYSIWYG DocBook editors like oXygen and XMLMind, this is the case even if you're not typing the markup in manually. When I write, I want to think of sequences of paragraph, not nodes in trees. LaTeX lets me. I'm concerned that DocBook won't.
My current plan, then, is to take my draft Introduction for Fastware! and translate it into LaTeX. We'll see how it goes.
Subscribe to:
Post Comments (Atom)
7 comments:
You may want to look into reStructuredText[1], developed by the Python community. Python's documentation had been maintained for many years in LaTeX format. In the last year, however, all the LaTeX markup has been translated into reStructuredText, using the Sphinx documentation generator.[2]
Having worked as a LaTeX typesetter for a number of years, I can tell you that the Python docs were not a simplistic use of LaTeX. I was initially surprised that reStructuredText was up to the richness of the LaTeX markup but the new docs look great and function even better. More importantly, reStructured is much easier to author. See the new Python docs[3] and click the "Show Source" link in the left column on any page to see the reStructuredText source (e.g., [4,5]) -- seeing is believing, especially if you loathe the idea of typing <para> everywhere.
The Sphinx project has made it easy to use reStructuredText and publish beautiful looking code-heavy pages online or in PDF format (by translating to LaTeX); it's not limited to just Python. If nothing else, reStructuredText+Sphinx might make a good a translation target for online viewing.
LaTeX may be better suited for printing pages and mathematics but I can tell you from experience that customizing LaTeX can be very time consuming.
You can talk with the people involved in the Python docs transition on the DOC-SIG mailing list.[6] I'm sure they would happy to answer any questions you come up with.
[1] http://docutils.sourceforge.net/rst.html
[2] http://sphinx.pocoo.org/
[3] http://docs.python.org/
[4] http://docs.python.org/library/multiprocessing.html
[5] http://docs.python.org/library/re.html
[6] http://mail.python.org/pipermail/doc-sig/
You mentioned XMLmind and WYSIWYG in the same sentence... XMLmind is definitely not WYSIWYG. Just fyi.
Silly me, the DocBook Wiki says it's WYSIWYG, and the demo looks WYSIWYGy, so I figured it was. Thanks for the clarification.
I find this ironic, since I remember answering your (grumpy) LaTeX questions at Brown.
I was going to recommend reStructuredText + Sphinx, but David Niergarth beat me to it.
I'm looking into reST now. I'll write up my initial impressions once I know enough to have some.
Great to hear someone think about the colors (I'm colorblind). I tend to go one step further and use colors only to emphasize information already distinguished in some other way.
~Matt
Who knows where to download XRumer 5.0 Palladium?
Help, please. All recommend this program to effectively advertise on the Internet, this is the best program!
Post a Comment