 |
Proposing a MakeDoc Standard
(This is the second part of a blog about MakeDoc. See below for the first part.) The beauty of the MakeDoc format is that it is simple. It is easy to take the MakeDoc program and modify it to produce exactly what you need. For instance, the show.r program that does slide presentations is based on MakeDoc (and I have a newer show.r based on MakeDoc2). The actual REBOL manual is generated by a slight variation of MakeDoc2, and this blog is created by a variant of MakeDoc2. And, of course, MakeDocPro from Robert Muench is based on the original MakeDoc program, and there are yet other variations out there. As far as I'm concerned, when it comes to output formats for MakeDoc, "Vive les variations". In other words, tune MakeDoc to produce the output format that you need. That format can be HTML, XHTML, XML, PostScript, plain text, slideshows, or whatever. However, I think it is in the best interest of the REBOL community to standardize the input format for MakeDoc. That way, you can format my document, and I can format your document. We would have a handy and compatible document exchange format. What I'm really talking about here, when it comes down to the nuts and the bolts, is to see if we can standardize the PARSE rules for MakeDoc. That's where MakeDoc2 provides a good starting point. MakeDoc2 is designed as a two step process. The first step is the PARSE which outputs a block that is a simple REBOL representation of the document. That block is then used as input to one of many different output formatters. This block format also has the advantage that it makes generating things like tables of contents very easy. You can quickly scan the block in separate output phases. Also, when formatting rules require "look-ahead" or even "look-behind" they become much easier to code. Yes... I know you've been hearing about MakeDoc2 for quite a while. MakeDoc2 has been in use for several years. The reason I've not released it is because although it is a nice redesign of the original MakeDoc, it does not yet have all of the features that I put into the original MakeDoc. So, I figured it was better not to put it out yet. However, perhaps the time has come to take action on this MakeDoc issue. I propose that we find a single standard for the MakeDoc text input format, if at all possible. That standard describes the parse rules for the input format and also generates a standard intermediate block format that can be used with any number of output formatters. I propose that the end result become an official standard of REBOL, and that RT will publish it as a standard for everyone to use. To this end, I should say this: The only element of the MakeDoc format that I am strongly attached to and will not compromise is that the text format of MakeDoc must allow text to be easily read from any editor or OS shell. That essentially means that blank lines are a critical part of the markup and are used to separate each of the individual elements of the document. It also means that other markup, such as section headers, be simple and clean, as is already the case in all MakeDoc derivatives that I have seen. Let's continue this conversation on the REBOL AltME world to see who else wants to be part of it. From there, we'll move to a private AltME world to nail down the details and make it happen. As a starting point, and for history reasons, here is a link to the original MakeDoc 1 documentation. It is still quite accurate today.
|
 |
Updated 24-Nov-2024 - Copyright Carl Sassenrath - WWW.REBOL.COM - Edit - Blogger Source Code |