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

[bch <bra...@gm...>]

On Mon, Jul 24, 2023 at 13:02 Torsten Berg <be...@ty...> wrote:

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


Mandoc/ mdoc:
.Os operating system
.Nm some command
.Op Fl someflag
.Op Fl otherflag Ar arg-here
.An “John Smith” Aq Mt jo...@em...

Are along lines of what I think of as semantic, the others (headers, emph)
are one step better than display isomorphisms, which isn’t *nothing*, but
not a whole lot more.

-bch


>
> 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
>
>
> _______________________________________________
> Tcl-Core mailing list
> Tcl...@li...
> https://lists.sourceforge.net/lists/listinfo/tcl-core
>