Subject: [xml2rfc] <discussion> construct

From: Dave CROCKER <[email-masked]>
Date: Thu, 04 Aug 2011 10:01:17 -0700

Howdy,

Pursuing an item raised (once again) on the IETF list:

I suggest the addition of a <discussion> construct, for including a URL or email 
address to pursue discussion of a draft.

To anticipate the alternative already raised on the IETF list:  I-Ds often are 
not associated with a working group.  As a consequence, using the existing 
working group construct is not possible.

Even when it is possible, it's a level of indirection and extra effort that 
seems to me, at best, too IETF cliquish.

d/
-- 

   Dave Crocker
   Brandenburg InternetWorking
   bbiw.net

---

From: Julian Reschke <[email-masked]>
Date: Thu, 04 Aug 2011 19:51:58 +0200

On 2011-08-04 19:01, Dave CROCKER wrote:
> I suggest the addition of a <discussion> construct, for including a URL
> or email address to pursue discussion of a draft.
>
> To anticipate the alternative already raised on the IETF list: I-Ds
> often are not associated with a working group. As a consequence, using
> the existing working group construct is not possible.
>
> Even when it is possible, it's a level of indirection and extra effort
> that seems to me, at best, too IETF cliquish.

+0.5

So, where should it go in the Internet Draft?

Maybe even into the header?

Best regards, Julian

---

From: Ned Freed <[email-masked]>
Date: Thu, 04 Aug 2011 14:46:54 -0700 (PDT)

+1. This really needs to be a separate element so that the processing 
of it can be automated (e.g., it shows up in draft mode, not RFC mode).

				Ned

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

---

From: Dave CROCKER <[email-masked]>
Date: Thu, 04 Aug 2011 15:05:47 -0700

On 8/4/2011 2:46 PM, Ned Freed wrote:
> +1. This really needs to be a separate element so that the processing of it can
> be automated (e.g., it shows up in draft mode, not RFC mode).

I hadn't thought of that.  good point.

As for Julian's question, I worry a bit about adding another line to the first 
page header, but I think the only other standardized place for 'housekeeping' 
information would be the Authors section, I think, and that's not designed for 
anything other than author info.

My own convention has increasingly moved towards a "Considerations" major 
section, with Security and IANA as subsections.  Major sections trigger a new 
page and the Considerations stuff doesn't warrant it, IMO.  In that model, a 
"Discussion" subsection would be pretty comfortable.  But it's not a typical 
template for folks to organize the document that way.

mumble.

d/

-- 

   Dave Crocker

---

From: Paul Hoffman <[email-masked]>
Date: Thu, 4 Aug 2011 16:52:51 -0700

-1 to this as an XML element. It would freeze both the position in the document and probably limit the introductory text. The latter is important for non-WG documents that the author wants discussed on a WG mailing list.

The idea of having this in drafts is fairly important; it should be encouraged in the IETF. However, that can be done simply by encouraging (or maybe forcing by ADs who are presented with individual submissions).

--Paul Hoffman

---

From: Julian Reschke <[email-masked]>
Date: Fri, 05 Aug 2011 09:02:26 +0200

On 2011-08-05 00:05, Dave CROCKER wrote:
>> of it can
> As for Julian's question, I worry a bit about adding another line to the
> first page header, but I think the only other standardized place for
> 'housekeeping' information would be the Authors section, I think, and
> that's not designed for anything other than author info.
>
> My own convention has increasingly moved towards a "Considerations"
> major section, with Security and IANA as subsections. Major sections
> trigger a new page and the Considerations stuff doesn't warrant it, IMO.
> In that model, a "Discussion" subsection would be pretty comfortable.
> But it's not a typical template for folks to organize the document that
> way.
 > ...

You can simply add a <note> below the <abstract>.

Best regards, Julian

---

From: Paul Hoffman <[email-masked]>
Date: Fri, 5 Aug 2011 07:59:16 -0700

> You can simply add a <note> below the <abstract>.

Or at the end of the Introduction (which seems to be more typical).

--Paul Hoffman

---

From: Julian Reschke <[email-masked]>
Date: Fri, 05 Aug 2011 17:14:28 +0200

On 2011-08-05 16:59, Paul Hoffman wrote:
>> You can simply add a<note>  below the<abstract>.
>
>

If it's more typical then maybe because people do not realize they can 
add a <note>. :-)

---

From: Paul Hoffman <[email-masked]>
Date: Fri, 5 Aug 2011 08:40:48 -0700

On Aug 5, 2011, at 8:14 AM, Julian Reschke wrote:

> If it's more typical then maybe because people do not realize they can add a <note>. :-)

Semantically, it belongs in the introductory material, not the abstract material. Material that is only in the abstract and not in the body of the document is not an abstract.

--Paul Hoffman

---

From: "Murray S. Kucherawy" <[email-masked]>
Date: Fri, 5 Aug 2011 08:43:23 -0700

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On Behalf Of Paul Hoffman
> Sent: Friday, August 05, 2011 8:41 AM
> To: Julian Reschke
> Cc: xml2rfc
> Subject: Re: [xml2rfc] <discussion> construct
> 
> Semantically, it belongs in the introductory material, not the abstract
> material. Material that is only in the abstract and not in the body of
> the document is not an abstract.

I've been including it in an appendix so far, based on the idea that several of those (e.g., changes since last version) will be deleted prior to publication anyway.

---

From: Julian Reschke <[email-masked]>
Date: Fri, 05 Aug 2011 17:50:51 +0200

On 2011-08-05 17:40, Paul Hoffman wrote:
>> If it's more typical then maybe because people do not realize they can add a<note>. :-)
>
>

The <note> creates a subsection *following* the abstract; it's not part 
of it. (I agree that this doesn't belong into the abstract).

Best regards, Julian

---

From: Joe Abley <[email-masked]>
Date: Fri, 5 Aug 2011 11:55:36 -0400

> Semantically, it belongs in the introductory material, not the abstract material. Material that is only in the abstract and not in the body of the document is not an abstract.

I like to include an appendix in drafts which provides some crude revision history, clearly marked at the start "This section (and following sub-sections) should be removed before publication". That's where I include a suggestion for the venue for discussion, if there is clear advice to give.

My thinking is that anybody who wants to comment on the draft seriously is probably going to review the history before they say anything, and so they'll see the note.

I appreciate this is not easily machine-readable, but since we're talking about comments by humans rather than comments by machines this does not seem like a big loss.

Joe

---

From: "John Levine" <[email-masked]>
Date: 5 Aug 2011 16:00:23 -0000

>the document is not an abstract.

Then why not define <discussion> and have xml2rfc and its friends
turn it into a sentence in the introductory part?  We already have
lots of other places where the order of items in the XML is different
from that in the formatted versions.

R's,
John

---

From: Julian Reschke <[email-masked]>
Date: Fri, 05 Aug 2011 18:20:13 +0200

On 2011-08-05 18:00, John Levine wrote:
> Then why not define<discussion>  and have xml2rfc and its friends

We can allow people to put it wherever they want and still mark it up...

---

From: Ned Freed <[email-masked]>
Date: Sat, 06 Aug 2011 17:44:57 -0700 (PDT)

> -1 to this as an XML element. It would freeze both the position in the
> document and probably limit the introductory text. The latter is important for
> non-WG documents that the author wants discussed on a WG mailing list.

Please explain how having an element defined for this would necessarily have
any impact on other document content, because I for one am not seeing
any such limitation.

> The idea of having this in drafts is fairly important; it should be
> encouraged in the IETF. However, that can be done simply by encouraging (or
> maybe forcing by ADs who are presented with individual submissions).

And so is the idea of being able to extract this information mechanically and
use it in, say, I-D announcements. <note> won't work for this unless you intend
to reserve it's use for this function, which sure seems like a bad idea to
me.

It also makes it automatic suppression of the information without actually
removing it from the XML possible when the document goes to RFC. I like
automating such things since relying on people to do it often results
in screwups.

				Ned

---

From: Paul Hoffman <[email-masked]>
Date: Sat, 6 Aug 2011 20:22:00 -0700

On Aug 6, 2011, at 5:44 PM, Ned Freed wrote:

> use it in, say, I-D announcements.

<sound of my brain exploding> How can the information be extracted unless it is in the document content? We still do not require XML for input.

Further, people have disagreed that the information should be part of I-D announcements.

> <note> won't work for this unless you intend

Agree.

> automating such things since relying on people to do it often results

And I like assuming that the RFC Editor staff will find such things and ask the authors whether or not they intended to leave them in the RFC. In some cases, they probably *do* want to leave the mailing list in the RFC.

--Paul Hoffman

---

From: Ned Freed <[email-masked]>
Date: Sat, 06 Aug 2011 20:27:20 -0700 (PDT)

> <sound of my brain exploding> How can the information be extracted unless it
> is in the document content? We still do not require XML for input.

Pretty simple: The information is taken from the element and placed in a
well known location in the output text. We already extract a bunch of
stuff from drafts in this fashion.

Actually, I hope that at some point providing the XML on submission (which is
currently supported) will allow extraction of all of this stuff directly from
the XML, since the current scraping code doesn't always work quite correctly.
(It has difficulty finding the end of the abstract, for one thing.)

> Further, people have disagreed that the information should be part of I-D

Sounds pretty darned silly to me. What's the reasoning?

> And I like assuming that the RFC Editor staff will find such things and ask
> the authors whether or not they intended to leave them in the RFC.

That's a recipe for additional errata.

> In some
> cases, they probably *do* want to leave the mailing list in the RFC.

In which case you put it in the text. Hardly a reason not to do this.

				Ned