Tcl/Tk Documentation and Website: Tcl/Tk Documentation and Website

Tcl/Tk Documentation and Website

Let's make Tcl welcoming to beginners! Then help the experts with their documentation issues!

Improve the Tcl/Tk messaging by making the documentation web presence look more contemporary
Improve the content (end goal is to also enhance www.tcl-lang.org)

We should in the end address all four quadrants of documentation (https://documentation.divio.com):

Some page links:

Generate perfect (Pandoc) markdown files from the nroff manual pages of the latest Tcl/Tk releases (8.6 and 9.0)
Make a script md2html.tcl for Tcl core (this will make use of Pandoc)
Make the HTML look and feel similar to what mkdocs themes do (possibly not directly using mkdocs)
Update and enhance the markdown files with e.g. more explanations, examples
Convert the Tcl/Tk manual pages of older Tcl/Tk versions (< 8.6.13) but not change them content-wise, just make them visually more pleasing by using the same procedure as for the current ones – and include a note on them about being outdated and linking to the current version(s))
SEO (Search Engine Optimization) so that e.g. not the Tcl version 8.4 manual pages come up first in Google's search
Write a custom Pandoc reader/writer (or a Tcl script - see point 8) to convert perfectly between markdown and Tcllib doctools (in order make transition easier for Tcllib or vice versa)
See whether we can have the new workflow from markdown to HTML in pure Tcl so we have everything in core and don't need external dependencies such as Pandoc and mkdocs (we could expand the Tcllib markdown module to do it)

The alternative format 'doctools' is currently not considered because it does not support links and tables ('doctools' is widely used for Tcllib) -- see also markdown and doctools
Markdown is widely used, there are lots of editors for it and the syntax is easy and visually pleasing, sothis is an advantage of markdown vs. doctools to get people write good documentation and keeping the hurdle low
Pandoc's markdown is very comprehensive (and extensible via fenced_divs and brackeded_spans) and serves a very good generic format from which other formats can be generated
Another alternative is AsciiDoc but the syntax is not so easy to read as markdown and it does not offer anything not possible with Pandoc's markdown

Perfect markdown can be achieved using this workflow:

modify tcl core man.macros to produce parseable markup strings instead of doing typesetting at this stage
convert the nroff to markdown with Pandoc, using the modified man.macros
use a Lua filter to convert the own parseable markup strings (produced from man.macros) to clean markdown, e.g. into fenced_divs and bracketed_spans

In the first place we should rely on Pandoc for most of the work so we can do this step quickly
Tcl does the administrative part, defining the strucutral part of the HTML and Pandoc cando the actual markdown-HTML conversion
We can also supplement this by building Pandoc filters in Tcl if needed/desired

Get all command names under the NAME section so we can automatically link them from other files when they are referenced in a text
see Navigation structure

Explicitly show in which Tcl version the command (or even command option) was added (could also be encoded in a YAML metadata block)
Also look at the hacks in the tcl core scripts tools/tcltk-man2html.tcl and tools/tcltk-man2html-utils.tcl to unify the manual pages and get rid of inconsistencies
We could add a link on each page to the respective Tcl Wiki page for that command (if it exists) since those pages often have more examples ... or we can transfer some educational examples to the manual page
Link to relevant TIPs? They use markdown as well

As there is still a debate over "the best markdown" and semantic markup and since Tcllib is not using nroff or markdown but doctools, we should make conversion between markdown and doctools as easy as possible and ideally without information loss. Then, we can always decide on the final markup language afterwards

We want to eat our own dog food ... when Tcl can do the whole workflow, why not use Tcl for it. It can serve as a nice "best pratice" example