logo

Fandoc

Overview

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

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

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

Inline Formatting

- Inline code: 'FandocParser'
- Strong: **foo bar**
- Emphasis: *foo bar*
- Hyperlink: `http://fandev.org/`
- Hyperlink: [Fan Home Page]`http://fandev.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!

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

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]`http://fandev.org/doc/logo.png`

fan logo

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 1

Ex Heading 2

Ex Heading 3

Hyperlinks

The docCompiler 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
- `sys::Str`: API for type
- `sys::Str.slice`: 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
- `WebApp`: chapter (internal to pod)
- `WebApp#LogStep`: anchor within chapter (internal to pod)

APIs:

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>