pod

fandoc

Fandoc parser and DOM

mixins

DocWriter	DocWriter is used to output a fandoc model using a series of callbacks.

classes

BlockQuote	BlockQuote models a block of quoted text.
Code	Code is inline code
Doc	Doc models the top level node of a fandoc document.
DocElem	DocElem is a container node which models a branch of the doc tree.
DocNode	DocNode is the base class for nodes in a fandoc model.
DocText	DocText segment.
Emphasis	Emphasis is italic text
FandocDocWriter	FandocDocWriter outputs a fandoc model to plain text fandoc format
FandocParser	FandocParser translate fandoc text into an in-memory representation of the document.
Heading	Heading
Hr	Hr models a horizontal rule.
HtmlDocWriter	HtmlDocWriter outputs a fandoc model to XHTML
Image	Image is a reference to an image file
Link	Link is a hyperlink.
ListItem	ListItem is an item in an OrderedList and UnorderedList.
MarkdownDocWriter	MarkdownDocWriter outputs a fandoc model to Markdown
OrderedList	OrderedList models a numbered list
Para	Para models a paragraph of text.
Pre	Pre models a pre-formated code block.
Strong	Strong is bold text
UnorderedList	UnorderedList models a bullet list

enums

DocNodeId	DocNodeId
OrderedListStyle	OrderedListStyle

errs

FandocErr	FandocErr

docs

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.

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

Chapter I
1. Section 1
2. Section 2
  1. Subsection a
  2. Subsection b
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`

fan logo

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>

pod