Subject: [Tools-discuss] .txt? [I-D Action: draft-xxx.txt]

From: Brian E Carpenter <[email-masked]>
Date: Sun, 27 Jun 2021 11:07:51 +1200

Why does the subject field and the Filename say ".txt" for a v3 draft?

   Brian

-------- Forwarded Message --------
Subject: [Anima] I-D Action: draft-ietf-anima-asa-guidelines-01.txt
Date: Sat, 26 Jun 2021 15:43:05 -0700
From: [email-masked]
Reply-To: [email-masked]
To: [email-masked]
CC: [email-masked]

A New Internet-Draft is available from the on-line Internet-Drafts directories.
This draft is a work item of the Autonomic Networking Integrated Model and Approach WG of the IETF.

        Title           : Guidelines for Autonomic Service Agents
        Authors         : Brian Carpenter
                          Laurent Ciavaglia
                          Sheng Jiang
                          Pierre Peloso
	Filename        : draft-ietf-anima-asa-guidelines-01.txt
	Pages           : 27
	Date            : 2021-06-26

Abstract:
   This document proposes guidelines for the design of Autonomic Service
   Agents for autonomic networks.  Autonomic Service Agents, together
   with the Autonomic Network Infrastructure, the Autonomic Control
   Plane and the Generic Autonomic Signaling Protocol constitute base
   elements of a so-called autonomic networks ecosystem.

The IETF datatracker status page for this draft is:
https://datatracker.ietf.org/doc/draft-ietf-anima-asa-guidelines/

There is also an HTML version available at:
https://www.ietf.org/archive/id/draft-ietf-anima-asa-guidelines-01.html

A diff from the previous version is available at:
https://www.ietf.org/rfcdiff?url2=draft-ietf-anima-asa-guidelines-01

Internet-Drafts are also available by anonymous FTP at:
ftp://ftp.ietf.org/internet-drafts/

_______________________________________________
Anima mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/anima

---

From: "John Levine" <[email-masked]>
Date: 26 Jun 2021 21:32:56 -0400

>Why does the subject field and the Filename say ".txt" for a v3 draft?

Because you can still submit text I-D's if you want.  If you submit xml
it'll render it into text, but it can't go the other way.

If your I-D makes it into the publication queue and there isn't an XML
version, the RPC will hand convert your text but that doesn't happen
very often now except for people who write their drafts in MS Word.

R's,
John

---

From: Brian E Carpenter <[email-masked]>
Date: Sun, 27 Jun 2021 14:03:47 +1200

Well, let me ask it another way.

Why aren't we actively encouraging people to submit xml2rfcv3 source, and rewarding those who do so with a message that makes it clear that this is what we prefer?

I accidentally submitted xml2rfcv2 source the other day, and the system just sucked it in without even pointing out that it was so 20th century.

I hope that the various tool updates we've been promised will firmly nudge people towards v3.

Regards
   Brian Carpenter

---

From: "John R Levine" <[email-masked]>
Date: 26 Jun 2021 22:14:17 -0400

> Why aren't we actively encouraging people to submit xml2rfcv3 source, and rewarding those who do so with a message that makes it clear that this is what we prefer?

Among the many things on the to-do list is to redo the I-D submission page 
to make it clearer that you only need to submit one version of a draft, 
and that we'd appreciate the XML version if you have one.

R's,
John

>>>   elements of a so-called autonomic networks ecosystem.

Regards,
John Levine, [email-masked], Taughannock Networks, Trumansburg NY
Please consider the environment before reading this e-mail. https://jl.ly

---

From: Brian E Carpenter <[email-masked]>
Date: Sun, 27 Jun 2021 14:31:34 +1200

> and that we'd appreciate the XML version if you have one.

Excellent. Is there any reason not to run the v2 to v3 converter automatically?

   Brian

---

From: "John R Levine" <[email-masked]>
Date: 26 Jun 2021 22:40:40 -0400

> Excellent. Is there any reason not to run the v2 to v3 converter automatically?

We really want people to stop using v2.  It's obsolete and missing some 
semantic features of v3.

Regards,

---

From: Brian E Carpenter <[email-masked]>
Date: Sun, 27 Jun 2021 17:09:14 +1200

> We really want people to stop using v2.  It's obsolete and missing some 

I fully agree. But isn't the submission page the primary place to put the necessary nudges and warnings?

I'm sure you and Robert know this, but between the ancient state of https://xml2rfc.tools.ietf.org/ and the confusing state of https://xml2rfc.tools.ietf.org/experimental.html, what is a poor user supposed to do, if they don't want to install and maintain their own copy of everything?

    Brian

---

From: Carsten Bormann <[email-masked]>
Date: Sun, 27 Jun 2021 08:03:48 +0200

On 27. Jun 2021, at 04:40, John R Levine <[email-masked]> wrote:
> We really want people to stop using v2.  It's obsolete and missing some semantic features of v3.

People are now often submitting v2 with v3 features, which is perfectly fine until v3 stabilises.
Why doesn’t the submission page run this through the v2 to v3 converter?

The behaviour that runs last decade’s tools when it detects v2 may have been acceptable as a safety measure for a couple of months when the transition started but is completely broken now.  This really needs to be fixed NOW.  Sheesh.

Grüße, Carsten

---

From: Carsten Bormann <[email-masked]>
Date: Sun, 27 Jun 2021 08:26:02 +0200

> We really want people to stop using v2.  It's obsolete and missing some semantic features of v3.

John,

let me be blunt here.

The attitude that it is OK to be hostile to document authors in order to further some meaningless abstract goal is completely unacceptable and has to stop.

There are good reasons to continue submitting v2 or v2-with-v3 documents.

For people actually authoring in XML, the version control history of all but the most recently started documents is in v2.  A wholesale v3 conversion loses all that history.

For people using a tool to generate the XML, it is unacceptable to require their tools to generate exactly the v3 of the day, in particular as xml2rfc has a perfect v3 generator inside, which by the nature of the process is more likely to stay in sync with the ongoing fixes to v3.

And, in case I haven't been clear enough, the needs (and even more so the wants!) of the RPC are entirely secondary to those of the authors here, as 98 % of the work on a document happens before the RPC gets it, and the resources feeding that work are non-renewable.

(And yes, the abstract goal of furthering the v3 transition is not entirely meaningless in the long run, but we are *way* off from that goal being a realistic short-term objective.  And the feature of xml2rfc to be more permissive in its converter input than the v3 publishing format must *never* go away, at least as long as we consider the time and quality of work of our authors and tool makers to be a precious resource.)

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Sun, 27 Jun 2021 11:00:59 +0200

> For people actually authoring in XML, the version control history of all but the most recently started documents is in v2.  A wholesale v3 conversion loses all that history.

I think that's a stretch. AFAIU, the only things that actually need to
be edited are list and table markup.

But yes, revision history is important.

> ...

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Sun, 27 Jun 2021 11:40:55 +0200

> be edited are list and table markup.

Well, I talked about a wholesale conversion.
Manual upgrade is a complete non-starter, and it still pollutes the revision history.

> But yes, revision history is important.

Indeed.

Grüße, Carsten

---

From: "Andrew G. Malis" <[email-masked]>
Date: Sun, 27 Jun 2021 08:53:12 -0400

Just speaking as a document author, I've written my share of drafts over
the many years, in just about every format that the IETF has supported -
plain text, nroff, generated nroff (nroffedit), various versions of the
Word template, various versions of XML, generated XML via KramDown.
and others that I've probably forgotten.

My goal as an author is to write drafts to get my ideas expressed without
having to worry about the syntax for a pseudo-programming language as well.

Currently, I've found that KramDown comes closest to meeting that need, and
I'm very happy to let others (thanks, Carsten!) keep up with the current
state of XML. But what would be really cool would be something similar to
what we had with nroffedit - you just type what needs to be written, and
the tool makes it look nice in real time. and then generates what's needed
to be submitted to the process in the syntax of the day.

I get that the transition to v3 is important for the process, and makes
things better behind the curtain. But I'm sure the great majority of drafts
authors really don't really care, just want to get their ideas expressed as
easily as possible, and are happy to leave the programming details behind
the curtain where they belong.

Cheers,
Andy

On Sun, Jun 27, 2021 at 2:26 AM Carsten Bormann <[email-masked]> wrote:

> The attitude that it is OK to be hostile to document authors in order to
> further some meaningless abstract goal is completely unacceptable and has
> to stop.
>
> For people actually authoring in XML, the version control history of all
> but the most recently started documents is in v2.  A wholesale v3
> conversion loses all that history.
>
> For people using a tool to generate the XML, it is unacceptable to require
> their tools to generate exactly the v3 of the day, in particular as xml2rfc
> has a perfect v3 generator inside, which by the nature of the process is
> more likely to stay in sync with the ongoing fixes to v3.
>
> And, in case I haven't been clear enough, the needs (and even more so the
> wants!) of the RPC are entirely secondary to those of the authors here, as
> 98 % of the work on a document happens before the RPC gets it, and the
> resources feeding that work are non-renewable.
>
> (And yes, the abstract goal of furthering the v3 transition is not
> entirely meaningless in the long run, but we are *way* off from that goal
> being a realistic short-term objective.  And the feature of xml2rfc to be
> more permissive in its converter input than the v3 publishing format must
> *never* go away, at least as long as we consider the time and quality of
> work of our authors and tool makers to be a precious resource.)
>
> Grüße, Carsten
>
> ___________________________________________________________
> 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: "John R Levine" <[email-masked]>
Date: 27 Jun 2021 15:48:32 -0400

On Sun, 27 Jun 2021, Andrew G. Malis wrote:
> But what would be really cool would be something similar to

You and me both.  There's a variety of ways we might do that.

There are commercial XML editors like that, you edit a roughly formatted 
version of the document and it writes out the XML.  They're unlikely to be 
useful to us for several reasons.  One is that our XML turns out to be 
quite unlike everyone else's XML so people who've tried the editors say 
they don't work well with our grammar.  Also, they're expensive, and I 
doubt many ietfers would want to install and learn the quirks of yet 
another editor.

Another possibility is some MS Word stylesheets and macros and a
converter between docx and xml2rfc.  A lot of people like Word, and I 
think it would not be too hard to come up with a set of styles that could 
be reliably converted to xml2rfc.  I realize a lot of people don't like 
Word, but at least it's not a new program to learn.

There are a lot of markdown editors, some of which are browser apps, some 
of which are separate programs. I haven't looked to see if any of them 
might be suitable to adapt.

Regards,

---

From: Julian Reschke <[email-masked]>
Date: Sun, 27 Jun 2021 22:08:54 +0200

Am 27.06.2021 um 21:48 schrieb John R Levine:
> version of the document and it writes out the XML.  They're unlikely to
> be useful to us for several reasons.  One is that our XML turns out to
> be quite unlike everyone else's XML so people who've tried the editors
> say they don't work well with our grammar.  Also, they're expensive, and
> I doubt many ietfers would want to install and learn the quirks of yet
> another editor.
>
> think it would not be too hard to come up with a set of styles that
> could be reliably converted to xml2rfc.  I realize a lot of people don't
> like Word, but at least it's not a new program to learn.
>
> There are a lot of markdown editors, some of which are browser apps,
> some of which are separate programs. I haven't looked to see if any of
> them might be suitable to adapt.
> ...

Or you could run a text-editor and web browser side-by-side and use
rfc2629.xslt's "live HTML refresh" feature (see
<https://greenbytes.de/tech/webdav/rfc2629xslt/rfc2629xslt.html#html.live.refresh>).

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Sun, 27 Jun 2021 22:15:34 +0200

> <https://greenbytes.de/tech/webdav/rfc2629xslt/rfc2629xslt.html#html.live.refresh>).

Doing something like this server-based (server runs on your laptop) is a SMOP (small matter of programming), and I’m already using that for other kinds of markdown.
Coming to an I-D/RFC markdown processor of your choice whenever next I have half a day to burn.

Grüße, Carsten

---

From: "Andrew G. Malis" <[email-masked]>
Date: Sun, 27 Jun 2021 17:00:43 -0400

Carsten,

Cool, thanks!

Cheers,
Andy

On Sun, Jun 27, 2021 at 4:15 PM Carsten Bormann <[email-masked]> wrote:

> > <
> https://greenbytes.de/tech/webdav/rfc2629xslt/rfc2629xslt.html#html.live.refresh
> >).
>
> Doing something like this server-based (server runs on your laptop) is a
> SMOP (small matter of programming), and I’m already using that for other
> kinds of markdown.

---

From: Michael Richardson <[email-masked]>
Date: Sun, 27 Jun 2021 17:22:33 -0400

https://codimd.ietf.org/mcr-kramdown-test

This is 90% of the way there.
It doesn't process the {{Stuff}}.
It also doesn't seem to reflow text quite as I would expect it to.

--
Michael Richardson <[email-masked]>   . o O ( IPv6 IøT consulting )
           Sandelman Software Works Inc, Ottawa and Worldwide

---

From: Jay Daley <[email-masked]>
Date: Mon, 28 Jun 2021 09:36:09 +1200

> On 27/06/2021, at 5:09 PM, Brian E Carpenter <[email-masked]> wrote:
> 

Indeed, your analysis is quite correct and there is an RFP currently open that includes a full replacement of those two pages

	https://www.ietf.org/media/documents/Author_tools_web_services_re-implementation_RFP.pdf

Jay

> List info (including how to Unsubscribe): https://www.ietf.org/mailman/listinfo/tools-discuss
> 

-- 
Jay Daley
IETF Executive Director
[email-masked]

---

From: "John Levine" <[email-masked]>
Date: 28 Jun 2021 00:51:39 -0000

>This is 90% of the way there.

That last 10% is a killer.  I think codimd is swell, but its version of markdown is not the same 
as Carsten or Miek's.  Codimd is from a commercial provider called Hackmd.  There is an open source
fork but I would not want to maintain a mutant version of their giant blob of Javascript and I expect
asking for custom mods would be expensive.

Also, even if someone were to modify Codimd/Hackmd to handle one of our dialects, the rendering
of <markdown> -> Codimd -> html would not be the same as <markdown> -> kramdown/mmark -> xml2rfc -> html.
Some differences wouldn't matter, but some could easily be misleading and frustrating.

I hope we can buy or build markdown editing tools but I really do not want to do something
half baked and unmaintainable.  We already have too much of that.

R's,
John
-- 
Regards,
John Levine, [email-masked], Primary Perpetrator of "The Internet for Dummies",
Please consider the environment before reading this e-mail. https://jl.ly

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 28 Jun 2021 03:45:03 +0200

On 28. Jun 2021, at 02:51, John Levine <[email-masked]> wrote:
> That last 10% is a killer.

+1.

Note that CodiMD (which these days is called HedgeDoc, we are just running an older version) is already quite useful for editing rfc-markdown.
As is the markdown support in GitHub.

But to get those last 10 % of fidelity (“WYSIWYG”), we need xml2rfc in the loop.
For now, this means server-based approaches, as I alluded to.

As soon as references etc. are in cache, my laptop translates the source of RFC 8949 (approximately 80 pages (*)) to HTML in about 2.6 s (0.8 s kramdown-rfc + 1.8 s xml2rfc).
Adding a few 100 ms for browser processing, this means that the latency from an editor save to a redisplay could be ≈ 3 s.
Maybe not good enough for editing NFSv4.1, but for everything else, this should be quite usable.
(And I have a few ideas how to speed this up by a factor of three, but crawling comes before walking.)

Grüße, Carsten

(*) Yeah, I know.  We don’t get page numbers any more, except in the PDF, and that is slightly more dense, at 66 pages here.  Hence “approximately”.  But most people will have a feel for the size of their I-Ds in plaintext pages, so I’m using the 80 pages the I-D was.

---

From: Warren Kumari <[email-masked]>
Date: Mon, 28 Jun 2021 14:38:41 -0400

On Sun, Jun 27, 2021 at 8:53 AM Andrew G. Malis <[email-masked]> wrote:
>
> Just speaking as a document author, I've written my share of drafts over the many years, in just about every format that the IETF has supported - plain text, nroff, generated nroff (nroffedit), various versions of the Word template, various versions of XML, generated XML via KramDown. and others that I've probably forgotten.
>
> My goal as an author is to write drafts to get my ideas expressed without having to worry about the syntax for a pseudo-programming language as well.
>
> Currently, I've found that KramDown comes closest to meeting that need, and I'm very happy to let others (thanks, Carsten!) keep up with the current state of XML. But what would be really cool would be something similar to what we had with nroffedit - you just type what needs to be written, and the tool makes it look nice in real time. and then generates what's needed to be submitted to the process in the syntax of the day.
>
> I get that the transition to v3 is important for the process, and makes things better behind the curtain. But I'm sure the great majority of drafts authors really don't really care, just want to get their ideas expressed as easily as possible, and are happy to leave the programming details behind the curtain where they belong.

+lots.

People have a workflow, and have become accustomed to it. As an
example, I've been writing drafts for ~12 years (yes, I'm a newbie),
and have probably 80+ drafts, with around 580 revisions[0]. I have a
workflow that "just works" - I'm sure it isn't the best workflow, but
it's been working just fine for me 580 times...

Other than "because we said so" it's very unclear *why* I should
change my existing workflow. Yes, what I've been doing will stop
working, but there hasn't been a great message about how this helps
the author - it certainly feels like "we are making a breaking change
to the API, deal with it..." type signal, not a "here, look at the new
API, it has the following features which makes *your* life better.
Come try it!"

W

[0]: $find . -name '*.xml' -exec grep 'docName' {} \; | grep -v '<!--' | wc -l
587
$

-- 
The computing scientist’s main challenge is not to get confused by the
complexities of his own making.
  -- E. W. Dijkstra

---

From: Toerless Eckert <[email-masked]>
Date: Mon, 28 Jun 2021 21:38:15 +0200

I only converted the last rfc i was editor for during the final revisions to go to rfc,
and i only did this so i could use the only one new feature of v3 that i felt i wanted
to use, name the Contributors tag. I still don't know what else i as an author
would benefit from in v3.

I did find the conversion sufficient for that last mile to RFC editor, but not persuasive to
suggest it to authors if/when they want to continue doing mayor edits to the document. This
is primarily beceause the v3 ended up with a tag-verbose XMLv3 than the v2 i had
edited for years. This specifically included inlining the rfc/draft references as opposed 
to keeping the references, but also several other tags that where written out more verbosely
and with a lot of default parameters (unnecessarily).  Hope i remember this all correctly.

This v2->v3 conversion process feels a bit like attempting to have a good idea but then
outsource the conversion cost.  Reminds me of linux. Great new SDK/Library, but now all
the third-party apps developed against an older version have to be rewritten. In comparison,
in Windows i can have 10 versions of the same core SDK co-installed and all the old but
still useful programs will still run. But no linux distributions do not support such slotting
or do not compile all old library versions, and library developers don't care about supporting
multi-slotting... *sigh*

Chers
    Toerless

-- 
---
[email-masked]

---

From: Brian E Carpenter <[email-masked]>
Date: Tue, 29 Jun 2021 09:48:36 +1200

> I still don't know what else i as an author

1. A very nice looking HTML result instead of a geeky thing.
2. UTF-8
3. SVG. Hard work to use, but well worth it.
4. Using tools that are currently maintained.

I've had no trouble at all editing XML in v3. The only real
annoyance is that the converter can't do anything sensible with
<vspace blankLines="1"/> which I used to use a lot. Everything
else is trivial.

(The converter insists on inserting lots of format="default"
and toc="default" which are just noise and can be deleted.)

Regards
   Brian

---

From: Brian E Carpenter <[email-masked]>
Date: Tue, 29 Jun 2021 09:59:36 +1200

Warren, I just gave my answer to your *why* question:
https://mailarchive.ietf.org/arch/msg/tools-discuss/rDeV5p4_JFYl-Woauplx_VM9R0o/

Regards
   Brian

On 29-Jun-21 06:38, Warren Kumari wrote:
>> Just speaking as a document author, I've written my share of drafts over the many years, in just about every format that the IETF has supported 
- plain text, nroff, generated nroff (nroffedit), various versions of the 
Word template, various versions of XML, generated XML via KramDown. and others that I've probably forgotten.
>>> The attitude that it is OK to be hostile to document authors in order 
to further some meaningless abstract goal is completely unacceptable and has to stop.
>>> For people using a tool to generate the XML, it is unacceptable to require their tools to generate exactly the v3 of the day, in particular as 
xml2rfc has a perfect v3 generator inside, which by the nature of the process is more likely to stay in sync with the ongoing fixes to v3.
>>>
>>> And, in case I haven't been clear enough, the needs (and even more so 
the wants!) of the RPC are entirely secondary to those of the authors here, as 98 % of the work on a document happens before the RPC gets it, and the resources feeding that work are non-renewable.
>>>
>>> (And yes, the abstract goal of furthering the v3 transition is not entirely meaningless in the long run, but we are *way* off from that goal being a realistic short-term objective.  And the feature of xml2rfc to be more permissive in its converter input than the v3 publishing format must 
*never* go away, at least as long as we consider the time and quality of work of our authors and tool makers to be a precious resource.)

---

From: Toerless Eckert <[email-masked]>
Date: Tue, 29 Jun 2021 01:47:07 +0200

> 3. SVG. Hard work to use, but well worth it.

Thanks for explaining. 

> 4. Using tools that are currently maintained.

Quite a big churn for third party tooling for these benefits.

> I've had no trouble at all editing XML in v3.

Some tags got more convoluted. And figuring out how to put RFC references into v3 was also more convoluted han in v2.

> The only real

Yes. There should be more rendering hints permitted/maintained. 

> and toc="default" which are just noise and can be deleted.)

That too.

Well, i am just trying to write my first draft in kramdown, i'll have more opinions later.

-- 
---
[email-masked]

---

From: Julian Reschke <[email-masked]>
Date: Tue, 29 Jun 2021 08:08:48 +0200

> Some tags got more convoluted. And figuring out how to put RFC references into v3 was also more convoluted han in v2.

a) Which?

b) It's just a slightly different syntax (a standard one instead of a
what actually was a hack).

> Yes. There should be more rendering hints permitted/maintained.

There've been a lot of dicussions about that, actually. There are bery
good reasons not to have them.

>> and toc="default" which are just noise and can be deleted.)

IMHO a bug.

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 29 Jun 2021 15:09:25 +0200

>> […] And figuring out how to put RFC references into v3 was also more convoluted han in v2.
> 
> […]
> 

This sentence(†) is a nice demonstration for the confusion in this space.

As a format for the publishing process (RPC), having a standards-based mechanism is good.  (The references don’t make it to the published RFC, as they have been expanded by then, but the process may still benefit.)

As a format for authoring, making the input vastly more complicated in the name of some lofty goal (here: standards conformance) is exactly the leading symptom of the v3 development process.  Offering a bespoke, efficient(*) way of keyboarding IETF document references is exactly the right way to handle this, at least for people still authoring in XML.

Grüße, Carsten

(†) I have removed the attribution, because this observation is not about a single person.  It is about the groupthink that derailed some of the v3 process.

(*) In case that isn’t clear: Efficiency here is all about saving time for the author while continuing to achieve a high quality result.

---

From: Warren Kumari <[email-masked]>
Date: Tue, 29 Jun 2021 09:54:24 -0400

> 1. A very nice looking HTML result instead of a geeky thing.

This is working on the assumption that I *wanted* an HTML result and
not a "geeky thing" which has 50+ years of deployment, tradition and
recognizable look-and-feel. The falls into the bug, not feature bucket
for me.

> 2. UTF-8

Ok, this one I like.

> 3. SVG. Hard work to use, but well worth it.

Again, see #1. I believe that requiring that complex things be
explainable using ASCII art was a feature - if your protocol is
sufficiently complex that it cannot be easily explained using words
and ascii art, it's probably too complex.

> 4. Using tools that are currently maintained.

Tools like the XML2RFC XMLMind plugin were working just fine with the
V2 format; every few years I'd release a new version when XMLMind
updated their major version, but it was literally just a version bump.
Same thing for my "copy the last RFC, change the title and words". #4
sounds very much like "people weren't keeping the tools maintained the
way we liked, so we made a breaking change to force them to abandon
what they were doing, and use what we think is better.

Anyway, I realize that this ship has sailed, and I'm doing a good
impression of "Old Man Yells at Cloud"... but someone asked why more
stuff wasn't being submitted in v3 format, and this is at least one
set of reasons why...

W

---

From: Julian Reschke <[email-masked]>
Date: Tue, 29 Jun 2021 17:05:18 +0200

> As a format for authoring, making the input vastly more complicated in the name of some lofty goal (here: standards conformance) is exactly the leading symptom of the v3 development process.  Offer…

It is not "vastly more complicated". It's a different syntax (with the
benefit of it not being PI-based which is yet another XML complication
for most authors). (*)

IFIUC, you miss the feature of not having to specify the complete URL of
the reference? (Or is there something else I'm not aware of?).

Best regards, Julian

(*) And, BTW the *other* way to include stuff as explained in
<https://greenbytes.de/tech/webdav/rfc7749.html#including.files>
continues to work, as it's just a basic XML feature.

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 29 Jun 2021 18:05:14 +0200

> benefit of it not being PI-based which is yet another XML complication

Yes.  Not using PIs means that this feature now comes under the strict eyes of the chaperone, the RNG validation.
So we all have to fix up the RFCXML RNC to make this feature available in various environments.
This is not progress.

Also, the fact that there now need to be full URIs instead of more reasonable document identifiers is confusing people.
(Not that the old ones were particularly good, but they should have been simplified, not pessimized.)

Yes, PIs are unclean in some universe.  They are also useful for adding features where being clean gets in the way.

> the reference? (Or is there something else I'm not aware of?).

Typing full URLs is not a good use of author time.

> continues to work, as it's just a basic XML feature.

Which is, of course the one I used during the first 10 years of using RFCXML; I wasn’t even aware about the PI form before I moved away from keyboarding XML.
But others were (and some still use XML), and I’m trying to be their advocate here.

Grüße, Carsten

---

From: Toerless Eckert <[email-masked]>
Date: Tue, 29 Jun 2021 18:31:33 +0200

> and ascii art, it's probably too complex.

I looked at the RFCs with SVG given as examples on the URL earlier here
in this thread. Unfortunately, these all had only SVG that where not
a bit more useful than their ASCII renderings. so no points scored for SVG
in the v3 marketing materials.

I am not sure what you call "protocol", , but there is certainly more in
RFCs than just what would fit ASCII art:

Think of all the draft/RFCs in IRTF that want to have actual
measurement diagrams like research papers have them. Try to render those
in ASCII. Or graphics showing some forwarding plane / chip architecture,
or real-world topologies of large networks of interest.

If i could just figure out the workflow to take some existing bitmap
and abuse SVG to include it into a draft. Still not sure if that
(bitmap in SVG) is even allowed by the XMLv3 laws

> what they were doing, and use what we think is better.

Did v2 and does v3 have incremental enhancements ? If the language(s)
are themselves fixed, then tool maintenance would only be necessary
if other conditions change, like in your case XMLMind. If one builds a
standalone tool, maintenance might not even be necessary.

Cheers
    Toerless

-- 
---
[email-masked]

---

From: "John R Levine" <[email-masked]>
Date: 29 Jun 2021 12:51:53 -0400

> (bitmap in SVG) is even allowed by the XMLv3 laws

Since the V in SVG stands for Vector, I hope not.  Also note S for 
Scalable.

What we need, of course, is some way to render the diagram from which you 
created the bitmap into a SVG, and also for us to figure out what profile 
of SVG makes sense.  It's clear to me that our current choice aimed too 
low.

Regards,

---

From: Toerless Eckert <[email-masked]>
Date: Tue, 29 Jun 2021 19:12:55 +0200

On Tue, Jun 29, 2021 at 12:51:53PM -0400, John R Levine wrote:
> Since the V in SVG stands for Vector, I hope not.  Also note S for Scalable.
> 
> created the bitmap into a SVG, and also for us to figure out what profile of
> SVG makes sense.  It's clear to me that our current choice aimed too low.

If you look from the reality of how e.g.: research papers are
created, you will see that almost everybody goes through bitmaps
for graphics so that any tooling can be used. Forcing vector graphics
will just cause much less adoption of graphics.

Scalability is sufficiently served by asking for high enough pixel resolution
(150dpi or more AFAIK) for bitmap graphics.

I personally like the vector religion. I was so unhappy when NeWS on
Sun was replaced by *yuck* X10/X11, but then again, accepting reality
is a virtue too.

Cheers
    Toerless

---

From: Eric Rescorla <[email-masked]>
Date: Tue, 29 Jun 2021 10:29:31 -0700

> and ascii art, it's probably too complex.

I'm sure I'm going to regret this, but....

Obviously things *can* be explained using words and ASCII art. The question
is whether it would be easier to explain with diagrams that were better
looking. I -- as I imagine you have -- have read a number of books
documenting network protocols and nearly universally they use high quality
diagrams, not ASCII art. I would suggest that this is a strong indication
that our format reduces clarity.

There are a number of cases that are particularly burdensome
- State machine diagrams
- Math of any kind
- Ladder/swimlane diagrams in which there is nontrivial amounts of stuff
happening on each step

People who make the kind of argument you are making -- a related one being
that engineers should have to use slow computers or tiny displays in order
to keep complexity down -- usually seem to have in mind that this will
result in the output being better along some axis. Is that in fact your
thesis? If so, so you have any evidence that forcing people to use ASCII
art reduces output complexity?

-Ekr

---

From: Julian Reschke <[email-masked]>
Date: Tue, 29 Jun 2021 20:27:53 +0200

> So we all have to fix up the RFCXML RNC to make this feature available in various environments.

Concrete example?

If this really is a problem in practice, we can of course publish a
schema that takes this into account (a pre-include schema).

FWIW, with the old style PIs, documents by definition never were valid
because of dangling anchors.

> Yes, PIs are unclean in some universe.  They are also useful for adding features where being clean gets in the way.

These are orthogonal issues. As I said above, a v2 document using PIs
for includes by definition can not be valid, so I'm not sure how the
switch to x:include makes things worse. There's even a tiny chance of
things being better if the validator applies x:include before validation
(which it should).

Yes, we could have added an inclusion mechanism which is not generic,
and special-cases reference inclusion. We still can do that if people
feel that's important.

> Typing full URLs is not a good use of author time.

You don't type them - you paste them.

> But others were (and some still use XML), and I’m trying to be their advocate here.

Can we hear from them, please?

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 29 Jun 2021 21:55:14 +0200

> schema that takes this into account (a pre-include schema).

(Such a grammar actually exists; I forget the reason why I did have to create my own version anyway.)

> because of dangling anchors.

But that doesn’t get in the way as much as structural deviations do.
(Most editors allow you to have an IDREF before putting in the ID.)

Sure (from an unsolicited passage in a recent e-mail exchange where I was asked to convert an older draft from XML to markdown):

> I started writing this draft before I switched to markdown. Now I hate everytime I have to edit xml....

I rest my case.

Grüße, Carsten

---

From: Brian E Carpenter <[email-masked]>
Date: Wed, 30 Jun 2021 09:34:52 +1200

> in the v3 marketing materials.

That's really a matter of opinion and in the reader's brain, not the writer's.
But basically I agree with EKR.
 
> (bitmap in SVG) is even allowed by the XMLv3 laws

Well, see the two attached files. The first one is png produced by gnuplot. The second one is SVG produced by gnuplot, and then run through my SVG 
color fixer followed by the IETF's SVG checker.

Since gnuplot is the de facto standard for producing plots in academic articles, I think we are fine.

    Brian

---

From: Toerless Eckert <[email-masked]>
Date: Tue, 29 Jun 2021 23:41:06 +0200

> > Some tags got more convoluted. And figuring out how to put RFC references into v3 was also more convoluted han in v2.

I forgot the details and it would take me effort to put that together,
and right now i do not have the trust that spending that effort would
achieve anything in getting the tool improved.

So, for now i have submitted a ticket for what i consider from my own experience to
be the worst problem, and if that actually does get fixed, i will go back and look
into reporting the other issues.

https://trac.ietf.org/trac/xml2rfc/ticket/650

> what actually was a hack).

v2 was already a fairly bad markup for human editing, even if many
of us seem to suffer from Stockholm syndrom and claim to like it.

When we make v3 even harder to edit by humans because it needs to
be better for machine processing, then we should really talk about
a standard tools-team supported text-edit format like kramdown.

> good reasons not to have them.

Which bery ? https://youtu.be/EF4m4h15qEA?t=27

To repeat from our last thread about this: I would be a lot more
persuaded of the power of html rendering if datatracker
would allow me to select amongst different CSS to render draft/rfc
content on datatracker for me (being logged into my account).

Cheers
    Toerless

-- 
---
[email-masked]

---

From: Toerless Eckert <[email-masked]>
Date: Tue, 29 Jun 2021 23:45:41 +0200

On Wed, Jun 30, 2021 at 09:34:52AM +1200, Brian E Carpenter wrote:
> Well, see the two attached files. The first one is png produced by gnuplot. The second one is SVG produced by gnuplot, and then run through my SVG color fixer followed by the IETF's SVG checker.

Thanks for the effort, but:

I don't know how to use he tool-chains to use SVG (outside of drafts or for drafts)
Is there an easy to rmember URL where to find such instructions to start using SVG ?

> Since gnuplot is the de facto standard for producing plots in academic articles, I think we are fine.

Ok, thats great, but that still leaves all those hand-drawn diagrams of architecures,
designs, topologies, concepts or the like, whee i for example have accustomed to
use powerpoint and am most productive with. Is there a tool-chain to convert such
powerpoint output to SVG ?

Cheers
    toerless

-- 
---
[email-masked]

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 29 Jun 2021 23:49:36 +0200

> On 29. Jun 2021, at 23:45, Toerless Eckert <[email-masked]> wrote:
> 

Maybe running gnuplot in an SVG rendering mode could be supported by kramdown-rfc.
Brian:  Do you have the commands handy that produced your example?

Grüße, Carsten

---

From: John Scudder <[email-masked]>
Date: Tue, 29 Jun 2021 21:57:08 +0000

On Jun 29, 2021, at 5:46 PM, Toerless Eckert <[email-masked]> wrote:

Is there a tool-chain to convert such
powerpoint output to SVG ?

Friends don’t encourage friends to use PowerPoint, but there are allegedly such tools, including (again allegedly) natively to PowerPoint. No bets as to whether the output is compliant with the much-maligned SVG profile we use, though.

https://lmgtfy.app/?q=export+svg+from+ppt

—John

---

From: Eric Rescorla <[email-masked]>
Date: Tue, 29 Jun 2021 15:00:00 -0700

Carsten,

You might or might not be able to beat on Rmarkdown [0] to get full R
support in kramdown, including svg output.

-Ekr

[0] https://rmarkdown.rstudio.com/

---

From: Brian E Carpenter <[email-masked]>
Date: Wed, 30 Jun 2021 10:36:09 +1200

> Is there an easy to rmember URL where to find such instructions to start using SVG ?

I suspect not. Maybe we need to crowd-source that somehow.
 
> powerpoint output to SVG ?

I tried quite hard to convert diagrams that work with LibreOffice to SVG, 
using LibreOffice's export mechanism. The results were hopeless, mainly due to LibreOffice
producing enormous complexity (including built-in scripts, a complete no-no for
our Tiny SVG dialect) for very simple diagrams. I have no access to Microsoft Office, so I don't know if that is any better. Use a simple tool like dia and things work out better.

You can convert a sketch from (say) PNG to SVG at https://convertio.co/png-svg/ but the results are mediocre. As John pointed out, the V means Vector, so going through a bitmap format will never be satisfactory.

  Brian
 
>>>>>> This v2->v3 conversion process feels a bit like attempting to have 
a 
>> good idea but then

---

From: Brian E Carpenter <[email-masked]>
Date: Wed, 30 Jun 2021 11:04:47 +1200

Sent off-list.

Regards
   Brian Carpenter

On 30-Jun-21 09:49, Carsten Bormann wrote:
> 
>> On 29. Jun 2021, at 23:45, Toerless Eckert <[email-masked] <mailto:[email-masked]>> wrote:
>>

---

From: Toerless Eckert <[email-masked]>
Date: Wed, 30 Jun 2021 01:46:47 +0200

Thanks, but not on my powerpoint (some old version on Mac).
Certainly stockholm syndrom with me and powerpoint, but
all my experience has also been that all this vector stuff never
works. Even when i ask powerpoint to export as image, it doesn't
get exactly rendered as what i see on screen. For the last
research papers, i simply took screenshot of what i saw.

IMHO there is too much fundamentalism in our tooling groups
(or whoever makes policies for them). 

Cheers
    Toerless

-- 
---
[email-masked]

---

From: Julian Reschke <[email-masked]>
Date: Wed, 30 Jun 2021 07:37:07 +0200

> https://trac.ietf.org/trac/xml2rfc/ticket/650

Please see the xml2rfc --help:

V2-V3 Converter Options:
   --add-xinclude        replace reference elements with RFC and
Internet-Draft
                         seriesInfo with the appropriate XInclude element
   --draft-revisions, --draft-revs
                         Reference explicit draft revisions when inserting
                         XIncludes for draft references
   --strict              be strict about stripping some deprecated
attributes

> a standard tools-team supported text-edit format like kramdown.

"...because if needs to be better for machine processing..." - who said
that?

There are places where there are currently discussions to remove
authoring features in favor of easier processing, and it would be nice
if I wasn't the only one arguing for being author-friendly (in this
case: content model for lists).

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 30 Jun 2021 07:38:52 +0200

On 30. Jun 2021, at 07:37, Julian Reschke <[email-masked]> wrote:
> content model for lists

Got a reference?

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Wed, 30 Jun 2021 07:46:54 +0200

> On 30. Jun 2021, at 07:37, Julian Reschke <[email-masked]> wrote:

It's about making <t> inside <li> mandatory, even for single paragraph
list items; should be mentioned either in
<https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis> or in the "RFC
XML and Style Guide Change Management Team" meeting notes (will try to
find it later).

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Wed, 30 Jun 2021 14:54:03 +0200

> XML and Style Guide Change Management Team" meeting notes (will try to

Found it:
<https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/46>,
<https://trac.ietf.org/trac/xml2rfc/ticket/633>, and
<https://www.ietf.org/archive/id/draft-levkowetz-xml2rfc-v3-implementation-notes-12.html#name-mixed-content-model>.

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 30 Jun 2021 14:59:54 +0200

> <https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/46>,

Closed (WONTFIX, but not explicitly labeled as such)

> <https://trac.ietf.org/trac/xml2rfc/ticket/633>, and

I see nothing wrong with the preptool using only a subset of the syntax.
(I also don’t know why it would help, though, and why it wouldn’t be done for other instances of mixed content.)

> <https://www.ietf.org/archive/id/draft-levkowetz-xml2rfc-v3-implementation-notes-12.html#name-mixed-content-model>.

“Resolution: Rejected.¶”

I thought we were in all-clear state about the risk of this becoming part of v3.

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Wed, 30 Jun 2021 15:02:56 +0200

> (I also don’t know why it would help, though, and why it wouldn’t be done for other instances of mixed content.)

What scared me was "This would make it easier for them to make drafts
consistent when not created by software that already does that". So
consistency was considered more important than less markup.

> I thought we were in all-clear state about the risk of this becoming part of v3.

Yep, hopefully.

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 30 Jun 2021 15:30:49 +0200

> consistency was considered more important than less markup.

For those who haven’t fallen asleep yet:

The underlying problem is that SGML created a “mixed content” approach that works well when (both!) tags can be optional; the parser simply fills in the <t>/</t> and the processor only seems the normalized form.
SGML’s optional tags allowed truly acrobatic forms of schema evolution when the DTD changed for an unchanged instance.
XML has inherited “mixed content”, but not the optional tags.
(This is still visible in the <tbody> issue that xhtml has and that v3 normalized at the expense of more noise.)

So I think that wanting to normalize mixed content at the semantic level is a well-recognized tendency with grammars that started out in SGML-land (which is true for anything derived from HTML).  The prep-tool provides a weird form of PSVI where one can indulge in that vice.  We must resist...

Grüße, Carsten