Sample markup documentation file for a Tcl/Tk package

[Harald Oehlmann]

Dear Tcl/Tk group,
I would love to author the documentation of my latest package in markup
(following TIP700 ;-) ).

Here is the package
https://github.com/oehhar/zxing-cpp-wrapper-tcl

Is there any example how to author the documentation in markup ?

Thanks for any idea,
Harald

[Robert Heller]

What *I* do is use Doxygen to generate HTML from documentation in the source
code. I have a *simple* HTML widget (a widget originally by Stephen Uhler,
modified by Clif Flynt and by me and converted to a SNIT widget).

Post by Harald Oehlmann
Dear Tcl/Tk group,
I would love to author the documentation of my latest package in markup
(following TIP700 ;-) ).
Here is the package
https://github.com/oehhar/zxing-cpp-wrapper-tcl
Is there any example how to author the documentation in markup ?
Thanks for any idea,
Harald

[Harald Oehlmann]

Thanks Robert,
that is a great answer. I use Doxygen for C and tcl (old version
supported it).

But I want to be ahead of time. In future, Tcl documentation will be in
markdown (and not nroff). I suppose, this will be valids for packages
too. So, I already want to typeset the documentation using the TCL
markdown format.

Thanks,
Harald

Post by Robert Heller
What *I* do is use Doxygen to generate HTML from documentation in the source
code. I have a *simple* HTML widget (a widget originally by Stephen Uhler,
modified by Clif Flynt and by me and converted to a SNIT widget).

Post by Harald Oehlmann
Dear Tcl/Tk group,
I would love to author the documentation of my latest package in markup
(following TIP700 ;-) ).
Here is the package
https://github.com/oehhar/zxing-cpp-wrapper-tcl
Is there any example how to author the documentation in markup ?
Thanks for any idea,
Harald

[Rolf Ade]

Post by Harald Oehlmann
Dear Tcl/Tk group,
I would love to author the documentation of my latest package in
markup (following TIP700 ;-) ).

To get a feeling what TIP 700 [1] mean in praxis some weeks ago I
started to transfer the ooxml documentation into the markdown variant
proposed by the TIP (note to myself: I should pick this up again and
finish it).

What I have done so far is [2].

As you I looked for examples and found [3], which has versions of
automatically from troff to md converted man pages of all Tcl (and Tk)
commands and C API functions.

Having the documentation as md source is only the start. To get the
man and HTML documentation from your new documentation sources you may
peek how I did [4] (which is far away from being canonical, just a fast
scribbled way for my simple case).

For the HTML you need some css. To have one I just picked up [5]
although I think someone™ should give some love to that.

rolf

[1] https://core.tcl-lang.org/tips/doc/trunk/tip/700.md

[2] https://fossil.sowaswie.de/ooxml/file?name=doc/ooxml.md&ci=tip&txt=1

[3] https://github.com/ShaunKulesa/Docs-Maker/tree/main/docs

[4] https://fossil.sowaswie.de/ooxml/file?udc=1&ln=65-72&ci=tip&name=Makefile.in

[5] https://github.com/ShaunKulesa/Docs-Maker/tree/main/css

Post by Harald Oehlmann
Here is the package
https://github.com/oehhar/zxing-cpp-wrapper-tcl
Is there any example how to author the documentation in markup ?

[TorstenBerg]

Hi,

what did you use to produce the HTML with? For TIP 700, I propose Pandoc
for now as we do not yet have our own Tcl library that is capable of all
the markdown constructs we would like to have.

Especially the `[string]{.optarg}` construct you mention is not possible
to render with e.g. the tcllib markdown module as it is a Pandoc
markdown syntax element.

If you need to render it with Pandoc, you have to specify the
corresponding CSS element (Pandoc translates `.optarg` into a CSS class)
which could look like this (untested):

optarg {
font-style: italic;

&:before {
content: '?';
}

&:after {
content: '?';
}
}


Regards, Torsten

[Harald Oehlmann]

Post by TorstenBerg
Hi,
what did you use to produce the HTML with? For TIP 700, I propose Pandoc
for now as we do not yet have our own Tcl library that is capable of all
the markdown constructs we would like to have.
Especially the `[string]{.optarg}` construct you mention is not possible
to render with e.g. the tcllib markdown module as it is a Pandoc
markdown syntax element.
If you need to render it with Pandoc, you have to specify the
corresponding CSS element (Pandoc translates `.optarg` into a CSS class)
optarg {
 font-style: italic;
 &:before {
   content: '?';
 }
 &:after {
   content: '?';
 }
}
Regards, Torsten

Hi Torsten,
thanks for your contribution.
That is all ok and great.

I was following the steps described by Rolf:

- download pandoc.exe
- take main.css from
https://github.com/ShaunKulesa/Docs-Maker/tree/main/docs
- invoke Pandoc as described by Rolf:
pandoc\pandoc.exe --standalone -f markdown -t html zxingcpp.md --css
main.css -o zxingcpp.html
- follow TIP700 syntax ({.optorg} etc.)

It is not a problem, that it does not work now.
When the documentation system is ready, I will enhance this.

Thanks for all the work and thanks for the {.optorg} explanation.

Take care,
Harald