[Lazarus] FPDoc now with Markdown support

[Graeme Geldenhuys]

Hi Sergey,

[I've replied off the mailing list]

On 06/01/2021 2:16 am, Sergey Bodrov via lazarus wrote:
> Wikipedia and hundreds of wiki sites (includes freepascal wiki). De-facto
> standard for updateable documentation.

Markdown doesn't have any official (single) standard. Many versions exist
all over the internet. Wikipedia differs from, Github, which differs from
Gitlab, which differs from Grubber's original Markdown etc etc. It's a
total hit and miss if what you type is going to generate what you expect.
Yes, basic syntax like Bold, Italic etc works, but I'm talking about
more advanced document syntax.

>
> Main advantage in markdown, that it almost not uses closing tags for large
> blocks. So, no need to keep in mind whole document structure, no troubles
> with copy-paste and random edits.

Asciidoc is exactly the same, but it has an official syntax that everybody
adheres too. It also has a much richer syntax that Markdown lacks.

Off the top of my head:
 * comments inside your document that will not generate. Markdown doesn't
   have such support at all, and many recommend using HTML comments, but
   that only works if you were going to generate HTML output. What if I
   generate PDF's, TXT, IPF, MAN pages etc output.
 * Markdown also doesn't support:
    * Admonition
    * Sidebars
    * Block titles
    * includes files
   etc. All features very often used in documentation and books.
 * Note the HTML usage (again) for cross references in Markdown. AsciiDoc
   supports that seamlessly without reverting the embedded HTML.
 * Markdown doesn't support annotated code blocks (aka Callouts).


Further info with a side-by-side comparisons can be seen here:

  https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-markdown/

The official Asciidoc Users Guide:

  https://asciidoc.org/asciidoc.html


Regards,
  Graeme

-- 
fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal
http://fpgui.sourceforge.net/

My public PGP key:  http://tinyurl.com/graeme-pgp