Subject: [Tools-discuss] WYSIWYG XML editor that supports xml2rfc v3?

From: Bob Briscoe <[email-masked]>
Date: Mon, 4 Oct 2021 16:17:09 +0100

Hi,

Can anyone recommend an XML editor that supports xml2rfc v3 and is 
(roughly) WYSIWYG?

I've just tried (2nd attempt) to switch to v3 xml2rfc. In the 1st 
attempt, a bug held me back. Now the bug is fixed (thank you to those 
who helped), but I might still have to stick at v2 xml2rfc because for 
me the benefits of v3 xml2rfc are not worth a regression to editing XML 
in a plain text editor. I find I can write much clearer documents with a 
WYSIWIG editor.

When I convert one of my drafts from v2 to v3 and load it into XMLMind 
with Bill Fenner's excellent xml2rfc plugin{1} it throws up 219 
warnings, and the content is now WYSIPMU (What you see is pretty much 
unreadable), because all the x-refs and sections headings are littered 
with pulldown menus and warning text.

Alternatively, @Jay, did you publish the results of your survey of draft 
editing tools that you were talking about at the end of 2020 on this 
list? That would give me an idea of how others edit their XML.

(BTW, I don't particularly want to switch to editing markdown right now, 
given I have a large number of drafts in the late stage of their lives, 
so the pain of fixing all the little niggles translating .xml to .md and 
back again is likely to be high.)

Cheers

Bob

{1} Maintained most recently by Warren Kumari, for which many thanks.

PS. I have the latest version of the xml2rfc plugin (0.8.5) for XMLMind 
which is supported by XMLMind v9+ (I am using v9.3).

-- 

-- 
________________________________________________________________
Bob Briscoe                               http://bobbriscoe.net/

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 4 Oct 2021 17:26:13 +0200

On 2021-10-04, at 17:17, Bob Briscoe <[email-masked]> wrote:
> v3 xml2rfc

The RNC used to be at

http://svn.tools.ietf.org/svn/tools/xml2rfc/trunk/cli/xml2rfc/data/v3.rnc

You’ll have to make sure your tool is up to date with that (trivial with emacs nxml-mode…).

Grüße, Carsten

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 4 Oct 2021 17:35:22 +0200

> http://svn.tools.ietf.org/svn/tools/xml2rfc/trunk/cli/xml2rfc/data/v3.rnc

… and now at:

https://svn.ietf.org/svn/tools/xml2rfc/trunk/cli/xml2rfc/data/v3.rnc

Grüße, Carsten

---

From: Bob Briscoe <[email-masked]>
Date: Mon, 4 Oct 2021 17:57:27 +0100

Carsten,

I had never heard of an RNC before this email, and now I've looked it 
up, I get what is does, but I still I don't know what I do with one.

I've found this: 
https://www.xmlmind.com/xmleditor/_distrib/doc/rngsupport/rngsupport.pdf
But I only understand about half the words.

Bob

---

From: Jay Daley <[email-masked]>
Date: Tue, 5 Oct 2021 07:28:11 +1300

Hi Bob

> On 5/10/2021, at 5:57 AM, Bob Briscoe <[email-masked]> wrote:
> 
> Carsten,
> 
> I had never heard of an RNC before this email, and now I've looked it up, I get what is does, but I still I don't know what I do with one.

Most XML editors, including Emacs in nXML mode, OxygenXML, XMLMind and XMLSpy support auto-completion and other schema aware editing functions if your document specifies an RNC grammar.  The full list of editors is those with a Yes under "Autocomplete using schema" in https://en.wikipedia.org/wiki/Comparison_of_XML_editors  That table also lists all that have WYSIWYG support.

> 
> I've found this: https://www.xmlmind.com/xmleditor/_distrib/doc/rngsupport/rngsupport.pdf

To enable the RNC you should replace the line:

	<!DOCTYPE rfc SYSTEM "rfc2629.dtd">

with these lines:

	<!DOCTYPE rfc SYSTEM "rfc2629-xhtml.ent">
	<?xml-model href="rfc7991bis.rnc"?>

and put the two attached files into the same directory as your source file.  

(For info, rfc7991bis.rnc is the latest version from https://github.com/rfc-format/v3grammar renamed)

Jay

> ___________________________________________________________
> 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

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

---

From: Jay Daley <[email-masked]>
Date: Tue, 5 Oct 2021 09:30:08 +1300

> On 5/10/2021, at 4:17 AM, Bob Briscoe <[email-masked]> wrote:
> 
> Hi,
> 
> Can anyone recommend an XML editor that supports xml2rfc v3 and is (roughly) WYSIWYG?
> 
> I've just tried (2nd attempt) to switch to v3 xml2rfc. In the 1st attempt, a bug held me back. Now the bug is fixed (thank you to those who helped), but I might still have to stick at v2 xml2rfc because for me the benefits of v3 xml2rfc are not worth a regression to editing XML in a plain text editor. I find I can write much clearer documents with a WYSIWIG editor.
> 
> When I convert one of my drafts from v2 to v3 and load it into XMLMind with Bill Fenner's excellent xml2rfc plugin{1} it throws up 219 warnings, and the content is now WYSIPMU (What you see is pretty much unreadable), because all the x-refs and sections headings are littered with pulldown menus and warning text.
> 
> Alternatively, @Jay, did you publish the results of your survey of draft editing tools that you were talking about at the end of 2020 on this list? That would give me an idea of how others edit their XML.

Here it is:

https://www.ietf.org/blog/results-and-analysis-of-the-survey-of-i-d-authors-on-formats-and-tools/

Jay

> 
> (BTW, I don't particularly want to switch to editing markdown right now, given I have a large number of drafts in the late stage of their lives, so the pain of fixing all the little niggles translating .xml to .md and back again is likely to be high.)
> 
> Cheers
> 
> 
> Bob
> 
> PS. I have the latest version of the xml2rfc plugin (0.8.5) for XMLMind which is supported by XMLMind v9+ (I am using v9.3).
> 
> -- 
> 
> -- 

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

---

From: Bob Briscoe <[email-masked]>
Date: Mon, 4 Oct 2021 22:46:40 +0100

Jay, [re-sending with links not attachments, to avoid auto-redirect to 
list moderation]

Thanks for the help (and thanks, Carsten as well).
I've put those two files in my working dir.
And I added this one as well:
https://www.rfc-editor.org/materials/format/SVG-1.2-RFC.rnc
because an include line required it, and XMLMind wouldn't load the doc 
without it.

However, XMLMind needs to know how to render each type of element - it's 
meaning, not just its syntax validity.
XMLMind might be able to do auto-completion now (which it wouldn't need, 
'cos the point of using XMLMind is that you don't have to write any XML).
But the XMLMind xml2rfc plugin still doesn't know:

  * how to render the 'name' in a section heading as it used to render a
    'title'
  * how to render a <ul> like it used to render a <list>
  * how to render a <table> (at least) as if it was a <texttable>
  * and it doesn't understand what <xi:include> means, so it can't
    access any of the references.
  * and so on...

Here are two images of XMLMind editing my test document before and after 
v3 conversion (whether with the files you provided or without makes no 
difference to the latter, except to the syntax checking window):
https://bobbriscoe.net/tmp/XMMLMind-xml2rfc-v2.resized.png
https://bobbriscoe.net/tmp/XMMLMind-xml2rfc-v3.resized.png

I found the results of your survey of I-D authoring tools 
<https://ietf.co1.qualtrics.com/results/public/aWV0Zi1VUl8zT3laRG9JQWxidUkxZ0otNWZhOGIyYjc1NzI0NjQwMDBmMWNiYzM2#/pages/Page_e5bcd72e-8f86-4ab1-b153-ad9f3f403021>. 
It doesn't look like many people use XMLMind. Unfortunately I didn't 
receive the invitation to take part, although I've used the same email 
for years, and I've submitted over 300 revisions of drafts in the last 
10 years. Here's my profile 
<https://datatracker.ietf.org/person/[email-masked]>.

Bob

On 04/10/2021 19:28, Jay Daley wrote:
> Hi Bob
>
>> On 5/10/2021, at 5:57 AM, Bob Briscoe<[email-masked]>  wrote:
>>
>> Carsten,
>>
> Most XML editors, including Emacs in nXML mode, OxygenXML, XMLMind and XMLSpy support auto-completion and other schema aware editing functions if your document specifies an RNC grammar.  The full list of editors is those with a Yes under "Autocomplete using schema" inhttps://en.wikipedia.org/wiki/Comparison_of_XML_editors   That table also lists all that have WYSIWYG support.
>
>> I've found this:https://www.xmlmind.com/xmleditor/_distrib/doc/rngsupport/rngsupport.pdf
> (For info, rfc7991bis.rnc is the latest version fromhttps://github.com/rfc-format/v3grammar  renamed)
>
> Jay
>
>
>> Bob
>>
>>> On 2021-10-04, at 17:26, Carsten Bormann<[email-masked]>  wrote:
>>>> The RNC used to be at
>>>>
>> Bob Briscoehttp://bobbriscoe.net/
>>
>> Tools-discuss mailing list [email-masked]
>> * 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

-- 
________________________________________________________________
Bob Briscoehttp://bobbriscoe.net/

---

From: Jay Daley <[email-masked]>
Date: Tue, 5 Oct 2021 11:40:19 +1300

> On 5/10/2021, at 10:46 AM, Bob Briscoe <[email-masked]> wrote:
> 
> Jay, [re-sending with links not attachments, to avoid auto-redirect to list moderation]
> 
>     https://www.rfc-editor.org/materials/format/SVG-1.2-RFC.rnc <https://www.rfc-editor.org/materials/format/SVG-1.2-RFC.rnc>
> because an include line required it, and XMLMind wouldn't load the doc without it.
> 
> However, XMLMind needs to know how to render each type of element - it's meaning, not just its syntax validity.
> XMLMind might be able to do auto-completion now (which it wouldn't need, 'cos the point of using XMLMind is that you don't have to write any XML). 
> how to render the 'name' in a section heading as it used to render a 'title'
> how to render a <ul> like it used to render a <list>
> how to render a <table> (at least) as if it was a <texttable>
> and it doesn't understand what <xi:include> means, so it can't access any of the references.
> and so on...
> Here are two images of XMLMind editing my test document before and after v3 conversion (whether with the files you provided or without makes no difference to the latter, except to the syntax checking window):
> https://bobbriscoe.net/tmp/XMMLMind-xml2rfc-v2.resized.png <https://bobbriscoe.net/tmp/XMMLMind-xml2rfc-v2.resized.png>
> https://bobbriscoe.net/tmp/XMMLMind-xml2rfc-v3.resized.png <https://bobbriscoe.net/tmp/XMMLMind-xml2rfc-v3.resized.png>

I’ve not used XMLMind but in general there are two ways that XML gets rendered, one is with CSS directly and the second is with XSLT.  It would be useful to document how XMLMind does it so I’ll take a look.

> 
> I found the results of your survey of I-D authoring tools <https://ietf.co1.qualtrics.com/results/public/aWV0Zi1VUl8zT3laRG9JQWxidUkxZ0otNWZhOGIyYjc1NzI0NjQwMDBmMWNiYzM2#/pages/Page_e5bcd72e-8f86-4ab1-b153-ad9f3f403021>. It doesn't look like many people use XMLMind. Unfortunately I didn't receive the invitation to take part, although I've used the same email for years, and I've submitted over 300 revisions of drafts in the last 10 years. Here's my profile <https://datatracker.ietf.org/person/[email-masked]>. 

I’ve checked and you were on the mailing list used for the survey invitations, so I guess it was filtered as spam.

Jay

>>> On 5/10/2021, at 5:57 AM, Bob Briscoe <[email-masked]> <mailto:[email-masked]> wrote:
>>> 
>>> Carsten,
>>> 
>> Most XML editors, including Emacs in nXML mode, OxygenXML, XMLMind and XMLSpy support auto-completion and other schema aware editing functions if your document specifies an RNC grammar.  The full list of editors is those with a Yes under "Autocomplete using schema" in https://en.wikipedia.org/wiki/Comparison_of_XML_editors <https://en.wikipedia.org/wiki/Comparison_of_XML_editors>  That table also lists all that have WYSIWYG support.
>> 
>>> I've found this: https://www.xmlmind.com/xmleditor/_distrib/doc/rngsupport/rngsupport.pdf <https://www.xmlmind.com/xmleditor/_distrib/doc/rngsupport/rngsupport.pdf>
>> (For info, rfc7991bis.rnc is the latest version from https://github.com/rfc-format/v3grammar <https://github.com/rfc-format/v3grammar> renamed)
>> 
>> Jay
>> 
>> 
>>> Bob
>>> 
>>>> On 2021-10-04, at 17:26, Carsten Bormann <[email-masked]> <mailto:[email-masked]> wrote:
>>>>> The RNC used to be at
>>>>> 
>>>>> http://svn.tools.ietf.org/svn/tools/xml2rfc/trunk/cli/xml2rfc/data/v3.rnc <http://svn.tools.ietf.org/svn/tools/xml2rfc/trunk/cli/xml2rfc/data/v3.rnc>
>>>> … and now at:
>>>> 
>>>> https://svn.ietf.org/svn/tools/xml2rfc/trunk/cli/xml2rfc/data/v3.rnc <https://svn.ietf.org/svn/tools/xml2rfc/trunk/cli/xml2rfc/data/v3.rnc>
>>>> 
>>>> Grüße, Carsten
>>>> 
>>> -- 
>>> Bob Briscoe                               http://bobbriscoe.net/ <http://bobbriscoe.net/>
>>> 
>>> Tools-discuss mailing list - [email-masked] <mailto:[email-masked]>
>>> * Report datatracker and mailarchive bugs to: [email-masked] <mailto:[email-masked]>
>>> * Report tools.ietf.org bugs to: [email-masked] <mailto:[email-masked]>
>>> * Report all other bugs or issues to: [email-masked] <mailto:[email-masked]>
>>> List info (including how to Unsubscribe): https://www.ietf.org/mailman/listinfo/tools-discuss <https://www.ietf.org/mailman/listinfo/tools-discuss>
> 
> -- 
> Bob Briscoe                               http://bobbriscoe.net/ <http://bobbriscoe.net/>
-- 
Jay Daley
IETF Executive Director
[email-masked]

---

From: Bob Briscoe <[email-masked]>
Date: Tue, 5 Oct 2021 00:00:49 +0100

Jay,

Thankyou for going the extra mile.

In case it's relevant, my XML wasn't quite as you described it, so I 
improvised.
Below is the diff after my edits of the XML that had been produced by 
the v2 to v3 conversion, in case I did something wrong.
In addition to adding 3 files:
     rfc7991bis.rnc
     rfc2629-xhtml.ent
     SVG-1.2-RFC.rnc

Bob

/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\
diff --git a/draft-ietf-tsvwg-aqm-dualq-coupled-17.xml 
b/draft-ietf-tsvwg-aqm-dualq-coupled-17.xml
index fa7fa38..084d9c9 100644
--- a/draft-ietf-tsvwg-aqm-dualq-coupled-17.xml
+++ b/draft-ietf-tsvwg-aqm-dualq-coupled-17.xml
@@ -1,10 +1,11 @@
  <?xml version='1.0' encoding='utf-8'?>
-<!DOCTYPE rfc [
+<!DOCTYPE rfc SYSTEM "rfc2629-xhtml.ent" [
    <!ENTITY nbsp    "&#160;">
    <!ENTITY zwsp   "&#8203;">
    <!ENTITY nbhy   "&#8209;">
    <!ENTITY wj     "&#8288;">
  ]>
+<?xml-model href="rfc7991bis.rnc"?>
  <!-- This template is for creating an Internet Draft using xml2rfc,
      which is available here: http://xml.resource.org. -->
  <?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\

On 04/10/2021 23:40, Jay Daley wrote:
>
>
>> On 5/10/2021, at 10:46 AM, Bob Briscoe <[email-masked] 
>> <mailto:[email-masked]>> wrote:
>>
>> However, XMLMind needs to know how to render each type of element - 
>> it's meaning, not just its syntax validity.
>> XMLMind might be able to do auto-completion now (which it wouldn't 
>> need, 'cos the point of using XMLMind is that you don't have to write 
>> any XML).
>>   * how to render the 'name' in a section heading as it used to
>>     render a 'title'
>> Here are two images of XMLMind editing my test document before and 
>> after v3 conversion (whether with the files you provided or without 
>> makes no difference to the latter, except to the syntax checking window):
> I’ve not used XMLMind but in general there are two ways that XML gets 
> rendered, one is with CSS directly and the second is with XSLT.  It 
> would be useful to document how XMLMind does it so I’ll take a look.
>
>>
>> receive the invitation to take part, although I've used the same 
>> email for years, and I've submitted over 300 revisions of drafts in 
>> the last 10 years. Here's my profile 
> I’ve checked and you were on the mailing list used for the survey 
> invitations, so I guess it was filtered as spam.
>
> Jay
>
>>
>>
>>
>> Bob
>>
>>
>>>> * Reporttools.ietf.org  <http://tools.ietf.org>  bugs to:[email-masked]
> [email-masked] <mailto:[email-masked]>
>

---

From: Julian Reschke <[email-masked]>
Date: Tue, 5 Oct 2021 12:24:05 +0200

Am 05.10.2021 um 00:40 schrieb Jay Daley:
>>   * how to render the 'name' in a section heading as it used to render
>>     a 'title'
> ...

I had a quick look at the (archived) source, and it appears to glue
together XSLT, CSS and Java. So this definitively would require work to
get working with V3.

Best regards, Julian

---

From: Bob Briscoe <[email-masked]>
Date: Tue, 5 Oct 2021 16:03:19 +0100

Julian,

> together XSLT, CSS and Java. So this definitively would require work to

[BB] This is the most useful statement I have seen. Aong with the 
apparent lack of comparable WYSIWYG editors, it means I know for sure 
that I have to stick at v2, and forget about v3 xml2rfc for now.

Thank you.

Bob

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

---

From: Bob Briscoe <[email-masked]>
Date: Tue, 5 Oct 2021 16:29:48 +0100

Julian, Jay, all,

So, to close off with an answer to my original question...

> Can anyone recommend an XML editor that supports xml2rfc v3 and is 
One can maintain v2 RFC XML for WYSIKN editing in the XMLMind XML Editor 
(XXE). Then just before posting each revision of a draft, produce v3 RFC 
XML using the v2-v3 converter,
but,  when editing the next revision, go back to your saved v2 RFC XML, 
ad infinitum.

Bob

---

From: Julian Reschke <[email-masked]>
Date: Tue, 5 Oct 2021 17:55:51 +0200

> that I have to stick at v2, and forget about v3 xml2rfc for now.

If you need WYSIWYG.

Or somebody could invest time in upgrading the plugin.

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 5 Oct 2021 17:57:03 +0200

On 2021-10-05, at 17:29, Bob Briscoe <[email-masked]> wrote:
> 
> One can maintain v2 RFC XML for WYSIKN editing in the XMLMind XML Editor (XXE). Then just before posting each revision of a draft, produce v3 RFC XML using the v2-v3 converter,
> but,  when editing the next revision, go back to your saved v2 RFC XML, ad infinitum.

There is no need to convert manually; the submission interface will now do that automatically (and will accept any v3 features embedded in the v2 if you choose to use them despite lack of WYSI).

Grüße, Carsten

---

From: Warren Kumari <[email-masked]>
Date: Tue, 5 Oct 2021 12:21:36 -0400

> Or somebody could invest time in upgrading the plugin.

+1. It lives here: https://github.com/wkumari/xml2rfc-xxe

Most of this was written by Bill Fenner (billo) back in 2006-2009. It has a
pile-o-java, and was written using xcode as the environment/build
system/etc.
Attempting to build the Jar on "modern" xcodes produces the opaque message:
"Jam is deprecated and has been removed; targets that use Jam must be
upgraded to native targets. For more information on doing this, consult the
Xcode documentation."
An (admittedly short) review of the documentation around java built targets
and dependencies made both billo and I despair , and so I've just been
including "the magic jar file" in each new version -- see
https://github.com/wkumari/xml2rfc-xxe/commit/0e8049e74a74655545303ff07fcd48e09c640721

I'm suspecting that the large majority of upgrading the plugin to support
V3 would be dinkering with the build system to kudgel Java into actually
producing a jar. The actual schema bit is likely handled fairly well by the
editor itself.

W

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

---

From: Bob Briscoe <[email-masked]>
Date: Tue, 5 Oct 2021 23:05:53 +0100

Carsten,

> There is no need to convert manually; the submission interface will now do that automatically (and will accept any v3 features embedded in the v2 if you choose to use them despite lack of WYSI).

[BB] Of course, yes. Thanks

Bob

---

From: Bob Briscoe <[email-masked]>
Date: Thu, 7 Oct 2021 13:53:10 +0100

Carsten,

On 05/10/2021 23:05, Bob Briscoe wrote:
>>> One can maintain v2 RFC XML for WYSIKN editing in the XMLMind XML 
>>> Editor (XXE). Then just before posting each revision of a draft, 
>>> produce v3 RFC XML using the v2-v3 converter,
>> There is no need to convert manually; the submission interface will 
>> now do that automatically (and will accept any v3 features embedded 
>> in the v2 if you choose to use them despite lack of WYSI).
>

[BB2] Actually, in practice, no. Using the Dev version of xml2rfc online 
<https://xml2rfc.tools.ietf.org/experimental.html#xml2rfcv2>:
* I just converted my v2 XML manually with the "convert v2 to v3 XML" 
option, then re-input the resulting V3 XML into the same tool but with 
just plaintext output.
    It worked fine - no errors.
* Whereas, when I input the v2 XML to the same tool, but with 
"v3-plaintext" output option, it errors on the first external reference:

  INPUT: Line 1318: Unable to resolve external request: "reference.RFC.2119"

Bob