Menu
▾
▴
Re: [TCLCORE] [External] Re: TCT/TIP reform
|
From: Georg L. <jor...@ma...> - 2023-07-23 08:50:23
|
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... |
