Subject: Re: Document language editing session in London

From: Ted Lemon <[email-masked]>
Date: Sat, 1 Feb 2014 16:25:29 -0500

If your daughter is interested in trying again, it might be worthwhile for her to document the process, ask for help when stuck, and document what she did to get unstuck and what advice she got.   The XML editor issue is a big pet peeve of mine too—the physical process of reviewing IETF documents is _way_ too hard.   Pen and paper would almost be easier than what we currently do.

---

From: "MORTON, ALFRED C (AL)" <[email-masked]>
Date: Sat, 1 Feb 2014 17:13:52 -0500

Hi Ted,

As the recipient of two of Ann's reviews, I can say that I was very glad to 
see grammatical and punctuation suggestions, and I'd much rather get these
in an edited version of the xml,  not on paper.  I think I may have 
suggested that Ann deliver her work in "ready-to-edit/pub-request/etc/" form,
because it made a simple process to check and adopt the changes.
Ann used XXE, IIRC, Bill - keep me honest on these details.

regards,
Al
________________________________________
From: WGChairs [[email-masked]] On Behalf Of Ted Lemon [[email-masked]]
Sent: Saturday, February 01, 2014 4:25 PM
To: Bill Cerveny
Cc: [email-masked] Chairs; Heather Flanagan (RFC Series Editor)
Subject: Re: Document language editing session in London

---

From: Bill Cerveny <[email-masked]>
Date: Sat, 1 Feb 2014 18:41:58 -0500

HI Al and Ted,

I've pinged Ann for more feedback and comments.  Ann certainly asked me a lot of questions when she began reviewing documents.

Before being an IETF document author and WG chair, I had never used an XML editor. I can (OK, "maybe" I can) see the value of writing the documents in XML, but working with XMLMind's XML Editor was a bit of a new adventure for me.  There are a couple of bugs in the MacOS X implementation of the xmlrfc XXE plugin that were a little annoying, but the plugin was very useful in general.

Al, you're right about the XML editor; Ann used the last no-cost personal version of XMLMind Editor (XXE) and made her suggested changes using XXE.  Ann had less trouble getting accustomed to XXE than I did; I feared she would have trouble installing XXE on her older MacBook, but she was able to install and use it without problem.

When Ann had completed the changes in XXE, I created a 'document "compare" report' using an application called "DeltaWalker", which is a pretty nifty document comparison utility. The report looked a little like an HTML  graphical "diff" report. So, in addition to the edited XML document with suggested changes, Ann also provided the authors with a HTMLized report showing the changes in the XML document.

Regards,

Bill

---

From: "Black, David" <[email-masked]>
Date: Sat, 8 Feb 2014 10:32:54 -0500

Big +1 on XXE and especially the xml2rfc plugin.

That combination made it possible for me to shift from Word to XML for authoring drafts.  The fact that I don't have to understand xml2rfc's schema in order to write drafts is a major feature (i.e., not a bug).  It's a shame that there's no longer a free version for use in IETF work, as I'm also on the last free version that was available.

Is there some way that the ISOC could work with the outfit that produces XXE to make a free (or cheap) version available that is restricted to using the xml2rfc plugin?  That could make a massive difference to the pain and suffering that is coming (from authors who will have to abandon familiar tools) when XML becomes the required format for drafts.

Thanks,
--David

________________________________
From: WGChairs [[email-masked]] On Behalf Of Bill Cerveny [[email-masked]]
Sent: Saturday, February 01, 2014 6:41 PM
To: Al Morton; Ted Lemon
Cc: [email-masked] Chairs; Heather Flanagan (RFC Series Editor)
Subject: Re: Document language editing session in London

HI Al and Ted,

Regards,

Bill

---

From: Mark Nottingham <[email-masked]>
Date: Sun, 9 Feb 2014 13:42:58 +1100

FWIW - I went a different way. 

These days, I write *all* of my drafts in Markdown, using <https://github.com/cabo/kramdown-rfc2629> plus a Makefile to glue it together.

E.g., see <https://raw.github.com/mnot/I-D/master/httpbis-alt-svc/draft.md>.

As an author, it’s a huge breath of fresh air; my biggest worry is that this toolchain makes it *too* easy to write an I-D (only half joking here).

All that the tool needs IMO is some better documentation about what markdown produces what outcomes.

YMMV, of course.

Cheers,

--
Mark Nottingham   http://www.mnot.net/

---

From: Leif Johansson <[email-masked]>
Date: Sun, 09 Feb 2014 11:17:27 +0100

> All that the tool needs IMO is some better documentation about what markdown produces what outcomes.
Yeah me too, and just to nerd all the way out, I once used
github-pages+travis-ci to do a publish-on-push :-)

---

From: Carsten Bormann <[email-masked]>
Date: Sun, 9 Feb 2014 14:53:10 +0100

>> All that the tool needs IMO is some better documentation about what markdown produces what outcomes.

I’m hearing you all!
I have this half-baked I-D about this that I need to finish.
Unfortunately, I have quite a few more half-baked I-Ds that I need to finish before London cutoff...

BTW, just updated kramdown-rfc2629 to facilitate using the other bibxml bibliographies at xml.resource.org.
(Unfortunately, the 3GPP ones need some serious hacking, because “3GPP.51.021” is not a valid ID in XML.  
Oh well.  Automated that all away.  Except for a little piece of noise:
   [_3GPP.51.021]
              3GPP, "Base Station System (BSS) equipment specification;
              Radio aspects", 3GPP TS 51.021 10.7.0, December 2012.
)
So, time for another “gem update” if that is useful for you.

> github-pages+travis-ci to do a publish-on-push :-)

Tell us more about that.
(I really just want to add a commit comment “[I-D publish]” to my markdown commit and be done with all that rigamarole...)

Grüße, Carsten

---

From: Donald Eastlake <[email-masked]>
Date: Sun, 9 Feb 2014 10:40:31 -0500

I dunno. I don't spend any time on or have any trouble with tool chains...

Of course, I've always written my drafts in generic nroff and continue
to do so. Works for me and on any UNIX derived system I've run into
including modern MacOS.

Thanks,
Donald
=============================
 Donald E. Eastlake 3rd   +1-508-333-2270 (cell)
 155 Beaver Street, Milford, MA 01757 USA
 [email-masked]

On Sun, Feb 9, 2014 at 8:53 AM, Carsten Bormann <[email-masked]> wrote:
> I'm hearing you all!
> (Unfortunately, the 3GPP ones need some serious hacking, because "3GPP.51.021" is not a valid ID in XML.
> So, time for another "gem update" if that is useful for you.
>
> (I really just want to add a commit comment "[I-D publish]" to my markdown commit and be done with all that rigamarole...)
>
> Grüße, Carsten
>

---

From: Leif Johansson <[email-masked]>
Date: Mon, 10 Feb 2014 14:27:11 +0100

> (I really just want to add a commit comment “[I-D publish]” to my markdown commit and be done with all that rigamarole...)
https://github.com/leifj/draft-johansson-fticks is one such example -
there are docs for travis telling you how to manage deploy-keys for
github pages

        Cheers Leif

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Mon, 10 Feb 2014 09:46:16 -0800

On 1/21/14 7:53 AM, Thomas Narten wrote:
> My larger point about all this is:
> 
> 1) Per my first message, the ADs shouldn't be sitting down with
> authors to teach them how to write. It doesn't scale and I have a hard
> time seeing it address the real problem in a meaningful way. If that
> were part of a larger plan, maybe it would make sense, but I don't
> recall discussion of a larger plan.
> 
> 2) The problem of poor writing is big and hard. If we were seriously
> interested in fixing it, my usual recommendation is to create a design
> team of sorts (formal or informal) that looks at the bigger picture
> and thinks through it in more detail - and then has the output of the
> group reviewed by others. I.e, having a clear problem statement, clear
> goals, and an execution strategy, etc. And an important thing here is
> to have a real plan that folk think might actually help the overall
> problem. Otherwise, the community ends up making poor use of our
> (limited) cycles.
<snip>

One of the ideas I've been toying with is setting up an official, RFC
Editor supported writing lab for the IETF.  Depending on how such a lab
is done, it could consume quite a bit of resources, which is why I've
left it somewhat on the backburner for now.  But perhaps an informal
design team to help me brainstorm a bit further on this would be a good
next step, one that could help me figure out exactly what resources
would be required and a roadmap on how to get there from here (if we
decide "there" is a place we want to go.)

If anyone is interested in discussing this further with me, drop me a
note offline.  For right now, this is just to determine the level of
interest in chasing down this idea.

Thanks,
Heather Flanagan, RSE

---

From: "George, Wes" <[email-masked]>
Date: Wed, 12 Feb 2014 15:01:57 -0500

I recently discovered that XMLMind (XXE) maintains an archive of old versions of the program from before they went to the model where there was no personal use version.
Here’s a link to the right version for multiple OSes.
http://www.xmlmind.com/archive/xmleditor/5.3.0/

That enabled me to continue using it despite moving to a new computer that no longer had the older version. Hopefully it helps some other folks too.

Thanks,

Wes

From: <Black>, David <[email-masked]<mailto:[email-masked]>>
Date: Saturday, February 8, 2014 at 10:32 AM
To: Bill Cerveny <[email-masked]<mailto:[email-masked]>>, Al Morton <[email-masked]<mailto:[email-masked]>>, Ted Lemon <[email-masked]<mailto:[email-masked]>>
Cc: "[email-masked]<mailto:[email-masked]> Chairs" <[email-masked]<mailto:[email-masked]>>, "Heather Flanagan (RFC Series Editor)" <[email-masked]<mailto:[email-masked]>>
Subject: XXE and xml2rfc

Thanks,
--David

________________________________
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.