[Lazarus] FPDoc now with Markdown support

[Don Siders]

On Sun, Jan 3, 2021 at 6:06 PM Michael Van Canneyt
<michael at freepascal.org> wrote:

> >> I've been looking at allowing markdown for the description files (they would
> >> be less verbose then), ...

> > Oh boy. I guess it is inevitable, but I don't think it's a
> > particularly good idea.

> Personally, I don't plan to use Markdown as input for fpdoc.

Seems both my assumption and jump to conclusion are unfounded. ;)

> Times change, and I can imagine that people prefer a more 'free' format.
> I'm just hoping to attract more users and possibly contributors...

I spent too many years trying to do the same thing for an open source
project... unsuccessfully I might add. It was my experience that
changing the tooling does attract a little short-term interest, but
not actual content contributors.

> > I would rather see sectioning added to the FPDoc tags/content model:
> >
> > <topic>
> >  <section>
> >    <title>Using the Control</title>
> >    <p>Lorem ipsum sic dolor amet.</p>
> >  </section>
> > </topic>
>
> And what would this do in terms ouf output ?

In general, it would make FPDoc more usable for non-reference type
material. Grouping related content. If <section> has a name, it could
provide another level of navigation in the TOC. It provides a standard
way to tag a Formal Para, instead of emulating it it with:

  <p>
    <b>Using the Control</b>
  </p>
  <p>
    Lorem ipsum sic dolor amet.
  </p>

In specific, <section> could render like the HTML equivalent (as a
biock). <title> renders like the HTML H4 tag. The rest of the content
model renders just like the current usage.

> > I'd like to see PDF output from FPDoc too.>
> Currently PDF is generated through LaTeX.

Yeah... I know.

> The LaTeX typesetting engine is difficult to beat.
> Hyphenation, page breaks: you get all that for free.

Sorry, but Latex gives me the hives. After twenty years, I still have
DataLogic Pager nightmares. :)

Don