MakeDoc was created to provide a portable, easy-to-edit format
for REBOL documents. The program was designed to convert a
simple text formatted file into HTML or other document formats
(such as PDF or REBOL/View). The beauty of the format is that
the text documents are quick to write and are very readable.
You can also use this program to create the first version of an
HTML file and then resume your editing in an HTML editor
(although out of the dozen HTML editors I have tried, I have not
found one that is as productive as the MakeDoc approach to
writing documents quickly.)
Input Files
The input file is an ordinary text file. Indented lines
can be done with tabs or spaces.
The text file is specified to MakeDoc in one of two ways:
If you run the MakeDoc program and a file request will prompt
you for the filename of the text file.
Or, you can specify the text file as an argument to the
MakeDoc program.
This second approach allows you to embed a REBOL script within
your text document that automatically calls MakeDoc if the
text file is evaluated. This is handy if your text editor
supports an "evaluate script" shortcut key. With the press
of a single key, you can view your formatted output. To prevent
the REBOL header from being formatted, use the ### as described
below.
Formatting
A very simple text format is used. It is trivial to create
and easy to edit.
Primary Rule
The main rule that you will need to follow is to separate
all paragraphs, sections, subsections, etc. with a blank
line. For example:
This is paragraph one.
This is paragraph two.
If you fail to do this, your paragraphs will be merged together.
Title Line
The text file should begin with a title line. This will be used
for the document title as well as the HTML title tag. For
example, this document started with line:
The MakeDoc Program
Boilerplate
If you follow the title line with a blank line then a few
indented lines, the will be used as your boilerplate.
Note that this is not currently a special style, it uses
the indented code format.
This document began with:
Author: Carl Sassenrath
Date: 30-Jan-2001
Table of Contents
The table of contents is automatically generated by the
section headings. It contains links to each section.
No other effort is required.
Section 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 Section
These section headings are used to create the table
of contents.
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 ---.
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. 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.
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 flush left, 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.
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.
Definitions
A list of word definitions is created with a leading : for
the word, followed by a - for the definition.
For example, the definitions:
:word - This is the first definition.
:example - This is the second definition.
:next word - This is the second word. Note that it can
include more than one word.
would appear as:
word
This is the first definition.
example
This is the second definition.
next word
This is the second word. Note that it can
include more than one word.
Indented Sections
To indent a section of text, you will need to use a \in
and a /in around the text to indicate the extent of the
indentation.
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
produces:
This is a section of indented text. It can contain most of the
other special formats. For example, here are a few bullet
points:
bullet 1
bullet 2
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
produces:
Images
Images are placed in a document with the =image tag.
The line:
=image nyc.jpg
Would include the image centered in the document:
To left justify the image:
=image left nyc.jpg
Layouts
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:
=view
The second is done with a:
=view left
The resulting image file will be created in the
graphics directory. It can be given a base file
name with a line like:
=view example
All other =view commands that follow will use the
same base name. If no base name is given, the word
"image" will be used.
Comments
Comments begin with a semicolon (;) and continue through
the end of the paragraph.
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. 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.
For example:
###
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 %makedoc.r %makedoc.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.
Full Example
For a complete example of a MakeDoc document, view the
makedoc.txt file that was used to create this document.
New Features
Relaxed Formatting
Normally, when the input file begins with a text line it is used
as a title line. A table of contents is generated, each section
and subsection is numbered, and sections are divided with
horizontal bars.
However, if the first content line is a section or
subsection header, then the above frills are disabled. The
document will not include a table of contents, there will be no
numbering of sections, and no horizontal divider bars will be
inserted.
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.
The inserted file can use all of the same commands and body text
as accepted by MakeDoc.
Any number of =include commands can be used, and included files
can also contain =include commands.
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.
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.
Font Settings
The =fonts command has been added to allow you to specicfy font
characteristics. The =fonts command will accept a file name or a
block. When a file name is specified, the corresponding file is
must contain a block of font preferences. For example, to use a
file called doc-fonts.r, you would include the line:
=fonts doc-fonts.r
and the doc-fonts.r file could include these definitions:
title: <font face="arial,helvetica" size="5">
h1: <font face="arial,helvetica" size="4">
h2: <font face="arial,helvetica" size="3">
h3: <font face="arial,helvetica" size="2">
h4: <font face="arial,helvetica" size="2" color="#005000">
h5: <font face="arial,helvetica" size="1" color="maroon">
normal: <font face="arial,helvetica" size="2">
toc: normal
list: normal
define: normal
url: normal
All of these definitions are optional. When a font setting is
not specified, the font setting will remain unchanged.
The font definition is an evaluated REBOL block and can include
any valid REBOL expression. For example the NORMAL font style
shown above is used multiple times once it has been defined.
Currently, only an HTML font tag specifications are accepted;
however, future versions of MakeDoc may allow a more generic
description of fonts for PDF and other output formats.
The =fonts command also allows you to specify inline font
changes when followed by a block:
=fonts [normal: <font size="1">]
This would set normal text to a font size of 1.
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
You can also provide email links with:
=url mailto:info@rebol.com Send us Email.
An in-line linking method will be provided eventually.
