After reading a lot of compliments to MMD, I decided to give it a go. However, I found out that I’m a complete and unabridged noob on this. So I came here begging for some help. It’s not Scrivener-related; I was trying to use vanilla MMD. But this forum is so good that posting here seemed the best option.
And, before anyone asks: I read the documentation, I swear. I thought I had understood it. But, when it came to make the damn thing work, well, I was at a loss.
So, without further ado, here are my questions:
What exactly is the workflow? Suppose I have a sometext.md file. I wrote it using the correct syntax, all looks good. Now I have to use a .pl script, right? So I go to the Terminal, I drop the .pl script there (for now, let’s say it’s mmd2XHTML.pl) and then drop sometext.md. And press return.
So the .pl script converts my file to a HTML. What I don’t understand is: when do the .xlst files enter the game? How can I use them?
If I try the above method with mmd2RTF.pl, a lot of code fills up the Terminal window, and I get no file. What am I doing wrong?
Well, that’s about it for now. Only two questions, because that’s how far I managed to go with this… Any help would be very, very much appreciated.
Those may be basic MMD questions, but I can’t answer them. For the very simple reason that I let the Scrivener compile draft function handle all my MMD processing. If you’ve got Scrivener I would seriously recommend you give that route a go.
Eventually you’ll get sucked in and start tweaking the XSLT files to get exactly what you want coming out (mainly customising Latex in my case).
You can specify them in your document’s meta-data section, for instance:
XHTML XSLT: xhtml-toc.xslt
LaTeX XSLT: latex-snippet.xslt
selects xhtml-toc.xslt for XHTML output and latex-snippet.xslt for LaTeX output. mmd2XHTML.pl is just a wrapper script that calls MMD to convert plain text to XHTML and - if necessary - calls the xsltproc program to transform the XHTML.
What does the output look like? If it’s the RTF output, you should write it to a file:
It sounds like you are doing pretty good, actually. Like McGruff says, I think most people just interface with MMD via Scrivener’s compiler automation and never mess with the command-line stuff at all.
So, right. Again, Scrivener has fantastic exporting features right out of the box. Not only does it automate this whole process and produce a variety of files for you, it also makes titling and footnoting easy, and 2.0 will have even more in way of editing-to-syntax support, such as inline images getting converted to MMD codes; captioning of the images; better document flow support with the compiler; a variable replacement feature letting you use even easier to read codes that expand into full MMD code upon compile (people who insert raw LaTeX into their Scrivener documents will probably really like that one); and more. So if you aren’t already doing so, I’d give Scrivener’s integration a shot. I use it to produce any MMD documents larger than a few pages—just for the titling alone. For short documents (like this one), I just use TextMate.
Many MMD documents in Scrivener hardly look like MMD files at all. Nevertheless, I think it is good that you’ve gone about learning MMD “from scratch” as that will give you a much better background in understanding what Scrivener is doing behind the scenes, and how to fix things if they go wrong.
As the script name intimates, yes the intended result is an HTML file. If you want to apply an XSLT to the HTML file (there is an example script, called xhtml-toc.xslt, which will analyse your header structure and produce a hyperlinked table of contents at the top of the file), then you need to supply a pointer to that in the meta-data block, like this:
XHTML XSLT: xhtml-toc.xslt
Note that you need to specify a target in modern versions of MMD. In the past you could just use a general “XSLT” field but this system has been replaced so that you can supply different XSLTs for different purposes. You could have that line in your meta-data block, and also this line:
LaTeX XSLT: article.xslt
Now if you use the mmd2XHTML.pl script, you’ll get a nice table of contents in a web file, but if you use the mmd2LaTeX.pl script, you’ll get a document typeset using the standard article styles.
In this document, I’m actually using the LaTeX line to produce BBCode for the forum, with:
LaTeX XSLT: bbcode.xslt
When I’m all proofed and ready to post, I just press [b]Opt-Cmd-L[/b] in TextMate, and I get a nicely formatted BBCode document that I can paste into the forum software.
All these meta-data codes do is inform the relevant script of which XSLT to run the file against. In the case of the XHTML script, if you supply nothing then no XSLT is used at all. LaTeX defaults to memoir.xslt, and I think the RTF script uses nothing unless you supply an [b]RTF XSLT[/b] meta-data code. I’ve never actually done that, but I bet that works more like the XHTML XSLT—it transforms the HTML file—before converting to RTF using TextUtils—rather than working like the LaTeX one which takes an HTML file and converts it to another format entirely.
So that is how you use them and what they do. In case you don’t know, XSL is a language for taking an XML file and styling it (in this particular nomenclature, the word “style” is quite a bit different than in normal rich text usage). There are two basic modes of operation: one produces another XML file, another produces in text mode, letting you create whatever you want from the XML structure. The XHTML-based XSLTs work like the former; the LaTeX ones like the latter. It’s all just a convenient way to look for XML elements (which an XHTML file is technically composed of) and then generating output or storing output for later use, at the point of occurrence. A simple XSLT could look for “html:strong”, all bold text, and print out the text on lines—thus producing a text file that consists of one line for each bold statement in the document. The LaTeX XSLTs just take that principle to a massive level, addressing most of the XHTML language and converting it to relevant LaTeX typesetting codes.
That script was never updated to the new system, I believe, and still produces its output to the terminal. In other words all of that code that fills up the Terminal window is your RTF file. RTF is, at its roots, just a plain-text format that gets rendered in a pretty fashion when loaded in an RTF reader—not too dissimilar from HTML in philosophy, though it contains thousands of typesetting oriented codes, whereas HTML much, much simpler and has hardly any mechanism for typesetting (deferring that job to CSS).
So, what you need to do when a program dumps output into terminal (this is called STDOUT, in UNIX parlance), is trap that output and “pipe” it into a file. It’s pretty easy to do, actually. Here’s the trick:
The first part of that you already know, the new stuff starts at [b]>[/b]. Be very careful to use a new filename after the [b]>[/b] symbol. UNIX always assumes you know what you are doing, and will merrily overwrite whatever you have on the right side of that symbol! This can of course also be useful if you made a mistake the first time, you can overwrite the bad file with the new one.
Of course you probably could copy and paste the code dump in Terminal into an empty text file and call it something.rtf, but that is much less reliable and the top of the file, if large, might scroll off your Terminal history, as well.
The reason why this method is often preferred by UNIX programs is that you can also pipe to other programs. In fact, that is what MMD does behind the scenes. Your MD file gets sent to a script called SmartyPants that fixes up quotes and such, and the result of that is piped to the base script that converts your cleaned syntax to XHTML, which is then piped to the XSLT formatting engine, and then piped to TextUtils which creates an RTF file. The way the RTF script is set up makes it so that you could pipe the results to another program if you wanted… or to a file. We use the file method to create an RTF file.
Wow. I knew this was the right place to come for help!
MrGruff, signinstranger and Ioa: thanks so much for the replies. signinstranger, you were right on spot. And Ioa, your great explanation wiped out any doubts remaining. (For now, that is. Let’s see how this develops… )
I’ll certainly experiment with Scrivener’s export features. It’s just that I usually like to know how backstage stuff works. Also, I’m trying to implement a text-only, software-independent information management scheme, so it made sense to learn MMD from scratch. (I’m checking out the topic on this regularly.)
So, again, thanks very much! Your help was invaluable.
In that case you might be interested in a discussion we are having in this thread over here. We’ve been talking about plain-text file and folder systems for massive organisation and personal archival. That thread also links to a great blog article on the concept, and a few of my longer discourses on the topic as well. This forum has kick-started some new techniques that de-centralise data from applications and strive for ultra-long-term security of information, including new ways of organising and visualising data. Lots of interesting stuff to read if you have the time.
Of course, I’m a huge advocate of coupling MMD with this sort of approach. It is, in my opinion, the perfect archival format since the end product is de-coupled from the data in a readable way. The end product can then be expanded and updated over time, without touching the original archives.
RTF is, at its roots, just a plain-text format that gets rendered in a pretty fashion when loaded in an RTF reader—not too dissimilar from HTML in philosophy, though it contains thousands of typesetting oriented codes, whereas HTML much, much simpler and has hardly any mechanism for typesetting (deferring that job to CSS).