Re: [TCLCORE] [External] Re: TCT/TIP reform

[Torsten B. <be...@ty...>]

Hi,

looking at the discussion on the chat (I can only access it via the jabber logs at http://tclers.tk/conferences/tcl/right now, TkChat complains deep down in xml::parser) and my email correspondance with Shaun and Steve, let me propse to not throw yet another formatter/documentation language into the pool. I took a short look at poshdoc and it seems it is HTML with some additions.

First, I disagree that markdown is not semantic. Lok at this:

doctools: [section {Section A}]
HTML: <h2>Section A</h2>
markdown: ## Section A

doctools: [emph {Some emphasized text}]
HTML: <emph>Some emphasized text</emph>
markdown: *Some emphasized text*

I do not see the difference. All three use some kind of "markup"/"symbols" to signify that a certain portion of text has a special meaning or belongs to a specific context. Markdown uses least "noise" making that particular format human-readable for most parts, the markup is not looking as if it were programming/coding the text, making the documents accessible to people not wanting to "read code". That was the an important part of the whole purpose of markdown in the first place - make writing easy.

Whether <emph> or '*' makes the text italics or bold or something entirely different is not part of the markup, it is part of the later interpretation. The markup just tells the parser that some content of a document means something specific and it is left to the formatting engine to visualize that content in a sensible way.

The main reason for me to stick to markdown is that it is used in so many places that people can easily contribute to the content (that's what we want in the end, right? Content from the people, to the people!) without needing to learn yet another markup. They can put the sources into their favorite formatter and play around with it easily.

Then, using the right markdown "dialect" for the manual pages, in this case Pandoc's markdown, we get free access to not less than some 15+ output formats. We also get for free: custom readers and writers to implement other formats (we could easily do markdown2doctools.tcl), filters (for special treatment of the markdown when converting to other formats) and much more. Pandoc is being actively worked at by John McFarlane with an astonishing pace (he is also father of CommonMark).They have a very helpful and friendly community, just as we have.

Reason 1 not to go for markdown would be: it doesn't have semantics for everything we need. "command syntax" markup comes to mind:

example: lsort -integer <aList>
doctools:  [call [cmd lsort] [opt [-integer]] [arg aList]]

It can be done with Pandoc's markdown, just not with the basic syntax, here using class names:

[lsort]{.cmd} [-integer]{.opt} [aList]{.arg}

We can even use key/value-pairs if we need more fine-grained control. Or we put the original line into a fenced div:

:::call:::
lsort -integer <aList>
:::

... and write a Pandoc filter to pull this apart and do something sensible with it equivalent to the first approach.


Reason 2 not to go for markdown would be: we want a pure Tcl toolchain and not rely on external tools (so documentation can be built as part of the compile process when building Tcl, only having typical tools such as gcc, make etc. at hand. This is currently impossible, even with doctools and markdown. We would need to move tcllib modules such as doctools and markdown and their dependencies into the core (and enhance them on the way to cover our needs).


Cheers, Torsten

> Am 23.07.2023 um 10:23 schrieb Georg Lehner <jor...@ma...>:
> 
> Hello,
> 
> Thanks for stepping forward. I agree on the need for improved and more documentation.
> 
> My 2 x 2c:
> 
> 1. Documentation source format
> 
> doctools, man(doc) and HTLM are semantic text markup languages which convey meaning for terms and keywords.
> 
> Markdown is a formating language without semantics. If we use markdown as the documentation source language, we'll loose semantics. Let's not do that, but rather have/use good tools for a selected semantic text markup language. My personal preference would be POSH (HTML), with extensions for Tcl/Tk. Plug: see poshdoc.org for an incomplete introduction.
> 
> 2.  Audience and style
> 
> Let me define two audiences for Tcl/Tk documentation: a) beginners, b) programmers.
> 
> The entry point for beginners are overviews, tutorials and detailed examples. These will ultimately lead to reference documents.
> 
> The entry point for programmers are reference documents - "man pages".  These shall be terse, contain a minimal number of terse examples and reference overviews, tutorials and detailed examples.
> 
>  Your proposals address both of these document categories - that's great!
> 
> Best Regards,
> 
>   Georg
>