[Lazarus] FPDoc now with Markdown support

Michael Van Canneyt michael at freepascal.org
Mon Jan 4 00:06:35 CET 2021



On Sun, 3 Jan 2021, Don Siders via lazarus wrote:

>> Hello !
>>
>> I didn't make it quite in time for the new year, but still:
>>
>> The fpdoc engine (what is used to document the FPC & Lazarus units)
>> is now capable of outputting the documentation in markdown.
>>
>> This can be used as input for mkdocs or another engine such as sphinx.
>> As a first engine, I tackled mkdocs.
>> ...
>
> Happy New Year, Michael.

Thank you :-)

>
> I'm glad to see that FPDoc is getting some "love". I applaud any
> effort to improve or modernize the help.

Well, most 'love' has been going into the source parser in the last years.

For my day job I came into contact with mkdocs and sphinx, and was impressed
by some of the output it can generate. So the idea was born to leverage that
in fpdoc.

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

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


>
> I have no aversion to XML tagging. I don't mind its rigid nature
> because it guarantees consistent, predictable input.

I agree fully with this point of view, but not everyone may agree :-).

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

>
> 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
> large, structured documentation project. I would never choose to
> author reference topics using markdown.

Personally, I agree :-)

>
> 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 ?

>
> I'd like to see PDF output from FPDoc too.

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

Both sphinx and mkdocs can also generate PDFs from the markdown.

Using the fpPDF support of FPC it should of course be possible to create PDF output
directly.

Michael.


More information about the lazarus mailing list