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

[<chr...@gm...>]

On 7/21/23 at 4:09 AM, 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



Hello Torsten, thanks for sharing this.

>From a quick glance, I think your ideas are good, particularly as someone who is rather “new school” and prefers reading online documentation in a web browser, rather than from a locally installed copy in a terminal.

I am aware not everyone is a fan of Markdown, e.g. how it may be underpowered for some purposes, or how in practice there are various Markdown-like flavors rather than a single Markdown. But I think it is often good enough and could elicit greater maintenance participation. I had thought about at least converting remaining READMEs to Markdown.

Regarding more complete tutorials/examples, Tcl probably has greater need for this, since TkDocs.com provides a fairly comprehensive Tk tutorial (in multiple programming languages). I would guess that, historically, the Tcl Wiki is what the community expected to use for tutorials and examples, but it has become somewhat sprawling/disorganized and outdated in places, and the official documentation for various Tcl/Tk features does not guide readers toward relevant wiki pages.

An idea I would like to suggest is to have the documentation say much more about feature history, and act more as a version migration guide. That could make it much more useful to those with code written for older Tcl/Tk versions, and those (e.g. library maintainers) who still need to support multiple Tcl/Tk versions. I think the Python documentation is a good example of what to do: it extensively notes which version added a feature (going back several years), and whether a feature will change or be removed in a future version. The Tcl/Tk documentation, by contrast, seems written with only the current version in mind. Figuring out which version added or changed a feature could require comparing documentation across versions, consulting release notes, or potentially even source code repository history. And there is not always advance warning when a feature will change or be removed in an upcoming version: for example, the 8.6 and 8.7 docs do not warn that tilde substitution will be removed in 9.0 (by TIP 602).

Hope this helps,
Christopher A. Chavez