Menu
▾
▴
Re: [TCLCORE] [External] Re: TCT/TIP reform
|
From: Torsten B. <tor...@ic...> - 2023-07-24 18:28:57
|
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 > > On 7/21/23 10:55, Torsten Berg wrote: >> Dear all, >> >> as a long time user of Tcl I can only welcome this initiative. >> >> I cannot really help with coding of the core (although I'm slowly learning more and more of it and would like to be able to) but I am a big fan of good documentation. Just the last two years, I have trained two people in my company to code in Tcl ... and we found time and time again is, the manual pages are great if you know how to read them but they often could be improved with some more explanations, examples and code snippets for those who struggle with the terse wording. And, they could be more accessible and good-looking. >> >> I have now seen (on the chat and in Steve's talk at the EuroTcl 2023) that the manual pages are being re-written in markdown. I was thinking of proposing exactly the same and I think this effort this will make editing, maintenance and enhancing the manual pages much simpler. Converting the pages to other formats from markdown is easy as there are so many good converters out there, first and foremost the fabulous Pandoc where the output can be customized heavily using e.g. filters! >> >> I am interested to help there, depending on how this is done right now. I have myself thought about a nicer visual appearance of the manual pages and once made some (local) changes to the Tcl core script (tcltk-man2html.tcl) producing the html manual pages from the nroff original. Unfortunately, these changes to the script somehow got lost but an unfinished sample html page is still here to illustrate the idea (see attached images if they get through). I would like to see a navigation area on the left (as you often find for that kind of documentation) to quickly switch between areas and commands. This area would not only list the categories we already have but also group the commands by topic (strings, lists, files, error handling, ...), the idea being to find the right doc with a minimal amount of clicking (especially guiding beginners). The pages would be more colourful and vivid. >> >> We need many more example code for every command and also should cross link even more to other related commands. In terms of examples, we should have more basic examples. Often, the only example present illustrates some complex case which will not help beginners. I am aware that this is perhaps beyond a pure manual that serves the purpose of just explaining the working of a command. A manual is not a tutorial. My feeling is just that people will be much more likely to use Tcl and be able to write good quality code more easily when they have really great documentation. >> >> The TOC should also go somewhere else so that it stays visible all the time instead of taking up the whole screen space when at the top of the page. Sometimes you have to scroll a few pages until you finally get to the first real sentence of the manual page (especially in the C API categories)! >> >> The current categories are also something to clean up. In "Tcl Commands" you will not only find commands but also variables set by Tcl (but there is not yet a category for this) and even the Dodecalogue is hidden in there under "Tcl". This one should be much more visible and accessible right from the navigation area. >> >> Then, we could have a yaml block in the beginning of each manual document where we store relevant metadata. One thing I often wished was that the version in which a command (or even a command option) first appeared would be stated in the document (it partly is in the nroff files but not in the html version). >> >> So, feel free to contact me if I can help! >> >> Best regards, Torsten >> >> >> >> >> >> >>> Am 12.05.2023 um 10:57 schrieb Reinhard Max <rei...@m4...>: >>> >>> Hi, >>> >>> Am 12.05.2023 08:43, schrieb Poor Yorick: >>> >>>> If it's a commit, then people know exactly what they are voting on. The >>>> idea is that a vote is analogous to a decision to approve the merge >>>> request. If any additional changes are made, and a merge request >>>> supersedes a previous request, then the vote starts fresh on the new >>>> request. The merge would not normally be a cherry pick. >>> ah, but then the term "specific commit" is maybe a bit misleading (at least I think it misled me). We're not talking about the changes of a single commit on a branch, but about the state on a branch at a specific point in time (or after a specific commit), including any earlier commits on that branch, but exluding any later. Right? >>> >>> cu >>> Reinhard >>> >>> >>> _______________________________________________ >>> Tcl-Core mailing list >>> Tcl...@li... >>> https://lists.sourceforge.net/lists/listinfo/tcl-core >> >> >> _______________________________________________ >> Tcl-Core mailing list >> Tcl...@li... >> https://lists.sourceforge.net/lists/listinfo/tcl-core > > -- > MagmaSoft e.U. (FN 601643w) > Inhaber: Ing. Georg Lehner > Kolpingstraße 15, A-4020 Linz > https://magma-soft.at/ > mailto:jo...@ma... > > > > _______________________________________________ > Tcl-Core mailing list > Tcl...@li... > https://lists.sourceforge.net/lists/listinfo/tcl-core |
