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

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/`

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`

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`

fan logo

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/`

alt

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.

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:

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>