search

ietf-tools / author-tools

Author Tools
https://author-tools.ietf.org
BSD 3-Clause "New" or "Revised" License
35 stars 30 forks source link

Missing tools #1

Open larseggert opened 2 years ago

larseggert commented 2 years ago

I think not all the tools that kramdown-rfc2629 supports are installed. You can use https://github.com/larseggert/i-d-toolchain/blob/main/draft-i-d-toolchain-test-00.md to see what you need to install, that document executes all the currently supported converters.

(You can also look at https://github.com/larseggert/i-d-toolchain/blob/main/Dockerfile for how to install them.)

kesara commented 2 years ago

Here's list of tools that I compiled from kramdown-rfc2629 experimental features:

Tool Language Notes Other dependencies Added to AT
GoAT Go ASCII (plaintext) art to figure conversion. No updates since 2016. svgcheck ✅
ditta Java ASCII (plaintext) art to figure conversion JDK
mscgen C Message sequence charts generator. No updates since 2011.
plantuml Java Multi-purpose diagram generator graphviz
mermaid JavaScript SVG converter NodeJS, chromium, puppeteer, Additional JavaScript dependencies
athjax-node-cli JavaScript Provides tex2svg. NodeJS, Additional JavaScript dependencies
asciiTeX fork C ASCII equation renderer. The original project is abandoned.
aasvg JavaScript Convert ASCII art diagrams into SVG. NodeJS ✅

Including all these tools, increases the maintenance overhead and security risks because some tools are not supported anymore. Is there are any guide on which of these tools used widely by the community?

kesara commented 2 years ago

Feature branch: https://github.com/ietf-tools/ietf-at/tree/feature/kramdown-experimental-features

larseggert commented 2 years ago

Are these tools now installed on the service? Because https://github.com/larseggert/i-d-toolchain/blob/main/draft-i-d-toolchain-test-00.md still cannot be rendered.

larseggert commented 2 years ago

This one also fails.

draft-example-mmark.md

kesara commented 2 years ago

@larseggert, At the moment "Author Tools" only supports GoAT. About page has a list of tools.

Including all of these tools, increases the maintenance overhead and security risks because some tools are not supported anymore. It would be nice if we can cut down the list of tools. Is there are any guide on which of these tools used widely by the community?

kesara commented 2 years ago

This one also fails.

draft-example-mmark.md

Looks like this fails because this doesn't have a [seriesInfo] section, so mmark generates an empty seriesInfo entity.

With the verification API work, author tools will provide more meaningful error messages.

larseggert commented 2 years ago

About tools: if kramdown-rfc2629 or mmark allow source files that rely on third-party tools, IMO we should support them. Otherwise we end up offering a partial service.

About error messages: can we not at least show the stderr output in the browser when conversion fails?

kesara commented 2 years ago

About error messages: can we not at least show the stderr output in the browser when conversion fails?

Author tools currently do that. But the keyword being "stderr", not all tools (specially xml2rfc) wrote errors into stderr. :( Plan is to address this shortcoming with verification API work.

larseggert commented 2 years ago

Do they write to stdout? If so, show both in case the conversion fails?

kesara commented 2 years ago

Yes, it does. But stdout is noisy. So, I've written regex to collect errors and warnings for the verification API piece.

rjsparks commented 2 years ago

About tools: if kramdown-rfc2629 or mmark allow source files that rely on third-party tools, IMO we should support them. Otherwise we end up offering a partial service.

I think we need to limit what plugins we are going to add. Each addition adds a support load for us, and something may become unmaintained (or unsecure) in ways that we wouldn't keep providing the service, but someone running those applications in a standalone manner might put up with

Kramdown itself (if you install it) simply looks for the existence of the binaries for the extensions and issues an error if the tool isn't there, and we should pass that along in general.

Is there really community use of all the tools Kesara lists at the top that justifies taking on the maintenance load for the install of those things at this service?

rjsparks commented 2 years ago

Lets focus on mermaid briefly - it has a lot in it that I would use, so I urge supporting it, but when some other markup package comes along that does diagramming in a slightly better way, do we add it to and take mermaid away? Or are we going to end up maintain the use of an open-ended set of things. And in particular, are we delegating the decision to add that load to multiple individuals (Carsten, Miek, etc.)

rjsparks commented 2 years ago

Note also what Carsten says at https://github.com/cabo/kramdown-rfc2629/wiki/SVG#mermaid. Instead, I think our service starts minimal, and we add when there's sufficient community pressure to add something. If someone wants the latest bells from one of the underlying things, they can build their own install.

The question is, what should that minimal set be. I disagree that its "everything the included tools support". Given Carsten's note above, I'm actually on the fence about mermaid (though I do find it very appealing).

larseggert commented 2 years ago

Can we at least collect statistics about how often conversion fails because a plugin is missing, and which one?

kesara commented 2 years ago

Can we at least collect statistics about how often conversion fails because a plugin is missing, and which one?

Good idea. I will implement that.

miekg commented 2 years ago

Do they write to stdout? If so, show both in case the conversion fails?

Note: there are no incorrect markdown documents, so for mmark I opted to only output some logging (to stderr) when it spots errors.