The Makespec Document Formatter

Author: Carl Sassenrath
Date: 5-Feb-2001
Version: 1.2.0
Corrections: carl@rebol.com

Contents

1. Objective

Makespec 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 Makespec approach to writing documents quickly.)

2. 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 Makespec in one of two ways:

  1. If you run the Makespec program and a file request will prompt you for the filename of the text file.
  2. Or, you can specify the text file as an argument to the Makespec program.

This second approach allows you to embed a REBOL script within your text document that automatically calls Makespec 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.

3. Formatting

A very simple text format is used. It is trivial to create and easy to edit.

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

3.2. 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 Makespec Program

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

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

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

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

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

3.8. 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:

3.9. 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:

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

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

3.11. 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:

3.12. 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:

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:

  1. number one
  2. number two

3.13. Images

Images are placed in a document with the =image tag.

The line:

=image nyc.jpg

Would include the image centered in the document:

[ Image ]

To left justify the image:

=image left nyc.jpg
[ Image ]

3.14. 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:

[ Image ]

But, it can also be shown left justified as:

[ Image ]

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.

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

3.16. 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 %makespec.r %makespec.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.

4. Full Example

For a complete example of a Makespec document, view the makespec.txt file that was used to create this document.

5. New Features

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

5.2. 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 makespec.

Any number of =include commands can be used, and included files can also contain =include commands.

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

5.4. 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 makespec 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.

Font Names

Please be aware that some fonts names are not universally supported on all browser platforms. When machine specific fonts are used, please provide a more universal alternate font as shown in the examples above.

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