Subject: [edu-team] Re: [xml2rfc] New ID-Checklist to replace ID-nits (fwd)
From: [email-masked] (Michael Richardson)
Date: Mon, 31 May 2004 15:09:35 -0400

-----BEGIN PGP SIGNED MESSAGE-----

>>>>> "Fred" == Fred Baker <[email-masked]> writes:
    Fred> At 01:14 PM 05/31/04 -0400, Michael Richardson wrote: I have
    Fred> historically used the first (cf Tevia), and still find it
    Fred> useful when I am not connected to the Internet, when
    Fred> xml.resource.org is not accessible and xml2rfc fails with a
    Fred> "socket failure" - hotels, airplanes, and WLAN-less meeting

    >> % rsync -l rsync://lox.sandelman.ca/ rfcxml RFC biblography in
    >> XML idxml ID biblography in XML
    >> 
    >> Copies of the stuff from xml.resource.org. wget'ed nightly.

    Fred> not sure I get your point. If I'm not attached tot he net, I
    Fred> can't get to your site either. The point is "what happens when
    Fred> I'm not connected".

  I now get it... I was thinking that you had difficulties even getting
copies of the content locally.

  The answer is that one should be using URIs, and should have a local
URI->file: resolver if you have a copy of the documents locally.

- --
]     "Elmo went to the wrong fundraiser" - The Simpson         |  firewalls  [
]   Michael Richardson,    Xelerance Corporation, Ottawa, ON    |net architect[
] [email-masked]      http://www.sandelman.ottawa.on.ca/mcr/ |device driver[
] panic("Just another Debian GNU/Linux using, kernel hacking, security guy"); [

From: [email-masked] (Fred Baker)
Date: Mon, 31 May 2004 11:12:05 -0700
Subject: [edu-team] Re: [xml2rfc] New ID-Checklist to replace ID-nits (fwd)
In-Reply-To: <[email-masked]>
References: <p0602040cbcdf95050084@[192.168.2.2]> <[email-masked]> <[email-masked]> <p0602040cbcdf95050084@[192.168.2.2]> <[email-masked]> <[email-masked]> <[email-masked]>
Message-ID: <[email-masked]>

At 01:14 PM 05/31/04 -0400, Michael Richardson wrote:
>     Fred> I have historically used the first (cf Tevia), and still find
>     Fred> it useful when I am not connected to the Internet, when
>     Fred> xml.resource.org is not accessible and xml2rfc fails with a
>     Fred> "socket failure" - hotels, airplanes, and WLAN-less meeting
>
>% rsync -l rsync://lox.sandelman.ca/
>rfcxml          RFC biblography in XML
>idxml           ID biblography in XML
>
>Copies of the stuff from xml.resource.org. wget'ed nightly.

not sure I get your point. If I'm not attached tot he net, I can't get to 
your site either. The point is "what happens when I'm not connected". 

From: [email-masked] (Fred Baker)
Date: Mon, 31 May 2004 11:10:01 -0700
Subject: [edu-team] Re: [xml2rfc] New ID-Checklist to replace ID-nits (fwd)
In-Reply-To: <p06020416bce0c8759f95@[192.168.2.2]>
References: <p0602040cbcdf95050084@[192.168.2.2]> <[email-masked]> <[email-masked]> <p0602040cbcdf95050084@[192.168.2.2]> <[email-masked]> <[email-masked]> <p06020416bce0c8759f95@[192.168.2.2]>
Message-ID: <[email-masked]>

At 07:43 AM 05/31/04 -0400, Margaret Wasserman wrote:
>The RFC Editor strongly prefers symbolic references over numeric 
>references.  They explain why in 
>ftp://ftp.rfc-editor.org/in-notes/rfc-editor/instructions2authors.txt:
>
>       Simple numeric citations ("[53]")

that is citations. the discussion is concerning bulleted vs numbered lists. 

From: [email-masked] (Michael Richardson)
Date: Mon, 31 May 2004 13:14:03 -0400
Subject: [edu-team] Re: [xml2rfc] New ID-Checklist to replace ID-nits (fwd)
In-Reply-To: Message from Fred Baker <[email-masked]> of "Sun, 30 May 2004 22:37:12 PDT." <[email-masked]>
References: <p0602040cbcdf95050084@[192.168.2.2]> <[email-masked]> <[email-masked]> <p0602040cbcdf95050084@[192.168.2.2]> <[email-masked]>  <[email-masked]>
Message-ID: <[email-masked]>

-----BEGIN PGP SIGNED MESSAGE-----

>>>>> "Fred" == Fred Baker <[email-masked]> writes:
    Fred> I have historically used the first (cf Tevia), and still find
    Fred> it useful when I am not connected to the Internet, when
    Fred> xml.resource.org is not accessible and xml2rfc fails with a
    Fred> "socket failure" - hotels, airplanes, and WLAN-less meeting

% rsync -l rsync://lox.sandelman.ca/
rfcxml          RFC biblography in XML
idxml           ID biblography in XML

Copies of the stuff from xml.resource.org. wget'ed nightly.

- --
]     "Elmo went to the wrong fundraiser" - The Simpson         |  firewalls  [
]   Michael Richardson,    Xelerance Corporation, Ottawa, ON    |net architect[
] [email-masked]      http://www.sandelman.ottawa.on.ca/mcr/ |device driver[
] panic("Just another Debian GNU/Linux using, kernel hacking, security guy"); [

From: [email-masked] (David T. Perkins)
Date: Mon, 31 May 2004 10:03:21 -0700
Subject: [edu-team] Re: [xml2rfc] New ID-Checklist to replace ID-nits (fwd)
In-Reply-To: <p06020425bce1069d892e@[192.168.2.2]>
References: <[email-masked]> <[email-masked]> <p0602040cbcdf95050084@[192.168.2.2]> <[email-masked]> <[email-masked]> <p0602040cbcdf95050084@[192.168.2.2]> <[email-masked]> <[email-masked]> <[email-masked]>
Message-ID: <[email-masked]>

HI,

 From what I've seen, the xml2rfc tool always numbers references so that
there are no gaps. That is all the numbers are consecutive starting
at the normative refs and flowing into the informative. And if you
add another reference item, then references (and citations) are
renumbered.

Maybe MTR can give us the definitive on this.

>Apparently the RFC editor finds it "confusing" when references 1, 2 and 5 are in the
>normative section, while references 3 & 4 are in the informative section.
>
>Personally, I don't find that confusing, but I do find symbolic references easier to use
>than numeric ones.  I don't have religion about this, though, I was just quoting the
>RFC editor's published position.

Regards,
/david t. perkins 

From: [email-masked] (Julian Reschke)
Date: Mon, 31 May 2004 18:49:40 +0200
Subject: [edu-team] Re: [xml2rfc] New ID-Checklist to replace  ID-nits (fwd)
In-Reply-To: <[email-masked]>
References: <[email-masked]> <p0602040cbcdf95050084@[192.168.2.2]> <[email-masked]> <[email-masked]> <p0602040cbcdf95050084@[192.168.2.2]> <[email-masked]> <[email-masked]> <[email-masked]>
Message-ID: <[email-masked]>

David T. Perkins wrote:

> ...
> On appendices...
> If you want them before references, then you specify "appendix"
> elements in the "middle" element. If you want them after the
> references, then you specify "section" elements in the "back"
> element after the two "reference" elements (one is the normative
> and the other is the informative). 

IMHO, this is incorrect (MTR, please correct me if I'm wrong).

The appendix has been added *experimentally* to take case of new RFC 
Editor requirements; but as far as I'm aware of, this is still 
work-in-progress.

In particular, whether a section labelled "appendix" is normative or not 
has nothing to do with it's position in the document. *Everything* in 
the document is normative, unless otherwise stated explicitly.

Best regards, Julian

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

From: [email-masked] (Margaret Wasserman)
Date: Mon, 31 May 2004 12:01:45 -0400
Subject: [edu-team] Re: [xml2rfc] New ID-Checklist to replace ID-nits (fwd)
In-Reply-To: <[email-masked]>
References: <[email-masked]> <p0602040cbcdf95050084@[192.168.2.2]> <[email-masked]> <[email-masked]> <p0602040cbcdf95050084@[192.168.2.2]> <[email-masked]> <[email-masked]> <[email-masked]>
Message-ID: <p06020425bce1069d892e@[192.168.2.2]>

Hi Dave,

At 8:56 AM -0700 5/31/04, David T. Perkins wrote:
>I read the paragraph that you quoted below and could not figure out
>the "confusing gaps" in first sentence. The xml2rfc does not (as far
>as I could determine) support the n1, n2, ... and i1, i2, ... method.
>So, it does kind of lead one down the path of symbolic refs.

Apparently the RFC editor finds it "confusing" when references 1, 2 
and 5 are in the
normative section, while references 3 & 4 are in the informative section.

Personally, I don't find that confusing, but I do find symbolic 
references easier to use
than numeric ones.  I don't have religion about this, though, I was 
just quoting the
RFC editor's published position.

Thanks for the information on appendices.

Margaret

From: [email-masked] (David T. Perkins)
Date: Mon, 31 May 2004 08:56:08 -0700
Subject: [edu-team] Re: [xml2rfc] New ID-Checklist to replace ID-nits (fwd)
In-Reply-To: <p06020416bce0c8759f95@[192.168.2.2]>
References: <[email-masked]> <p0602040cbcdf95050084@[192.168.2.2]> <[email-masked]> <[email-masked]> <p0602040cbcdf95050084@[192.168.2.2]> <[email-masked]> <[email-masked]>
Message-ID: <[email-masked]>

HI,

I read the paragraph that you quoted below and could not figure out
the "confusing gaps" in first sentence. The xml2rfc does not (as far
as I could determine) support the n1, n2, ... and i1, i2, ... method.
So, it does kind of lead one down the path of symbolic refs.

On appendices...
If you want them before references, then you specify "appendix"
elements in the "middle" element. If you want them after the
references, then you specify "section" elements in the "back"
element after the two "reference" elements (one is the normative
and the other is the informative). 

At 07:43 AM 5/31/2004 -0400, Margaret Wasserman wrote:

>Hi David,
>
>
>>At 02:04 PM 05/30/04 -0700, David T. Perkins wrote:
>>>1) you use symbolic references. I couldn't find a definitive guidance to use numeric or symbolic. Why did you choose symbolic over numeric?
>
>The RFC Editor strongly prefers symbolic references over numeric references.  They explain why in ftp://ftp.rfc-editor.org/in-notes/rfc-editor/instructions2authors.txt:
>
>      Simple numeric citations ("[53]") can cause confusing gaps when
>      the list of references is split between normative and informative.
>      A good alternative is to have two separate series, "[n1]", "[n2]",
>      ... "[i1]", "[i2]" for citations to normative and informative
>      references.  Other choices include author abbreviations, possibly
>      a year ("[Smith93]"), and some brief encoding of the title and
>      year ("[MPLS99a]").
>
>Most of the I-Ds/RFCs that I've worked on include an encoding of the title without the year.
>
>>>3) You didn't include any appendices. Should they be before or after the references?
>
>How do you add an appendix in XML2RFC?
>
>Margaret
Regards,
/david t. perkins 

From: [email-masked] (Margaret Wasserman)
Date: Mon, 31 May 2004 07:43:01 -0400
Subject: [edu-team] Re: [xml2rfc] New ID-Checklist to replace ID-nits (fwd)
In-Reply-To: <[email-masked]>
References: <p0602040cbcdf95050084@[192.168.2.2]> <[email-masked]> <[email-masked]> <p0602040cbcdf95050084@[192.168.2.2]> <[email-masked]> <[email-masked]>
Message-ID: <p06020416bce0c8759f95@[192.168.2.2]>

Hi David,

>At 02:04 PM 05/30/04 -0700, David T. Perkins wrote:
>>1) you use symbolic references. I couldn't find a definitive 
>>guidance to use numeric or symbolic. Why did you choose symbolic 
>>over numeric?

The RFC Editor strongly prefers symbolic references over numeric 
references.  They explain why in 
ftp://ftp.rfc-editor.org/in-notes/rfc-editor/instructions2authors.txt:

       Simple numeric citations ("[53]") can cause confusing gaps when
       the list of references is split between normative and informative.
       A good alternative is to have two separate series, "[n1]", "[n2]",
       ... "[i1]", "[i2]" for citations to normative and informative
       references.  Other choices include author abbreviations, possibly
       a year ("[Smith93]"), and some brief encoding of the title and
       year ("[MPLS99a]").

Most of the I-Ds/RFCs that I've worked on include an encoding of the 
title without the year.

>>3) You didn't include any appendices. Should they be before or 
>>after the references?

How do you add an appendix in XML2RFC?

Margaret

From: [email-masked] (Julian Reschke)
Date: Mon, 31 May 2004 10:39:05 +0200
Subject: [edu-team] Re: [xml2rfc] New ID-Checklist to replace  ID-nits (fwd)
In-Reply-To: <[email-masked]>
References: <p0602040cbcdf95050084@[192.168.2.2]> <[email-masked]> <[email-masked]> <p0602040cbcdf95050084@[192.168.2.2]> <[email-masked]> <[email-masked]>
Message-ID: <[email-masked]>

This is a multi-part message in MIME format.
--------------020107030602000400060407
Content-Type: text/plain; charset=us-ascii; format=flowed
Content-Transfer-Encoding: 7bit

Fred Baker wrote:
> ...
> I have historically used the first (cf Tevia), and still find it useful 
> when I am not connected to the Internet, when xml.resource.org is not 
> accessible and xml2rfc fails with a "socket failure" - hotels, 
> airplanes, and WLAN-less meeting rooms are far too frequent. I have no 
> problem with the latter when I happen to be connected. BTW, the second 
> doesn't have an obvious extension to internet drafts or ITU documents, 
> so I think I wind up using the <?rfc ... ?> form anyway in such cases.
> 
> I have the same problem with Cisco IT's predilection for software 
> packages that assume one is connected to Cisco's internal network, and 
> by the way connected using 100-MBPS-or-faster links. It is a hard 
> discussion to have, because they never wander far from their ivory 
> towers and have no concept that there is an issue.
> 
> Neither the <?rfc ... ?> nor the &rfc2629 model are accepted by XMLSpy; 
> it indicates that both are "not standard XML", and I have to "save 
> anyway". I'd prefer something along the lines of Carl Malamud's 
> suggestion of a mechanism where I can simply refer to things in the text 
> and the tool works out the right set of references.
> ...

Using the XML standard entity inclusion mechanism has the drawback of 
not working when you're disconnected (and don't have the required local 
caching software, which seems to be unlikely).

Using <?rfc include...> has the *additional* drawback of producing XML 
documents that do not conform to the DTD, there are rightfully rejected 
by any conforming and validating XML parser. These documents are 
fundamentally broken, even though xml2rfc may process them.

*Both* methods have the fundamental problem that the actual contents of 
the specification may change at any point of time, thus it IMHO is 
completely unacceptable as a format that gets submitted for publication 
by the IETF (once we get there).

I think we should acknowledge that XML-formatted IDs and RFCs need to be 
complete and should not depend on any "extra" files (that you may not 
have or that may change over time).

Now, not having to manually include references of course is legitimate 
wish, but IMHO this should be moved into a separate tool. I've been 
playing with the following format:

1) Add <reference> elements for each reference you need, but do only 
specify the anchor attribute and a new extension attribute that 
specifies an inclusion source:

<references>
   <reference anchor="RFC2395" 
ed:copy-reference-from="rfc2396.reference.xml"/>
</references>

2) Have a separate tool that scans the file for inclusion instructions 
and let it resolve them, *keeping* the inclusion instruction. The result 
  would be a fully included reference *plus* the original inclusion 
instruction. This allows to re-run the tool anytime you like. Note this 
tool would need to run using a non-validating XML parser.

I think this nicely resolves all the issues above, and it can be run 
automatically. All we'd need would be a DTD change that allows that 
import directive (because we want to keep it in the result document).

The toold is dead simple using XSLT (attached). Note that is also 
supports a variant where the reference element content can be extracted 
from another RFC2629-style formatted document.

Feedback appreciated,

Julian

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

--------------020107030602000400060407
Content-Type: text/xml;
 name="update-references.xslt"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline;
 filename="update-references.xslt"

<!--
    Resolve import instructions on reference elements.
    
    Copyright (c) 2004 Julian F. Reschke ([email-masked])

    placed into the public domain

    change history:

    2004-05-31  [email-masked]

    Experimental release.

-->

<xsl:transform xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                version="1.0"
                xmlns:ed="http://greenbytes.de/2002/rfcedit"
>

<!-- reference update -->

<xsl:template match="reference[@ed:extract-front-from]">
  <xsl:message>Extracing front for reference `<xsl:value-of select="@anchor"/>' from `<xsl:value-of select="@ed:extract-front-from"/>'</xsl:message>
  <xsl:variable name="import" select="document(@ed:extract-front-from)/*/front"/>
  <xsl:copy>
    <xsl:apply-templates select="@*"/>
    <xsl:choose>
      <xsl:when test="$import">
        <xsl:text>&#10;</xsl:text>
        <xsl:comment>Extracted from `<xsl:value-of select="@ed:extract-front-from"/>'</xsl:comment>
        <xsl:copy-of select="$import"/>
        <xsl:text>&#10;</xsl:text>
      </xsl:when>
      <xsl:otherwise>
        <xsl:message>Extraction failed</xsl:message>
        <xsl:apply-templates select="front"/>
      </xsl:otherwise>
    </xsl:choose>
    <xsl:apply-templates select="*[not(self::front)]"/>
  </xsl:copy>
</xsl:template>

<xsl:template match="reference[@ed:copy-reference-from]">
  <xsl:message>Copying reference for `<xsl:value-of select="@anchor"/>' from `<xsl:value-of select="@ed:copy-reference-from"/>'</xsl:message>
  <xsl:variable name="import" select="document(@ed:copy-reference-from)/reference"/>
  <xsl:copy>
    <xsl:apply-templates select="@*"/>
    <xsl:choose>
      <xsl:when test="$import">
        <xsl:copy-of select="$import/@*[not(self::anchor)]"/>
        <xsl:text>&#10;</xsl:text>
        <xsl:comment>Copied from `<xsl:value-of select="@ed:copy-reference-from"/>'</xsl:comment>
        <xsl:copy-of select="$import/node()"/>
        <xsl:text>&#10;</xsl:text>
      </xsl:when>
      <xsl:otherwise>
        <xsl:message>Extraction failed</xsl:message>
        <xsl:apply-templates select="*"/>
      </xsl:otherwise>
    </xsl:choose>
  </xsl:copy>
</xsl:template>

<!-- rules for identity transformations -->

<xsl:template match="processing-instruction()">
  <xsl:text>&#10;</xsl:text>
  <xsl:copy><xsl:apply-templates select="node()|@*" /></xsl:copy>
</xsl:template>

<xsl:template match="*|text()|comment()|@*"><xsl:copy><xsl:apply-templates select="node()|@*" /></xsl:copy></xsl:template>

<xsl:template match="/">
	<xsl:copy><xsl:apply-templates select="node()" /></xsl:copy>
</xsl:template>

</xsl:transform>
--------------020107030602000400060407--

From: [email-masked] (Fred Baker)
Date: Sun, 30 May 2004 22:37:12 -0700
Subject: [edu-team] Re: [xml2rfc] New ID-Checklist to replace ID-nits (fwd)
In-Reply-To: <[email-masked]>
References: <p0602040cbcdf95050084@[192.168.2.2]> <[email-masked]> <[email-masked]> <p0602040cbcdf95050084@[192.168.2.2]> <[email-masked]>
Message-ID: <[email-masked]>

The file you sent is interesting. I'll have to think about it. I may use it.

At 02:04 PM 05/30/04 -0700, David T. Perkins wrote:
>1) you use symbolic references. I couldn't find a definitive guidance to 
>use numeric or symbolic. Why did you choose symbolic over numeric?

To my limited knowledge, the IETF permits angels, dancing, and pins with 
heads. It doesn't tell us how many of the first may be occupied with the 
second while standing on the third. I could be wrong.

I use symbolic references because I like bullets better than numbers; if I 
really want to number something, I can, and I usually find myself numbering 
it as a paragraph rather than as a list item. One thing I would like, BTW, 
would be a way to know a priori what I can put in those fields rather than 
having to remember the words "Symbolic", "Numeric", and "HangText". Or was 
it "Symbols"?

>2) the order of the following sections is different in your version from 
>what I've been working on: IANA Considerations, Security Considerations, 
>Acknowledgements. What order should these go?

My understanding is that they must be present, but that the order is not 
specified.

In the IANA section (as your template notes), if I don't have anything to 
say, IANA humbly requests that I say "I don't have anything to say", so I 
also say "RFC Editor, you may remove this section when the time comes".

I prefer to put the acknowledgements last. Tevia's explanation is sufficient...

>3) You didn't include any appendices. Should they be before or after the 
>references?

I honestly don't know. I'd suggest you try both positions and see if the 
tool emits anything different. I suspect it doesn't.

>4) One of the questions last week was whether or not the <?rfc include ... 
>?> processing instruction should be used or the method specified in 
>http://xml.resource.org be used. What opinion do you have on this issue?

I have historically used the first (cf Tevia), and still find it useful 
when I am not connected to the Internet, when xml.resource.org is not 
accessible and xml2rfc fails with a "socket failure" - hotels, airplanes, 
and WLAN-less meeting rooms are far too frequent. I have no problem with 
the latter when I happen to be connected. BTW, the second doesn't have an 
obvious extension to internet drafts or ITU documents, so I think I wind up 
using the <?rfc ... ?> form anyway in such cases.

I have the same problem with Cisco IT's predilection for software packages 
that assume one is connected to Cisco's internal network, and by the way 
connected using 100-MBPS-or-faster links. It is a hard discussion to have, 
because they never wander far from their ivory towers and have no concept 
that there is an issue.

Neither the <?rfc ... ?> nor the &rfc2629 model are accepted by XMLSpy; it 
indicates that both are "not standard XML", and I have to "save anyway". 
I'd prefer something along the lines of Carl Malamud's suggestion of a 
mechanism where I can simply refer to things in the text and the tool works 
out the right set of references.

From: [email-masked] (David T. Perkins)
Date: Sun, 30 May 2004 14:04:04 -0700
Subject: [edu-team] Re: [xml2rfc] New ID-Checklist to replace ID-nits (fwd)
In-Reply-To: <[email-masked]>
References: <p0602040cbcdf95050084@[192.168.2.2]> <[email-masked]> <[email-masked]> <p0602040cbcdf95050084@[192.168.2.2]>
Message-ID: <[email-masked]>

--=====================_407276192==_
Content-Type: text/plain; charset="us-ascii"

Fred,

I looked at your template, and compared it with an update that
I've done of the one originally from Pekka Savola. Would you take 
a look at it (it's attached)?

There are a few items in yours that are not in my update, and
there many more items in my update. I would like to continue
updating the one originally from Pekka Savola with items from yours.
How does that sound?

I do have a few questions....
1) you use symbolic references. I couldn't find a definitive
   guidance to use numeric or symbolic. Why did you choose
   symbolic over numeric?
2) the order of the following sections is different in your
   version from what I've been working on: IANA Considerations,
   Security Considerations, Acknowledgements.
   What order should these go?
3) You didn't include any appendices. Should they be before
   or after the references?
4) One of the questions last week was whether or not the
   <?rfc include ... ?> processing instruction should be used
   or the method specified in http://xml.resource.org be used.
   What opinion do you have on this issue?

Regards,
/david t. perkins
--=====================_407276192==_
Content-Type: application/xml; name="template1b.xml"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="template1b.xml"

--=====================_407276192==_--

From: [email-masked] (Fred Baker)
Date: Sun, 30 May 2004 10:23:12 -0700
Subject: [edu-team] Re: [xml2rfc] New ID-Checklist to replace ID-nits (fwd)
In-Reply-To: <p0602040cbcdf95050084@[192.168.2.2]>
References: <[email-masked]> <[email-masked]> <p0602040cbcdf95050084@[192.168.2.2]>
Message-ID: <[email-masked]>

At 09:42 AM 05/30/04 -0400, Margaret Wasserman wrote:
>XML2RFC folks, would you like to put this up on your site (and send us a 
>pointer)?  Or would you rather that we included it on the EDU Team site?

Either way, maybe you should take my address out of it :^) 

From: [email-masked] (Margaret Wasserman)
Date: Sun, 30 May 2004 09:42:43 -0400
Subject: [edu-team] Re: [xml2rfc] New ID-Checklist to replace ID-nits (fwd)
In-Reply-To: <[email-masked]>
References: <[email-masked]> <[email-masked]>
Message-ID: <p0602040cbcdf95050084@[192.168.2.2]>

Thanks, Fred.

Hopefully we can get this up on the web somewhere and point to it 
from our editors training materials.

XML2RFC folks, would you like to put this up on your site (and send 
us a pointer)?  Or would you rather that we included it on the EDU 
Team site?

Thanks,
Margaret

At 8:56 AM -0700 5/29/04, Fred Baker wrote:
>Is the attached what you had in mind? It is what I use to create a new draft.
>
>At 01:09 AM 05/26/04 +0300, Pekka Savola wrote:
>>What I'd be interested in seeing a fully working template, including
>>the most important options (commented out or not), the typical
>>sections, the examples of how to manage the RFC/I-D references and
>>section cross-references, a bulleted/numbered list, etc. -- the basic
>>stuff.  The template might also include a few explanations on the
>>typical xml2rfc error messages ("check that you're terminating the
>>elements properly") but this is not necessary.
>
>
>Content-Type: application/xml; name="new draft.xml"
>Content-Disposition: attachment; filename="new draft.xml"
>
>Attachment converted: Macintosh HD:new draft 1.xml (????/----) (0008741F)
>_______________________________________________
>edu-team mailing list
>[email-masked]
>https://www1.ietf.org/mailman/listinfo/edu-team

From: [email-masked] (Fred Baker)
Date: Sat, 29 May 2004 08:56:14 -0700
Subject: [xml2rfc] New ID-Checklist to replace ID-nits (fwd)
In-Reply-To: <[email-masked]>
References: <[email-masked]>
Message-ID: <[email-masked]>

--=====================_58597989==_
Content-Type: text/plain; charset="us-ascii"; format=flowed

Is the attached what you had in mind? It is what I use to create a new draft.

At 01:09 AM 05/26/04 +0300, Pekka Savola wrote:
>What I'd be interested in seeing a fully working template, including
>the most important options (commented out or not), the typical
>sections, the examples of how to manage the RFC/I-D references and
>section cross-references, a bulleted/numbered list, etc. -- the basic
>stuff.  The template might also include a few explanations on the
>typical xml2rfc error messages ("check that you're terminating the
>elements properly") but this is not necessary.

--=====================_58597989==_
Content-Type: application/xml; name="new draft.xml"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="new draft.xml"

--=====================_58597989==_--

From: [email-masked] (Julian Reschke)
Date: Sat, 29 May 2004 12:16:44 +0200
Subject: [xml2rfc] strict question: erefs in abstract
Message-ID: <[email-masked]>

Hi,

I just noticed that in "strict" mode, xml2rfc rejects eref elements in 
the abstract. Many I-Ds want to put references to mailing list on the 
front page, though. Does this mean those should go into a <note> element 
rather than the <abstract>?

Best regards, Julian

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

From: [email-masked] (Alex Rousskov)
Date: Thu, 27 May 2004 10:09:06 -0600 (MDT)
Subject: [xml2rfc] Updated template file
In-Reply-To: <[email-masked]>
References: <[email-masked]> <[email-masked]> <[email-masked]> <[email-masked]>
Message-ID: <[email-masked]>

On Thu, 27 May 2004, Julian Reschke wrote:

> Alex Rousskov wrote:
>
> > ...
> > #1 looks ugly. #2 duplicates source code/information, which is often a
> > bad idea. Option #3 requires additional processing step and, if custom
> > include-statements are used, is essentially creating a new language to
> > write RFCs, making RFC sources more difficult to share.
>
> Unless you share the result of the preprocessing step....

Which would make it more difficult to accept/integrate patches and
such... Sharing non-sources for purposes that do not involve looking
at or modifying them is fine, of course.

Alex.

From: [email-masked] (Julian Reschke)
Date: Thu, 27 May 2004 17:57:25 +0200
Subject: [xml2rfc] Updated template file
In-Reply-To: <[email-masked]>
References: <[email-masked]> <[email-masked]> <[email-masked]>
Message-ID: <[email-masked]>

Alex Rousskov wrote:

> ...
> #1 looks ugly. #2 duplicates source code/information, which is often a
> bad idea. Option #3 requires additional processing step and, if custom
> include-statements are used, is essentially creating a new language to
> write RFCs, making RFC sources more difficult to share.

Unless you share the result of the preprocessing step....

> We seem to be dealing with XML limitations here. XML is not
> a human-friendly language designed for RFC authoring.

Yes and no. It's partly caused by some of the design decisions in 
rfc2629. For instance instance, includes are part of XSLT 1.0 and work 
just fine.

Best regards, Julian

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

From: [email-masked] (Julian Reschke)
Date: Thu, 27 May 2004 17:34:54 +0200
Subject: [xml2rfc] Updated template file
In-Reply-To: <[email-masked]>
References: <[email-masked]> <[email-masked]> <[email-masked]> <[email-masked]>
Message-ID: <[email-masked]>

David T. Perkins wrote:

> Thank you for looking at the updated template file. I'm assuming that
> you actually read it and approve of all of the other portions. If not,

No, I still have to do that.

> would you take some time looking at it and send feedback. The original
> template file didn't validate and I didn't see feedback on those
> issues. Did you provide feedback earlier?

No.

> I missed your earlier response to my email on how to use the
> reference library (which you call the citation library). Would
> you repost your response so that we are all clear as to the
> best way to use references. Also, would you include a pointer

Any way to use references is ok *except* using the "rfc include" 
Processing Instruction (because that one breaks the XML processing 
model; for instance the DTD validation).

> that describes how an I-D author would submit additions
> (and updates) to the reference library.

That's a question for MTR, methinks.

Julian

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

From: [email-masked] (Alex Rousskov)
Date: Thu, 27 May 2004 09:22:16 -0600 (MDT)
Subject: [xml2rfc] Updated template file
In-Reply-To: <[email-masked]>
References: <[email-masked]> <[email-masked]>
Message-ID: <[email-masked]>

On Thu, 27 May 2004, Julian Reschke wrote:

> As far as I can tell, there are two alternatives.
>
> #1: follow the instructions on <http://xml.resource.org/> (Helpful Hints
> / Including files), or
>
> #2: just include the <reference> element (as obtained from the citation
> library) in your source.

  #3: use a preprocessor to preprocess include PIs or similar
      include-statements

#1 looks ugly. #2 duplicates source code/information, which is often a
bad idea. Option #3 requires additional processing step and, if custom
include-statements are used, is essentially creating a new language to
write RFCs, making RFC sources more difficult to share.

We seem to be dealing with XML limitations here. XML is not
a human-friendly language designed for RFC authoring.

Alex.

From: [email-masked] (David T. Perkins)
Date: Thu, 27 May 2004 07:28:08 -0700
Subject: [xml2rfc] Updated template file
In-Reply-To: <[email-masked]>
References: <[email-masked]> <[email-masked]> <[email-masked]>
Message-ID: <[email-masked]>

HI,

Thank you for looking at the updated template file. I'm assuming that
you actually read it and approve of all of the other portions. If not,
would you take some time looking at it and send feedback. The original
template file didn't validate and I didn't see feedback on those
issues. Did you provide feedback earlier?

I missed your earlier response to my email on how to use the
reference library (which you call the citation library). Would
you repost your response so that we are all clear as to the
best way to use references. Also, would you include a pointer
that describes how an I-D author would submit additions
(and updates) to the reference library.

At 09:34 AM 5/27/2004 +0200, Julian Reschke wrote:
>David T. Perkins wrote:
>
>>HI,
>>Attached is an updated template file. I want to work on it some more,
>>but spent way too much time trying to figure out XML errors. I ended
>>up switching to XMLspy, which provided me with useful error messages
>>about XML errors. And I guess, that is a horrible problem with XML
>>tools, in not being very helpful.
>>Let me know if you want to update the file. I've got a full day
>>meeting scheduled for tomorrow, so I may not be able to apply
>>updates until the evening.
>>Take care,
>>/david t. perkins
>
>1) The document doesn't validate (<references> is empty).
>2) There are dangling references...
>
>This is because you are using the <?rfc include...> directive which IMHO /MUST/ be deprecated. The file as posted is invalid XML and will only be processed by one specific xml2rfc processor (Marshall's).
>
>Best regards,
>
>Julian
>
>-- 
><green/>bytes GmbH -- http://www.greenbytes.de -- tel:+492512807760
Regards,
/david t. perkins 

From: [email-masked] (Hollenbeck, Scott)
Date: Thu, 27 May 2004 07:52:43 -0400
Subject: [xml2rfc] Updated template file
Message-ID: <[email-masked]>

> OK, so I got that to work for RFCs, but I seem to have 
> trouble to get it to
> work for I-Ds.
> 
> I have:

[snip]

Bert, what you're doing works fine for me.  What kind of error/problem are
you having?  I can send you a complete XML source file that works with the
current web version of xml2rfc if that would help.

-Scott-

From: [email-masked] (Wijnen, Bert (Bert))
Date: Thu, 27 May 2004 13:36:02 +0200
Subject: [xml2rfc] Updated template file
Message-ID: <[email-masked]>

> > OK, so I got that to work for RFCs, but I seem to have 
> trouble to get it to
> > work for I-Ds.
> > 
> > I have:
> > 
> > <!DOCTYPE rfc SYSTEM "rfc2629bis.dtd"
> > [
> > <!ENTITY rfc2578 PUBLIC '' 
> 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2578.xml'>
> >  <?ENTITY ietf-ipcdn-qos-mib PUBLIC '' 
> 'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf
-ipcdn-qos-mib.xml'>
> ]>

>Typo (question mark rather than excl.?)

Yep.... that's it.... Blush!? ;-)

.. snip ..

>>#2: just include the <reference> element (as obtained from 
>>the citation library) in your source.
>>
> 
> The above is laready quite a bit more typing (or paste/copy) work than I
> like, but doing #2 is not good at all I think. I think I'd have to
> redo it every time an I-D gets a new version, right?

>Actually, referencing to an unspecified I-D version IMHO is a Bad Idea 
>as well. For instance, section numbers may be changing without you ever 
>noticing...

Sometimes it is a bad idea (I agree) but often it is OK, for example when
a set of I-Ds are sort of going together.

Thanks
Bert

From: [email-masked] (Julian Reschke)
Date: Thu, 27 May 2004 13:29:06 +0200
Subject: [xml2rfc] Updated template file
In-Reply-To: <[email-masked]>
References: <[email-masked]>
Message-ID: <[email-masked]>

Wijnen, Bert (Bert) wrote:

> OK, so I got that to work for RFCs, but I seem to have trouble to get it to
> work for I-Ds.
> 
> I have:
> 
> <!DOCTYPE rfc SYSTEM "rfc2629bis.dtd"
> [
> <!ENTITY rfc2578 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2578.xml'>
>  <?ENTITY ietf-ipcdn-qos-mib PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-ipcdn-qos-mib.xml'>
> ]>

Typo (question mark rather than excl.?)

> I then use in the text:
> 
>    <xref target="RFC2578"/>
>    <xref target="I-D.ietf-ipcdn-qos-mib"/>
> 
> And in the back matter I have
> 
> <references title="Normative References">
> &rfc2578;
> &ietf-ipcdn-qos-mib;
> </references>
> 
> So what am I doing frong here?

That part should be ok.

>>#2: just include the <reference> element (as obtained from 
>>the citation library) in your source.
>>
> 
> The above is laready quite a bit more typing (or paste/copy) work than I
> like, but doing #2 is not good at all I think. I think I'd have to
> redo it every time an I-D gets a new version, right?

Actually, referencing to an unspecified I-D version IMHO is a Bad Idea 
as well. For instance, section numbers may be changing without you ever 
noticing...

Best regards, Julian

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

From: [email-masked] (Wijnen, Bert (Bert))
Date: Thu, 27 May 2004 13:06:58 +0200
Subject: [xml2rfc] Updated template file
Message-ID: <[email-masked]>

> >>1) The document doesn't validate (<references> is empty).
> >>2) There are dangling references...
> >>
> >>This is because you are using the <?rfc include...> directive which IMHO 
> >>/MUST/ be deprecated. The file as posted is invalid XML and will only be 
> >>processed by one specific xml2rfc processor (Marshall's).
> >>
> > 
> > Can you show HOW one then  SHOULD do the reference?
> > 
> > I found the <?rfc include ...> one of the better things, so that
> > I do not have to recall (look up) all the details or current I-D 
> > version if I reference an internet draft.
> 
> As far as I can tell, there are two alternatives.
> 
> #1: follow the instructions on <http://xml.resource.org/> 
> (Helpful Hints 
> / Including files), or
> 
OK, so I got that to work for RFCs, but I seem to have trouble to get it to
work for I-Ds.

I have:

<!DOCTYPE rfc SYSTEM "rfc2629bis.dtd"
[
<!ENTITY rfc2578 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2578.xml'>
 <?ENTITY ietf-ipcdn-qos-mib PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-ipcdn-qos-mib.xml'>
]>

I then use in the text:

   <xref target="RFC2578"/>
   <xref target="I-D.ietf-ipcdn-qos-mib"/>

And in the back matter I have

<references title="Normative References">
&rfc2578;
&ietf-ipcdn-qos-mib;
</references>

So what am I doing frong here?

> #2: just include the <reference> element (as obtained from 
> the citation library) in your source.
> 
The above is laready quite a bit more typing (or paste/copy) work than I
like, but doing #2 is not good at all I think. I think I'd have to
redo it every time an I-D gets a new version, right?

Bert
> Best regards, Julian
> 
> -- 
> <green/>bytes GmbH -- http://www.greenbytes.de -- tel:+492512807760
> 

From: [email-masked] (Julian Reschke)
Date: Thu, 27 May 2004 11:38:18 +0200
Subject: [xml2rfc] Updated template file
In-Reply-To: <[email-masked]>
References: <[email-masked]>
Message-ID: <[email-masked]>

Wijnen, Bert (Bert) wrote:

>>1) The document doesn't validate (<references> is empty).
>>2) There are dangling references...
>>
>>This is because you are using the <?rfc include...> directive which IMHO 
>>/MUST/ be deprecated. The file as posted is invalid XML and will only be 
>>processed by one specific xml2rfc processor (Marshall's).
>>
> 
> Can you show HOW one then  SHOULD do the reference?
> 
> I found the <?rfc include ...> one of the better things, so that
> I do not have to recall (look up) all the details or current I-D 
> version if I reference an internet draft.

As far as I can tell, there are two alternatives.

#1: follow the instructions on <http://xml.resource.org/> (Helpful Hints 
/ Including files), or

#2: just include the <reference> element (as obtained from the citation 
library) in your source.

Best regards, Julian

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

From: [email-masked] (Wijnen, Bert (Bert))
Date: Thu, 27 May 2004 11:33:53 +0200
Subject: [xml2rfc] Updated template file
Message-ID: <[email-masked]>

> 1) The document doesn't validate (<references> is empty).
> 2) There are dangling references...
> 
> This is because you are using the <?rfc include...> directive which IMHO 
> /MUST/ be deprecated. The file as posted is invalid XML and will only be 
> processed by one specific xml2rfc processor (Marshall's).
> 
Can you show HOW one then  SHOULD do the reference?

I found the <?rfc include ...> one of the better things, so that
I do not have to recall (look up) all the details or current I-D 
version if I reference an internet draft.

Bert

From: [email-masked] (Julian Reschke)
Date: Thu, 27 May 2004 11:07:32 +0200
Subject: [xml2rfc] Updated template file
In-Reply-To: <[email-masked]>
References: <[email-masked]>
Message-ID: <[email-masked]>

Pekka Savola wrote:
> On Thu, 27 May 2004, Julian Reschke wrote:
> 
>>1) The document doesn't validate (<references> is empty).
>>2) There are dangling references...
>>
>>This is because you are using the <?rfc include...> directive which IMHO 
>>/MUST/ be deprecated. The file as posted is invalid XML and will only be 
>>processed by one specific xml2rfc processor (Marshall's).
> 
> 
> Which is just fine if you will just stick to using Marshall's xml2rfc 
> processor.

No, that's not "fine". RFC2629 defines an XML format with a DTD, so it 
is supposed to be validated. Sticking to a syntax that does not conform 
to the DTD is a Very Bad Idea, in particular in an example document.

> ..

Best regards, Julian

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

From: [email-masked] (Pekka Savola)
Date: Thu, 27 May 2004 11:50:39 +0300 (EEST)
Subject: [xml2rfc] Updated template file
In-Reply-To: <[email-masked]>
Message-ID: <[email-masked]>

On Thu, 27 May 2004, Julian Reschke wrote:
> 1) The document doesn't validate (<references> is empty).
> 2) There are dangling references...
> 
> This is because you are using the <?rfc include...> directive which IMHO 
> /MUST/ be deprecated. The file as posted is invalid XML and will only be 
> processed by one specific xml2rfc processor (Marshall's).

Which is just fine if you will just stick to using Marshall's xml2rfc 
processor.

The second approach shown by David seems a tad too cryptic to me.

-- 
Pekka Savola                 "You each name yourselves king, yet the
Netcore Oy                    kingdom bleeds."
Systems. Networks. Security. -- George R.R. Martin: A Clash of Kings

From: [email-masked] (Julian Reschke)
Date: Thu, 27 May 2004 09:37:08 +0200
Subject: [xml2rfc] Using the reference library
In-Reply-To: <[email-masked]>
References: <[email-masked]>
Message-ID: <[email-masked]>

David T. Perkins wrote:

> ...
> 
> So, which of these approaches should be used? (Or should another

As stated in my previous mail, documents using the rfc include PI aren't 
valid according to the DTD.

> approach be used, like put the reference info directly into
> the document?) Also, if one is authoring a collection of

I do the latter, because including XML entities from other servers may 
be rejected by XML-capable browsers, thus making the source file 
unusable on the web.

> documents, should the library approach be used, or should
> the members in the collection be directly specified in each
> document in the collection?
> 
> Regards,
> /david t. perkins

Best regards, Julian

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

From: [email-masked] (Julian Reschke)
Date: Thu, 27 May 2004 09:34:43 +0200
Subject: [xml2rfc] Updated template file
In-Reply-To: <[email-masked]>
References: <[email-masked]> <[email-masked]>
Message-ID: <[email-masked]>

David T. Perkins wrote:

> HI,
> 
> Attached is an updated template file. I want to work on it some more,
> but spent way too much time trying to figure out XML errors. I ended
> up switching to XMLspy, which provided me with useful error messages
> about XML errors. And I guess, that is a horrible problem with XML
> tools, in not being very helpful.
> 
> Let me know if you want to update the file. I've got a full day
> meeting scheduled for tomorrow, so I may not be able to apply
> updates until the evening.
> 
> Take care,
> /david t. perkins

1) The document doesn't validate (<references> is empty).
2) There are dangling references...

This is because you are using the <?rfc include...> directive which IMHO 
/MUST/ be deprecated. The file as posted is invalid XML and will only be 
processed by one specific xml2rfc processor (Marshall's).

Best regards,

Julian

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

From: [email-masked] (Julian Reschke)
Date: Thu, 27 May 2004 09:30:01 +0200
Subject: [xml2rfc] Attributes of <rfc>
In-Reply-To: <[email-masked]>
References: <[email-masked]> <[email-masked]>
Message-ID: <[email-masked]>

David T. Perkins wrote:

> ...
> What I meant by that is that the updates/obsoletes can be only numbers.
> Thus, you cannot say that you update, say, STD 1, and RFC 2000.

Those are always RFC numbers.

Best regards, Julian

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

From: [email-masked] (David T. Perkins)
Date: Wed, 26 May 2004 23:02:04 -0700
Subject: [xml2rfc] Updated template file
In-Reply-To: <[email-masked]>
References: <[email-masked]>
Message-ID: <[email-masked]>

--=====================_93956702==_
Content-Type: text/plain; charset="us-ascii"

HI,

Attached is an updated template file. I want to work on it some more,
but spent way too much time trying to figure out XML errors. I ended
up switching to XMLspy, which provided me with useful error messages
about XML errors. And I guess, that is a horrible problem with XML
tools, in not being very helpful.

Let me know if you want to update the file. I've got a full day
meeting scheduled for tomorrow, so I may not be able to apply
updates until the evening.

Take care,
/david t. perkins
--=====================_93956702==_
Content-Type: application/xml; name="template1b.xml"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="template1b.xml"

--=====================_93956702==_--

From: [email-masked] (David T. Perkins)
Date: Wed, 26 May 2004 22:56:23 -0700
Subject: [xml2rfc] Attributes of <rfc>
In-Reply-To: <[email-masked]>
References: <[email-masked]>
Message-ID: <[email-masked]>

HI,

At 06:22 AM 5/27/2004 +0300, Pekka Savola wrote:
>On Wed, 26 May 2004, David T. Perkins wrote:
>> In http://xml.resource.org/authoring/draft-mrose-writing-rfcs.html
>> (april 2, 2004 version, the description of the "rfc" element
>> (in the DTD), says that the attributes are supplied by the
>> RFC editor. However, in the example, you have specified attributes
>> "ipr", "category", "docName", "updates", and "obsoletes".
>> 
>> What are the instructions to follow?
>
>I'd fill those in because updates/obsoletes is seen by the folks, ipr 
>is needed, and category is just simply nice to have there ;-)

I did more research, and here is the text for the updated version
of the template:
    <!-- Information about the document.
         categories values: std, bcp, info, exp, and historic
         For Internet-Drafts, specify attribute "ipr".
         (ipr values are: full3667, noModification3667, noDerivatives3667),
         Also for Internet-Drafts, can specify values for
         attributes "iprExtract", and "docName".  Note
         that the value for iprExtract is the anchor attribute
         value of a section that can be extracted, and is only
         useful when the value of "ipr" is not "full3667". -->
    <!-- TODO: verify which attributes are specified only
            by the RFC editor.  It appears that attributes
            "number", "obsoletes", "updates", and "seriesNo"
            are specified by the RFC editor (and not by
            the document author). -->
 
>> By the way, the DTD doesn't seem to be allow a document to 
>> obsolete or update documents in different categories,
>> or in categories different from the category of the current
>> document. This seems too limiting to me.
>
>Uhh.. Sure?  I don't think updates/obsoletes has any dependence on 
>categories of documents being updated/obsoleted..
What I meant by that is that the updates/obsoletes can be only numbers.
Thus, you cannot say that you update, say, STD 1, and RFC 2000.

Regards,
/david t. perkins

From: [email-masked] (Pekka Savola)
Date: Thu, 27 May 2004 06:22:58 +0300 (EEST)
Subject: [xml2rfc] Attributes of <rfc>
In-Reply-To: <[email-masked]>
Message-ID: <[email-masked]>

On Wed, 26 May 2004, David T. Perkins wrote:
> In http://xml.resource.org/authoring/draft-mrose-writing-rfcs.html
> (april 2, 2004 version, the description of the "rfc" element
> (in the DTD), says that the attributes are supplied by the
> RFC editor. However, in the example, you have specified attributes
> "ipr", "category", "docName", "updates", and "obsoletes".
> 
> What are the instructions to follow?

I'd fill those in because updates/obsoletes is seen by the folks, ipr 
is needed, and category is just simply nice to have there ;-)
 
> By the way, the DTD doesn't seem to be allow a document to 
> obsolete or update documents in different categories,
> or in categories different from the category of the current
> document. This seems too limiting to me.

Uhh.. Sure?  I don't think updates/obsoletes has any dependence on 
categories of documents being updated/obsoleted..

-- 
Pekka Savola                 "You each name yourselves king, yet the
Netcore Oy                    kingdom bleeds."
Systems. Networks. Security. -- George R.R. Martin: A Clash of Kings

From: [email-masked] (David T. Perkins)
Date: Wed, 26 May 2004 15:36:00 -0700
Subject: [xml2rfc] Using the reference library
Message-ID: <[email-masked]>

HI,

It appears that there is at least two ways of using a library
of references (called the citation library on http://xml.resource.org/).

Your example used one way, which was to
 1) create a directory of files, each specifying the content for
    a reference
 2) populate the directory with reference files from the zip or
    tgz targets specified on http://xml.resource.org/
 3) in the appropriate reference section, use the "include"
    processing instruction to "pull in" the reference 
    definition text. For example,
       <references title="Normative References">
           <?rfc include="reference.RFC.2661" ?>
       </references>

However, on the main page for http://xml.resource.org/, another
approach is show, which is the following to include the definitions
of references to RFC 2119 RFC 2629 and 
  1) in the beginning of the XML document, insert the following
     <!DOCTYPE rfc SYSTEM 'rfc2629.dtd' [
         <!ENTITY rfc2119 PUBLIC ''
           'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>
         <!ENTITY rfc2629 PUBLIC '' 
           'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2629.xml'>
     ]>
  2) in the appropriate references section, expand each XML macro,
     such as:
       <references title="Normative References">
           &rfc2119;
       </references>

So, which of these approaches should be used? (Or should another
approach be used, like put the reference info directly into
the document?) Also, if one is authoring a collection of
documents, should the library approach be used, or should
the members in the collection be directly specified in each
document in the collection?

Regards,
/david t. perkins

From: [email-masked] (Marshall Rose)
Date: Wed, 26 May 2004 15:11:54 -0700
Subject: [xml2rfc] Problem with escapings
In-Reply-To: <4.2.0.58.J.20040509210922.05be1300@localhost>
References: <4.2.0.58.J.20040509210922.05be1300@localhost>
Message-ID: <[email-masked]>

On May 26, 2004, at 02:26, Martin Duerst wrote:

> I'm using version 1.23 of xml2rfc, and maybe this has already been
> reported or fixed:

it was reported and fixed.

/mtr

From: [email-masked] (David T. Perkins)
Date: Wed, 26 May 2004 15:08:41 -0700
Subject: [xml2rfc] Attributes of <rfc>
In-Reply-To: <[email-masked]>
References: <[email-masked]>
Message-ID: <[email-masked]>

HI,

In http://xml.resource.org/authoring/draft-mrose-writing-rfcs.html
(april 2, 2004 version, the description of the "rfc" element
(in the DTD), says that the attributes are supplied by the
RFC editor. However, in the example, you have specified attributes
"ipr", "category", "docName", "updates", and "obsoletes".

What are the instructions to follow?

By the way, the DTD doesn't seem to be allow a document to 
obsolete or update documents in different categories,
or in categories different from the category of the current
document. This seems too limiting to me.

Regards,
/david t. perkins

From: [email-masked] (David T. Perkins)
Date: Wed, 26 May 2004 14:55:21 -0700
Subject: [xml2rfc] Processing instructions
Message-ID: <[email-masked]>

HI,

The file http://xml.resource.org/authoring/README.html lists
processing instructions in section 4.1.1.

1) Are the values for "subcompact" only "yes" and "no", or is
   "compact" also a valid value?

2) What is the behavior of the "editing='yes'" processing
   instruction. That is, it seems like you need to have access
   to older versions of a document.

3) It seems like "iprnotified" overlaps with the value of attribute
   "ipr" in element "rfc". What is suppose to be used? That is,
    is "iprnotified" obsolete?

Regards,
/david t. perkins

From: [email-masked] (Marshall Rose)
Date: Wed, 26 May 2004 06:04:38 -0700
Subject: [xml2rfc] New ID-Checklist to replace ID-nits (fwd)
In-Reply-To: <[email-masked]>
References: <[email-masked]>
Message-ID: <[email-masked]>

hi. it's a good start. just two things:

you have

	<area>Operations & Management</area>

which should be

	<area>Operations &amp; Management</area>

also, you may want to consider formatting your comments with more 
whitespace in the source in order to make it more readible to folks.

/mtr

From: [email-masked] (Pekka Savola)
Date: Wed, 26 May 2004 12:44:11 +0300 (EEST)
Subject: [xml2rfc] New ID-Checklist to replace ID-nits (fwd)
In-Reply-To: <[email-masked]>
Message-ID: <[email-masked]>

  This message is in MIME format.  The first part should be readable text,
  while the remaining parts are likely unreadable without MIME-aware tools.
  Send mail to [email-masked] for more info.

--1589707168-188463868-1085564651=:6748
Content-Type: TEXT/PLAIN; charset=US-ASCII

FWIW, 

I got an inspiration for this myself, and I created a reasonably short 
template which should cover the most important issues to every 
potential new xml2rfc user.

This should cut the learning curve a bit..

Comments, etc. welcome of course.

On Wed, 26 May 2004, Pekka Savola wrote:
> One thing which could still be improved here, which may fall under the 
> EDU team charter, but is probably a thing to be worked out by xml2rfc 
> folks in practice..
> 
> When I've educated people to use xml2rfc, I've been a bit annoyed that
> there is no easily referenceable, simple to use "xml2rfc skeleton
> draft" which would show the most tricks of the trade to the users.  
> And in most cases, I've had a dialogue of 2-3 messages, sending and
> explaining a couple of my own .xml files, with the folks.
> 
> I mean, you can figure out mostly based on the hints, reading through 
> RFC2629(bis) pages, etc. -- but this is too heavyweight a process, and 
> the users will miss important clues.
> 
> What I'd be interested in seeing a fully working template, including
> the most important options (commented out or not), the typical
> sections, the examples of how to manage the RFC/I-D references and
> section cross-references, a bulleted/numbered list, etc. -- the basic
> stuff.  The template might also include a few explanations on the
> typical xml2rfc error messages ("check that you're terminating the
> elements properly") but this is not necessary.
> 
> In short, I think there would be *very* much use to a have a simple
> and easily referenceable .xml -formatted text file that could just be
> taken to use intuitively by about every half-intelligent person,
> without having to start scratching the head.
> 
> Any volunteers for cooking up something like this?
> 
> ---------- Forwarded Message ----------
> Date: 20. mai 2004 09:34 -0400
> From: The IESG <[email-masked]>
> To: IETF-Announce
> Subject: New ID-Checklist to replace ID-nits
> 
>     As you probably all know, we have used the ID-nits for a few
>     years to help you all to prepare your Internet-Drafts such that
>     they will process faster through the AD-review, IETF Last Call
>     and IESG approval process.
> 
>     The name was somewhat wrong in that it is more a serious checklist
>     than merely "nits" (however, there are some nits too).
>     The IESG, RFC-Editor and IANA have evaluated the checklist, and
>     a new (improved) ID-Checklist is now available at
> 
>             http://www.ietf.org/ID-Checklist.html
> 
>     Please help us all by actually CHECKING your Internet-Draft BEFORE
>     you pass it on to your AD and the IESG via a "request to publish".
>     It will help to make the process go faster and reduce the workload
>     on all of us if your document has been checked and complies with
>     the guidance/rules in the ID-Checklist.
> 
>     Thanks, the IESG
> 
> 
> _______________________________________________
> IETF-Announce mailing list
> [email-masked]
> https://www1.ietf.org/mailman/listinfo/ietf-announce
> 
> 
> 
> ---------- End Forwarded Message ----------
> 
> 
> 
> 
> 
> 
> 
> _______________________________________________
> xml2rfc mailing list
> [email-masked]
> http://lists.xml.resource.org/mailman/listinfo/xml2rfc
> 

-- 
Pekka Savola                 "You each name yourselves king, yet the
Netcore Oy                    kingdom bleeds."
Systems. Networks. Security. -- George R.R. Martin: A Clash of Kings

--1589707168-188463868-1085564651=:6748
Content-Type: TEXT/xml; name="template.xml"
Content-Transfer-Encoding: BASE64
Content-ID: <[email-masked]>
Content-Description: 
Content-Disposition: attachment; filename="template.xml"

--1589707168-188463868-1085564651=:6748--

From: [email-masked] (Martin Duerst)
Date: Wed, 26 May 2004 18:26:00 +0900
Subject: [xml2rfc] Problem with escapings
Message-ID: <4.2.0.58.J.20040509210922.05be1300@localhost>

I'm using version 1.23 of xml2rfc, and maybe this has already been
reported or fixed:

If I put the following in the XML source:   "D&amp;#252;rst"
I get "Durst" in the .txt output, and "D&#252;rst" in the HTML
*source* output.

You might think that in particular the later is what I want,
but in this case it is not. A "&amp;" in the XML input stands
for a literal "&", and what follows are therefore also literal
characters, not to be messed with, and "D&#252;rst" should
therefore appear both in the .txt output as well as in the
HTML as viewed (which means that the HTML source has to look
like "D&amp;#252;rst" or some such.

  To check, please have a look at
http://www.w3.org/International/iri-edit/draft-duerst-iri.xml,
http://www.w3.org/International/iri-edit/draft-duerst-iri.txt, and
http://www.w3.org/International/iri-edit/draft-duerst-iri.html.

The problem seems to occur only in this one instance. It could
be that attribute values are (wrongly) treated differently form
element content.

Regards,    Martin. 

From: [email-masked] (Pekka Savola)
Date: Wed, 26 May 2004 01:09:19 +0300 (EEST)
Subject: [xml2rfc] New ID-Checklist to replace ID-nits (fwd)
Message-ID: <[email-masked]>

Hi,

One thing which could still be improved here, which may fall under the 
EDU team charter, but is probably a thing to be worked out by xml2rfc 
folks in practice..

When I've educated people to use xml2rfc, I've been a bit annoyed that
there is no easily referenceable, simple to use "xml2rfc skeleton
draft" which would show the most tricks of the trade to the users.  
And in most cases, I've had a dialogue of 2-3 messages, sending and
explaining a couple of my own .xml files, with the folks.

I mean, you can figure out mostly based on the hints, reading through 
RFC2629(bis) pages, etc. -- but this is too heavyweight a process, and 
the users will miss important clues.

What I'd be interested in seeing a fully working template, including
the most important options (commented out or not), the typical
sections, the examples of how to manage the RFC/I-D references and
section cross-references, a bulleted/numbered list, etc. -- the basic
stuff.  The template might also include a few explanations on the
typical xml2rfc error messages ("check that you're terminating the
elements properly") but this is not necessary.

In short, I think there would be *very* much use to a have a simple
and easily referenceable .xml -formatted text file that could just be
taken to use intuitively by about every half-intelligent person,
without having to start scratching the head.

Any volunteers for cooking up something like this?

---------- Forwarded Message ----------
Date: 20. mai 2004 09:34 -0400
From: The IESG <[email-masked]>
To: IETF-Announce
Subject: New ID-Checklist to replace ID-nits

    As you probably all know, we have used the ID-nits for a few
    years to help you all to prepare your Internet-Drafts such that
    they will process faster through the AD-review, IETF Last Call
    and IESG approval process.

    The name was somewhat wrong in that it is more a serious checklist
    than merely "nits" (however, there are some nits too).
    The IESG, RFC-Editor and IANA have evaluated the checklist, and
    a new (improved) ID-Checklist is now available at

            http://www.ietf.org/ID-Checklist.html

    Please help us all by actually CHECKING your Internet-Draft BEFORE
    you pass it on to your AD and the IESG via a "request to publish".
    It will help to make the process go faster and reduce the workload
    on all of us if your document has been checked and complies with
    the guidance/rules in the ID-Checklist.

    Thanks, the IESG

_______________________________________________
IETF-Announce mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/ietf-announce

---------- End Forwarded Message ----------

From: [email-masked] (Alex Rousskov)
Date: Fri, 21 May 2004 09:10:53 -0600 (MDT)
Subject: [xml2rfc] List style "format"
In-Reply-To: <[email-masked]>
References: <[email-masked]> <[email-masked]>
Message-ID: <[email-masked]>

On Fri, 21 May 2004, Julian Reschke wrote:

> The issue here is -- what do you do with xrefs to "LMRed" when they
> occur outside the scope of the list? After all, the list entry names
> aren't guaranteed to be unique across the document...

These are different issues, I think. The first issue is how to "name"
what we want to reference (i.e., how to render the reference). We know
how to render <section>, <figure>, or bibliography references. We do
not know how to render references to list items. Generating "list item
R1" is probably not always appropriate.

As you know, LaTeX solution to this problem is to allow the author to
name things that do not have standard names. LaTeX just provides a
number that is rendered to the right from the named object. The author
can then say
	Figure~\ref{LMRed}
or
	Expression~\ref{LMRed}
or
	requirement~\ref{LMRed}

This requires placing a number somewhere next to the object. In RFCs
this can be done on the left margin (although that may break some RFC
processing scripts):

(1)   R1:
          description of Red requirement
(2)   R2:
          description of blue. And a xref to R1.

It might be a good idea to let the author assign the label explicitly
instead of relying on auto-generated numbers.

(Red)  R1:
          description of Red requirement
(Blue) R2:
          description of blue. And a xref to R1.

However, there is not much space for these.

Overall, it feels like it would be difficult to overcome plain RFC
formatting limitations to implement anchor-for-anything feature.

As for uniqueness of anchors, it should be author responsibility.
Tools can warn authors if anchors are not unique. Same for labels if
they are author-generated.

Alex.

From: [email-masked] (Pekka Savola)
Date: Fri, 21 May 2004 15:44:04 +0300 (EEST)
Subject: [xml2rfc] Norm/Inform bug with strict
In-Reply-To: <[email-masked]>
Message-ID: <[email-masked]>

On Fri, 21 May 2004, Julian Reschke wrote:
> David T. Perkins wrote:
> > ...
> > There also seems to be a bug that if you specify element
> >   <references title="Normative References">
> > it doesn't check that you have element
> >   <references title="Informative References">
> > (In general, it is desirable that if you specify two "references"
> > elements, then it would title the first "Normative References"
> > and the second "Informative References". Also, this should work
> > with "strict='yes'", and it should check that there is either
> > one or two "references" elements.)
> 
> I'm not sure I follow. It should be perfectly not to have informative 
> references at all, right?

For what it's worth, if we want to be fascists, we could (in strict 
mode) check and complain if there is a section called 
(simply) 'References'.

-- 
Pekka Savola                 "You each name yourselves king, yet the
Netcore Oy                    kingdom bleeds."
Systems. Networks. Security. -- George R.R. Martin: A Clash of Kings

From: [email-masked] (Julian Reschke)
Date: Fri, 21 May 2004 12:30:00 +0200
Subject: [xml2rfc] ANN: experimental support for cref in rfc2629.xslt and friends
Message-ID: <[email-masked]>

Hi,

rfc2629.xslt now has experimental support for the new "cref" element 
(get it from <http://greenbytes.de/tech/webdav/rfc2629xslt.zip>).

Related question: what's the expectation for both inline=yes and 
inline=no for paged media such as PDF? Currently, rfc2629toFO.xslt will 
generate footnotes for inline=no and inline-text for inline=yes.

Feedback appreciated,

Julian

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

From: [email-masked] (Julian Reschke)
Date: Fri, 21 May 2004 12:26:04 +0200
Subject: [xml2rfc] Norm/Inform bug with strict
In-Reply-To: <[email-masked]>
References: <[email-masked]>
Message-ID: <[email-masked]>

David T. Perkins wrote:

> ...
> There also seems to be a bug that if you specify element
>   <references title="Normative References">
> it doesn't check that you have element
>   <references title="Informative References">
> (In general, it is desirable that if you specify two "references"
> elements, then it would title the first "Normative References"
> and the second "Informative References". Also, this should work
> with "strict='yes'", and it should check that there is either
> one or two "references" elements.)

I'm not sure I follow. It should be perfectly not to have informative 
references at all, right?

 > ...

Best regards, Julian

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

From: [email-masked] (Julian Reschke)
Date: Fri, 21 May 2004 12:24:35 +0200
Subject: [xml2rfc] List style "format"
In-Reply-To: <[email-masked]>
References: <[email-masked]>
Message-ID: <[email-masked]>

David T. Perkins wrote:

> I'm have a difficult time figuring out how to use the attribute
> style with value format for element "list". I can see that you
> can generate a list member identifier, but it seems like the
> feature is incomplete. That is, it seems like members of
> a list should be another element type other than "t", where
> an "anchor" attribute could be used. That way you could then
> xref the generated list member elements. For example, say,
> "lm" was used instead "t", and the following:
>    <list style="format R%d:">
>       <lm anchor="LMred">description of Red requirement</lm>
>       <lm anchor="LMblue">description of blue. And
>            a xref to <xref target="LMred"/>.</lm>
>    </list>
> Which would result in
>   R1:
>      description of Red requirement
>   R2:
>      description of blue. And a xref to R1.

Interesting idea (in general I do agree that any element should allow an 
anchor attribute, btw).

The issue here is -- what do you do with xrefs to "LMRed" when they 
occur outside the scope of the list? After all, the list entry names 
aren't guaranteed to be unique across the document...

Best regards, Julian

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

From: [email-masked] (David T. Perkins)
Date: Wed, 19 May 2004 11:38:38 -0700
Subject: [xml2rfc] List style "format"
Message-ID: <[email-masked]>

HI,

I'm have a difficult time figuring out how to use the attribute
style with value format for element "list". I can see that you
can generate a list member identifier, but it seems like the
feature is incomplete. That is, it seems like members of
a list should be another element type other than "t", where
an "anchor" attribute could be used. That way you could then
xref the generated list member elements. For example, say,
"lm" was used instead "t", and the following:
   <list style="format R%d:">
      <lm anchor="LMred">description of Red requirement</lm>
      <lm anchor="LMblue">description of blue. And
           a xref to <xref target="LMred"/>.</lm>
   </list>
Which would result in
  R1:
     description of Red requirement
  R2:
     description of blue. And a xref to R1.

Regards,
/david t. perkins

From: [email-masked] (David T. Perkins)
Date: Wed, 19 May 2004 11:04:21 -0700
Subject: [xml2rfc] Norm/Inform bug with strict
Message-ID: <[email-masked]>

HI,

It appears to me that the logic when "strict='yes'" and "symref='no'"
is incorrect. To reproduce, take the sample.xml file and change
"symref='yes'" to "symref='no'".
There also seems to be a bug that if you specify element
  <references title="Normative References">
it doesn't check that you have element
  <references title="Informative References">
(In general, it is desirable that if you specify two "references"
elements, then it would title the first "Normative References"
and the second "Informative References". Also, this should work
with "strict='yes'", and it should check that there is either
one or two "references" elements.)

Also, the documentation for xml2rfc has nothing that I could find
about the issue of using "Normative References" and "Informative
References" instead of just "References".

Regards,
/david t. perkins

From: [email-masked] (Julian Reschke)
Date: Mon, 17 May 2004 10:40:13 +0200
Subject: [xml2rfc] References between two documents
In-Reply-To: <[email-masked]>
References: <[email-masked]>
Message-ID: <[email-masked]>

Clive D.W. Feather wrote:
> The documentation for xml2rfc says that I can write &rfc.number; and get
> the number of the RFC I'm writing (substituted by XXXX at the I-D stage).
> 
> It now looks like our document will be split into two, published
> simultaneously, with each referring to the other. Is there any particular
> way to do this, or will I have to edit every reference when we reach RFC
> publication?

Side note: that notation IMHO produces non-wellformed XML (it's an 
undefined entity, right?), and thus won't work with rfc2629.xslt. If 
this is a feature that is really needed, it will need to be supported 
differently...

Best regards, Julian

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

From: [email-masked] (Clive D.W. Feather)
Date: Mon, 17 May 2004 08:43:14 +0100
Subject: [xml2rfc] References between two documents
Message-ID: <[email-masked]>

The documentation for xml2rfc says that I can write &rfc.number; and get
the number of the RFC I'm writing (substituted by XXXX at the I-D stage).

It now looks like our document will be split into two, published
simultaneously, with each referring to the other. Is there any particular
way to do this, or will I have to edit every reference when we reach RFC
publication?

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

From: [email-masked] (Glen Zorn)
Date: Sun, 16 May 2004 15:32:30 -0700
Subject: [xml2rfc] Entity References and Imported? Processing Instructions
In-Reply-To: <[email-masked]>
Message-ID: <[email-masked]>

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

> Julian Reschke wrote:
> 
>> Hollenbeck, Scott wrote:
>> 
>>> ...
>>> So what's going on here?  Is this an XML parser error, or is
>>> xml2rfc doing something funny with the PI found in the imported
>>> reference?  If I copy all of the reference XML elements into the
>>> document to replace the entity reference (less the PI) it all works
>>> fine. 
>> 
>> 
>> I'm not entirely sure why this is the case, but the parsers (same for
>> MSXML and XML-parser-built-into-Saxon) require that the external
>> entitiy declares it's encoding.
> 
> (Google to the rescue...)
> 
>  From <http://www.w3.org/TR/REC-xml/#sec-TextDecl>:
> 
> [77] TextDecl ::=   	'<?xml' VersionInfo? EncodingDecl S? '?>'

This seems to imply that many (if not all) of the references at
xml.resource.org are incorrect.
BTW, I'm getting the same kind of error from XMLSpy -- not being an XML
expert, I thought that it was a bug in the verifier...

> 
> Best regards, Julian

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] (Julian Reschke)
Date: Sun, 16 May 2004 21:16:51 +0200
Subject: [xml2rfc] experimental iref element extension
In-Reply-To: <[email-masked]>
References: <[email-masked]> <[email-masked]> <[email-masked]>
Message-ID: <[email-masked]>

David T. Perkins wrote:

> HI,
> 
> Also, can the tools generate a "dependency" list. That is, take the
> normative and non-normative refs and expand out the ancestors. And
> then for each ancestor, create a lists of direct, one-level indirect,
> two-level-indirect, etc (with pruning so only the "closest" reference
> is listed). That way, we would know for a collection of documents
> (such as RFCs) that if a referenced document was updated, then
> all of the possibly affected documents.

This is an interesting idea, but of course requires that you have all 
the involved documents in RFC2629 format.

In the meantime, I have enhanced "check-ietf-references.xslt" to also 
print out the standards state and possibly alternate names for a 
referenced document, such as:

    > saxon rfc2518.xml check-ietf-references.xslt
    Normative References:
    RFC1766: [PROPOSED STANDARD] obsoleted by RFC3066 RFC3282
    RFC2277: [BEST CURRENT PRACTICE] (-> BCP0018) ok
    RFC2119: [BEST CURRENT PRACTICE] (-> BCP0014) ok
    RFC2396: [DRAFT STANDARD] ok
    RFC2069: [PROPOSED STANDARD] obsoleted by RFC2617
    RFC2068: [PROPOSED STANDARD] obsoleted by RFC2616
    RFC2141: [PROPOSED STANDARD] ok
    RFC2279: [PROPOSED STANDARD] obsoleted by RFC3629
    Informational References:
    RFC2026: [BEST CURRENT PRACTICE] (-> BCP0009) ok
    RFC1807: [INFORMATIONAL] ok
    RFC2291: [INFORMATIONAL] ok
    RFC2413: [INFORMATIONAL] ok
    RFC2376: [INFORMATIONAL] obsoleted by RFC3023

(check-ietf-references.xslt is part of my rfc2629xslt distribution 
available from <http://greenbytes.de/tech/webdav/rfc2629xslt.zip>).

Note that for automatic checks, it would be nice if there'd be a way to 
identify those "references" elements that in fact contain normative 
references...

Best regards, Julian

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

From: [email-masked] (Julian Reschke)
Date: Sun, 16 May 2004 21:08:51 +0200
Subject: [xml2rfc] experimental iref element extension
In-Reply-To: <[email-masked]>
References: <[email-masked]> <[email-masked]>
Message-ID: <[email-masked]>

Marshall Rose wrote:

> this is really cool. rob austein has been asking for similar 
> functionality, the ability to <xref/> between documents (like me, he's a 
> fan of LaTeX!) in other words, he'd like the use of <xref/> in a 
> document to produce a file that other documents could use...

I'm not sure I understand this one (although I've been using LaTeX as 
well, but it's /really/ a long time ago).

Are we talking about something like <xref target="x" fragment="y"/>, 
where -- given that "x" identifies a reference elemen -- we're adressing 
the fragment (in URI speak) "y" of that document? Such as:

<xref target="RFC2616" fragment="rfc.section.3" />

could be rendered as link to 
<http://greenbytes.de/tech/webdav/rfc2616.html#rfc.section.3>?

I think that would be great, but that would require:

- either known locations for various variants of the document (possibly 
already covered by reference/format)

- consistent fragment identifiers inside the generally used 
representations (right now, not even xml2rfc and rfc2629.xslt produce 
consistent document anchors)

> i think if we can come up with a minimalist solution to address both 
> kinds of extensions, we should do it.

I'm not sure there's really overlap, but I'll be happy to work on both.

What *I* need is the ability to have iref elements to point to other 
documents; this basically requires additional information for

- display information for rendering the reference (basically a shorthand 
name for the document, and the section number to point to)
- the actual URI for the link target

Such as in:

          <iref x:basedoc="rfc2518" x:section-number="9.3" 
x:anchor="rfc2518.html#rfc.iref.29" item="Headers" subitem="Destination" 
primary="true"/>

(this is what I'm currently using experimentally).

An alternative design would make it more abstract (however it would also 
make processing more expensive; not sure whether this matters here):

          <iref x:basedoc="rfc2518.xml" x:iref-number="123" />

(this one would point to the 123rd iref in rfc2518.xml -- the processor 
would need to actually access that document to pull out the actual 
information.

Best regards, Julian

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

From: [email-masked] (Julian Reschke)
Date: Fri, 14 May 2004 19:54:14 +0200
Subject: [xml2rfc] Entity References and Imported? Processing Instructions
In-Reply-To: <[email-masked]>
References: <[email-masked]> <[email-masked]>
Message-ID: <[email-masked]>

Julian Reschke wrote:

> Hollenbeck, Scott wrote:
> 
>> ...
>> So what's going on here?  Is this an XML parser error, or is xml2rfc 
>> doing
>> something funny with the PI found in the imported reference?  If I 
>> copy all
>> of the reference XML elements into the document to replace the entity
>> reference (less the PI) it all works fine.
> 
> 
> I'm not entirely sure why this is the case, but the parsers (same for 
> MSXML and XML-parser-built-into-Saxon) require that the external entitiy 
> declares it's encoding.

(Google to the rescue...)

 From <http://www.w3.org/TR/REC-xml/#sec-TextDecl>:

[77] TextDecl ::=   	'<?xml' VersionInfo? EncodingDecl S? '?>'

Best regards, Julian

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

From: [email-masked] (Julian Reschke)
Date: Fri, 14 May 2004 19:15:46 +0200
Subject: [xml2rfc] Entity References and Imported? Processing Instructions
In-Reply-To: <[email-masked]>
References: <[email-masked]>
Message-ID: <[email-masked]>

Hollenbeck, Scott wrote:

> ...
> So what's going on here?  Is this an XML parser error, or is xml2rfc doing
> something funny with the PI found in the imported reference?  If I copy all
> of the reference XML elements into the document to replace the entity
> reference (less the PI) it all works fine.

I'm not entirely sure why this is the case, but the parsers (same for 
MSXML and XML-parser-built-into-Saxon) require that the external entitiy 
declares it's encoding.

Best regards, Julian

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

From: [email-masked] (Hollenbeck, Scott)
Date: Fri, 14 May 2004 12:57:56 -0400
Subject: [xml2rfc] Entity References and Imported? Processing Instruct ions
Message-ID: <[email-masked]>

> So what's going on here?  Is this an XML parser error, or is 
> xml2rfc doing
> something funny with the PI found in the imported reference?  
> If I copy all
> of the reference XML elements into the document to replace the entity
> reference (less the PI) it all works fine.

Sorry, the way I asked this question makes it sound like there's a problem
with xml2rfc.  There's not; it seems to work just fine.

What I'm trying to determine is if there's a problem with the 2629
_structure_ of the XML instance or if there's a problem with the parser.
Sorry if that wasn't clear.

-Scott-

From: [email-masked] (Hollenbeck, Scott)
Date: Fri, 14 May 2004 12:16:32 -0400
Subject: [xml2rfc] Entity References and Imported? Processing Instructions
Message-ID: <[email-masked]>

paf just asked me a question about xml2rfc processing of entity references
that has me a bit confused, so I figured I'd try asking here.  He ran into a
situation with an XML editor (<oXygen/>) that's throwing an error when
trying to validate an XML instance that uses an entity reference for a
reference document, and I've just confirmed that Xerces-J throws the same
error.

Suppose one has an XML instance that starts like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd"
[
  <!ENTITY rfc2119 PUBLIC '' 
   'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>

and then down in the document's "References" section, we do this:

<references title="Normative References">      
  &rfc2119;

The XML for the RFC 2119 reference starts like this:

<?xml version="1.0" ?> 
<reference anchor="RFC2119">

Xerces-J complains when trying to validate the document:

"[Fatal Error] reference.RFC.2119.xml:1:20: More pseudo attributes are
expected."

It shouldn't be asking for more attributes in the PI, because they're
optional.  Then again, the PI shouldn't actually get imported into the
reference because that would/should force an error like this:

" The processing instruction target matching "[xX][mM][lL]" is not allowed."

So what's going on here?  Is this an XML parser error, or is xml2rfc doing
something funny with the PI found in the imported reference?  If I copy all
of the reference XML elements into the document to replace the entity
reference (less the PI) it all works fine.

-Scott-

From: [email-masked] (Glen Zorn)
Date: Mon, 10 May 2004 16:30:54 -0700
Subject: [xml2rfc] Bug in <list style="letters"> ??
In-Reply-To: <[email-masked]>
Message-ID: <[email-masked]>

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

> I am using v1.24 and it seems that
> 
>     <list style="letters">
>       <t>Required if IANA has to create a new registry or modify
>          rules for an existing registry.
>       </t>
>       <t>Required if the document requires IANA to assign or update
>          values in an IANA registry before RFC publication.
>       </t>
>       <t>See <xref target="RFC2434"/> and also <xref
>          target="RFC2780"/> in some cases.
>       </t>
>     </list>
> 
> generates an extra new-line in the HTML output:
> 
>    A
>        Required if IANA has to create a new registry or modify rules
>        for an existing registry.
>    B
>        Required if the document requires IANA to assign or update
>        values in an IANA registry before RFC publication.
>    C
>        See [RFC2434] and also[RFC2780]in some cases.
> 
> Is that a bug ?? Does not happen for bulleted or numbered lists.

Also doesn't seem to happen for hanging list (though I really wish it
did).

> 
> Thanks,
> Bert
> _______________________________________________
> 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] (Wijnen, Bert (Bert))
Date: Tue, 11 May 2004 00:41:58 +0200
Subject: [xml2rfc] Bug in <list style="letters"> ??
Message-ID: <[email-masked]>

I am using v1.24 and it seems that 

    <list style="letters">
      <t>Required if IANA has to create a new registry or modify
         rules for an existing registry.
      </t>
      <t>Required if the document requires IANA to assign or update
         values in an IANA registry before RFC publication.
      </t>
      <t>See <xref target="RFC2434"/> and also <xref target="RFC2780"/>
         in some cases.
      </t>
    </list>

generates an extra new-line in the HTML output:

   A 
       Required if IANA has to create a new registry or modify rules
       for an existing registry. 
   B 
       Required if the document requires IANA to assign or update values
       in an IANA registry before RFC publication. 
   C 
       See [RFC2434] and also[RFC2780]in some cases. 

Is that a bug ?? Does not happen for bulleted or numbered lists.

Thanks,
Bert 

From: [email-masked] (Marshall Rose)
Date: Mon, 10 May 2004 13:09:38 -0700
Subject: v1.24 released (was: Re: [xml2rfc] v1.25 released)
In-Reply-To: <[email-masked]>
References: <[email-masked]> <[email-masked]>
Message-ID: <[email-masked]>

On May 10, 2004, at 11:13, Jonathan Lennox wrote:

> Was there a typo in the subject line?  It looks like 1.24 is the most 
> recent
> version in <http://xml.resource.org/authoring/>.

yes, that was a typo.

/mtr

From: [email-masked] (Jonathan Lennox)
Date: Mon, 10 May 2004 14:13:10 -0400
Subject: [xml2rfc] v1.25 released
In-Reply-To: <[email-masked]>
References: <[email-masked]>
Message-ID: <[email-masked]>

On Friday, May 7 2004, "Marshall Rose" wrote to "xml2rfc mailing list" saying:

> this version has a lot of fixes to the nroff output, courtesy of Clive 
> DW Feather
> 
> also, the <cref/> element is now finalized
> 
> finally, the usual collection of bug fixes

Was there a typo in the subject line?  It looks like 1.24 is the most recent
version in <http://xml.resource.org/authoring/>.

-- 
Jonathan Lennox
[email-masked]

From: [email-masked] (Carl Malamud)
Date: Sat, 8 May 2004 11:53:35 -0700 (PDT)
Subject: [xml2rfc] experimental iref element extension
In-Reply-To: <[email-masked]>
Message-ID: <[email-masked]>

> However, this requires a relatively small extension in the <iref> 
> element, namely adding optional attributes to specify the name of the 
> target document, the section number and possibly an anchor, such as in...
> 
>           <iref x:basedoc="rfc2518" x:section-number="9.3" 
> x:anchor="rfc2518.html#rfc.iref.29" item="Headers" subitem="Destination" 
> primary="true"/>
> 

I agree with Marshall that this is really cool, and that there ought to be
a way to do the same thing on iref and xref.

For xref, we know we have a reference at the end.  If that reference has
format tags, a processor ought to be able to build an appropriate
reference.  

It sure would be nice to move a lot of that stuff out of the iref tag
or xref tag, since you might be referring to the same basedoc 
numerous times.

FWIW, the way docbook handles this is they make you do a scan of each
external document in question, build an index, and then you include
that index with your source doc when you're processing it.  I'm about
90% sure that's wrong for 2629, but I'm just throwing it out as an
example of existing practice.

Docbook calls these things olinks:

http://www.dpawson.co.uk/docbook/styling/linking.html

Doxygen, a source code documentation system uses a similar preprocessing
step for what they call doxytags:

http://www.stack.nl/~dimitri/doxygen/external.html

Again, I find this extra step pretty distasteful and maybe hard to handle.
What if I want to reference an anchor in a document outside my network and
I don't have the xml source, but I do know where the text, tml, pdf, and
nroff transformations of the document live?  Or, conversely, I have the
xml, but don't know where the html and txt transformations are going to live.

Regards,

Carl  

From: [email-masked] (David T. Perkins)
Date: Sat, 08 May 2004 11:36:26 -0700
Subject: [xml2rfc] experimental iref element extension
In-Reply-To: <[email-masked]>
References: <[email-masked]> <[email-masked]>
Message-ID: <[email-masked]>

HI,

Also, can the tools generate a "dependency" list. That is, take the
normative and non-normative refs and expand out the ancestors. And
then for each ancestor, create a lists of direct, one-level indirect,
two-level-indirect, etc (with pruning so only the "closest" reference
is listed). That way, we would know for a collection of documents
(such as RFCs) that if a referenced document was updated, then
all of the possibly affected documents.

At 10:29 AM 5/8/2004 -0700, Marshall Rose wrote:
>this is really cool. rob austein has been asking for similar functionality, the ability to <xref/> between documents (like me, he's a fan of LaTeX!) in other words, he'd like the use of <xref/> in a document to produce a file that other documents could use...
>
>i think if we can come up with a minimalist solution to address both kinds of extensions, we should do it.
>
>/mtr

Regards,
/david t. perkins 

From: [email-masked] (Marshall Rose)
Date: Sat, 8 May 2004 10:29:43 -0700
Subject: [xml2rfc] experimental iref element extension
In-Reply-To: <[email-masked]>
References: <[email-masked]>
Message-ID: <[email-masked]>

this is really cool. rob austein has been asking for similar 
functionality, the ability to <xref/> between documents (like me, he's 
a fan of LaTeX!) in other words, he'd like the use of <xref/> in a 
document to produce a file that other documents could use...

i think if we can come up with a minimalist solution to address both 
kinds of extensions, we should do it.

/mtr

From: [email-masked] (Julian Reschke)
Date: Sat, 08 May 2004 13:57:51 +0200
Subject: [xml2rfc] experimental iref element extension
Message-ID: <[email-masked]>

Hi,

I'm experimenting with generating compound index documents from a set of 
rfc2629-formatted documents. For example, this document

	<http://greenbytes.de/tech/webdav/common-index.html>

summarizes all index entries of WebDAV and related specs.

Auto-generating things like this is relatively simple, as long as all 
documents use a consistent style to add things to the index (such as 
HTTP header names or Method names). If this is the case, all the index 
entries can simply be thrown together, and formatted inside one document.

However, this requires a relatively small extension in the <iref> 
element, namely adding optional attributes to specify the name of the 
target document, the section number and possibly an anchor, such as in...

          <iref x:basedoc="rfc2518" x:section-number="9.3" 
x:anchor="rfc2518.html#rfc.iref.29" item="Headers" subitem="Destination" 
primary="true"/>

I'm currently supporting that as extension in rfc2629.xslt, but to 
produce a TXT version from that (for instance, if you would want to 
publish a compound index as IETF document), this would require xml2rfc 
support.

Feedback appreciated,

Julian

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

From: [email-masked] (Marshall Rose)
Date: Fri, 7 May 2004 23:10:53 -0700
Subject: [xml2rfc] v1.25 released
Message-ID: <[email-masked]>

this version has a lot of fixes to the nroff output, courtesy of Clive 
DW Feather

also, the <cref/> element is now finalized

finally, the usual collection of bug fixes

/mtr

From: [email-masked] (Carl Malamud)
Date: Thu, 6 May 2004 19:08:26 -0700 (PDT)
Subject: [xml2rfc] XML source for RFCs
In-Reply-To: <[email-masked]>
Message-ID: <[email-masked]>

Hi -

You'll find 412 of them here:

http://xml.resource.org/public/rfc/xml/

Regards,

Carl

> HI,
> 
> Is there a place to get the XML source that was used to generate RFCs?
> 
> Regards,
> /david t. perkins
> 
> _______________________________________________
> xml2rfc mailing list
> [email-masked]
> http://lists.xml.resource.org/mailman/listinfo/xml2rfc
> 

From: [email-masked] (David T. Perkins)
Date: Thu, 06 May 2004 16:41:58 -0700
Subject: [xml2rfc] XML source for RFCs
Message-ID: <[email-masked]>

HI,

Is there a place to get the XML source that was used to generate RFCs?

Regards,
/david t. perkins

From: [email-masked] (Marshall Rose)
Date: Tue, 4 May 2004 13:56:53 -0700
Subject: [xml2rfc] Problem with sample.xml
In-Reply-To: <[email-masked]>
References: <[email-masked]>
Message-ID: <[email-masked]>

>
> I just downloaded xml2rfc and used it to general sample.txt from
> sample.xml. The output was different. "Refernces" was a numbered
> section and also was not proceeded by a page break.
>
> What do I need to get the "correct" behavior, or is sample.xml
> no longer correct?

sample.txt is out of date. what xml2rfc generated is correct. the next 
release will have an updated sample.txt

/mtr

From: [email-masked] (David T. Perkins)
Date: Tue, 04 May 2004 12:09:07 -0700
Subject: [xml2rfc] Problem with sample.xml
Message-ID: <[email-masked]>

HI,

I just downloaded xml2rfc and used it to general sample.txt from
sample.xml. The output was different. "Refernces" was a numbered
section and also was not proceeded by a page break.

What do I need to get the "correct" behavior, or is sample.xml
no longer correct?

/david t. perkins