Subject: Re: [Tools-discuss] [rfc-i] Direction of the RFC Format Development effort

From: "George, Wes" <[email-masked]>
Date: Tue, 15 Oct 2013 13:50:54 -0400

Last year I asked whether there were alternatives to XMLMind for XML document editing. I realized I wasn't asking the question correctly when I got back answers on good tools to manually edit XML (e.g. Emacs, etc). A recent change in laptop leaves me without a good solution, so I ask again, rephrased.

Is there a FOSS tool (or a commercially-available tool that isn't punitively expensive) to do direct WYSIWYG editing of XML files using IETF's DTD?

Prior to their change in licensing structure in September 2012, XMLMind offered a robust tool for what they call "near WYSIWYG" and when used with a plugin that integrated XML2RFC directly into the tool (xml2rfc-xxe on google code) and Elywn Davies's XML templates, it was nearly one-stop shopping for I-D production for those who weren't keen on hacking XML directly. However, XMLMind no longer offers a free version, and their licensing costs are prohibitive (starting at $350USD/250EUR, or $11K for a site license), and my searches for alternatives haven't netted much in the way of results.

As far as I can tell, the current options are to either manually edit XML, or to use a WYSIWYG editor to generate markdown, or HTML, or NROFF, or to use MS Word to generate text, then translate that to XML, then translate that to canonical text and other formats using XML2RFC. I would think that one of the primary goals of the RFC format transition would be to cut some of the steps out of document production to reduce complexity and make the process more accessible for newer participants. It's unclear from the text below if this need for a WYSIWYG XML editing tool with XML2RFC integration is something that the RFC Editor and/or Tools team is already aware of and working to find a solution to or not.

I'd love for someone to tell me that I'm needlessly complicating this and the solution is right under my nose, but that's not the sense I get from the existing ID prep tools page...

Thanks,

Wes George

> -----Original Message-----
> From: [email-masked] [mailto:rfc-interest-
> [email-masked]] On Behalf Of Heather Flanagan (RFC Series
> Editor)
> Sent: Thursday, May 02, 2013 4:34 PM
>
> The direction we will be exploring is one where the Canonical format -
> the format that is authoritative for content of an RFC - is XML using
> the xml2rfc DTD.  [WEG] [snip]
> * Given the difficulty some authors have expressed in using xml2rfc, is
> it possible to add new elements to allow for additional Publication
> format while still having a commonly usable tool?
>

Anything below this line has been added by my company's mail server, I have no control over it.
-----------------

This E-mail and any of its attachments may contain Time Warner Cable proprietary information, which is privileged, confidential, or subject to copyright belonging to Time Warner Cable. This E-mail is intended solely for the use of the individual or entity to which it is addressed. If you are not the intended recipient of this E-mail, you are hereby notified that any dissemination, distribution, copying, or action taken in relation to the contents of and attachments to this E-mail is strictly prohibited and may be unlawful. If you have received this E-mail in error, please notify the sender immediately and permanently delete the original and any copy of this E-mail and any printout.

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 15 Oct 2013 20:34:17 +0200

On Oct 15, 2013, at 19:50, "George, Wes" <[email-masked]> wrote:

> need for a WYSIWYG XML editing tool

Who "needs" that?

I sure understand that it's not easy to like editing XML directly.

But I'm not sure what "WYSIWYG" means here -- do you mean looking at paged line printer ASCII (.txt) format or looking at XSLT-formatted XML/HTML?

> needlessly complicating this 

Yes.

There is a clear industry trend towards markdown-based publishing chains (draftin.com, leanpub.com, ...; simple tools such as IA writer, Byword, Writedown, Mou; more powerful tool chains such as Scrivener...).

The tools we have today for building RFCs from markdown (Miek Gieben's pandoc solution or kramdown-rfc2629) aren't perfect yet but are doing their job.  Both are using RFC2629 XML as a lingua france to interoperate with the other tools, so there is no need to destabilize the entire RFC editor tools set while we improve them.

Editing markdown is rather close to "WYSIWYG editing" of an ASCII RFC.

Grüße, Carsten

---

From: Nico Williams <[email-masked]>
Date: Tue, 15 Oct 2013 14:39:03 -0500

>> need for a WYSIWYG XML editing tool

I don't, but I got bored of editing XML by hand (even with VIM).

So I wrote a tool that allows one to write I-Ds with LyX (a WYSIWYM
tool), lyx2rfc (http://lyx2rfc.org/lyx2rfc/lyx2rfc.html).  Yaron
Scheffer webified it.

There's other similar tools, from ones that use markdown to to ones
based on nroff (e.g., http://aaa-sec.com/nroffedit/).

See the list archives.

> I sure understand that it's not easy to like editing XML directly.

No, it's not easy to *like* editing XML directly.

> But I'm not sure what "WYSIWYG" means here -- do you mean looking at paged line printer ASCII (.txt) format or looking at XSLT-formatted XML/HTML?

Just look at NroffEdit or lyx2rfc screenshots and you'll get an idea
of what Wes probably has in mind.

> There is a clear industry trend towards markdown-based publishing chains (draftin.com, leanpub.com, ...; simple tools such as IA writer, Byword, Writedown, Mou; more powerful tool chains such as Sc…

I don't care that much for markdown.  I don't care that much for
editing source.  I do care for vi keybindings though, and that's a bit
of a problem that leaves one with few options but markdown.  But
that's another story.

> Editing markdown is rather close to "WYSIWYG editing" of an ASCII RFC.

I don't think so.  There's a lot of things that are not trivial in
markdown.  From description lists to artwork to tables, and so on.
The simple things, on the other hand, really are simple in markdown.

Nico
--

---

From: "George, Wes" <[email-masked]>
Date: Tue, 15 Oct 2013 15:44:48 -0400

> From: Carsten Bormann [mailto:[email-masked]]
> Sent: Tuesday, October 15, 2013 2:34 PM
>
[WEG] Well, after having used one for 2+ years (essentially the entire time I've been writing I-Ds), and knowing how it streamlines the workflow of building I-Ds, I do. The fact that an XML2RFC plugin existed for it (maintained by Bill Fenner and Warren Kumari IIRC) tells me that I'm not the only one who was using XMLMind. I understand that plenty of people are not going to see the need for anything other than a text editor plus some CLI tools to turn out I-Ds. I'm not one of those folks, and I think user-friendliness should be a goal here.
>
> But I'm not sure what "WYSIWYG" means here -- do you mean looking at
> paged line printer ASCII (.txt) format or looking at XSLT-formatted
> XML/HTML?
[WEG] I think it's the latter. XMLMind's UI looks somewhat similar to a word processing interface, with buttons to {add, promote, demote} sections, insert [un]numbered lists, tables, figures, and a pulldown to handle IPR declarations, document type, etc. It has the ability to simply click in a given section and type, as well as the ability to copy/paste objects (sections, references, figures, etc) in addition to copy/paste of raw text, plus spell check and direct validation of the 2629 XML DTD, and both txt and html output using XML2RFC. It doesn't replicate the format of a TXT I-D in the editing mode, but it does wrangle the XML tags for all except a few tweaks here and there.
I can supply screenshots if they'd be useful to the discussion.

>
> There is a clear industry trend towards markdown-based publishing chains...
[WEG] Yet Heather's recommendation in no way mentions markdown. So I think my point stands - there's multiple intermediate steps between the raw text and something that the RFC editor process can accept (XML), and replicating the functionality of something like XMLmind would be a useful way to allow people to interact directly with XML files without the intermediate steps.
> Editing markdown is rather close to "WYSIWYG editing" of an ASCII RFC.
[WEG] Note that I never mentioned editing ASCII RFCs. There is so little formatting that happens in an ASCII version of an RFC that is user-influenced that I'd rather not have to worry about the ASCII RFC formatting rules. However, as we start talking about the differences between the canonical version of an I-D and other versions (HTML, etc) that can support more robust formatting, there is going to be a need for a tool to help do things a little more WYSIWYG.
While editing Markdown is arguably easier than editing XML, I don't see much point in learning a secondary set of tags and how to use another tool to convert back and forth between XML and Markdown vs simply editing XML directly if those are my only options. Perhaps if we were to select one or more FOSS markdown WYSIWYG editors and build a useful plugin to integrate macros to generate the formatting and references unique to I-Ds and the pandoc or kramdown translation functions so that what comes out the other side is XML (and one can open an XML source doc and the tool can convert to markdown in order to edit it), that might be a workable alternative.

Wes George

---

From: Dave Crocker <[email-masked]>
Date: Wed, 16 Oct 2013 08:46:13 +1300

>> need for a WYSIWYG XML editing tool

It probably won't qualify as good enough, but Oxygen's Author tool has 
an author mode that does a rough wysywig display, if it's given a css 
file.

At this point, I've lost track of what xml2rfc files are part of 
xml.resource.org and what files came from Julian Reschke, but in any 
event the necessary support files are readily available.

d/

-- 
Dave Crocker
Brandenburg InternetWorking
bbiw.net

---

From: Dave Crocker <[email-masked]>
Date: Wed, 16 Oct 2013 08:47:51 +1300

It probably won't qualify as good enough, but Oxygen's Author tool has 
an author mode that does a rough wysywig display, if it's given a css file.

d/

---

From: "George, Wes" <[email-masked]>
Date: Tue, 15 Oct 2013 15:56:02 -0400

> From: Dave Crocker [mailto:[email-masked]]
>

[WEG] Dunno. I looked at Oxygen, but abandoned it quickly after discovering that it suffers from the same problem as XMLMind -- sticker shock.

Thanks
Wes George

---

From: Julian Reschke <[email-masked]>
Date: Tue, 15 Oct 2013 22:42:16 +0200

On 2013-10-15 22:30, Phillip Hallam-Baker wrote:
> ...
> It would be useful if the xml2rfc tool generated HTML in a way that was
> not 'lossy'. If the tool generates <H1> headings rather than <p> tags
> with style sheet links it is much easier to recover structure.
> ...

It does. Or am I missing something?

---

From: Dave Crocker <[email-masked]>
Date: Wed, 16 Oct 2013 09:52:00 +1300

On 10/16/2013 9:42 AM, Julian Reschke wrote:
>> ... It would be useful if the xml2rfc tool generated HTML in a way
>> that was not 'lossy'. If the tool generates <H1> headings rather
>> than <p> tags with style sheet links it is much easier to recover
>> structure. ...
>

 From an xml2rfc draft I'm editing, here's the html produced through the 
oXygen processor:

> <h2 id="rfc.section.1.2"><a
> href="#rfc.section.1.2">1.2</a>&nbsp;Working Group Authority and
> Consensus</h2>
>
> <p id="rfc.section.1.2.p.1">A core premise of IETF working groups is
> that the working group has final authority over the content of its
> documents, within the constraints of the working group charter. No
> individual has special

Note that the header is second-level.  Doc also contains h1, of course.

d/

---

From: Warren Kumari <[email-masked]>
Date: Wed, 16 Oct 2013 09:19:08 +0300

> [WEG] Well, after having used one for 2+ years (essentially the entire time I've been writing I-Ds), and knowing how it streamlines the workflow of building I-Ds, I do. The fact that an XML2RFC plu…

Yeah. 
It was sad when they removed the free version, but editing XML in Emacs made me sufficiently unhappy that I ponied up the $$$ and bought a copy :-(

W

> Tools-discuss mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/tools-discuss
> 
> Please reports datatracker.ietf.org bugs at http://tools.ietf.org/tools/ietfdb
> Please reports tools.ietf.org bugs at http://tools.ietf.org/tools/issues or
> send email to [email-masked]
> 

--
"Working the ICANN process is like being nibbled to death by ducks,
it takes forever, it doesn't make sense, and in the end we're still dead in the water." 
    -- Tom Galvin, VeriSign's vice president for government relations.

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Wed, 16 Oct 2013 08:18:29 -0700

> As far as I can tell, the current options are to either manually edit XML, or to use a WYSIWYG editor to generate markdown, or HTML, or NROFF, or to use MS Word to generate text, then translate tha…
As a point of clarification, the RFC Editor will have to accept text
I-Ds; not everyone is ready/willing/able to handle XML.  Enough people
are conversant with XML that I think going with XML as the canonical
format makes sense, but I have to be open to accepting text as well. 
Limiting the number of inputs is good, but no sense making everyone's
life more difficult by insisting on one input and one input only. 

Regarding an nroffedit-like tool for XML, I agree that would be an
excellent thing.  I don't think one can be created until we have a
better idea if/how the XML DTD is going to change, but someone with more
programming experience than I should speak to that point.

-Heather Flanagan, RSE

---

From: Nico Williams <[email-masked]>
Date: Wed, 16 Oct 2013 10:38:13 -0500

> programming experience than I should speak to that point.

For my tool (lyx2rfc) it's no problem for it to exist now with unknown
future changes to the xml2rfc DTD/Schema: any changes in it will
merely require corresponding changes (or composition with new XSLs) to
the XSLT that lyx2rfc is using internally.

No WYSIWYG/WYSIWYM tool developers should feel held back by the
possibility of changes to the xml2rfc DTD/Schema: as long as it's all
XML it's all just a matter of applying appropriate XSL
transformations.

Nico
--

---

From: Phillip Hallam-Baker <[email-masked]>
Date: Tue, 15 Oct 2013 16:30:50 -0400

I don't need pure WISYWIG but I do need an editing format in which I can
remember the tags without having to constantly go to the web to read the
reference.

Which is why I now use HTML. I wrote a tool that converts from either
XML2RFC or HTML source and outputs either format or traditional plaintext.
The source is up on Sourceforge.

I am currently tweaking the tool as I discover features of things like
Google Drive which will output HTML but cannot generate DL tags. The reason
I would like to be able to use Google Drive is that it then becomes trivial
for two authors to work on the same doc at the same time.

It would be useful if the xml2rfc tool generated HTML in a way that was not
'lossy'. If the tool generates <H1> headings rather than <p> tags with
style sheet links it is much easier to recover structure.