Subject: [Rfc-markdown] New xml2rfc release: v2.45.0

From: Henrik Levkowetz <[email-masked]>
Date: Wed, 27 May 2020 04:28:54 -0700

Hi,

This is an automatic notification about a new xml2rfc release, 
v2.45.0, generated when running the mkrelease script.

Release notes:

xml2rfc (2.45.0) ietf; urgency=medium

  * Fixed the html rendering of <cref> with display=false.
    Fixes issue #516.

  * Fixed the text rendering of <cref> with display=false.
    Fixes issue #515.

  * Fixed an error in postal address rendering for Sweden.
    Fixes issue #520.

  * Changed the internals of the text formatter to retain <br> information 
    for longer internally, in order to make <br> have effect in for instance 
    <dd> and <td> element text.  Fixes issues #508 and #513.

  * Fixed erroneous indentation of first line of second and following 
    paragraphs of multi-paragraph <dd> elements, and changed code to retain 
    <br> in filled text.

  * Added a font-family setting for @page in PDF mode, and added code to 
    warn about missing Roboto Mono fonts if the python-fontconfig package
    is available

  * Added instructions for RobotoMono to the installation help for the 
    --pdf switch.

 -- Henrik Levkowetz <[email-masked]>  27 May 2020 04:07:48 -0700

The preferred way to install xml2rfc is by doing 'pip install xml2rfc',
and 'pip install --upgrade xml2rfc' to upgrade.  If there are system-
installed python modules which pip will not upgrade, you may have to
use 'pip install --upgrade --no-deps xml2rfc' and install dependencies
manually.

The new version is also available through SVN checkout, with
  'svn checkout http://svn.tools.ietf.org/svn/tools/xml2rfc/tags/cli/2.45.0'

Regards,

	Henrik
	(via the mkrelease script)

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 29 May 2020 21:56:41 +0200

Hi Henrik,

I no longer get SVG through this version that has been “repaired” by svgcheck -qra; the SVG processing now seems very picky.  (I haven’t updated since 2.39, so this might have happened earlier.)

(I do get figures through this version that have the attribute foo=“bar”, so it can’t just be more picky XML processing.)

Before I generate a more detailed test case: Is svgcheck still intended to be the tool to be used with xml2rfc to make SVG palatable to it?  Is that being updated along with xml2rfc getting more picky?

Grüße, Carsten

y2020-05-29svg.xml(606): Error: Invalid attribute shape-rendering for element svg, at /rfc/middle/section[2]/section[2]/artset[1]/artwork[1]/*
y2020-05-29svg.xml(645): Error: Invalid attribute stroke for element text, at /rfc/middle/section[2]/section[2]/artset[2]/artwork[1]/*/*[2]/*[7]
y2020-05-29svg.xml(646): Error: Invalid attribute stroke for element text, at /rfc/middle/section[2]/section[2]/artset[2]/artwork[1]/*/*[2]/*[8]
y2020-05-29svg.xml(647): Error: Invalid attribute stroke for element text, at /rfc/middle/section[2]/section[2]/artset[2]/artwork[1]/*/*[2]/*[9]
y2020-05-29svg.xml(648): Error: Invalid attribute stroke for element text, at /rfc/middle/section[2]/section[2]/artset[2]/artwork[1]/*/*[2]/*[10]
y2020-05-29svg.xml(635): Error: Invalid attribute shape-rendering for element svg, at /rfc/middle/section[2]/section[2]/artset[2]/artwork[1]/*
y2020-05-29svg.xml(666): Error: Invalid attribute stroke for element path, at /rfc/middle/section[2]/section[2]/artset[3]/artwork[1]/*/*[2]/*[4]
y2020-05-29svg.xml(670): Error: Invalid attribute stroke for element text, at /rfc/middle/section[2]/section[2]/artset[3]/artwork[1]/*/*[2]/*[8]
y2020-05-29svg.xml(671): Error: Invalid attribute stroke for element text, at /rfc/middle/section[2]/section[2]/artset[3]/artwork[1]/*/*[2]/*[9]
y2020-05-29svg.xml(672): Error: Invalid attribute stroke for element text, at /rfc/middle/section[2]/section[2]/artset[3]/artwork[1]/*/*[2]/*[10]
y2020-05-29svg.xml(659): Error: Invalid attribute shape-rendering for element svg, at /rfc/middle/section[2]/section[2]/artset[3]/artwork[1]/*
y2020-05-29svg.xml(692): Error: Invalid attribute stroke for element text, at /rfc/middle/section[2]/section[2]/artset[4]/artwork[1]/*/*[2]/*[8]
y2020-05-29svg.xml(693): Error: Invalid attribute stroke for element text, at /rfc/middle/section[2]/section[2]/artset[4]/artwork[1]/*/*[2]/*[9]
y2020-05-29svg.xml(694): Error: Invalid attribute stroke for element text, at /rfc/middle/section[2]/section[2]/artset[4]/artwork[1]/*/*[2]/*[10]
y2020-05-29svg.xml(695): Error: Invalid attribute stroke for element text, at /rfc/middle/section[2]/section[2]/artset[4]/artwork[1]/*/*[2]/*[11]
y2020-05-29svg.xml(696): Error: Invalid attribute stroke for element text, at /rfc/middle/section[2]/section[2]/artset[4]/artwork[1]/*/*[2]/*[12]

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 29 May 2020 23:29:06 +0200

Well, OK, this is now SVG generated by ditaa instead of goat, and ditaa seems to want to show of its knowledge of SVG some more.  So that may not be a change in xml2rfc at all.  My question is mostly still valid, though:

> Is svgcheck still intended to be the tool to be used with xml2rfc to make SVG palatable to it?  Is that being updated along with xml2rfc ...?

Grüße, Carsten

---

From: Brian E Carpenter <[email-masked]>
Date: Sat, 30 May 2020 11:24:40 +1200

Do you know what bit of SVG it is barfing on?

I'm curious because I've done some personal patching of svgcheck and discovered what a minefield this all is. Indeed, some drawing tools produce stuff that others don't, so there is a strong element of crapshoot.

Regards
   Brian

On 30-May-20 09:29, Carsten Bormann wrote:
> _______________________________________________
> xml2rfc mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/xml2rfc
>

---

From: Carsten Bormann <[email-masked]>
Date: Sat, 30 May 2020 08:42:16 +0200

Hi Brian,

> On 2020-05-30, at 01:24, Brian E Carpenter <[email-masked]> wrote:
> 

I had some error messages in my first message.  Let me expand on these:
AFAICS this is all about attributes that xml2rfc does not accept on specific SVG elements.

Consolidating these messages a bit, I get:

y.xml(722): Error: Invalid attribute shape-rendering for element svg, […]
y.xml(776): Error: Invalid attribute stroke for element path, […]
y.xml(818): Error: Invalid attribute stroke for element text, […]
(And then, apparently as a result of these:
y.xml(14): Error: Invalid document before running preptool.
.)

Well, this is not the whole story, as stroke needs to be a valid attribute for path; this seems to be about the value stroke="#000000” for path (which probably needs to be replaced by stroke=“black”) and stroke="none” for text (which probably is default anyway).
This was for ditaa.  With mscgen, I additionally get:

ymscgen.xml(87): Error: Invalid attribute text-rendering for element svg, […]

> I'm curious because I've done some personal patching of svgcheck and discovered what a minefield this all is. Indeed, some drawing tools produce stuff that others don't, so there is a strong elemen…

Yes, those words describe it pretty well.

Of course, I could easily integrate my own additions of svgcheck-like processing into kramdown-rfc.
Unfortunately, adding serious XML processing adds some deployment considerations (one would normally use a gem that causes some installation difficulties on older platforms as it requires compiling native code).

Grüße, Carsten

> Rfc-markdown mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/rfc-markdown

---

From: Carsten Bormann <[email-masked]>
Date: Sat, 30 May 2020 18:23:04 +0200

> Unfortunately, adding serious XML processing adds some deployment considerations (one would normally use a gem that causes some installation difficulties on older platforms as it requires compiling…

Well, I chose an older gem that doesn’t have this problem (but is quite slow and less tested); I can now do svgcheck workarounds and am doing those for the breakage I have seen for ditaa and mscgen.

So kramdown-rfc2629 version 1.3.7 now supports ditaa and mscgen (in addition to goat, which was added in 1.3.2) for automatic artset generation.  

So, for instance, you can now write

~~~ mscgen
msc {
  a,b,c;

  a->b  [label="ab()"] ;
  b->c  [label="bc(TRUE)"];
  c=>c  [label="process(1)"];
  c=>c  [label="process(2)"];
  ...;
  c=>c  [label="process(n)"];
  c=>c  [label="process(END)"];
  a<<=c [label="callback()"];
  ---   [label="If more to run", ID="*"];
  a->a  [label="next()"];
  a->c  [label="ac()"];
  b<-c  [label="cb(TRUE)"];
  b->b  [label="stalled(...)"];
  a<-b  [label="ab() = FALSE"];
}
~~~

and get what you can see at http://www.tzi.de/~cabo/1-3-7-mscgen.png .

As usual, update with

	gem update kramdown-rfc2629

The tool that you want to use (goat, mscgen, or ditaa) needs to be installed and on the path of the process that runs kramdown-rfc.

If there is any other tool like that that you’d like to see supported, and it produces SVG that can be made palatable to xml2rfc without superhuman effort, please tell me.

There is no doubt that you can write ditaa that will break svgcheck’s (and my workarounds’) little mind; e.g., preferably, try to stay black-and-white.

Note that for mscgen, the mscgen source may not exactly be what you want in a plaintext-based RFC (but the SVG output is probably what you do want in your HTML renderings); I’d appreciate any proposals on how to turn mscgen into ASCII art…

Grüße, Carsten

---

From: Tom Pusateri <[email-masked]>
Date: Sat, 30 May 2020 14:21:48 -0400

> On May 30, 2020, at 12:23 PM, Carsten Bormann <[email-masked]> wrote:
> 

I use Boxy SVG (https://boxy-svg.com) and need to make some drawings for a draft so I’ll try it when I get a chance.

Tom

---

From: Carsten Bormann <[email-masked]>
Date: Sun, 31 May 2020 02:15:18 +0200

> I use Boxy SVG (https://boxy-svg.com) and need to make some drawings for a draft so I’ll try it when I get a chance.

Hi Tom,

I’m using that, too, occasionally (outside of RFCs).
Does that come with a command line tool for transforming a “source” (e.g., ASCII art)?
This is the use case that I was addressing first, as the source then stands in fine as a plaintext replacement for the graphics.

I could clearly add

~~~ svg
{::include boxy-output.svg}
~~~

as a shortcut for all the things that need to be done to include SVG, but where would the plaintext stand-in come from?

(And what might be good markdown for the “artset” approach used by beta v3?)

Grüße, Carsten

---

From: Miek Gieben <[email-masked]>
Date: Sun, 31 May 2020 08:00:40 +0200

[ Quoting <[email-masked]> in "[Rfc-markdown] 1.3.7: supporting di..." ]
>So, for instance, you can now write

I've had a similar idea and implemented it as a separate binary that manipulates
the markdown: https://mmark.miek.nl/post/markdown-filter/

This allows you to create pipelines, example one that uses a python program called
'protocol': https://github.com/mmarkdown/filter/tree/master/plugins/protocol

``` protocol
Source:16,TTL:8,Reserved:40
```
Figure: This is a protocol.

Will be transformed with `filter -p protocol < protocol.md | mmark -markdown`, to:

We describe the following protocol:

```
  0                   1                   2                   3
  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|             Source            |      TTL      |               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+               +
|                            Reserved                           |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
```
Figure: This is a protocol.

/Miek

--
Miek Gieben

---

From: Carsten Bormann <[email-masked]>
Date: Sun, 31 May 2020 09:11:49 +0200

(FDT list: Talking about diagram generation in RFC markdown; look at the thread in https://mailarchive.ietf.org/arch/msg/rfc-markdown/meUO_DWdsJJm36FwTVYcto00tRo/ )

Hi Miek,

> This allows you to create pipelines,

Yea, troff (nroff) has been using this approach successfully for almost half a century now.
I was trying to do a slightly more “batteries included” approach.
The disadvantage of both approaches is that any change in the document requires running all the filters again, and for SVG output these are often unwieldy Java clunkers; some form of smart caching (as is done for the bibxml retrieval) would probably help.

On to your filter example:

> example one that uses a python program called

It strikes me “protocol” is not a smart name for something that does only the box notation part of the work…  (Also, “protocol” is taken in pip, so I don’t even know how to install the thing.)

> Figure: This is a protocol.

Nice!
I never got around to doing a box notation generator; mostly because box notation in reality can be a bit more complicated.

https://tools.ietf.org/html/rfc7252#section-3
https://tools.ietf.org/html/rfc7400#section-3.3
https://tools.ietf.org/html/rfc793#section-3.1

Maybe the author of that tool should talk to Stephen McQuistin…
https://tools.ietf.org/html/draft-mcquistin-augmented-ascii-diagrams-04

On another note, I just found plantuml’s ascii_art mode; if sequence diagrams are good enough, this might solve the plaintext vs. svg issue one has with mscgen.  Next on the todo list now...

Grüße, Carsten

---

From: Carsten Bormann <[email-masked]>
Date: Sun, 31 May 2020 10:26:30 +0200

On 2020-05-31, at 09:11, Carsten Bormann <[email-masked]> wrote:
> 
> On another note, I just found plantuml’s ascii_art mode; if sequence diagrams are good enough, this might solve the plaintext vs. svg issue one has with mscgen.  Next on the todo list now…

OK, I also found “skinparam handwritten true”, so it had to be done.

~~~ plantuml-utxt
skinparam handwritten true
actor Alice
database Bob
Alice -> Bob : Hi
Bob -> Alice : Who are you?
Alice -> Bob : Alice
Bob -> Alice : You are in!
~~~

The -utxt means that the ascii_art part of the artset (which isn’t ASCII any more) also is processed by plantuml, a bare plantuml gives you the source in the plaintext version.

-utxt output in Plaintext:

          ┌─┐           ,.-^^-._
          ║"│          |-.____.-|
          └┬┘          |        |
          ┌┼┐          |        |
           │           |        |
          ┌┴┐          '-.____.-'
         Alice            Bob
           │      Hi       │
           │──────────────>│
           │               │
           │ Who are you?  │
           │<──────────────│
           │               │
           │    Alice      │
           │──────────────>│
           │               │
           │ You are in!   │
           │<──────────────│
         Alice            Bob
          ┌─┐           ,.-^^-._
          ║"│          |-.____.-|
          └┬┘          |        |
          ┌┼┐          |        |
           │           |        |
          ┌┴┐          '-.____.-‘

Screenshot from output in HTML below.

Grüße, Carsten

---

From: Miek Gieben <[email-masked]>
Date: Sun, 31 May 2020 20:13:48 +0200

>The disadvantage of both approaches is that any change in the document requires running all the filters again, and for SVG output these are often unwieldy Java clunkers; some form of smart caching (…

fair enough, that's a sound approach, I just wanted to show another way of approaching
this.

>It strikes me “protocol” is not a smart name for something that does only the box notation part of the work…  (Also, “protocol” is taken in pip, so I don’t even know how to install the thing.)

yeah, not a name I would choose. I think I ended up downloading the python script and
making it executable (or some such - long time ago)

/Miek

--
Miek Gieben

---

From: Tom Pusateri <[email-masked]>
Date: Sun, 31 May 2020 15:56:31 -0400

> On May 30, 2020, at 8:15 PM, Carsten Bormann <[email-masked]> wrote:
> 

oh, I see. My case was simpler because I was taking an existing ASCII art and redrawing it in SVG.

I don’t have a way to generate both from scratch and Boxy SVG doesn’t have a command line option.

Tom