Subject: [xml2rfc] Re: getting xml2rfc to output the category
From: [email-masked] (David Meyer)
Date: Sat, 3 Jul 2004 08:10:11 -0700

On Sat, Jul 03, 2004 at 05:14:05AM -0400, John C Klensin wrote:
>> 
>> 
>> --On  Fri, 2 Jul 2004 11:01:30 -0700, David Meyer
>> <[email-masked]>, wrote...
>> 
>> > 	I have specificed the my category in the rfc element, but
>> > 	it's not (apparently) output anywhere. The reason I ask
>> > 	is because I like to put a category header on my drafts
>> > 	so people can see what I intend (I like to have it WG
>> > 	chair as well).
>> > 
>> > 	Anyway to do this?
>> 
>> Dave, without answering your question, I note that,
>> historically, Internet Drafts have been _prohibited_ from
>> containing that information, or "obsoletes or "updates"
>> statements, anywhere in the headers.  This has been out of
>> concern for confusion with RFCs and because it implies a claim
>> that isn't yet valid/approved.

	Oh. Maybe I should take that out of my nroff template
	stuff then. My personal opinon is that this the reason
	you give (as being historical) is pretty silly, as it's a
	draft in the first place. The information is useful (I
	don't know how many times I've asked authors "what
	category").

>> As with many other things related to I-Ds, Secretariat
>> enforcement of that requirement has been sporadic at best and, I
>> believe, on the decline in the last few years.  And I note that
>> 1id-guidelines.txt was changed in the latest version to now
>> prohibit this terminology only in the title, which is, IMO, a
>> useless restriction that does not reflect the original intent.
>> And 1id-guidelines.txt no longer mentions Obsoletes/Updates
>> which, I am fairly sure, were explicitly prohibited historically.
>> 
>> However, if one wants to follow those historical rules, it
>> identifies an issue with xml2rfc and with the current state of
>> documents and boilerplate generally.   For the specific case you
>> are concerned about, the historical solution has been to add
>> some sentences to the "Status of this Memo" section that says,
>> e.g., "If a successor to this document is ultimately approved,
>> it is expected to be a <foo> and to obsolete <bar>."  But, since
>> "Status of this Memo" is, using xml2rfc, entirely
>> automagically-generated boilerplate, there is no way to add that
>> sentence or associated explanatory material (such as the
>> location of mailing lists for discussion) to that section.

	Yep.

>> I note in passing that we are now committing the stylistic
>> obscenity of having two Acknowledgement sections in many
>> documents -- one supplied by authors in a <section> element and
>> another one added as part of the <back> boilerplate about RFC
>> Editor function funding (which should not be, IMO, included in
>> I-Ds at all, much less generated automatically).
>> 
>> It is not clear to me that these are problems with xml2rfc or
>> the DTD as much as they are difficulties created by confusion
>> about IESG or Secretariat (or other boilerplate source) norms,
>> and I would hope that those bodies would get their confusion
>> cleared up.

	Thanks John,

	Dave

From: [email-masked] (John C Klensin)
Date: Sat, 03 Jul 2004 05:14:05 -0400
Subject: [xml2rfc] Re: getting xml2rfc to output the category
In-Reply-To: <[email-masked]>
References: <[email-masked] .ca.us>
Message-ID: <[email-masked]>

--On  Fri, 2 Jul 2004 11:01:30 -0700, David Meyer
<[email-masked]>, wrote...

> 	I have specificed the my category in the rfc element, but
> 	it's not (apparently) output anywhere. The reason I ask
> 	is because I like to put a category header on my drafts
> 	so people can see what I intend (I like to have it WG
> 	chair as well).
> 
> 	Anyway to do this?

Dave, without answering your question, I note that,
historically, Internet Drafts have been _prohibited_ from
containing that information, or "obsoletes or "updates"
statements, anywhere in the headers.  This has been out of
concern for confusion with RFCs and because it implies a claim
that isn't yet valid/approved.

As with many other things related to I-Ds, Secretariat
enforcement of that requirement has been sporadic at best and, I
believe, on the decline in the last few years.  And I note that
1id-guidelines.txt was changed in the latest version to now
prohibit this terminology only in the title, which is, IMO, a
useless restriction that does not reflect the original intent.
And 1id-guidelines.txt no longer mentions Obsoletes/Updates
which, I am fairly sure, were explicitly prohibited historically.

However, if one wants to follow those historical rules, it
identifies an issue with xml2rfc and with the current state of
documents and boilerplate generally.   For the specific case you
are concerned about, the historical solution has been to add
some sentences to the "Status of this Memo" section that says,
e.g., "If a successor to this document is ultimately approved,
it is expected to be a <foo> and to obsolete <bar>."  But, since
"Status of this Memo" is, using xml2rfc, entirely
automagically-generated boilerplate, there is no way to add that
sentence or associated explanatory material (such as the
location of mailing lists for discussion) to that section.

I note in passing that we are now committing the stylistic
obscenity of having two Acknowledgement sections in many
documents -- one supplied by authors in a <section> element and
another one added as part of the <back> boilerplate about RFC
Editor function funding (which should not be, IMO, included in
I-Ds at all, much less generated automatically).

It is not clear to me that these are problems with xml2rfc or
the DTD as much as they are difficulties created by confusion
about IESG or Secretariat (or other boilerplate source) norms,
and I would hope that those bodies would get their confusion
cleared up.

best,
    john

From: [email-masked] (David Meyer)
Date: Fri, 2 Jul 2004 13:21:21 -0700
Subject: [xml2rfc] .xml2rfc.rc?
In-Reply-To: <[email-masked]>
References: <[email-masked]>
Message-ID: <[email-masked]>

On Fri, Jul 02, 2004 at 11:21:10AM -0700, David Meyer wrote:
>> 	I'm having a little trouble getting this to work. I'm
>> 	trying to set it up so exernal refs don't have to be in
>> 	the current working directory. This is what I have:

	Sorry folks, I see that you need to have a copy of this
	where ever your source file is.

	Thanks,

	Dave

From: [email-masked] (David Meyer)
Date: Fri, 2 Jul 2004 11:21:10 -0700
Subject: [xml2rfc] .xml2rfc.rc?
Message-ID: <[email-masked]>

	I'm having a little trouble getting this to work. I'm
	trying to set it up so exernal refs don't have to be in
	the current working directory. This is what I have:

global env tcl_platform

if {![string compare $tcl_platform(platform) windows]} {
 set sep ";"
} else {
 set sep ":"
}

if {[catch { set env(XML_LIBRARY) } library]} {
 set library ""
 append library $sep~/IETF/Drafts/xml/rfc
 append library $sep~/IETF/Drafts/xml/id
}

set nativeD [file nativename $inputD]
if {[lsearch [split $library $sep] $nativeD] < 0} {
 set library "$nativeD$sep$library"
}
set env(XML_LIBRARY) $library

	Is there some obvious problem here? There's not a lot of
	diagnostics available, so any help much appreciated.

	Thanks,

	Dave

From: [email-masked] (David Meyer)
Date: Fri, 2 Jul 2004 11:01:30 -0700
Subject: [xml2rfc] getting xml2rfc to output the category (info, bcp, etc)
Message-ID: <[email-masked]>

	I have specificed the my category in the rfc element, but
	it's not (apparently) output anywhere. The reason I ask
	is because I like to put a category header on my drafts
	so people can see what I intend (I like to have it WG
	chair as well).

	Anyway to do this?

	Thanks,

	Dave

From: [email-masked] (David T. Perkins)
Date: Fri, 02 Jul 2004 10:29:40 -0700
Subject: [xml2rfc] Question on References....
In-Reply-To: <[email-masked]>
Message-ID: <[email-masked]>

HI,

Why do you believe that terms should be used instead of numbers?

PS xml2rfc allows you to specify generation of terms or numbers.
   Its a processing instruction.
   
   <?rfc semrefs='yes'?> (terms) or <?rfc semrefs='no'?> (numbers)

 
At 08:13 PM 7/1/2004 -0400, Russ White wrote:
>It seems the xml2rfc tool only knows how to do references as numbers--one
>of the specific nits I always look for when editing docs is that all the
>references should be some short phrase indicating the reference, rather
>than a number. In other words, rather than using [1], you should really use
>[BGP-4].
>
>How would I go about changing the ref's in my final output from xml2rfc to
>use words I've put in, rather than [1], [2], etc. I've tried putting a
>title on the <reference> tag, but that doesn't seem to work.
>
>Thoughts?
>
>Russ

Regards,
/david t. perkins 

From: [email-masked] (Glen Zorn)
Date: Fri, 2 Jul 2004 08:54:09 -0700
Subject: [xml2rfc] Question on References....
In-Reply-To: <[email-masked]>
Message-ID: <[email-masked]>

[email-masked]
<mailto:[email-masked]> writes:

> It seems the xml2rfc tool only knows how to do references as
> numbers--one of the specific nits I always look for when editing docs
> is that all the references should be some short phrase indicating the
> reference, rather than a number. In other words, rather than using
> [1], you should really use [BGP-4].   
> 
> How would I go about changing the ref's in my final output from
> xml2rfc to use words I've put in, rather than [1], [2], etc. I've
> tried putting a title on the <reference> tag, but that doesn't seem
> to work.  

You can enable this by putting 

	<?rfc symrefs="yes" ?> 

in the processing instruction block at the top of the XML file.  If you
want the references sorted, too, add the line

	<?rfc sortrefs="yes"?>

in the same area.  Both options default to "no" and are mentioned (along
with others) in the readme file
(http://xml.resource.org/authoring/README.html).
 
> 
> Thoughts?
> 
> Russ
> 
> __________________________________
> [email-masked] CCIE <>< Grace Alone
> 
> 
> _______________________________________________
> xml2rfc mailing list
> [email-masked]
> http://lists.xml.resource.org/mailman/listinfo/xml2rfc 

Hope this helps,

~gwz

"They that can give up essential liberty to obtain a little temporary
safety deserve neither..." 
-- Benjamin Franklin, 1759

"It is forbidden to kill; therefore all murderers are punished unless
they kill in large numbers and to the sound of trumpets." 
-- Voltaire

From: [email-masked] (Aaron Falk)
Date: Fri, 2 Jul 2004 08:48:03 -0700
Subject: [xml2rfc] Question on References....
In-Reply-To: <[email-masked]>
References: <[email-masked]>
Message-ID: <[email-masked]>

Hi Russ-

I think it's just a matter of including

<?rfc symrefs="yes" ?>

at the top of your document.  Then the anchor string (as in <reference 
anchor="Falk04">) appears as the citation tag.

The only documentation I know of is in 
http://xml.resource.org/authoring/README.html#anchor7

Hope this helps,

--aaron

On Jul 1, 2004, at 5:13 PM, Russ White wrote:

>
> It seems the xml2rfc tool only knows how to do references as 
> numbers--one
> of the specific nits I always look for when editing docs is that all 
> the
> references should be some short phrase indicating the reference, rather
> than a number. In other words, rather than using [1], you should 
> really use
> [BGP-4].
>
> How would I go about changing the ref's in my final output from 
> xml2rfc to
> use words I've put in, rather than [1], [2], etc. I've tried putting a
> title on the <reference> tag, but that doesn't seem to work.
>
> Thoughts?
>
> Russ
>
> __________________________________
> [email-masked] CCIE <>< Grace Alone
>
>
> _______________________________________________
> xml2rfc mailing list
> [email-masked]
> http://lists.xml.resource.org/mailman/listinfo/xml2rfc

From: Russ White <[email-masked]> (Russ White)
Date: Fri, 2 Jul 2004 11:32:06 -0400 (Eastern Daylight Time)
Subject: [xml2rfc] Question on References....
In-Reply-To: <[email-masked]>
References: <[email-masked]> <[email-masked]>
Message-ID: <[email-masked]>

> Use
>
> 	<?rfc symrefs="yes"?>
>
> Best regards, Julian

Thanks!

:-)

Russ

__________________________________
[email-masked] CCIE <>< Grace Alone

From: [email-masked] (Julian Reschke)
Date: Fri, 02 Jul 2004 17:25:27 +0200
Subject: [xml2rfc] Question on References....
In-Reply-To: <[email-masked]>
References: <[email-masked]>
Message-ID: <[email-masked]>

Russ White wrote:

> It seems the xml2rfc tool only knows how to do references as numbers--one
> of the specific nits I always look for when editing docs is that all the
> references should be some short phrase indicating the reference, rather
> than a number. In other words, rather than using [1], you should really use
> [BGP-4].
> 
> How would I go about changing the ref's in my final output from xml2rfc to
> use words I've put in, rather than [1], [2], etc. I've tried putting a
> title on the <reference> tag, but that doesn't seem to work.
> 
> Thoughts?

Use

	<?rfc symrefs="yes"?>

Best regards, Julian

-- 
<green/>bytes GmbH -- http://www.greenbytes.de -- tel:+492512807760

From: [email-masked] (Graham Klyne)
Date: Fri, 02 Jul 2004 16:19:37 +0100
Subject: [xml2rfc] A couple of observations about XML2RFC (online service)
Message-ID: <[email-masked]>

Hi,

I've just spotted a couple of minor problems with the online XML2RFC 
service (one maybe applicable to the software):

...

(1) not ignoring content of XML comments:

[[
<!--
         START: <?rfc include="MIMEHeaderPermanentRegistry.xml"?>
-->
]]

generates an error message concerning the commented include statement (I 
have inlined the actual included text for online processing).

...

(2) The online service won't accept URI as well as file name.  I recognize 
this isn't strictly a problem with the service, but with HTML forms 
handling and file upload.  But, there is a general expectation (among some 
web developers, at least) that web resources can/should be usable like 
local files.  Some services provide a mechanism to specify a URI _or_ to 
upload a file; e.g. http://validator.w3.org/

...

#g

------------
Graham Klyne
For email:
http://www.ninebynine.org/#Contact

From: Russ White <[email-masked]> (Russ White)
Date: Thu, 1 Jul 2004 20:13:04 -0400 (Eastern Daylight Time)
Subject: [xml2rfc] Question on References....
Message-ID: <[email-masked]>

It seems the xml2rfc tool only knows how to do references as numbers--one
of the specific nits I always look for when editing docs is that all the
references should be some short phrase indicating the reference, rather
than a number. In other words, rather than using [1], you should really use
[BGP-4].

How would I go about changing the ref's in my final output from xml2rfc to
use words I've put in, rather than [1], [2], etc. I've tried putting a
title on the <reference> tag, but that doesn't seem to work.

Thoughts?

Russ

__________________________________
[email-masked] CCIE <>< Grace Alone

From: [email-masked] (Clive D.W. Feather)
Date: Thu, 1 Jul 2004 09:32:34 +0100
Subject: [xml2rfc] Consistency
In-Reply-To: <[email-masked]>
References: <[email-masked]> <[email-masked]>
Message-ID: <[email-masked]>

Marshall Rose said:
>> Is there a reason for this inconsistency, or is it going to be fixed?
> there are lots of differences in the formatting between the .txt and 
> .html output, the people who designed the html output said it looked 
> better that way. i can't get too worked up over it.

Um, you misunderstand my point (perhaps because I didn't make it very
well).

I'm happy that the HTML and TXT versions should be different. But the HTML
version is inconsistent in itself:

* In the table of contents, $ has a dot after it for References sections,
but not for "Author's Address".

* In the table of contents, References sections are unnumbered and at the
top level, but in the body of the document they are numbered and at
sub-levels. Furthermore, the "References" section in the document isn't
listed in the ToC at all.

* The HTML version puts a horizontal bar and [TOC] link between top level
sections *only*, and not between sub-sections, *EXCEPT* between References
and Normative References and between Normative References and Informative
References, where there are bars even though consistency with the rest of
the document says there shouldn't be.

Hope that makes it clearer.

-- 
Clive D.W. Feather  | Work:  <[email-masked]>   | Tel:    +44 20 8495 6138
Internet Expert     | Home:  <[email-masked]>  | Fax:    +44 870 051 9937
Demon Internet      | WWW: http://www.davros.org | Mobile: +44 7973 377646
Thus plc            |                            |