How To Generate Multiple Forms of Documentation

I’m working on an iPad application (more about that later), and I want to produce the documentation in three forms:

.pdf for general reading
.html for the web site
.xml (organized somewhat differently from the .html) for importing into the application (show and tell, sort of like Scrivener’s tutorial)

I know how to do this in Tinderbox: write export templates to produce XML, use an XML Transform to generate the .html and the internal .xml, and use XHTML2PDF to convert the .html to .pdf.

But I’d rather use Scrivener to compose the document. If I do that, generating the .pdf file is easy. But what about the .html file? (If I can generate the .html file I’m pretty sure I can transform the result into the internal .xml format). MMD, then compiler to .RTF and to .HTML?

Scrivener 2.0’s HTML exporter is significantly better for this sort of usage than it was in the past. You’ll want to visit the Import & Export preference pane and set it to XHTML 1.0 Strict (or Transitional if you use tables), and possible turn off CSS entirely if you plan on styling externally—definitely don’t do inline. This produces a pretty clean XHTML file. When you compile to HTML, you’ll also want to pay special attention to the Formatting option pane, which will let you assign HTML elements to different parts of the export. This means you can make your top level titles

, you second level titles

, and so on. By default these are not set up, but it’s easy to do so.

MMD will give you an even cleaner and more semantic XHTML right out of the box, because the way it works is by assignment of types to the text, rather than the assignment of visual styles. So a blockquote section (which you could use as a tip box) will come out as an actual

element, not a paragraph with a CSS style indenting it. What you would really want to do with MMD is to produce your PDFs via LaTeX, but I’m not sure what your inclination is towards that option. It can be frustratingly complex if you need to tweak something out of the box, but produces fantastic results (Scrivener’s documentation is a LaTeX generated PDF). The nice thing about that whole method is that it is easy to globally tweak style and presentation. I can produce a US Letter PDF in about 20 minutes (and most of that is because I have yet to set up my tables correctly so they need to be hand-tweaked after compile), but producing an A4 PDF takes about 10 seconds. Producing an iPad optimised PDF with an entirely different typesetting approach and “paper” metrics would take another 10 seconds. So there is a big advantage to MMD there, and since you are already (seemingly) familiar with XSL, you’d be right at home in how it works—that what it does for everything in fact. The core MMD format is XHTML, and it produces other formats through a complex of XSLT files. If you already know the language, tweaking them to produce the result you want is trivial.

You would, in general, not need or want MMD->RTF for the list you provided above, but if you were really loath to LaTeX it could be an option, it just won’t be nearly as pretty a result. Incidentally, MMD produces RTFs via XSLT as well, so if you know RTF it wouldn’t be too difficult to enact changes on that workflow.

So essentially you’re recommending that I use MMD, compile for MultiMarkdown -> LaTeX to generate the PDF file, compile for MultiMarkdown -> HTML to generate the HTML file, and transform the HTML file to generate the internal XML file. That sounds like it could work. I’ll explore further, and I’m sure you’ll get some desperate pleas for help from me. Thanks.

It’s one way, yes. It depends on how well Scrivener’s HTML exporter works for you. I’d give that a try, and if you can use it to get your XML file, it might be enough to just do that and use Scrivener like a regular word processor.