Subject: [Tools-discuss] prototype xml2rfc creation wizard tool

From: Tony Hansen <[email-masked]>
Date: Wed, 30 Mar 2011 07:36:39 -0400

One of the areas people still complain about with respect to writing 
internet drafts is how to get started.

So I've been playing around with a tool to help create the xml2rfc XML 
for a -00 internet draft. It works in wizard fashion, asking you a 
variety of questions and generates the XML on the fly. At the end, you 
can either cut and paste the generated XML or click a download button to 
save it to a file.

Please try it out: http://xml.resource.org/xml2rfc-wizard

All thoughts on it are welcome, even if you think it's a horrible idea. 
If you think it's a good idea, I'd like to hear about improvements to 
the user interface, where did I go wrong, and what else is needed.

Also, any thoughts on where to go from here would be appreciated. Is the 
notion of a set of wizards a good one? What other wizards would be helpful?

I'm thinking that this wizard, and possibly others, would eventually be 
linked to from the xml.resource.org web page.

     Tony Hansen
     [email-masked]

---

From: Scott Brim <[email-masked]>
Date: Wed, 30 Mar 2011 13:52:11 +0200

On Wed, Mar 30, 2011 at 13:36, Tony Hansen <[email-masked]> wrote:
> So I've been playing around with a tool to help create the xml2rfc XML for a
> -00 internet draft. It works in wizard fashion, asking you a variety of
> questions and generates the XML on the fly. At the end, you can either cut
> and paste the generated XML or click a download button to save it to a file.
>
> All thoughts on it are welcome, even if you think it's a horrible idea. If
> you think it's a good idea, I'd like to hear about improvements to the user
> interface, where did I go wrong, and what else is needed.
>

Cool!

I tried it and ran the xml through xml.resource.org and got this.  I
don't recall filling in facsimile.  I might have.

xml2rfc: error: xml2rfc: error: with content model {postal ? phone ?
facsimile ? email ? uri ?} for <address>, seen {postal phone email
uri} so far, now expecting </address>, but not <facsimile> around
input line 40 in "internally-preprocessed XML"

Syntax:
    40:<facsimile>
    29:<address>
    27:<author fullname="Scott Brim" initials="S.W." surname="Brim">
    25:<front>
    24:<rfc obsoletes="RFC2629" category="info"
docName="draft-brim-cats-and-dogs-00" ipr="trust200902">

Source around there is:

  <front>
    <title abbrev="Cats and Dogs">The Truth About Cats and Dogs</title>
    <author fullname="Scott Brim" initials="S.W." surname="Brim">
      <organization>ASPCA</organization>
      <address>
        <postal>
          <street>6 Green Street</street>
          <city>Elmwood</city>
          <region>Ohio</region>
          <code>48292</code>
          <country>USA</country>
        </postal>
        <phone></phone>
        <email>[email-masked]</email>
        <uri></uri>
        <facsimile>Elmwood</facsimile>
      </address>
    </author>
    <date year="2011" />
    <workgroup>ARF</workgroup>
    <abstract>
      <t>
Cats and dogs like each other.      </t>
    </abstract>
  </front>

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 30 Mar 2011 13:55:42 +0200

Good stuff.

Once you have created the XML hieroglyphics, you might want to try a tool like kramdown-rfc2629 to write the actual text.  (Only will help you much if you have experienced plaintext "wiki-style" writing as in markdown etc.)

https://github.com/cabo/kramdown-rfc2629
(Just do:
	gem install kramdown-rfc2629
if your laptop has somewhat recent tools.)

JFYI.

Gruesse, Carsten

---

From: Tony Hansen <[email-masked]>
Date: Wed, 30 Mar 2011 08:22:25 -0400

> don't recall filling in facsimile.  I might have.

Ordering problem -- fixed. Reload to get the fix.

One question: should the <facsimile/> and similar fields be output even 
if they're not filled in?

In other words, is it better to leave them in as an aid for people to 
fill in later when they're working on the XML, or is it better to just 
not list them?

     Tony

---

From: Julian Reschke <[email-masked]>
Date: Wed, 30 Mar 2011 14:48:23 +0200

> if they're not filled in?

Nope.

> fill in later when they're working on the XML, or is it better to just

You could include them, but comment them out.

Best regards, Julian

---

From: Fred Baker <[email-masked]>
Date: Wed, 30 Mar 2011 17:40:36 +0200

On Mar 30, 2011, at 2:22 PM, Tony Hansen wrote:
> One question: should the <facsimile/> and similar fields be output even if they're not filled in?

That's really a question of the DTD; there are some (organization in the author block) that are required even if empty, and some that are required (year in the date specification) but can be inferred by the tool. What you want to do is "do no harm", and make it easy for the consumer of the file to know what options they have that they may not have used. One way to do that is to specify everything even if empty, and as a quick solution it has something to recommend it. After the fact, I'm not sure it's all that important, and I could imagine tools like XMLMind interpreting the DTD and as a result not including them when *they* store them.

I personally don't mind which you do. But if it was me, I would probably specify them all just to make sure that any subtleties were finessed.

---

From: Julian Reschke <[email-masked]>
Date: Wed, 30 Mar 2011 18:02:44 +0200

On 30.03.2011 17:40, Fred Baker wrote:
>> One question: should the<facsimile/>  and similar fields be output even if they're not filled in?
>

<organization> isn't required anymore ((I think we changed that in 1.34).

> I personally don't mind which you do. But if it was me, I would probably specify them all just to make sure that any subtleties were finessed.

Well, absence of an element is different from it being empty. Even íf 
xml2rfc may treat them the same way we shouldn't rely on that.

BR, Julian

---

From: "J.D. Falk" <[email-masked]>
Date: Wed, 30 Mar 2011 17:39:25 -0700

On Mar 30, 2011, at 4:36 AM, Tony Hansen wrote:

> All thoughts on it are welcome, even if you think it's a horrible idea. If you think it's a good idea, I'd like to hear about improvements to the user interface, where did I go wrong, and what else is needed.

I wish I'd had this earlier.

In my test pass just now, it ignored most of the postal fields I filled in: street, region, code, country.  It got city, though.

There are probably other tweaks possible, but this is already enough to greatly reduce my startup time for new drafts.  Thank you.

--
J.D. Falk
the leading purveyor of industry counter-rhetoric solutions

---

From: Tony Hansen <[email-masked]>
Date: Thu, 31 Mar 2011 07:11:56 -0400

Thank you everyone who's tried out the XML2RFC internet draft creation 
wizard. I've folded in most of the comments and I think it's just about 
ready to release to the community.

I'd appreciate any further comments before I do so (probably tomorrow).

One of the comments suggested showing the output of xml2rfc as things 
are being generated. The current form does absolutely nothing remotely 
until the very end when you want to download the file to your browser, 
and I think the overhead of showing the xml2rfc output constantly would 
be onerous. However, it *would* be possible to add in a "preview" button 
on the final page. What do people think of that idea?

     Tony

On 3/30/2011 7:36 AM, Tony Hansen wrote:
> can either cut and paste the generated XML or click a download button 
> to save it to a file.
>
> All thoughts on it are welcome, even if you think it's a horrible 
> idea. If you think it's a good idea, I'd like to hear about 
> improvements to the user interface, where did I go wrong, and what 
> else is needed.
>
> Also, any thoughts on where to go from here would be appreciated. Is 
> the notion of a set of wizards a good one? What other wizards would be 
> helpful?
>
> I'm thinking that this wizard, and possibly others, would eventually 
> be linked to from the xml.resource.org web page.
>
>     Tony Hansen
>     [email-masked]

---

From: "David B Harrington" <[email-masked]>
Date: Thu, 31 Mar 2011 14:01:43 +0200

Hi,

There are xml2rfc templates for MIB documents, with sections and
boilerplate needed for MIB documents.
But authors can take a generic xml2rfc doc and install the appropriate
sections and boilerplate themselves.
I don't know if you want to try to include that in your tool.
The MIB document templates can be found at tools.ietf.org and I'm
available to advise.
There has been some discussion of developing comparable templates for
other data modules as well, such as YANG.

dbh

> -----Original Message-----
> From: [email-masked] 
> [mailto:[email-masked]] On Behalf Of Tony Hansen
> Sent: Thursday, March 31, 2011 1:12 PM
> To: Tools Team Discussion; RFC Interest; XML2RFC Interest 
> Group; RFC Editor; Glenn Kowack
> Subject: Re: [xml2rfc] prototype xml2rfc creation wizard tool
> 

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

---

From: Tony Hansen <[email-masked]>
Date: Thu, 31 Mar 2011 11:41:21 -0400

Would adding a single question along the lines of

     Do you plan on this being a Management Information Base (MIB) 
document? [no|yes]

do? If they say yes, then the sections relevant to MIBs would be added 
to the XML document.

     Tony

---

From: Elwyn Davies <[email-masked]>
Date: Thu, 31 Mar 2011 23:56:12 +0100

Quite useful. Particularly for author and references.

Oned thing I have considered (indeed once started on) were tools to 
produce author fragments and reference fragments which are the most 
tedious bits IMO

Nits

Why does the Phone number entry appear twice in author input?

You could save people a bit of typing by putting draft- or RFC in front 
of the reference fields.

Should keywords be allowed white space or not?

Regards,
Elwyn

Tony Hansen wrote:
> wizard. I've folded in most of the comments and I think it's just 
> about ready to release to the community.
>
> and I think the overhead of showing the xml2rfc output constantly 
> would be onerous. However, it *would* be possible to add in a 
> "preview" button on the final page. What do people think of that idea?
>
> Tony
>
>> So I've been playing around with a tool to help create the xml2rfc 
>> XML for a -00 internet draft. It works in wizard fashion, asking you 
>> a variety of questions and generates the XML on the fly. At the end, 
>> you can either cut and paste the generated XML or click a download 
>> button to save it to a file.
>>
>> the notion of a set of wizards a good one? What other wizards would 
>> be helpful?
>>