[Lazarus] FPDoc now with Markdown support

[Michael Van Canneyt]

On Tue, 5 Jan 2021, Graeme Geldenhuys via lazarus wrote:

> On 03/01/2021 7:48 pm, Don Siders via lazarus wrote:
>>> I've been looking at allowing markdown for the description files (they would
>>> be less verbose then), but there seems to be no decent markdown parser available
>>> for pascal. If somone cares to contribute one...
>> Oh boy. I guess it is inevitable, but I don't think it's a
>> particularly good idea.
>> 
>> I have no aversion to XML tagging. I don't mind its rigid nature
>> because it guarantees consistent, predictable input.
>> 
>> Markdown is anarchy in my opinion, and you can't impose order on
>> anarchy. Markdown is great for readme or FAQ files. Not so great for a
>
>
> Agreed. Markdown and FPDoc's description syntax suffer the same problems. The
> syntax isn't rich enough, and thus falls back to using embedded HTML syntax
> (officially or unofficially) and mostly assumes that HTML with be the
> final generated format. This is not always the case.
>
> On the other hand AsciiDoc has a MUCH richer syntax and is equally
> intuitive to write because it too looks like plain text emails you
> would normally write. But it also has a much richer syntax that covers
> everything you need for documentation or technical articles (excluding
> formulas). Things like comments in syntax, include files, an actual
> specification, less "derived alternatives" (eg: Github Markdown, original
> Gruber markdown etc).

Apart from AsciiDoc being equally intuitive, I agree with your statements.

> There are many articles on the Internet going in much more detail
> describing the issues of Markdown. Yet like Windows, it seem still so
> popular. I have no idea why.

Because people are naturally lazy and prefer easy & simple over strict & rich.

Add to that time pressure imposed by deadlines, and there you have all the
reasons why markdown is popular: great for quickly "mashing" some things together...
Many of github README.md files are not even worth the trouble of writing them
for all the use they offer.

Basically the same reasons why my cat prefers the awful can food I give her over going
out to hunt for her breakfast ;-)

Michael.