[Lazarus] FPDoc now with Markdown support

[Graeme Geldenhuys]

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).

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.


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