Re: [Lazarus] FPDoc now with Markdown support
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 lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
Re: [Lazarus] FPDoc now with Markdown support
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 lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
Re: [Lazarus] FPDoc now with Markdown support
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 lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
Re: [Lazarus] FPDoc now with Markdown support
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 lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
Re: [Lazarus] FPDoc now with Markdown support
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 lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
Re: [Lazarus] FPDoc now with Markdown support
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 lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
Re: [Lazarus] FPDoc now with Markdown support
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 lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
Re: [Lazarus] FPDoc now with Markdown support
> > 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 lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
Re: [Lazarus] FPDoc now with Markdown support
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 lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
Re: [Lazarus] FPDoc now with Markdown support
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 lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
Re: [Lazarus] FPDoc now with Markdown support
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 lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
Re: [Lazarus] FPDoc now with Markdown support
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 lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
Re: [Lazarus] FPDoc now with Markdown support
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 lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
Re: [Lazarus] FPDoc now with Markdown support
On Sun, 3 Jan 2021, Don Siders via lazarus wrote: > I would rather see sectioning added to the FPDoc tags/content model: > > > >Using the Control >Lorem ipsum sic dolor amet. > > 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 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: Using the Control Lorem ipsum sic dolor amet. In specific, could render like the HTML equivalent (as a biock). 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 node, as IMO it makes no sense to do this below the topic node because of the nesting. Michael. -- ___ lazarus mailing list lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
Re: [Lazarus] FPDoc now with Markdown support
On Sun, Jan 3, 2021 at 6:06 PM Michael Van Canneyt 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: > > > > > > > >Using the Control > >Lorem ipsum sic dolor amet. > > > > > > 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 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: Using the Control Lorem ipsum sic dolor amet. In specific, could render like the HTML equivalent (as a biock). 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 lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
Re: [Lazarus] FPDoc now with Markdown support
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: Using the Control Lorem ipsum sic dolor amet. 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 lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
Re: [Lazarus] FPDoc now with Markdown support
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 lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
Re: [Lazarus] FPDoc now with Markdown support
> 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 lazarus@lists.lazarus-ide.org https://lists.lazarus-ide.org/listinfo/lazarus
