REBOL 3 Document Editing and Notations

How to edit these wiki pages.

Accounts

Quick summary

Markup notations

Doc links, word markup

Bullet list

Numbered lists

Special

Accounts

To edit pages in this wiki, you need an account.

If you have an account on the R3 Chat system (run R3 and type "chat") with a user ranking greater than 50, your same username and password will give you access to this wiki.

If you are knowledgeable about REBOL or have experience with editing technical documentation, we welcome your involvement with this wiki. Please post a request in the R3 Chat group #22 (R3/Docs) for advanced ranking.

Quick summary

This is MakeDoc3, quite different from MakeDoc2.
Paragraphs are separated with blank lines.
Bullets no longer require blank line separation.
Code sections are indented. We use 4 spaces for tab indentation.
Main notations are listed below.
Special commands begin with = (equal sign).

Markup notations

The WIP system uses the MakeDoc "markdown" style (one of the original minimal-markup methods created for rapid web-page creation.)

Generally, you use blank lines as separators, followed by either paragraphs of content or special command lines.

The command lines normally begin with an equal sign "=", but for convenience, some special markups use other characters (such as "*" for bullets and "#" for enumerated lists.)

Headings

Notation	What	Details
==title	Main heading	Top level heading.
===title	Sub-heading	Second level heading.
====title	Subsection heading	Third level heading. Use only when necessary.

Special sections

Notation	What	Details
*item	Bullet item.	Displays a line of a bullet list. You can use more stars for deeper levels. See below.
#item	Numbered item.	Displays a line of a numbered list. You can use ## and ### for deeper levels.
:name - text description	Definition.	Displays a word followed by a description (indented).
(indented text)	Code example.	Displays a code example in a box with fixed-width font.
= output	Code result.	Displays console output in a box with fixed-width font.

Inline notations

Within the text of a paragraph, a special notation let's you easily make links to other sections of the document. A single character followed by a colon (:) and the page name is normally all you need to create a link with the proper visual style.

Notation	What	Details
c:word	Concept reference.	Creates a link to the given concept chapter, with its current title.
g:word	Guide reference.	Creates a link to the given user-guide section, with its current title.
f:word	Function reference.	Highlights a function name; links to function description.
r:/refinement	Function refinement.	Highlights a function refinement word.
d:word	Datatype reference.	Highlights a datatype name; links to datatype description.
e:word	Error reference	Links to the related error by name.
s:path	System object reference.	Highlights a path (and will eventually link to) a system variable.
w:word	Word in text.	Highlights a word in text that is not function, datatype, or other important thing.
v:word	Value reference	Highlights a value in the text.
:[page.html text link]	Hypertext link.	Links to the specified page using the text provided.

Special commands

Command	What	Details
=r3	R3 updated.	Put this tag just below the page title to indicate that the page has been updated to reflect REBOL 3.0. It will also remove the R2 note box (if present).
=note	Note box.	Starts a note box. Title of note can be on same line. Follow it with paragraphs that are in the note. End it with =/note command.
=code	Code line.	A single code line with reduced borders. Used often in tables (such as this one.)
=*	Bolded line.	Begins bold for a line. Necessary because star is also used for bullets.
=!text	Editor note.	Displays an editor note. Used mainly for notes about progress or content still needed. If no text is provided, will display a default note saying that more editing is needed.
=table	Start a table.	Starts a new table. Each cell of table follows, separated by a blank line. New rows begin with =row command. Table ends with =/table command.

Examples

Section title

The above "Examples" heading was written like this:

==Examples

Paragraphs:

Each paragraph can be wrapped or not wrapped, because
all paragraphs are separated with blank lines.

So this is the next paragraph. This method makes it
easier to deal with markup text from command shells
and other environments where line wrapping is problematic.

Code examples:

You simply indent the text. It gives you a box like this
and uses a fixed space font to provide proper blocking.
In addition the < and > chars are escaped so you don't
need to worry about them becoming tags.

To show code output, you can use a = followed by indentation. The result is:

print "example output"
example output

Doc links, word markup

Very easy. Just use the file name for the page, the link and title will be generated automatically

Link to the f:append function.

Link to the c:series concept.

Link to a d:datatype section.

Reference to a w:word

Reference to a v:value

Link to the append function.

Link to the series concept.

Link to a datatype! section.

Reference to a word

Reference to a value

Bullet list

*This is bullet one
*This is bullet two
**This is a sub-bullet
**This is another sub-bullet

This is bullet one
This is bullet two

This is a sub-bullet
This is another sub-bullet

Numbered lists

#Item one
#Item two
##Item two, sub one
##Item two, sub two

Item one
Item two

Item two, sub one
Item two, sub two

Special

To create bold text:

Here is some *bold text*!

Here is some bold text!

To create a bold line or paragraph, you must use a special notation to distinguish it from a bullet:

=*This is a bold line!*

This is a bold line!

For editor "in-progress" notes:

=!Special message from editor

Editor note: Special message from editor

To create a special note box:

=note Special note

Contents of the note go here. It can be any
kind of text or markup.

=/note

Special note

Contents of the note go here. It can be any kind of text or markup.