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

[Steve L. <st...@di...>]

Hi Torsten,

I would be very happy for you to be involved with cleaning up the documentation, especially if you can work with Shaun on the markdown source, focussing on enhancing the content.  I’ll contact you off-list to work out the practicalities.

-- Steve
On 21 Jul 2023 at 5:11 PM +0800, Torsten Berg <be...@ty...>, 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
> <PastedGraphic-1.png><PastedGraphic-2.png>