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.

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.

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

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.

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

Personally, I agree :-)

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.

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.

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

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.

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

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.

Michael Van Canneyt 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

Michael Van Canneyt 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

Michael Van Canneyt 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

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.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus-ide.org/pipermail/lazarus/attachments/20210106/64c14965/attachment-0001.html>

The latter.

Thanks for pinting it out.

Michael.

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

Michael.

Hi Sergey,

[I've replied off the mailing list]

Sergey Bodrov 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

Graeme Geldenhuys 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

Michael Van Canneyt wrote

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

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

Hello,
I see that nobody used to a tag <examples> for creating documentation lcl, lazutil. That tag is used only the fpc team.
I have read a documentation and saw rtl .xml`s and so. I want to create a directory for used examples of code as :

- lazarus/doc/exlcl
- lazarus/doc/exlazutil

and put inside files in notation with dots. For example: fileutil.findallfiles.pas (I think it will be convenient)

+ readme.txt (into those directories)
+ wiki descriptions about it.

I have checked it, a html`s works and a chm`s too.

What is yours opinion about it?
And how to create directory, also by patch?

Andrey Sobol.

Me personally prefer to place short code snippets into help pages, with some syntax highlight. Also, big code samples can be made as separate help (html) files, with detailed description. Same as in Wiki.

Pure code examples can be found in lazarus/examples directory, they even have browser, embedded in IDE (create progect, browse samples).

On Fri, Jan 15, 2021, 10:53 Соболь Андрей Евгеньевич via lazarus <

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus-ide.org/pipermail/lazarus/attachments/20210116/6fe0b3a4/attachment-0001.html>

I opened the topic about short code examples that should be embedded in the documentation. About the full examples I know.

Also I and Trevor have wrote a readme.txt file for those directories: The file you can read here:
https://drive.google.com/file/d/1wHiM-UMClcjvmBLj1PQDwwQ4sNKdXl79/view?usp=sharing

Andrey

Соболь Андрей Евгеньевич wrote

I see that nobody used to a tag <examples> for creating documentation lcl, lazutil. That tag is used only the fpc team.

It seem to be a decision made by the Lazarus team. I've used the EXAMPLE tag for years with the tiOPF project as well, and very happy with the result. I only use in for small code snippets though, not full programs.

tiOPF docs:
https://sourceforge.net/p/tiopf/tiopf_docs/ci/master/tree/

tiOPF HTML doc with example code:
http://geldenhuys.co.uk/tiopf/tiobject/ttiobject.dogetfieldbounds.html

Regards,
Graeme