Introducing %makedoc2.r and a whole markup standard

Source code and concept originally by Carl Sassenrath
REBOL Technologies

Contents:

1. Introduction to %makedoc2.r

MakeDoc is one of the gems of the REBOL programming environment. A simple thing made simple. A markup processor that turns easy to read and to create text files into professional looking documents.

This document is written in makedoc, and the cool thing is, that means plain text.

The default output is HTML and can use templates to control the overall look. Being a handy REBOL application, makedoc2.r includes a default template in the code that produces very nice looking documents.

This usage document uses the template that is built into the code itself. Right out of the box, makedoc2.r produces very readable output, but it is so easy to customize that you can apply your own look and flair with a minimum of effort and a maximum of creativity.

1.1 Main documentation

There is a web page that is the main MakeDoc standard user documentation, and acts a quick start at getting productive with MakeDoc.

This usage document is mainly for completeness in the rebol.org library and to point out some of the variants this style of document creation has spawned.

2. The basic rules

MakeDoc is built around the simple concept that paragraphs are separated by blank lines.

Some markup is implied in the structure of the document. The first line being the title. An optional boilerplate is included by an indented section that follows the title line.

Other indented sections will be treated as "examples" and will be output without further markup processing. Very handy for listing code and other output, and MakeDoc adds to this with an == that easily separates code from the code output in the final document.

Other markup uses very simple rules. === starts a main heading, --- a sub heading, +++ subsub and ... being a fourth level of heading. These headings can be included in a hyper linked Table of Contents with very little effort.

3. Link table

Described below is a plethora of MakeDoc related scripts, this table is a quick link to sources and information.

File	Author	Link
%makedoc2.r	Carl Sassenrath	MakeDoc2.r The MakeDoc Page
%make-doc2.r	Carl Sassenrath	Make-Doc.r The MakeDoc Page
%makespec.r	Carl Sassenrath	MakeSpec.r The MakeDoc Page
%texthtml.r	Carl Sassenrath	texthtml.r textdoc.r
%make-doc-pro.r	Robert M. M?nch	make-doc-pro.r mdp Documentation
%mdp-gui.r	ShadWolf	mdp-gui-package.r Documented in the package
%nicomdoc.r	John Niclasen	nicomdoc.r nicomdoc Home and nicomdoc Documentation
%eText.r	Andrew Martin	eText.r eText Sampler
%qml-ed.r	Gabrielle Santilli	QML editor package QML Starter Docs
%pdf-maker.r	Gabrielle Santilli	PDF Maker Home and pdf-maker-doc and source
%pdf-labels.r	Gregg Irwinn	PDF Labels Documented in script
%pdf-tables.r	Gabrielle Santilli	PDF Tables Home
%generate-doc.r	Daan Oosterveld	Inside the script
%color-code.r	Carl Sassenrath	Color Code Example: write %color-code.html color-code read %color-code.r
%colorize.r	Jeff Kreis	Colorize Example: colorize %rebolcode.r
%rebdoc.r	Carl Sassenrath	RebDoc do %rebdoc.r and it'll browse %rebdoc.html
%checklist.r	Unknown	Checklist Inside the script
%html-calendar.r	Bohdan Lechnowsky	HTML Calendar do %html-calendar.r
%document-search.r	rwvd.Zee	Document Search Inside the script
%build-site.r	Carl Sassenrath	Build Site Inside the script
%content-management.r	Christopher Ross-Gill	Content Management Articleand Home
%emit-rss.r	Christopher Ross-Gill	Emit RSS In the script and Home
%css.r	Andrew Martin	CSS dialect In the script
%mdlparser.r	Daniel Murrill	Markup Parser Inside the script
%crystal-reports.r	Christian Ensel	Crystal Report interface Inside the script. Requires REBOL/SDK

4. Different flavours

The MakeDoc standard is %makedoc2.r, but the concept has grown to include quite a few different variants on the theme.

If you just want to produce nice documents, visit the main documentation link mentioned above and you will be up and running in no time. If you want to be spoilt for choice, then read on.

4.1 The simplest first - makespec

The rebol.org script repository includes %makespec.r. This little program is a showcase program for what REBOL can accomplish in very few lines of code.

makespec includes the basic blank line separates paragraphs rule, has headings and sub-headings, allows for sidebars and indented text.

4.2 make-doc

Currently on version 2, the original %make-doc.r is still quite useful. It includes many of the features of %makedoc2.r and even includes a few features that were not upgraded to version 2. Things like the ability to call up REBOL/View, and include the layout image right in your document.

4.3 texthtml

A simple way of producing HTML files from text, one of the original MakeDoc programs.

4.4 mdp MakeDocPro

There is an extension to MakeDoc called Make Doc Pro. Quite sophisticated documents can be created with much of the simple rules and ease of use of %makedoc2.r. This project also comes with a very nice graphical frontend the can be found in the rebol.org repository as a package filed under %mdp-gui-package.r

4.5 nicomdoc

Another extension, nicomdoc allows for TeX quality math expressions in your documentation (among it's many other features). The author, John Niclasen, comes from a very scientific background and nicomdoc is a great support tool for such documents, but being a simple markup language is also great for general purpose use. To see the a sample of the awesome possibilities of what can be produced with nicomdoc check out John's page at the Niels Bohr Institutet

4.6 QML

A new candidate for the standard is QML. Built for the Qtask system by Gabrielle Santilli, the publishers kindly donated the code to the REBOL community and it can be found in the rebol.org repository as the qml-ed.r package. The markup engine will output HTML and can also be configured for PDF output and is destined to support others. Part of the work towards MakeDoc3.

4.7 PDF Maker (RECOMMENDED READING)

Gabrielle also has PDF Maker. Produce portable document format output from simple plain text documents. All REBOL programmers are urged to check this out. It is a path towrd full cross-platform printing from REBOL. The inputs are fairly simple and the outputs are gorgeous.

4.7 PDF Labels

Gregg Irwinn added a label maker.

4.7 PDF Tables

Gabrielle's extension to produce very nicely formatted tables in PDF.

4.8 eText

A different take on a markup processor, Andrew Martin has published eText, %etext.r

4.9 DocGen

The rebol.org repository also has %generate-doc.r

4.10 mdlparser.r

Daniel Murrill posted a fairly sophisticated markup processor as %mdlparser.r

5. Useful stuff

5.1 CheckList

If you'd like to produce a nice looking checklist, the repository has %checklist.r

5.2 Calendar

Bohdan Lechnowsky has written a nice short script for creating an HTML calendar, %html-calendar.r

5.3 DocSearch

Another somewhat related script is %document-search.r by rwvd.Zee

6. Websites and Syndication

The concept surrounding the MakeDoc standard can also be used to create websites from simple templates.

6.1 BuildSite

There is another script in the library, that was used to build the rebol.com web site. %build-site.r

6.2 Content Management

A variation of the MakeDoc standard includes Christopher Ross-Gills' site management script %content-management.r

6.3 RSS

Syndicate your work with Christopher Ross-Gills' %emit-rss.r

7. Source Code viewers

7.1 ColorCode

Carl Sassenrath has also scripted %color-code.r a program that will scan REBOL source code and produce a colorized version using HTML output. You can see a form of this script in action right on rebol.org by pressing the View in Color link while examining scripts in the repository.

7.2 Colorize

Another nice script for colorizing REBOL source code by Jeff Kreis.

7.3 RebDoc

This script by Carl Sassenrath produces an HTML file that documents the REBOL functions. With a little tweaking, it can be used to produce nice documentation for your own scripts.

8. Other Markup dialects

8.1 css

Andrew Martin has a nice little dialect for producing css, %css.r

8.2 mdlparser

Daniel Murrill posted %mdlparser.r to the rebol.org repository.

9. Other things

Not directly MakeDoc related, the rebol.org script library also has a script for interfacing to Crystal Reports?

9.1 Advanced Reporting

There is a REBOL/SDK interface to Crystal Reports? but this code uses load/library which requires a copy of non-free REBOL. %crystal-reports.r

10. MakeDoc3

There is currently development in the area of enhancing the MakeDoc standard. Keep an eye open for the release of MakeDoc3, a markup processor intended to output more than just HTML. Gabrielle Santilli already has a PDF emitter and there will be other output formats supported, all using the easy and simple MakeDoc input standard text markup.