Overview

Fandoc is documentation format written in plaintext similiar to Markdown. Fandoc is the format used for:

• Fantom source code documentation via the ** comment
• All the documentation manuals (including this document itself)
• Comments on fantom.org discussion groups

You can use the fandoc APIs to parse fandoc plaintext into a document object model and generate HTML.

Header

The begining of a Fandoc document may be prefixed with a header block. The header block includes a series of lines which begin with **. If the line includes a colon, then it is added a key/value pair to Doc.meta. For example, we use the following header in the standard documentation:

**************************************************************************
** title:      Fandoc
** author:     Brian Frank
** created:    10 Apr 08
** copyright:  Copyright (c) 2008, Brian Frank and Andy Frank
** license:    Licensed under the Academic Free License version 3.0
**************************************************************************

Inline Formatting

- Inline code: 'FandocParser'
- Strong: **foo bar**
- Emphasis: *foo bar*
- Strong+Emphasis: ** *foo bar* **
- Hyperlink: `https://fantom.org/`
- Hyperlink: [Fantom Home Page]`https://fantom.org/`

• Code inline: FandocParser
• Strong: foo bar
• Emphasis: foo bar
• Strong+Emphasis: foo bar
• Hyperlink: https://fantom.org/
• Hyperlink: Fantom Home Page

Paragraphs

Paragraphs are separated by a blank line:

Lorem ipsum dolor sit amet, consectetur adipisicing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris
nisi ut aliquip ex ea commodo consequat.

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Preformatted

When documenting a programming language, you tend to include lots of code snippets. Anything indented two or more spaces is considered preformatted (like the pre tag in HTML). Preformatted code cannot start with a dash/space, number/dot/space, or letter/dot/space otherwise it considerded a list:

Examples:
  "abcd"[0..2]   => "abc"
  "abcd"[3..3]   => "d"
  "abcd"[-2..-1] => "cd"

Examples:

"abcd"[0..2]   => "abc"
"abcd"[3..3]   => "d"
"abcd"[-2..-1] => "cd"

You can also denote a block of text as preformatted by wrapping it with the special tokens pre> and <pre:

pre>
- No markup
- I mean it!
<pre

- No markup
- I mean it!

Blocks annotated with the pre> token are trimmed based on the line with the left most margin.

Unordered List

Unordered lists use a dash followed by a space. Use indentation to indicate list hierarchy (two or more spaces):

- item 1
- item 2
- item 3
   - sub 3a
   - sub 3b
- item 4

• item 1
• item 2
• item 3
  • sub 3a
  • sub 3b
• item 4

Ordered List

Ordered lists use an identifier followed by a dot and space. The identifier can be a number, letter, or roman numeral (lower or upper case). Use indentation to indicate list hierarchy (two or more spaces):

I. Chapter I
  1. Section 1
  2. Section 2
    a. Subsection a
    b. Subsection b
II. Chapter II
  A. Section A
  B. Section B
    i. Subsection i
    ii.Subsection ii

1. Chapter I
   1. Section 1
   2. Section 2
      1. Subsection a
      2. Subsection b
2. Chapter II
   1. Section A
   2. Section B
      1. Subsection i
      2. Subsection ii

Horizontal Rules

Horizontal rules start with ---, and must be preceded by a blank line:

Above the rule

---

Below the rule

Above the rule

---

Below the rule

Block Quotes

Block quotes start the first line (or every line) of the paragraph with the ">" character followed by a space:

> Lorem ipsum dolor sit amet, consectetur adipisicing elit,
> sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

> Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris
nisi ut aliquip ex ea commodo consequat.

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Images

Images use the same syntax as a hyperlink with anchor text, but are prefixed with a bang:

![fan logo]`https://fantom.org/pod/fantomws/res/img/fantom.png`

You can set an explicit size for the image as follows:

![fan logo][80x18]`https://fantom.org/pod/fantomws/res/img/fantom.png`

You can make an image a link as follows with no spaces between the brackets:

[![alt]`https://fantom.org/pod/fantomws/res/img/fantom.png`]`https://fantom.org/`

Headings

Headings are a title line followed by an "underline". Documentation should define an anchor id for each heading:

Ex Heading 1 [#h1]
##################

Ex Heading 2 [#h2]
******************

Ex Heading 3 [#h3]
==================

Ex Heading 4 [#h4]
------------------

Ex Heading 1

Ex Heading 2

Ex Heading 3

Ex Heading 4

Note: By convention top level sections of a chapter use heading level 2. Heading level 1 is reserved for the chapter title.

Hyperlinks

The compilerDoc pod is used to compile API or stand-alone documentation. It allows you to use abstract uris to create cross reference hyperlinks. During the compilation these uris are translated into relative links to the appropiate HTML files. Hyperlinks to types and slots are automatically formatted as inline code.

**APIs:**
- `sys::index`: pod index
- `web::pod-doc`: pod documentation
- `sys::Str`: API for type
- `sys::Str.getRange`: API for slot
- `Int`: API for type (internal to pod)
- `Int.toHex` API for slot (internal to pod)
- [now]`sys::Duration.now` API with achor text

**Manuals:**
- `docLang::index`: pod index
- `docLang::Closures`: chapter
- `docLang::Closures#syntax`: anchor within chapter
- `Env`: chapter (internal to pod)
- `Env#index`: anchor within chapter (internal to pod)

APIs:

• sys: pod index
• Web: pod documentation
• Str: API for type
• Str.getRange: API for slot
• Int: API for type (internal to pod)
• Int.toHex API for slot (internal to pod)
• now API with achor text

Manuals:

• docLang: pod index
• Closures: chapter
• Closures: anchor within chapter
• Env: chapter (internal to pod)
• Env#index: anchor within chapter (internal to pod)

Fandoc API

The FandocParser class is used to parse fandoc plaintext into a document object model. The DocNode is the base class of all nodes in the document tree. The tree is organized as subclasses of DocElems. The leaves of the tree which contain the actual text content are DocText.

Once a tree has been parsed into a DOM, you can translate into alternate formats via the DocWriter class. You can use HtmlDocWriter to translate to XHTML:

// parse into document tree
doc := FandocParser.make.parseStr("you want to do *what*!")

// write as html snippet (we don't write the
// document itself, just its children)
doc.writeChildren(HtmlDocWriter.make)

// outputs
<p>you want to do <em>what</em>!</p>

// write as full html document with head/body tags
doc.write(HtmlDocWriter.make)

// outputs
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
  <meta http-equiv='Content-Type' content='text/html; charset=UTF-8'/>
</head>
<body>
<p>you want to do <em>what</em>!</p>
</body>