 |
The Origins of MakeDoc
(This is first in a 2 part blog on MakeDoc. Part 2 follows.) I originally wrote the REBOL documentation in MS Word. I've been using Word for a long time... since 1.0 on Mac and even its predecessor on DOS long before that. The peak for MS Word was around version three (it was great for writing the "Guru's Guide" back in 1988), but it has headed downhill from there. I still use Word from time to time, but only when absolutely necessary. After MS Word, I switched to a "professional" word processing package and converted all the REBOL docs to it (a painful process to say the least). I had selected the package based on the recommendations of several professional writers that I knew. But now, all I can say is that I feel really sorry for professional writers. The package was horrible. Not only did its user interface malfunction and get in the way, but its output was very complicated and difficult to convert to other formats. It especially did a bad job generating HTML output. I have to say that I am very picky about my documentation writing tools. That's because I write a lot and I measure my own productivity. I need to be extremely efficient. I often write thousands of pages of documentation each year. I cannot afford the word processor to get in my way. In fact after 25 years of nearly continuous document writing, I've found the difficult part of writing to be the sentence composition process, not the document formatting process. So, I need a word processor that gets out of my way and lets me crank out the words and sentences. My writing motto is: Please don't slow me down with trivial word processor annoyances. Finally, in an act of ultimate desperation, I converted all the REBOL docs back to plain text and wrote the MakeDoc program to process them. I've found this method to be optimally efficient, and I have stuck with it for many years. I use MakeDoc for everything now, even including this blog (it's part of the REBOL WIP wiki I use - so now the secret is out and you know how I can write my blogs so quickly). The primary objective of MakeDoc is to provide a simple mechanism of creating HTML and other output formats from a simple plain text specification. Over the years I've used many other document formatting systems, like all the roff cousins (roff, nroff, troff) and TeX, to name a few. Some are better than others. But, there was an important secondary objective that makes MakeDoc text format different from all the rest: All documents had to appear simple and easily readable in plain text format with minimal "markup interference" to the text. That is a unique and wonderful feature of MakeDoc. This second requirement meant that if you view any MakeDoc text file, it will always appear as a nicely readable document. Even if you read it from the Unix shell, REBOL console, or from MORE, VI, or in a web browser textbox. It looks like it was formatted for text viewing. This requirement is important, because in many environments, like when telnetting (ssh'ing) to a remote server, you probably just want to view the plain text files most of the time. You normally do not have the time or interest to run them through a text formatter. If you examine some of the plain text (MakeDoc) versions of REBOL documentation (such as the files that come in various distributions), you will note that you can easily read them, even if your editor is not set for automatic line wrapping (which, by the way, is the default mode in most code editors). Of importance is the fact that paragraphs are composed from adjacent lines of text and everything is separated by one or more blank lines. So, that is a short history of MakeDoc. In the next blog, I want to say a few words about MakeDocPro and MakeDoc2.
|
 |
Updated 24-Nov-2024 - Copyright Carl Sassenrath - WWW.REBOL.COM - Edit - Blogger Source Code |