Open larseggert opened 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?
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.
This one also fails.
@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?
This one also fails.
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.
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?
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.
Do they write to stdout? If so, show both in case the conversion fails?
Yes, it does. But stdout is noisy. So, I've written regex to collect errors and warnings for the verification API piece.
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?
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.)
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).
Can we at least collect statistics about how often conversion fails because a plugin is missing, and which one?
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.
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.
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.)