[Lazarus] FPDoc now with Markdown support

classic Classic list List threaded Threaded
24 messages Options
12
Reply | Threaded
Open this post in threaded view
|

[Lazarus] FPDoc now with Markdown support

Free Pascal - Lazarus mailing list

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.

Compare the official page for TObject.Dispatch:

https://www.freepascal.org/docs-html/current/rtl/system/tobject.dispatch.html

With the following pages:

They are all the same documentation page, but just use a different theme for mkdocs:

gitbook theme:
https://www.freepascal.org/~michael/docs-demo/gitbook/system/tobject.dispatch/

ivory theme:
https://www.freepascal.org/~michael/docs-demo/ivory/system/tobject.dispatch/

windmill theme: (seems broken)
https://www.freepascal.org/~michael/docs-demo/windmill/system/tobject.dispatch/

windmill dark theme: (seems broken)
https://www.freepascal.org/~michael/docs-demo/windmill-dark/system/tobject.dispatch/

docskimmer theme:
https://www.freepascal.org/~michael/docs-demo/docskimmer/system/tobject.dispatch/

default (mkdocs) theme:
https://www.freepascal.org/~michael/docs-demo/windmill-dark/system/tobject.dispatch/

readthedocs theme:
https://www.freepascal.org/~michael/docs-demo/readthedocs/system/tobject.dispatch/

material theme:
https://www.freepascal.org/~michael/docs-demo/material/system/tobject.dispatch/

Some themes work better than others.

Fun fact:
Generating the documentation in HTML with fpdoc takes a couple of seconds.
Depending on the theme, generating the docs with mkdocs (written in Python)
takes 3-7 minutes.

Just shows that Pascal code is very efficient, I suppose... ;-)

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

Enjoy,

Michael.


--
_______________________________________________
lazarus mailing list
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] FPDoc now with Markdown support

Free Pascal - Lazarus mailing list
> 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...

For "overview pages" (unit, class, package) I think need to move a "description section" to up and set it above a "uses section", because "description" is more useful information than list of units. Especially for the case when the list of files is big. I think that need to do for a html version also.
--
_______________________________________________
lazarus mailing list
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] FPDoc now with Markdown support

Free Pascal - Lazarus mailing list


On Sun, 3 Jan 2021, Соболь Андрей Евгеньевич 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...
>
> For "overview pages" (unit, class, package) I think need to move a
> "description section" to up and set it above a "uses section", because
> "description" is more useful information than list of units.  Especially
> for the case when the list of files is big.  I think that need to do for a
> html version also.

Good points. I am planning some small changes in the Markdown support.
I already moved the description up (after declaration, before members).

The uses section can indeed be moved down for units. I plan to add links to
the const/classes/types sections, because the menu may not always be very
accessible.

I am currently refactoring the HTML version so the layout can be changed
more easily, and descendents can be made. Once that is done, changes can be
implemented.

Michael.
--
_______________________________________________
lazarus mailing list
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] FPDoc now with Markdown support

Free Pascal - Lazarus mailing list
In reply to this post by Free Pascal - Lazarus mailing list
>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.

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

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

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>

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

>Enjoy,
>Michael.

Thanks for your efforts.

Best regards,

Don
--
_______________________________________________
lazarus mailing list
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] FPDoc now with Markdown support

Free Pascal - Lazarus mailing list


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.
--
_______________________________________________
lazarus mailing list
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] FPDoc now with Markdown support

Free Pascal - Lazarus mailing list
On Sun, Jan 3, 2021 at 6:06 PM Michael Van Canneyt
<[hidden email]> 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
--
_______________________________________________
lazarus mailing list
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] FPDoc now with Markdown support

Free Pascal - Lazarus mailing list


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

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

You do know that topics can be nested ?

I can add 'section', but it will be below the <descr> node, as IMO it makes no
sense to do this below the topic node because of the nesting.

Michael.

--
_______________________________________________
lazarus mailing list
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] FPDoc now with Markdown support

Free Pascal - Lazarus mailing list
In reply to this post by Free Pascal - Lazarus mailing list
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
--
_______________________________________________
lazarus mailing list
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] FPDoc now with Markdown support

Free Pascal - Lazarus mailing list


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.
--
_______________________________________________
lazarus mailing list
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] FPDoc now with Markdown support

Free Pascal - Lazarus mailing list

On 05/01/2021 9:47 am, Michael Van Canneyt via lazarus wrote:
> Because people are naturally lazy and prefer easy & simple over strict & rich.

Once again the simplest answer is always the one closest to the truth. :)


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

Oh my one cat is so fussy, he now wonders the neighbourhood looking all cute
and catches yet more suckers that will feed him something else. :-/


Regards,
  Graeme
--
_______________________________________________
lazarus mailing list
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] FPDoc now with Markdown support

Free Pascal - Lazarus mailing list
In reply to this post by Free Pascal - Lazarus mailing list
On 02/01/2021 2:31 pm, Michael Van Canneyt via lazarus wrote:
> material theme:
> https://www.freepascal.org/~michael/docs-demo/material/system/tobject.dispatch/

There seems to be an issue generating constants and values with a underscore
in the name.

You can see that here:

  https://www.freepascal.org/~michael/docs-demo/material/baseunix/arg_max/


const
   ARG\_MAX = UnixType.ARG\_MAX

instead of

const
  ARG_MAX = UnixType.ARG_MAX


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
--
_______________________________________________
lazarus mailing list
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] FPDoc now with Markdown support

Free Pascal - Lazarus mailing list
In reply to this post by Free Pascal - Lazarus mailing list
On 02/01/2021 2:31 pm, Michael Van Canneyt via lazarus wrote:
> Compare the official page for TObject.Dispatch:

Looking at another class with more detail... Did you explicitly enable
the functionality to generate Private, Protected fields and methods?
Or does the Markdown writer possibly not check if those were meant to
be hidden from the output.

The reason I ask, is because above you mentioned "official", and I know
in the official docs you don't generate private and protected
methods and fields in the output[1].

This page shows private and protected fields and methods:

 https://www.freepascal.org/~michael/docs-demo/material/classes/tlist/


Regards,
  Graeme


[1] https://www.freepascal.org/docs-html/rtl/classes/tlist.html

--
_______________________________________________
lazarus mailing list
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] FPDoc now with Markdown support

Free Pascal - Lazarus mailing list
In reply to this post by Free Pascal - Lazarus mailing list
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.

Wikipedia and hundreds of wiki sites (includes freepascal wiki). De-facto standard for updateable documentation.

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.

--
_______________________________________________
lazarus mailing list
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] FPDoc now with Markdown support

Free Pascal - Lazarus mailing list
In reply to this post by Free Pascal - Lazarus mailing list


On Wed, 6 Jan 2021, Graeme Geldenhuys via lazarus wrote:

> On 02/01/2021 2:31 pm, Michael Van Canneyt via lazarus wrote:
>> Compare the official page for TObject.Dispatch:
>
> Looking at another class with more detail... Did you explicitly enable
> the functionality to generate Private, Protected fields and methods?
> Or does the Markdown writer possibly not check if those were meant to
> be hidden from the output.

The latter.

Thanks for pinting it out.

Michael.
--
_______________________________________________
lazarus mailing list
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] FPDoc now with Markdown support

Free Pascal - Lazarus mailing list
In reply to this post by Free Pascal - Lazarus mailing list


On Wed, 6 Jan 2021, Graeme Geldenhuys via lazarus wrote:

> On 02/01/2021 2:31 pm, Michael Van Canneyt via lazarus wrote:
>> material theme:
>> https://www.freepascal.org/~michael/docs-demo/material/system/tobject.dispatch/
>
> There seems to be an issue generating constants and values with a underscore
> in the name.
>
> You can see that here:
>
>  https://www.freepascal.org/~michael/docs-demo/material/baseunix/arg_max/
>
>
> const
>   ARG\_MAX = UnixType.ARG\_MAX
>
> instead of
>
> const
>  ARG_MAX = UnixType.ARG_MAX

Hm. I'll need to check that. Seems I forgot to disable quoting for code
blocks. Thanks !.

Michael.
--
_______________________________________________
lazarus mailing list
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] FPDoc now with Markdown support

Free Pascal - Lazarus mailing list
In reply to this post by Free Pascal - Lazarus mailing list
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
--
_______________________________________________
lazarus mailing list
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] FPDoc now with Markdown support

Free Pascal - Lazarus mailing list

On 06/01/2021 5:48 pm, Graeme Geldenhuys via lazarus wrote:
> Hi Sergey,
>
> [I've replied off the mailing list]


Apologies, my stupid email client replaced the TO name, but still went
and sent it to the mailing list. :-(


Regards,
  Graeme
--
_______________________________________________
lazarus mailing list
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] FPDoc now with Markdown support

Free Pascal - Lazarus mailing list
In reply to this post by Free Pascal - Lazarus mailing list
El 05/01/2021 a las 10:47, Michael Van Canneyt via lazarus escribió:
>
> Because people are naturally lazy and prefer easy & simple over strict
> & rich.
>

But we could chose a language that is easy & simple for when you want to
do simple things (90% time) and rich when you need to do complex things.
Asciidoc is very easy, but more standarized, and very rich if you need
to to do complex things.

if markdown is to be used, it should be specified which flavor, not just
"markdown"
https://github.com/commonmark/commonmark-spec/wiki/Markdown-Flavors

if we are going for markdown (wouldn't be my first choice) I would go
for Github flavor
https://docs.github.com/en/free-pro-team@latest/github/writing-on-github

Once again, I would prefer Asciidoc

--
Saludos

Santiago A.

--
_______________________________________________
lazarus mailing list
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] FPDoc now with Markdown support

Free Pascal - Lazarus mailing list


On Thu, 7 Jan 2021, Santiago A. via lazarus wrote:

> El 05/01/2021 a las 10:47, Michael Van Canneyt via lazarus escribió:
>>
>> Because people are naturally lazy and prefer easy & simple over strict
>> & rich.
>>
>
> But we could chose a language that is easy & simple for when you want to
> do simple things (90% time) and rich when you need to do complex things.
> Asciidoc is very easy, but more standarized, and very rich if you need
> to to do complex things.
>
> if markdown is to be used, it should be specified which flavor, not just
> "markdown"
> https://github.com/commonmark/commonmark-spec/wiki/Markdown-Flavors
>
> if we are going for markdown (wouldn't be my first choice) I would go
> for Github flavor
> https://docs.github.com/en/free-pro-team@latest/github/writing-on-github
>
> Once again, I would prefer Asciidoc
Anyone is free to propose an FPDoc importer for AsciiDoc, MarkDown (insert flavour of the
month), ReStructuredText.

All it needs to do is convert the given format to fpdoc format, which will
then be processed by fpdoc in the usual manner.

As I said, I do not plan to switch the existing documentation format to markdown
or any other format. The idea is simply to make writing documentation easier for
other users.

I mentioned Markdown because I need it myself for work, so if I decide to work on it,
it will be markdown. In the original "Gruber" format, since that is what mkdocs uses,
and from first glances the used Python parser is very simple, straightforward and
extensible. The best I've seen yet.

Michael.
--
_______________________________________________
lazarus mailing list
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
Reply | Threaded
Open this post in threaded view
|

Re: [Lazarus] FPDoc now with Markdown support

Free Pascal - Lazarus mailing list
In reply to this post by Free Pascal - Lazarus mailing list
On 07/01/2021 9:49 am, Santiago A. via lazarus wrote:

> https://github.com/commonmark/commonmark-spec/wiki/Markdown-Flavors

Wow, I knew about a few variations, but I didn't know there
was that many. It's worse than I thought.


Regards,
  Graeme

--
_______________________________________________
lazarus mailing list
[hidden email]
https://lists.lazarus-ide.org/listinfo/lazarus
12