make-doc-pro documentation

make-doc-pro (MDP) uses an easy to learn markup language to specify different styles of a 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.

General Information Δ

MDP uses one or more plain text files as input file and generates an output file. The format of the output file can be selected. Each output format uses a different method to specify the style for 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.

Source Document structure Δ

A MDP documdnt consists of the following parts:

A title line and a boilerplate text part
An optional table-of-contents (TOC) done with =toc
One or more headings / subheadings
One or more paragraph of text
Special formating characters like ~, _ etc.
Special MDP commands all starting with a = character like, =include etc.
Special MDP directives for controlling the MDP engine like, =debug etc.

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 thru 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.

If you fail to do this, your paragraphs will be merged together. 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.

The Title Line Δ

The first line in a text file is always used as a title line. This text is used for the document title as well as the HTML title tag for the generated document.

Boilerplate Δ

If you follow the title line with a few indented lines, these lines are used as your boilerplate. The boilerplate uses a special style.

Table of Contents Δ

The table of contents (TOC) is automatically generated by the different section headings. It contains links to each section. No other effort is required. The TOC will indent and number the different sections and subsections. The level of indention is the same as later in the document text.

The TOC isn't included into your document by default. If you want to include a TOC use the following code where you want the TOC to appear. The TOC is only
generated for the contents following the tag:

=toc

Section Headings Δ

make-doc-pro supports four different sorts of headings. These headings are indented to give the document a structure. This structure is shown in the TOC too.

Major Sections Headings Δ

Major section headings are created with a line that begins with === that is followed by the text of the heading. Here is an example:

===This is a Major Section

Subsection Headings Δ

Minor section headings are created with a line that begins with --- and is followed by the text of the heading. Here is an example:

---This is a Subsection

A simple memory method for remembering that === is for sections and --- is for subsections is to note that === has more to it than ---. There are two more subsection headings you can use. The first is +++ and the second one is ... followed by the text of the heading. The subsections use different text sizes and indention levels to indicate the level of the heading.

Here is a summary of the available heading styles:

=== - Major Section heading
--- - Subsection
+++ - Subsubsection
... - Subsubsubsection

Inline Formatting Δ

You can change text decoration inline. You can use *bold* text, ~italic~ text or _underline_ text. As you can see, the formatting is quite easy for this:

*bold*
~italic~
_underline_

The word you are going to decorate must have spaces in front of and after the inline decoration character:

This is an _underlined source_ text.

Comments Δ

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.

End of Text Δ

If you follow your text with ### it will be used to mark the end of text formatting. Everything following it will be ignored. 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.

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:

... your text...
###
[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. The brackets are not required.

Structuring Markup Δ

MDP supports structuring a document either by using bullet points or numbered lists.

Bullet Points Δ

A handy way of creating a simple list of bullet points is done by beginning paragraphs with a * character. Remember to keep the text start left in the first column, otherwise it will become a code example. The example:

*This is the first of a few bullet points.

*This is a 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.

will produce:

This is the first of a few bullet points.
This is a 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.

Bullet Points Level Δ

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

Will produce:

First level

- Second level

- - Third level

- Second level

- - Third level

Numbered Points Δ

Similar to bullet points, you can create numbered points. Start each numbered line with a # that is followed by the text of the line.

For example:

#This is the first numbered line.
#This is the second numbered line.
#This is another bullet point. It contains a lot more text, so it will show how lines are wrapped on in the output.

produces:

This is the first numbered line.
This is the second numbered line.
This is another bullet point. It contains a lot more text, so it will show how lines are wrapped on in the output.

Special Markup Δ

This section describes some special markup rules you can use.

Code Examples Δ

To create a code example, all you have to do is indent the text. Code examples are printed in a fixed-space bold font. Notice that the example maintains its proper indentation.

Definitions Δ

A list of word definitions is created with a leading : for the word, followed by a - for the definition. The word of the definition can contain - characters too as long as there are no spaces. make-doc-pro recognizes the definition from the place starting after a "-" sequence is found.

For example, definitions look like this:

:word - This is the first definition.
:example-with- - This is the second definition.
:next word - This is the second word. Note that it can include more than one word.

Stand-alone URL Links Δ

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: The Main REBOL Site.

You can also provide email links with:

=url mailto:robert.muench@robertmuench.de Send me an email.

Sometimes it's necessary to use URL with spaces, especially if you want to link to a file on a intranet server. Than use the following form:

=url "//mycomputer/mydirectory with spaces/myfile.txt" URL with spaces

Indented Sections Δ

To increase indention level of a section of text, you will need to use a \in and a /in to indicate decreasing the indention level. This means you can use several \in and /in for indention controlling. Indention level is increased/decreased by 1cm a time.

For example:

\in

This is a section of text. I can contain most of the other special formats. For example, here are a few bullet points:
*bullet 1
*bullet 2

/in

Note Boxes Δ

Special notes can be shown in a callout box. A note begins with \note and ends with /note. The \note line can be followed by a box heading that will be shown at the top of the box.

The example:

\note Example Note Box

This is a special note. It can contain most
of the other special formats. For example, here
are a few numbered points:

#number one
#number two

/note

Tables Δ

make-doc-pro adds support for tables. You create tables like this:

\table
cell1 | cell2 ||
cell1 | cell2
/table

The last line doesn't have a || at the end, because there is no further line following.

Images Δ

Images are placed in a document with the image tag. The line:

=image mdp-logo.png

Would include the image, with the filename mdp-logo.png from the same directory as the source text file, centered in the document:

=image center /images/mdp-logo.png

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 image =image float /images/mdp-logo.png to include text styling graphics.

MDP controlling markup Δ

This section describes the commands you can use to control MDP's translation process.

Language Support Δ

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 than loaded and processed. From this point on the new definitions are used. So a good place to use this option is after the title/author block and before the TOC tag. In this case the TOC will have the correct description.

To specify an other language use the following code:

=language DE

This will read the file DE.r and execute the definitions inside. Here you see a sample content of such a file:

contents: "Inhalt"

copyright: [

]

Include Files Δ

While processing a file you can insert the contents of another file with the =include command. For example:

=include preface.txt

would include the file preface.txt at exactly the place where the include command was used.

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 source text file. But you can use path specification as well.

Alternate Output Files Δ

A single input file can create multiple output files. The new output file is specified with the =file command. For example:

=file directory.html

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 klick in the TOC and branch to an other file.

More than one =file command can be used. For example:

=file first.html

This is the text of the first file

=file second.html

This is the text of the second file.

=file third.html

This is the text of the third file.

robertmuench.de

To the point & Out of the box