--markdown command-line option

Overview

Run PasDoc with --markdown command-line option to understand (a subset of) Markdown syntax in the comments. This allows to specify various formatting options without writing @tags, which sometimes looks much more readable.

Supported blocks

Note that only a subset of Markdown syntax is supported.

  • Bold text: **bold** or __bold__ (output like @bold tag)

  • Italic text: *italic* or _italic_ (output like @italic tag)

  • Inline code: `code` (output like @code tag)

  • Links to external URLs: [Link Title](https://example.org/link-target) (output like @url tag)

  • Links to Pascal items:

    • (TODO, see #151) [PascalItem], when not followed immediately by an opening parenthesis, is a simple link to the given Pascal identifier. The link will lead to PascalItem and will also display PascalItem title. You can always use qualified Pascal identifiers, like UnitFoo.PascalItemInUnitFoo or TClassBar.PascalItemInTClassBar or even UnitFoo.TClassBar.PascalItemInTClassBar

    • Alternatively, provide separate link title and target, using # to indicate that target is a Pascal item (not URL). Like this: [Title of link](#PascalItem). This is compatible with Doxygen.

    • Note: Use backslash to prevent turning something into links, \[ in Markdown will result in outputting simple [ character. For example this is not a link: \[NotALink].

    • Output of Pascal links is just like @link tag.

  • Multi-line code (preformatted text, output like @preformatted tag):

    Important note: Use 3 backtick characters, like this ```, to make this work. In the example below we show 3 apostrophes because of a limitation of GitHub wiki formatting (seems to implement incomplete/old AsciiDoctor syntax for escaping).

    '''
Example
preformatted
multi-line
text.
'''

  • Multi-line Pascal code with syntax highlighting (output like @longCode tag):

    Important note: Use 3 backtick characters, like this ```, to make this work. In the example below we show 3 apostrophes because of a limitation of GitHub wiki formatting (seems to implement incomplete/old AsciiDoctor syntax for escaping).

    '''pascal
if Foo then
  Writeln('Example Pascal code'); // comment
'''

  • Unordered lists (output like @unorderedlist tag):

    * item 1
* item 2

  • Ordered lists (output like @orderedlist tag):

    1. item 1
2. item 2

Notes on lists

List items are defined with the usual format:

[WHITESPACE*N]MARKER[item contents]

Where:

  • WHITESPACE*N is any number (including zero) of tabs #9 or spaces #32

  • MARKER is

    • * or -, followed by one whitespace character, for unordered lists

    • NUMBER, followed by . or ), followed by one whitespace character, for ordered lists

Nested lists are supported as well. Each nested list must be indented with at least one more whitespace character than the parent item:

* item 1
  * item 1.2
    * item 1.3

Note that PasDoc implementation of lists is somewhat simpler and stricter than, f.i., GitHub has. PasDoc is much about indents - almost always a content belonging to one nesting level has the same indent. Exception is for text content without empty line only. Rules of how PasDoc reads list item contents (hereafter indent of a text line means number of leading whitespace characters and indent of a list item means number of leading characters before first character of item content - that is, leading whitespace characters plus list marker).

  • List item with indent lesser than current means current list is finished

 * item 1
  * item 1.2
 * item 2

  • List item with indent greater than current means nested list

* item 1
 * item 1.1

  • Line of text not preceded by empty line belongs to current item regardless of indent

* item 1
  * item 1.1
text 1.1
   text 1.1

  • Line of text preceded by empty line must have the same or greater indent to belong to current item. Text with lesser indent means current list is finished

* item 1
  * item 1.1
    text 1.1
      text 1.1
* item 2
  * item 2.1

   text 2

  • List item with the same indent is considered sibling of current item within current list (even preceded by empty line!)

* item 1

* item 2

* item 3

Example unit

See the test unit of this feature and pasdoc output for this test (generated with --markdown option).

Future

Going forward, we want to implement as much as possible from GitHub Flavored Markdown syntax. All new Markdown features implemented in PasDoc should follow that spec as closely as possible.