I would like to propose a step-by-step migration of fandoc to markdown. When we first created fandoc 20 years ago there were many competing plain text formats so it was only loosely based on markdown. But now markdown is definitely the winner, so it would be good to start the process of standardizing on it.
Last year Matthew ported a Java library with full support for Commonmark to Fantom via the new markdown pod. This pod also supports an extension mechanism. So this will be the new standard parser for documentation.
Proposed Initial Scope
My initial proposal is to convert only fandoc chapters files from .fandoc to .md. We will continue to use fandoc for all in-code documentation in .fan files, and also leave the forum posts in fandoc format for now. For example we would convert all the fandoc chapters of docLang, docDomkit, etc as well as in-pod chapters such as web/pod.fandoc. With this change, all the documentation files will be formatted nicely on GitHub and more easily edited/previewed using standard tools.
Proposed Syntax
The proposed syntax is the Commonmark specification as our standard markdown grammar with a few extensions:
maintain support for link shortcuts using [foo] syntax
Currently we use the following syntax for inline links as covered here:
**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 anchor 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)
With a full conversion to markdown the backticks will become inline code and will no longer be a link. Instead will will allow a specialized link syntax using only square brackets:
// current shortcut link to Str type
This is a link to `sys::Str`!
// proposed shortcut link to Str type
This is a link to [sys::Str]!
// which is essentially a shortcut for this
This is a link here [sys::Str](sys::Str)!
This link syntax allows us to still easily use terse hyperlinks, but much closer to markdown syntax.
brian Mon 8 Dec
I would like to propose a step-by-step migration of fandoc to markdown. When we first created fandoc 20 years ago there were many competing plain text formats so it was only loosely based on markdown. But now markdown is definitely the winner, so it would be good to start the process of standardizing on it.
Last year Matthew ported a Java library with full support for Commonmark to Fantom via the new markdown pod. This pod also supports an extension mechanism. So this will be the new standard parser for documentation.
Proposed Initial Scope
My initial proposal is to convert only fandoc chapters files from
.fandocto.md. We will continue to use fandoc for all in-code documentation in.fanfiles, and also leave the forum posts in fandoc format for now. For example we would convert all the fandoc chapters of docLang, docDomkit, etc as well as in-pod chapters such as web/pod.fandoc. With this change, all the documentation files will be formatted nicely on GitHub and more easily edited/previewed using standard tools.Proposed Syntax
The proposed syntax is the Commonmark specification as our standard markdown grammar with a few extensions:
[foo]syntaxCurrently we use the following syntax for inline links as covered here:
With a full conversion to markdown the backticks will become inline code and will no longer be a link. Instead will will allow a specialized link syntax using only square brackets:
This link syntax allows us to still easily use terse hyperlinks, but much closer to markdown syntax.
Comments and feedback welcome!