Menu
▾
▴
tcllib-devel
|
From: Andreas K. <aku...@sh...> - 2019-04-10 04:02:05
|
Hello to all 45 of you with an account at the Tcllib repository which has an email address in the contact field. I assume that you are at least a user of Tcllib, and possibly even a contributor or maintainer for one or more of its packages. I am broadcasting this message to all of you because I do not know who of you is also subscribed to the [Tcllib-devel](https://lists.sourceforge.net/lists/listinfo/tcllib-devel) [mailing list](mail:tcl...@li...). The list is cc'd however, to keep things open. With the administrative stuff done, let us come to the meat. If you are tracking Tcllib's [timeline](https://core.tcl.tk/tcllib/timeline) you might have seen that I am currently working in a branch [1] on a full set of guides for the various roles (user, installer/builder, developer/maintainer, release manager) associated with Tcllib. While there are still substantial holes in the guide for a release manager I believe that the other guides are now pretty complete, i.e. ready for a larger review of their contents. I am looking for feedback on things as simple as spelling and phrasing, up to higher-level discussion about maintainer commitments and the purpose of branches, how to work with them, etc. If you are (planning to be) a maintainer for one or more packages the [Maintainer commitments](https://core.tcl.tk/tcllib/doc/doc-overhaul/embedded/m d/tcllib/files/devdoc/tcllib_devguide.md#subsection2) are especially important and should be reviewed. While I tried to be sensible it is entirely possible that I did not succeed. The 'kind communication' part is essentially a belaboring of `be kind to each other when discussing things`. Very easy to forget, as such I believe the reminder is necessary. The plan is to integrate the feedback and then later merge the branch back to the trunk, at which point the guides would become official. All the new documentation is reachable via the new [Index Page](https://core.tcl.tk/tcllib/doc/doc-overhaul/embedded/index.md), in the section "Guides To Tcllib" at the top. __Note__ that the link points to a document on the branch, this is not yet the main index serving as Tcllib's homepage. To keep a modicum of forward momentum I am limiting the feedback period to a bit under three weeks, starting from now to Sunday April 28, 2019, 12:00 GMT. This is `clock format 1556452800`. ~ ~ ~~ ~~~ ~~~~~ ~~~~~~~~ ~~~~~~~~~~~~~ [1]: https://core.tcl.tk/tcllib/timeline?r=doc-overhaul "doc-overhaul" -- See you, Andreas Kupries <aku...@sh...> <http://core.tcl.tk/akupries/> Developer @ SUSE Software Canada ULC <and...@su...> EuroTcl 2019, Jun 29-30, Nuernberg/DE, http://eurotcl.eu/ Tcl'2019, Nov 4-8, Houston, TX, USA. http://www.tcl.tk/community/tcl2019/ ------------------------------------------------------------------------------- |
|
From: Andy G. <and...@gm...> - 2019-04-10 17:44:11
|
On 4/9/19 10:46 PM, Andreas Kupries wrote: > If you are tracking Tcllib's > [timeline](https://core.tcl.tk/tcllib/timeline) you might have seen > that I am currently working in a branch [1] on a full set of guides > for the various roles (user, installer/builder, developer/maintainer, > release manager) associated with Tcllib. Cute, putting this email in markdown format. > I am looking for feedback on things as simple as spelling and > phrasing, up to higher-level discussion about maintainer commitments > and the purpose of branches, how to work with them, etc. The big issue I see is extraneous backslashes in verbatim code blocks, those being lines of text that begin with at least four spaces. Plenty of examples here: https://core.tcl.tk/tcllib/doc/trunk/embedded/md/tcllib/files/modules/doctools/doctools_lang_syntax.md Here is the source for the above: https://core.tcl.tk/tcllib/artifact?fn=embedded/md/tcllib/files/modules/doctools/docidx_lang_intro.md&ci=trunk&txt=1 I'm not sure where to go to see any examples of this, but I am curious of extraneous backslashes are also present within `...` code spans. Here is the markdown rules reference: https://core.tcl.tk/tcllib/md_rules -- Andy Goth | <andrew.m.goth/at/gmail/dot/com> |
|
From: Andreas K. <and...@su...> - 2019-04-10 19:06:53
|
On Wed, 10 Apr 2019 12:44:03 -0500 Andy Goth <and...@gm...> wrote: > On 4/9/19 10:46 PM, Andreas Kupries wrote: > > If you are tracking Tcllib's > > [timeline](https://core.tcl.tk/tcllib/timeline) you might have seen > > that I am currently working in a branch [1] on a full set of guides > > for the various roles (user, installer/builder, > > developer/maintainer, release manager) associated with Tcllib. > > Cute, putting this email in markdown format. Made it easier to write the links. > The big issue I see is extraneous backslashes in verbatim code blocks, > those being lines of text that begin with at least four spaces. Yes. Arjen noted the same. I confirmed that pandoc does not like it either. I am currently working on that. Clearly I am overquoting the special characters. They are not special in the verbatim block and thus should not be quoted when I emit MD. > I'm not sure where to go to see any examples of this, but I am curious > of extraneous backslashes are also present within `...` code spans. Will check. Likely yes. And confirmed that pandoc treats specials in `...` like in verbatim, and when quoted the quotes are passed through also. This is currently no trouble because the doctools md generator does not emit `...` sequences for anything. It is something to watch for however should that happen in the future. > Here is the markdown rules reference: > > https://core.tcl.tk/tcllib/md_rules Thanks -- Andreas Kupries SUSE Software Canada ULC EuroTcl 2019, Jun 29-30, Nuernberg/DE, http://eurotcl.eu/ Tcl'2019, Nov 4-8, Houston, TX, USA. http://www.tcl.tk/community/tcl2019/ |
|
From: Andreas K. <and...@su...> - 2019-04-10 22:58:24
|
On Wed, 10 Apr 2019 11:46:22 -0700 Andreas Kupries <and...@su...> wrote: > On Wed, 10 Apr 2019 12:44:03 -0500 > Andy Goth <and...@gm...> wrote: > > > On 4/9/19 10:46 PM, Andreas Kupries wrote: > > > If you are tracking Tcllib's > > > [timeline](https://core.tcl.tk/tcllib/timeline) you might have > > > seen that I am currently working in a branch [1] on a full set of > > > guides for the various roles (user, installer/builder, > > > developer/maintainer, release manager) associated with Tcllib. > > The big issue I see is extraneous backslashes in verbatim code > > blocks, those being lines of text that begin with at least four > > spaces. > > Yes. Arjen noted the same. I confirmed that pandoc does not like it > either. I am currently working on that. Clearly I am overquoting > the special characters. They are not special in the verbatim block and > thus should not be quoted when I emit MD. Fix is in, the examples should look much nicer now. -- Andreas Kupries SUSE Software Canada ULC EuroTcl 2019, Jun 29-30, Nuernberg/DE, http://eurotcl.eu/ Tcl'2019, Nov 4-8, Houston, TX, USA. http://www.tcl.tk/community/tcl2019/ |
|
From: Andy G. <and...@gm...> - 2019-04-10 23:00:50
|
On 4/10/19 5:58 PM, Andreas Kupries wrote: > Fix is in, the examples should look much nicer now. Not quite. Backslash at end of line still renders as two backslashes. Look at the Fundamentals section here: http://core.tcl.tk/tcllib/doc/trunk/embedded/md/tcllib/files/modules/doctools/doctoc_lang_intro.md http://core.tcl.tk/tcllib/file?name=embedded/md/tcllib/files/modules/doctools/doctoc_lang_intro.md&txt=1 -- Andy Goth | <andrew.m.goth/at/gmail/dot/com> |
|
From: Andy G. <and...@gm...> - 2019-04-10 23:03:16
|
On 4/10/19 6:00 PM, Andy Goth wrote: > On 4/10/19 5:58 PM, Andreas Kupries wrote: >> Fix is in, the examples should look much nicer now. > > Not quite. Backslash at end of line still renders as two backslashes. > Look at the Fundamentals section here: > > http://core.tcl.tk/tcllib/doc/trunk/embedded/md/tcllib/files/modules/doctools/doctoc_lang_intro.md > > http://core.tcl.tk/tcllib/file?name=embedded/md/tcllib/files/modules/doctools/doctoc_lang_intro.md&txt=1 Also, I'm curious why period is quoted with backslash: \. -- Andy Goth | <andrew.m.goth/at/gmail/dot/com> |
|
From: Andreas K. <and...@su...> - 2019-04-10 23:21:15
|
On Wed, 10 Apr 2019 18:03:10 -0500 Andy Goth <and...@gm...> wrote: > On 4/10/19 6:00 PM, Andy Goth wrote: > > On 4/10/19 5:58 PM, Andreas Kupries wrote: > >> Fix is in, the examples should look much nicer now. > > > > Not quite. Backslash at end of line still renders as two > > backslashes. Look at the Fundamentals section here: > > > > http://core.tcl.tk/tcllib/doc/trunk/embedded/md/tcllib/files/modules/doctools/doctoc_lang_intro.md > > > > http://core.tcl.tk/tcllib/file?name=embedded/md/tcllib/files/modules/doctools/doctoc_lang_intro.md&txt=1 That double-backslash comes from the input file https://core.tcl.tk/tcllib/file?name=modules/doctools/doctoc_lang_intro.man&txt=1 A single backslash in the doctools input converts to space in what the generator sees, due to Tcl subst rules. Guess I need a bit more special handling for that, i.e. look for double-\ followed by \n > Also, I'm curious why period is quoted with backslash: \. Technically '.' is a special character in markdown, due to its use for ordered lists lead-in. I based this on http://tech.saigonist.com/b/code/escaping-special-characters-markdown.html Note also https://spec.commonmark.org/0.28/#backslash-escapes which I had not seen before. That is for inlines only, so not for verbatim blocks. -- Andreas Kupries SUSE Software Canada ULC EuroTcl 2019, Jun 29-30, Nuernberg/DE, http://eurotcl.eu/ Tcl'2019, Nov 4-8, Houston, TX, USA. http://www.tcl.tk/community/tcl2019/ |
|
From: Andy G. <and...@gm...> - 2019-04-11 00:02:31
|
On 4/10/19 6:20 PM, Andreas Kupries wrote: > On Wed, 10 Apr 2019 18:03:10 -0500 Andy Goth <and...@gm...> wrote: >> Also, I'm curious why period is quoted with backslash: \. > > Technically '.' is a special character in markdown, due to its use for > ordered lists lead-in. That makes sense. Thank you. I'm comparing the source with the generated markdown: http://core.tcl.tk/tcllib/artifact?fn=modules/doctools/docidx_lang_intro.man&ci=c74461e613 http://core.tcl.tk/tcllib/artifact?fn=embedded/md/tcllib/files/modules/doctools/doctools_lang_intro.md&ci=c74461e613&txt=1 http://core.tcl.tk/tcllib/doc/c74461e613/embedded/md/tcllib/files/modules/doctools/doctools_lang_intro.md But they seem to be quite different. What am I missing? The *.man source says: [subsection Fundamentals] While the [term {docidx markup language}] is quite similar to the [term {doctools markup language}], in the broadest terms possible, there is one key difference. An index consists essentially only of markup commands, with no plain text interspersed between them, except for whitespace. The markdown says: ## <a name='subsection1'></a>Fundamentals In the broadest terms possible the *doctools markup language* is LaTeX\-like, instead of like SGML and similar languages\. A document written in this language consists primarily of text, with markup commands embedded into it\. Also, what is idoc? http://core.tcl.tk/tcllib/artifact?fn=idoc/www/tcllib/files/modules/doctools/docidx_lang_intro.html&ci=c74461e613 At least for the section I quoted above, the idoc file matches the *.man source. -- Andy Goth | <andrew.m.goth/at/gmail/dot/com> |
|
From: Andy G. <and...@gm...> - 2019-04-17 06:13:23
|
I found another formatting issue in the new markdown related to complex nested lists. https://core.tcl.tk/tcllib/doc/trunk/embedded/md/tcllib/files/modules/doctools/doctools_lang_cmdref.md#26 Scroll down to the following two paragraphs sandwiched between bulleted lists. "Additionally the following names are recognized as shortcuts for some of the regular types:" "At last the following names are still recognized for backward compatibility, but are otherwise considered to be deprecated." The first list item (args and arg, respectively) of each list is not displayed correctly. https://core.tcl.tk/tcllib/file?name=embedded/md/tcllib/files/modules/doctools/doctools_lang_cmdref.md&txt=1 Reviewing the generated markdown, I don't see any syntax errors. This may be a fault in Fossil itself. I'd cross-post to Fossil, but Fossil no longer has a mailing list. Instead, it uses a forum: https://fossil-scm.org/forum/forum -- Andy Goth | <andrew.m.goth/at/gmail/dot/com> |
|
From: Andreas K. <and...@su...> - 2019-04-17 16:20:21
|
On Wed, 17 Apr 2019 01:13:11 -0500 Andy Goth <and...@gm...> wrote: > I found another formatting issue in the new markdown related to > complex nested lists. > https://core.tcl.tk/tcllib/doc/trunk/embedded/md/tcllib/files/modules/doctools/doctools_lang_cmdref.md#26 > > Scroll down to the following two paragraphs sandwiched between > bulleted lists. > > "Additionally the following names are recognized as shortcuts for some > of the regular types:" > > "At last the following names are still recognized for backward > compatibility, but are otherwise considered to be deprecated." > > The first list item (args and arg, respectively) of each list is not > displayed correctly. > > https://core.tcl.tk/tcllib/file?name=embedded/md/tcllib/files/modules/doctools/doctools_lang_cmdref.md&txt=1 > > Reviewing the generated markdown, I don't see any syntax errors. This > may be a fault in Fossil itself. I'd cross-post to Fossil, but Fossil > no longer has a mailing list. Instead, it uses a forum: > > https://fossil-scm.org/forum/forum I confirm your findings, i.e. the .md file looks to have no syntax errors, and the rendering of it is bad. Especially weird that the first of the nested lists is not affected at all. Only idea I have at the moment is invisible superfluous spaces causing this ... Checked, no spaces around, thus out of ideas. Ok. I will make a copy of this file later today and then try to reduce it to something minimal still exhibiting the issue. When I have that I will ping Richard. Thanks for the report. Seems that the docs of the entire Tcllib are a nice stress-tests for both my generator, and fossil's renderer. And other renderers If you look into examples rendered as block quotes (to allow for markup inside the example) you will note that I use ` ` for leading spaces to preserve indentation (somewhat, tab becomes space). I am not replacing any of the internal spaces at all. Because if I do that the pandoc parser seems to break down and misrender. Fossil maybe as well. -- Andreas Kupries SUSE Software Canada ULC EuroTcl 2019, Jun 29-30, Nuernberg/DE, http://eurotcl.eu/ Tcl'2019, Nov 4-8, Houston, TX, USA. http://www.tcl.tk/community/tcl2019/ |
|
From: Arjen M. <Arj...@de...> - 2019-04-17 06:41:18
|
Hi Andreas, I have several small remarks on the Tcl Library Source Code page: - Typo: ramafications should be ramification - In the section Trunk: "and this exactly" should be "and this is exactly" - In the section "Generate documentation for al modules" you may add that the tool updates the documentation, not simply generates everything - In the section Notes on Writing A Testsuite: "throws an understandable error. Instead of" should be "throws an understandable error, instead of" As for testsuites, I was impressed by this article, https://www.researchgate.net/publication/298896236, that, admittedly, is geared to a particular numerical algorithm but shows that even simple-looking algorithms can lead to an incredible number of test cases. Regards, Arjen DISCLAIMER: This message is intended exclusively for the addressee(s) and may contain confidential and privileged information. If you are not the intended recipient please notify the sender immediately and destroy this message. Unauthorized use, disclosure or copying of this message is strictly prohibited. The foundation 'Stichting Deltares', which has its seat at Delft, The Netherlands, Commercial Registration Number 41146461, is not liable in any way whatsoever for consequences and/or damages resulting from the improper, incomplete and untimely dispatch, receipt and/or content of this e-mail. |
|
From: Andreas K. <and...@su...> - 2019-04-17 16:36:48
|
On Wed, 17 Apr 2019 06:41:08 +0000 Arjen Markus <Arj...@de...> wrote: > Hi Andreas, > > I have several small remarks on the Tcl Library Source Code page: > - Typo: ramafications should be ramification Fixed > - In the section Trunk: "and this exactly" should be "and this is > exactly" Fixed > - In the section "Generate documentation for al modules" you may add > that the tool updates the documentation, not simply generates > everything I suspect that you are confusing the `doc` method here with `localdoc`. The latter is used to update the embedded and installation documentation. As such it generates all the docs multiple times (html, nroff, md), and updates the directories `embedded` and `idoc`. While the `doc` command as specified generates the all docs, it only generates the specified format, and places it into a `doc` directory which has nothing to do with the embedded nor installations docs/directories. > - In the section Notes on Writing A Testsuite: "throws an > understandable error. Instead of" should be "throws an understandable > error, instead of" Fixed > > As for testsuites, I was impressed by this article, > https://www.researchgate.net/publication/298896236, that, admittedly, > is geared to a particular numerical algorithm but shows that even > simple-looking algorithms can lead to an incredible number of test > cases. Added the reference Committed and pushed fixes. -- Andreas Kupries SUSE Software Canada ULC EuroTcl 2019, Jun 29-30, Nuernberg/DE, http://eurotcl.eu/ Tcl'2019, Nov 4-8, Houston, TX, USA. http://www.tcl.tk/community/tcl2019/ |
|
From: Arjen M. <Arj...@de...> - 2019-04-18 07:33:47
|
HI Andreas, -----Original Message----- From: Andreas Kupries <and...@su...> Sent: 17 April 2019 18:36 To: Arjen Markus <Arj...@de...> Cc: tcl...@li... Subject: Re: [Tcllib-devel] Tcllib - Dev- and other Guides - Looking For Feedback On Wed, 17 Apr 2019 06:41:08 +0000 Arjen Markus <Arj...@de...> wrote: > - In the section "Generate documentation for al modules" you may add > that the tool updates the documentation, not simply generates > everything I suspect that you are confusing the `doc` method here with `localdoc`. The latter is used to update the embedded and installation documentation. As such it generates all the docs multiple times (html, nroff, md), and updates the directories `embedded` and `idoc`. While the `doc` command as specified generates the all docs, it only generates the specified format, and places it into a `doc` directory which has nothing to do with the embedded nor installations docs/directories. >>AM: Ah, thanks for that clarification. Now I will go and read/comment on other pages. Regards, Arjen DISCLAIMER: This message is intended exclusively for the addressee(s) and may contain confidential and privileged information. If you are not the intended recipient please notify the sender immediately and destroy this message. Unauthorized use, disclosure or copying of this message is strictly prohibited. The foundation 'Stichting Deltares', which has its seat at Delft, The Netherlands, Commercial Registration Number 41146461, is not liable in any way whatsoever for consequences and/or damages resulting from the improper, incomplete and untimely dispatch, receipt and/or content of this e-mail. |
×
Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.
Thanks for helping keep SourceForge clean.
X