From Newsgroup: comp.lang.tcl

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
--- Synchronet 3.20c-Linux NewsLink 1.2

From Newsgroup: comp.lang.tcl

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).
At Mon, 20 Jan 2025 16:03:58 +0100 Harald Oehlmann <wortkarg3@yahoo.com> wrote:

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 -- Cell: 413-658-7953 GV: 978-633-5364
Deepwoods Software -- Custom Software Services
http://www.deepsoft.com/ -- Linux Administration Services
heller@deepsoft.com -- Webhosting Services
--- Synchronet 3.20c-Linux NewsLink 1.2

From Newsgroup: comp.lang.tcl

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

Am 20.01.2025 um 16:17 schrieb 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).

At Mon, 20 Jan 2025 16:03:58 +0100 Harald Oehlmann <wortkarg3@yahoo.com> wrote:

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

--- Synchronet 3.20c-Linux NewsLink 1.2

From Newsgroup: comp.lang.tcl


Harald Oehlmann writes:

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

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

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

--- Synchronet 3.20c-Linux NewsLink 1.2

From Newsgroup: comp.lang.tcl

Great, Rolf, I appreciate.
That is exactly what I was looking for.

Take care,
Harald

Am 22.01.2025 um 16:19 schrieb Rolf Ade:

Harald Oehlmann writes:

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

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

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

--- Synchronet 3.20c-Linux NewsLink 1.2

From Newsgroup: comp.lang.tcl

Hi Rolf,
I also tried it.

All the special syntax like [string]{.optarg} does not render for me.
But anyway, it is done.

For me, it looks better without style sheet, as the style sheet changes
some fonts, and some not.

I have added horizontal lines to avoid the strange spacing.

Anyway, early beginner...

Here is the result.

https://github.com/oehhar/zxing-cpp-wrapper-tcl/tree/master/wrappers/tcl/doc

To get the stylesheet version, just put "main.css" beside it ;-).

Thanks for all,
Harald

Am 22.01.2025 um 16:19 schrieb Rolf Ade:

Harald Oehlmann writes:

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

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

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

--- Synchronet 3.20c-Linux NewsLink 1.2

From Newsgroup: comp.lang.tcl

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
--- Synchronet 3.20c-Linux NewsLink 1.2

From Newsgroup: comp.lang.tcl

Am 24.01.2025 um 09:24 schrieb 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

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
--- Synchronet 3.20c-Linux NewsLink 1.2