Subject: [Tools-discuss] Request to retain kramdown compiler and author stats

From: Stewart Bryant <[email-masked]>
Date: Wed, 10 Mar 2021 10:14:23 +0000

Two tools that I find particularly useful, and hope are retained are:

The experimental version of XML2RFC which supports the kramdown compiler. I have found this useful when collaborating with others that are new to kramdown, and also those that are unable to install the kramdown compiler on their work machine due to company policy on third part software.

The other tool I find useful is the author statistics package which I have used to generate various (personal) activity reports for my management, updating my resume etc.

I hope that both of these tools will be retained in the move.

Best regards

Stewart

---

From: "STARK, BARBARA H" <[email-masked]>
Date: Wed, 10 Mar 2021 14:55:56 +0000

> The experimental version of XML2RFC which supports the kramdown compiler. I
> have found this useful when collaborating with others that are new to
> kramdown, and also those that are unable to install the kramdown compiler on
> their work machine due to company policy on third part software.

Ooh... that would be useful. I didn't know it existed. I've become resigned to needing a personal Linux laptop for doing IETF work. But the more we can get tools like this available online, the more we can make it so people need nothing more than a browser (of their choice) and some really simple instructions to do a basic ID. I think that should be a goal.
Barbara
 
> The other tool I find useful is the author statistics package which I have used to
> generate various (personal) activity reports for my management, updating my
> resume etc.
>

---

From: "Salz, Rich" <[email-masked]>
Date: Wed, 10 Mar 2021 15:00:26 +0000

>    Ooh... that would be useful. I didn't know it existed. I've become resigned to needing a personal Linux laptop for doing IETF work. 

At the risk of starting YAGT*, I'll point out that if the WG is on GitHub and uses Martin Thomson's tools, you can do it all via GitHub actions.

*Yet Another Github Thread

---

From: "STARK, BARBARA H" <[email-masked]>
Date: Wed, 10 Mar 2021 15:07:23 +0000

> >    Ooh... that would be useful. I didn't know it existed. I've become resigned to
> needing a personal Linux laptop for doing IETF work.
> 
> At the risk of starting YAGT*, I'll point out that if the WG is on GitHub and uses
> Martin Thomson's tools, you can do it all via GitHub actions.

I found the instructions for how to set this up to be something I couldn't figure out. They seem to assume a level of knowledge I don't currently possess.
Barbara

---

From: Julian Reschke <[email-masked]>
Date: Wed, 10 Mar 2021 16:16:23 +0100

Am 10.03.2021 um 15:55 schrieb STARK, BARBARA H:
> ...

I'm running kramdown and xml2rfc just fine on Cygwin. And I'm pretty
sure that WSL (Windows Subsytem for Linux) will even do better...

Best regards, Julian

---

From: "Martin Thomson" <[email-masked]>
Date: Thu, 11 Mar 2021 02:44:47 +1100

On Thu, Mar 11, 2021, at 02:07, STARK, BARBARA H wrote:
> I found the instructions for how to set this up to be something I 
> couldn't figure out. They seem to assume a level of knowledge I don't 
> currently possess.

Happy to walk anyone through what it might take to get started here.  I would take that as an opportunity to improve the documentation, which I will concede does assume a degree of familiarity with some of the tools.

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 10 Mar 2021 16:46:35 +0100

> Happy to walk anyone through what it might take to get started here.  I would take that as an opportunity to improve the documentation, which I will concede does assume a degree of familiarity with…

When I apply this to new repos, it just works.

It’s when upgrading older repos that I get weird results…
That would be a useful subject for an UPGRADING.md

Grüße, Carsten

---

From: Brian E Carpenter <[email-masked]>
Date: Thu, 11 Mar 2021 09:08:38 +1300

> The experimental version of XML2RFC which supports the kramdown compiler. I have found this useful when collaborating with others that are new to kramdown, and also those that are unable to install…

Assuming you mean https://xml2rfc.tools.ietf.org/experimental.html, yes, that's an essential tool and if it goes away I'll stop producing drafts. I have no intention of installing all that stuff on my Windows machine, even assuming it's possible.

(Not to mention https://xml2rfc.tools.ietf.org/, but I always use the "experimental" version.)

Note that https://xml2rfc.ietf.org redirects to https://xml2rfc.tools.ietf.org. I assume therefore that the 30% of draft authors who use a "web service" according to Jay's recent survey actually use tools.ietf.org.

However, Robert told us:

"We will be replacing the online xml2rfc and bibxml services with modern
rewrites of the existing services."

So that's fine, as long as the extras available at the "experimental" URL
are retained.

    Brian

---

From: Brian E Carpenter <[email-masked]>
Date: Thu, 11 Mar 2021 09:12:39 +1300

On 11-Mar-21 04:16, Julian Reschke wrote:
...> I'm running kramdown and xml2rfc just fine on Cygwin. And I'm pretty
> sure that WSL (Windows Subsytem for Linux) will even do better...

Why would I want to invest in that learning curve (or the GitHub one)
when the web service is just so much easier to use? Fortunately the plan
includes the web service anyway.

    Brian

---

From: "STARK, BARBARA H" <[email-masked]>
Date: Wed, 10 Mar 2021 22:04:13 +0000

> Happy to walk anyone through what it might take to get started here.  I would
> take that as an opportunity to improve the documentation, which I will concede
> does assume a degree of familiarity with some of the tools.

Given discussion, I'm going to first try with a new repo before taking you up on that.
I want to get a better idea of what my personal problems are. 😊
Barbara

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 11 Mar 2021 07:06:28 +0100

> includes the web service anyway.

That depends on your personal workflow.

Some people like to be able to do a “make” (usually mapped to a single key press) and get a result without further ado within sub-seconds; this enables editing on the source and near-simultaneously seeing one form of the result (usually the HTML form these days).  This requires a local installation and some caching of dependencies.

(Why is that a good thing?  There is a certain fatigue that sets in when one edits a document; seeing the same information in a different form can surmount that fatigue.  This is a rarely recognized reason for why documents that are edited in a non-WYSIWYG environment turn out better than WYSIWYG results, but it requires both forms to be readable — one more reason for the interest in humane markup such as markdown.)

Grüße, Carsten

---

From: Lars Eggert <[email-masked]>
Date: Thu, 11 Mar 2021 10:01:23 +0200

Hi,

> Some people like to be able to do a “make” (usually mapped to a single key press) and get a result without further ado within sub-seconds; this enables editing on the source and near-simultaneously…

if you have Docker installed, you do not need to install anything else if you do things as described here: https://github.com/larseggert/i-d-toolchain

The command is slightly longer than "make", but I guess you could create an alias and/or a shell script if you wanted to.

Thanks,
Lars

---

From: Dhruv Dhody <[email-masked]>
Date: Thu, 11 Mar 2021 16:10:09 +0530

Hi Lars,

In case this is useful for others who try your toolchain (can be added in
readme)

==

I got this error initially when I tried the command!

docker: Error response from daemon: Head
> https://docker.pkg.github.com/v2/larseggert/i-d-toolchain/i-d-toolchain/manifests/latest:
> no basic auth credentials

To fix this one needs to log into docker using GitHub username and personal
access token as a password with read:packages scope.

docker login -u $GITHUB_USERNAME -p $GITHUB_TOKEN docker.pkg.github.com

Create a token here: https://github.com/settings/tokens/new with
read:packages

==

Then I faced this error ->

n `read': No such file or directory @ rb_sysopen -
> /id/draft-i-d-toolchain-test-00.md (Errno::ENOENT)
> from
> /usr/lib/ruby/gems/2.7.0/gems/kramdown-rfc2629-1.3.37/bin/kramdown-rfc2629:320:in
> `<top (required)>'
> from /usr/bin/kramdown-rfc2629:23:in `load'
> from /usr/bin/kramdown-rfc2629:23:in `<main>'
> *** kramdown-rfc failed, status 1

I realized the file is missing! duh!
You do mention the local directory when describing kdrfc, but maybe make it
explicit :)

==

After that, it all worked like a charm! Thank you for making this public!

==

I hope this helps anyone who tries it and faces similar errors!

Thanks!
Dhruv
PS. I am on Ubuntu 18.04.5 LTS.

On Thu, Mar 11, 2021 at 1:31 PM Lars Eggert <[email-masked]> wrote:

> > Some people like to be able to do a “make” (usually mapped to a single
> key press) and get a result without further ado within sub-seconds; this
> enables editing on the source and near-simultaneously seeing one form of
> the result (usually the HTML form these days).  This requires a local
> installation and some caching of dependencies.
>
> if you have Docker installed, you do not need to install anything else if
> you do things as described here:
> https://github.com/larseggert/i-d-toolchain
>
> The command is slightly longer than "make", but I guess you could create
> an alias and/or a shell script if you wanted to.
>
> Thanks,
> Lars
>
> ___________________________________________________________
> Tools-discuss mailing list - [email-masked]
> This list is for discussion, not for action requests or bug reports.
> * Report datatracker and mailarchive bugs to: [email-masked]
> * Report tools.ietf.org bugs to: [email-masked]
> * Report all other bugs or issues to: [email-masked]
> List info (including how to Unsubscribe):
> https://www.ietf.org/mailman/listinfo/tools-discuss
>

---

From: Brian E Carpenter <[email-masked]>
Date: Fri, 12 Mar 2021 09:07:56 +1300

> if you have Docker installed, you do not need to install anything else if you do things as described here: https://github.com/larseggert/i-d-toolchain

Is that going to work if I install docker on Windows 10?
 
> The command is slightly longer than "make", but I guess you could create an alias and/or a shell script if you wanted to.

None of which beats the convenience of a web service, IMHO. Also, since we're talking elsewhere about making the IETF more inviting for newcomers, don't forget that a large fraction of the engineering population expects an installable Windows application. (That's something GitHub got right, in fact: GitHub Desktop rocks.)

Regards
    Brian

---

From: Lars Eggert <[email-masked]>
Date: Thu, 11 Mar 2021 22:10:23 +0200

Hi,

> Is that going to work if I install docker on Windows 10?

I don't know, since I don't have a Windows machine. I can report it works on MacOS and Linux.

> None of which beats the convenience of a web service, IMHO. Also, since we're talking elsewhere about making the IETF more inviting for newcomers, don't forget that a large fraction of the engineer…

Correct, and I'm not suggesting that this is a replacement for a web service. It can be a replacement for installing all the required pieces of the toolchain manually, however.

Thanks,
Lars

---

From: Lars Eggert <[email-masked]>
Date: Thu, 11 Mar 2021 22:15:27 +0200

On 2021-3-11, at 22:07, Brian E Carpenter <[email-masked]> wrote:
> Also, since we're talking elsewhere about making the IETF more inviting for newcomers, don't forget that a large fraction of the engineering population expects an installable Windows application. (That's something GitHub got right, in fact: GitHub Desktop rocks.)

Forgot to add: If someone wanted to, one could install a web server exposing a simple web service that executes the toolchain a part of the docker image. It might even be possible to package this into something clickable. I haven't found a need to do this, but would happily merge a PR.

Thanks,
Lars

---

From: Julian Reschke <[email-masked]>
Date: Fri, 12 Mar 2021 08:22:06 +0100

> Is that going to work if I install docker on Windows 10?

It's supposed to.

> None of which beats the convenience of a web service, IMHO. Also, since we're talking elsewhere about making the IETF more inviting for newcomers, don't forget that a large fraction of the engineer…

"a large fraction of the engineering population expects an installable
Windows application" - seriously?

I happen to use Windows as my work machine, but it seems that among
engineering people I'm a minority.

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 12 Mar 2021 09:12:12 +0100

> Forgot to add: If someone wanted to, one could install a web server exposing a simple web service that executes the toolchain a part of the docker image. It might even be possible to package this i…

Want!

Grüße, Carsten