Author: Robert M. Münch Date: 19-Jan-2012/13:21:17+1:00
make-doc-pro (MDP) uses an easy to learn markup language to specify various styles of text. This is quick and easy to use and it can be handled by scripts as well, making text processing a lot faster and simpler. The following sections explain the MDP markup language and show some special tips & tricks how to get the desired results.
MDP uses one or more plain text files as input and generates an output file. The format of the output file can be selected. Every output format can use its own method to specify the appearance of the MDP markup. For example, the HTML emitter uses a cascading-style-sheet (CSS) to specify the graphical appearance of the generated HTML file. The default CSS can be overwritten by an external CSS, so that you can change the look of the generated HTML files without big problems.
2. Source Document structure
2.2 Title Line
2.4 Table of Contents
2.5 Section Headings
2.6 Inline Formatting
2.7 Escaped characters
2.9 End of Text Formatting
4. Special Markup
4.3 Stand-alone URL Links
4.4 Indented Sections
4.5 Note Boxes
A MDP source document can contain the following (optional) parts:
- The title line
- The boilerplate text
- The table-of-contents (TOC)
- Paragraphs of text
- Inline formatting like ~, _, etc.
- Escaped characters
- Structuring markup
- Special markup
- MDP commands like =include, etc.
- Directives for controlling the MDP engine like =debug, etc.
- End of document mark eventually followed by some text
The main rule that you will need to follow is to separate all paragraphs with an empty line. Write a single paragraph either
- using soft line wrapping in your editor (without pressing your RETURN key) as one long line of text or
- press RETURN to include hard line breaks, if you want to keep a fixed source text layout.
Most text editors have a feature to word-wrap a text so that you can still see the complete paragraph if you go for option 1.
This is paragraph one.
This is paragraph two.
produce two paragraphs. If you fail to do this and write:
This is paragraph one. This is paragraph two.
, your paragraphs will be merged together.
The first line in the text file is used as the title line. The title line text is used both as the document title and as the HTML title of the generated document.
If you follow the title line with a few indented lines, the lines are used as your boilerplate. The boilerplate uses a special style.
Author : Robert M. Münch Corrections : email@example.com
The table of contents (TOC) can be generated from section headings. It will contain a link to every section in the document. The TOC will indent and number all sections and subsections. The indentation level is the same as in the document text.
The TOC isn't included into your document by default. If you want to include the TOC, use the
directive at the place where you want the TOC to appear. The TOC is generated only for the document contents following the directive.
make-doc-pro supports four different sorts of headings. The headings are indented to give the document a structure. The structure is shown in the TOC too.
Major section headings are created by a line beginning with === that is followed by the text of the heading. Here is an example:
===This is a Major Section
Minor section headings are created by a line that begins with --- that is followed by the text of the heading. Here is an example:
---This is a Subsection
A simple method to remember that === is for sections and --- is for subsections is to note that === has more to it than ---. There are two more subsection levels you can use. The first is +++ and the second one is ... followed by the text of the heading. Different subsection levels use different text sizes and indentation levels to indicate the level of the subsection.
A summary of the available heading styles:
Major Section heading
You can change text decoration inline. You can use bold text, italic text or underline text. The formatting is quite easy:
*bold* ~italic~ _underline_
The text you are going to decorate must have spaces in front of the starting- and following the ending inline decoration characters like:
This is a sentence containing an _underlined text_ part.
If you want to insert a specific character to the output (especially if it has a special meaning for the MDP engine) you can precede it by the ^ character. For example,
inserts the | character into the output even in case the unescaped | character would be understood as a table cell delimiter.
The ^ character itself has a special meaning for the MDP engine. That is why you need to write a pair
of these into the input file to insert a single ^ character to the output.
Comments begin with a semicolon (;) and continue through the end of the paragraph. It is OK to have whitespaces between the semicolon and the first character of the text.
Here is an example comment:
;This is a comment. It continues until a blank line is encountered. It is handy for commenting out paragraphs.
A line starting with ### will mark the end of text formatting. This is handy if you want to include some comments or notes to yourself at the end of the file, but you don't want them formatted into the document.
would end text formatting.
You can also embed a REBOL script to automatically format your text (as described above). To do so, follow the ### with a REBOL header. Here is an example:
### [REBOL  do/args %make-doc-pro.r %make-doc-pro.txt]
The ### marks the end of the formatting so the script portion will not be shown. The brackets around the script allow you to follow the line with notes or comments that are not evaluated. Otherwise the brackets are not required.
MDP supports structuring a document either by using bullet points or numbered lists.
A handy way of creating a simple list of bullet points is done by beginning paragraphs with a * character. Remember to keep the text flush left, otherwise it will become a code example. The example:
*This is the first of a few bullet points. *This is the second bullet point. *This is another bullet point. It contains a lot more text, so it will show how bullets are wrapped on in the output.
- This is the first of a few bullet points.
- This is the second bullet point.
- This is another bullet point. It contains a lot more text, so it will show how bullets are wrapped on in the output.
make-doc-pro supports three different levels of bullet points. To use them just use several bullet characters. Here is an example:
*First level **Second level ***Third level **Second level ***Third level
- First level
- Second level
- Third level
- Second level
- Third level
Similar to bullet points, you can create numbered points. Start each numbered line with a # that is followed by the text of the line.
#This is the first numbered line. #This is the second numbered line. #This is another numbered point. It contains a lot more text, so it will show how lines are wrapped on in the output.
- This is the first numbered line.
- This is the second numbered line.
- This is another numbered point. It contains a lot more text, so it will show how lines are wrapped on in the output.
This section describes some special markup rules you can use.
To create a code example, all you have to do is indent the text. Code examples are printed in a fixed-space bold font. For example:
foreach line paragraph [ print [ length? line mold line ] ]
Notice that the example maintains its proper indentation. In REBOL indentation defaults to 4 spaces.
A definition line starts with a leading : followed by the expression being defined. The <space>-<space> sequence starts the definition. The words in the expression being defined can contain - characters too as long as there is no single - character surrounded by spaces.
For example, the definitions:
:word - This is the first definition. :example-with- - This defines a word containing the - character. :two words - This defines an expression consisting of two words.
would appear as:
This is the first definition.
This defines a word containing the - character.
This defines an expression consisting of two words.
Simple types of URL links can be created with the =url command. This command provides a file or site reference, followed by the hyperlink text. For example, to provide a relative link:
=url work.html Where we work
To provide an absolute link:
=url http://www.rebol.com The Main REBOL Site
This will appear as follows
You can also provide email links with:
=url mailto:firstname.lastname@example.org Send me an email.
Sometimes it's necessary to use URL with spaces, especially if you want to link to a file on an intranet server. Use the following form then:
=url "//mycomputer/mydirectory with spaces/myfile.txt" URL with spaces
To increase the indentation level of a section of text you will need to use the \in mark. Use the /in mark to decrease the indentation level again. You can use several \in and /in for indentation control. Indentation level is increased/decreased by 1cm a time.
\in This is a section of text. It can contain most of the other special formats. For example, here are some bullet points:
*bullet 1 *bullet 2 /in
This is a section of indented text. It can contain most of the other special formats. For example, here are some bullet points:
- bullet 1
- bullet 2
Special notes can be shown in a callout box. A note begins with \note and ends with /note. The \note line can contain the box heading that will be shown at the top of the box.
\note Example Note Box
This is a special note. It can contain most of the other special formats. For example, here are some numbered points:
#number one #number two
make-doc-pro adds support for tables. It's only a basic thing yet but more to come. You create tables like this:
\table cell1 | cell2 || cell1 | cell2 /table
Images are placed in a document with the image tag.
=image center mdp-logo.png
Would include the image with the filename ms-word.gif from the same directory as the input text file centered in the document:
To left justify the image:
=image left mdp-logo.png
You can use right and float as well.
=image right mdp-logo.png
=image float mdp-logo.png
This is a text with an embedded imageto include text styling graphics.
VID layouts can be automatically generated as images. The images will be stored in a graphics folder in the local directory.
To create a layout, follow an example with a =view command. The command does not need to immediately follow the example. It will always print the last example that appeared. This gives you space to explain the results before showing them.
Here is an example layout:
backdrop %nyc.jpg 40.40.150 banner "Example Layout" text bold "Just an example...." button "Ok"
This will normally appear as:
But, it can also be shown left justified as:
The first is done with a:
The second is done with a:
A graphics dir will be created within the working dir, containing the *.png generated file. It can be given a base file name with a line like:
All other =view commands that follow will use the same base name. If no base name is given, the word "image" will be used.
This section describes the commands you can use to control MDP's translation process.
I added support for different languages to make-doc-pro. At the moment only the specifier for the contents and copyright section can be customized. By default make-doc-pro uses the english language option.
Language support isn't hardcoded into make-doc-pro. Instead you specify a filename, which is then loaded and processed. From this point on the new definitions are used. Thus a good place to use this option is after the title/boilerplate block and before the TOC tag. In this case the TOC will have the correct description.
To specify another language use the following code:
This will read the file DE.r and execute the definitions inside. Here you see sample contents of such a file:
copyright: [ <HR> <P id="end"> "Documentenformatierer Copyright Robert M. Münch. All Rights Reserved." <BR> "Formatiert mit Make-Doc-Pro Version:" system/script/header/version " am " now/date " um " now/time </P> ]
While processing a file you can insert the contents of another file with the =include command. For example:
would include the file preface.txt.
The inserted file can use all of the same commands and body text as accepted by make-doc-pro. Any number of =include commands can be used, and included files can also contain =include commands.
Include files should be placed into the same directory as the sourcetext file.
A single input file can create multiple output files. The new output file is specified with the =file command. For example:
would cause all text and commands that follow it to be stored in the directory.html file. When using several output files, the TOC is kept in sync. This makes it possible to click in the TOC and branch to another file.
More than one =file command can be used. For example:
This is the text of the first file
This is the text of the second file.
This is the text of the third file.