Subject: [xml2rfc] How to cite citations by reference
From: [email-masked] (Dan Kohn)
Date: Fri, 31 Jan 2003 12:25:16 -0800

This is a multi-part message in MIME format.

------_=_NextPart_001_01C2C966.DE0FC8BE
Content-Type: text/plain;
	charset="us-ascii"
Content-Transfer-Encoding: quoted-printable

Marshall, there appear to be three ways to cite external references with
xml2rfc.  The simplest is to copy and paste the XML to the references
section, though one obviously loses much of the value of cite by
reference.  The second, and your recommendation, is to use a <?rfc
include> processing instruction (PI).  This works fine with xml2rfc but
does not produce a document that can validate against the RFC2629 DTD.
The third option is to use external entities, which (when properly
constructed) do validate against the DTD, but do not currently work with
xml2rfc.  (Note that I'm using XMLspy rel 5 ver 3 to test
well-formedness and validation, but there should be nothing unique about
the XML processor used.)

There are exactly 5 errors in your example of external entities on
<http://xml.resource.org/> that prevent a document using them to
validate.  They are that entities must be declared in the DOCTYPE but
without the %, the URI is incorrect (it doesn't reference RFC 2629 and
it doesn't end with ".xml"), and that the external XML reference can't
have a separate DOCTYPE declaration in it, since XML documents can only
have one.

Once you fix these errors as shown below (and upgrade xml2rfc to use a
validating processor that expands external entities), it seems that the
webpage should recommend external entities as the preferred inclusion
mechanism over using a PI.  The main advantage is that <xref
target=3D"RFC2629"/> entities don't validate when used with a <?rfc
include=3D"reference.RFC.2629" ?> PI, but they do when used with a
correctly formatted external entity &rfc2629;.  Also, even without using
<xref>, an empty <reference/> is necessary in front of the PI's for
validation, so that the validating processor sees one <reference>, since
it doesn't recognize PIs.

However, xml2rfc unfortunately doesn't seem to be using a validating
processor to first load in the external entity before compiling, as the
attached external-entity.xml (which does validate) produces the
following error: "Can't read "xref(RFC2629)": no such element in array
around line 13".

The text near the bottom of <http://xml.resource.org/> should be changed
from:

----
However, you may also use the XML external entity mechanism, e.g.,=20

    <?xml version=3D'1.0'?>
    <!DOCTYPE rfc SYSTEM 'rfc2629.dtd'>

    <!ENTITY % rfc2629 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3080'>

    ...

    <references>
    ...
    &rfc2629;
    ...
    </references>

Note that this syntax is very tricky, i.e., you declare the entity
toward the top of your file and then you reference it exactly once
(using an "&") in the <references/> element to include it.=20
----

To:

----
However, you may also use the XML external entity mechanism, e.g.,=20

<?xml version=3D"1.0" encoding=3D"UTF-8"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
	<!ENTITY rfc2629 PUBLIC ''
'http://www.dankohn.com/reference.RFC.2629.xml'>
]>
...
<xref target=3D"RFC2629"/>
...
<references>&rfc2629;</references>
...
----

I would note more that the syntax is very specific rather than very
tricky. The only difference between the URI on my site and yours is
simply that I deleted the doctype declaration from mine.  I believe that
you should do this from every citation on your website, as there doesn't
appear to be much upside to being able to validate citations as
standalone documents, while the doctype declaration is preventing them
from being used as external entities.  (Of course, the final text should
point to your URI, once you remove the doctype.)

Finally, I'd note a subtlety of the syntax that "RFC2629" is an xref
attribute pointing to a reference while "&rfc2629;" is an entity
representing that reference.  Giving the same name with only the
capitalization different to do very different things is likely
unnecessarily confusing.

I'd also note that changing the string
'http://www.dankohn.com/reference.RFC.2629.xml' to
'reference.RFC.2629.xml' continues to work fine if you have a local copy
of the document but no Internet access (although, of course, that local
copy also can't have a doctype).

I've attached a file, external-entity.xml, that validates against the
rfc2629.dtd but does not work with xml2rfc (apparently because xml2rfc
doesn't use a validating processor).  I've also attached rfc-include.xml
which is well-formed and works fine with xml2rfc but does not validate.

As always, thanks for all your hard work in making RFC 2629 and xml2rfc
possible.

          - dan
--
Dan Kohn <mailto:[email-masked]>
<http://www.dankohn.com/>  <tel:+1-650-327-2600>

------_=_NextPart_001_01C2C966.DE0FC8BE
Content-Type: text/xml;
	name="rfc-include.xml"
Content-Transfer-Encoding: base64
Content-Description: rfc-include.xml
Content-Disposition: attachment;
	filename="rfc-include.xml"

PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4NCjwhRE9DVFlQRSByZmMgU1lT
VEVNICJyZmMyNjI5LmR0ZCI+DQo8cmZjIGlwcj0iZnVsbDIwMjYiPg0KCTxmcm9udD4NCgkJPHRp
dGxlLz4NCgkJPGF1dGhvcj4NCgkJCTxvcmdhbml6YXRpb24vPg0KCQk8L2F1dGhvcj4NCgkJPGRh
dGUgeWVhcj0iMjAwMyIvPg0KCTwvZnJvbnQ+DQoJPG1pZGRsZT4NCgkJPHNlY3Rpb24gdGl0bGU9
ImJvZHkiPg0KCQkJPHQ+DQoJCQkJPHhyZWYgdGFyZ2V0PSJSRkMyNjI5Ii8+DQoJCQk8L3Q+DQoJ
CTwvc2VjdGlvbj4NCgk8L21pZGRsZT4NCgk8YmFjaz4NCgkJPHJlZmVyZW5jZXM+IDw/cmZjIGlu
Y2x1ZGU9InJlZmVyZW5jZS5SRkMuMjYyOSIgPz48L3JlZmVyZW5jZXM+DQoJPC9iYWNrPg0KPC9y
ZmM+DQo=

------_=_NextPart_001_01C2C966.DE0FC8BE
Content-Type: text/xml;
	name="external-entity.xml"
Content-Transfer-Encoding: base64
Content-Description: external-entity.xml
Content-Disposition: attachment;
	filename="external-entity.xml"

------_=_NextPart_001_01C2C966.DE0FC8BE--

From: [email-masked] (Marshall Rose)
Date: Thu, 30 Jan 2003 16:44:52 -0800
Subject: [xml2rfc] 1.15 format style list numbering does not reset
In-Reply-To: <[email-masked]>
References: <[email-masked]> <[email-masked]> <[email-masked]>
Message-ID: <[email-masked]>

> > there's no way to reset it. you have to use a different format string.
> 
> Ok. I think having the option to specify a startAt="..." attribute would
> make it even more flexible ... and work for the draft I'm handling right
> now .. ,:-]

ok.

> > > Feature query:
> > >   There seems to be no way of using letters instead of numbers in
> > >   the format style list. On a whim I tried style="format [%c]" and 
> > >   style="letters format [%d]" without success; then I checked the
> > >   tcl code and saw that there's no provisions for that. It would be
> > >   nice to have, for now I'll use style="hanging" and label manually.
> > 
> > it's easy enough to add this, if you want.
> 
> Yes, please, that would be very good. In the current draft I've seen it
> makes sense both stylistically and to some extent semantically to have this
> option. So if it's not a tough nut....

i'll add something and send it to you for testing.
    
/mtr

From: [email-masked] (Henrik Levkowetz)
Date: Thu, 30 Jan 2003 22:33:47 +0100
Subject: [xml2rfc] 1.15 format style list numbering does not reset
In-Reply-To: <[email-masked]>
References: <[email-masked]> <[email-masked]>
Message-ID: <[email-masked]>

Inline comments..

On Thu, 30 Jan 2003 09:22:48 -0800, Marshall Rose
<[email-masked]> wrote:
> > Hi Marshall,
> > 
> > Bug?
> >   I'm using format style list numbering, and find that the second
> >   time I use the same format, the numbers continue in sequence
> >   instead of being reset to start from 1. I don't know if this was
> >   the intention, but it was not what I expected. Is this a bug, or
> >   alternatively, is there some way to reset the numbering sequence?
>     
> yes, that's the way it's supposed to work. the feature was added
> because some folks wanted to be able to serially list requirements
> throughout multiple sections, e.g.,
>     
>     <section ...>
>         R1: ...
>         R2: ...    
>     </section>
>     <section ...>
>         R3: ...
>     </section>
>     <section ...>
>         R4: ...
>         R5: ...    
>     </section>

Ok, I see that this can actually be very useful :-)

> there's no way to reset it. you have to use a different format string.

Ok. I think having the option to specify a startAt="..." attribute would
make it even more flexible ... and work for the draft I'm handling right
now .. ,:-]
     
> > Feature query:
> >   There seems to be no way of using letters instead of numbers in
> >   the format style list. On a whim I tried style="format [%c]" and 
> >   style="letters format [%d]" without success; then I checked the
> >   tcl code and saw that there's no provisions for that. It would be
> >   nice to have, for now I'll use style="hanging" and label manually.
> 
> it's easy enough to add this, if you want.

Yes, please, that would be very good. In the current draft I've seen it
makes sense both stylistically and to some extent semantically to have this option. So if it's not a tough nut....

Thanks for xml2rfc; the tool, Marshall. It makes a great difference for
turnaround time and consistency when producing drafts.

	Henrik

From: [email-masked] (Marshall Rose)
Date: Thu, 30 Jan 2003 10:19:07 -0800
Subject: [xml2rfc] Error in entity declaration example
In-Reply-To: <[email-masked]>
References: <[email-masked]>
Message-ID: <[email-masked]>

> Separately, I believe there are a couple of errors in the external
> entity declaration example at <http://xml.resource.org/>.
> 
> Based on the examples at
> <http://xmlwriter.net/xml_guide/entity_declaration.shtml>, I believe the
> following syntax is correct:
> 
> <!DOCTYPE rfc SYSTEM "rfc2629.dtd" 
> [
> <!ENTITY % rfc1036 PUBLIC ''
> 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.1036.xml'>
> ]>
> 
> Note that this validates for me.  But when I then try to use
> "&rfc1036;", it is well-formed but XMLspy says that "This file is not
> valid: DTD error- entity 'rfc1036' is undefined".
> 
> Here again, I need to have a blank reference in order to get the file to
> validate against rfc2629.dtd.
> 
> Any guidance would be greatly appreciated.

i can't parse your message. in particular, i can't figure out what works and
what doesn't work with either piece of software.

/mtr

From: [email-masked] (Marshall Rose)
Date: Thu, 30 Jan 2003 10:16:00 -0800
Subject: [xml2rfc] rfc strict and obsoletes
In-Reply-To: <[email-masked]>
References: <[email-masked]>
Message-ID: <[email-masked]>

> When I use "<?rfc strict="yes" ?>" the obsoletes in
> 
>   <rfc category="std" ipr="full2026" obsoletes="1036"
>   docName="draft-kohn-news-article-00.txt">
> 
> generates the xml2rfc error:
> 
>   can't read "counter(reference)": no such element
>   in array  Context: <rfc category="std" ipr="full2026"
>   obsoletes="1036" docName="draft-kohn-news-article-00.txt">
> 
> Removing either the rfc strict or the obsoletes fixes the error.  Could
> you please suggest what's wrong here?

it's a bug reported a little earlier. i'll email you a version with it fixed.

/mtr

From: [email-masked] (Marshall Rose)
Date: Thu, 30 Jan 2003 09:22:48 -0800
Subject: [xml2rfc] 1.15 format style list numbering does not reset
In-Reply-To: <[email-masked]>
References: <[email-masked]>
Message-ID: <[email-masked]>

> Hi Marshall,
> 
> Bug?
>   I'm using format style list numbering, and find that the second time I
>   use the same format, the numbers continue in sequence instead of
>   being reset to start from 1. I don't know if this was the intention,
>   but it was not what I expected. Is this a bug, or alternatively, is
>   there some way to reset the numbering sequence?
    
yes, that's the way it's supposed to work. the feature was added because
some folks wanted to be able to serially list requirements throughout
multiple sections, e.g.,
    
    <section ...>
        R1: ...
        R2: ...    
    </section>
    <section ...>
        R3: ...
    </section>
    <section ...>
        R4: ...
        R5: ...    
    </section>

there's no way to reset it. you have to use a different format string.

> Feature query:
>   There seems to be no way of using letters instead of numbers in the
>   format style list. On a whim I tried style="format [%c]" and 
>   style="letters format [%d]" without success; then I checked the tcl
>   code and saw that there's no provisions for that. It would be nice
>   to have, for now I'll use style="hanging" and label manually.

it's easy enough to add this, if you want.
    
/mtr

From: [email-masked] (Dan Kohn)
Date: Thu, 30 Jan 2003 07:37:44 -0800
Subject: [xml2rfc] rfc strict and obsoletes
Message-ID: <[email-masked]>

This is a multi-part message in MIME format.

------_=_NextPart_001_01C2C875.883ED746
Content-Type: text/plain;
	charset="us-ascii"
Content-Transfer-Encoding: quoted-printable

When I use "<?rfc strict=3D"yes" ?>" the obsoletes in

  <rfc category=3D"std" ipr=3D"full2026" obsoletes=3D"1036"
  docName=3D"draft-kohn-news-article-00.txt">

generates the xml2rfc error:

  can't read "counter(reference)": no such element
  in array  Context: <rfc category=3D"std" ipr=3D"full2026"
  obsoletes=3D"1036" docName=3D"draft-kohn-news-article-00.txt">

Removing either the rfc strict or the obsoletes fixes the error.  Could
you please suggest what's wrong here?

          - dan
--
Dan Kohn <mailto:[email-masked]>
<http://www.dankohn.com/>  <tel:+1-650-327-2600>

------_=_NextPart_001_01C2C875.883ED746
Content-Type: text/xml;
	name="news20030127.xml"
Content-Transfer-Encoding: base64
Content-Description: news20030127.xml
Content-Disposition: attachment;
	filename="news20030127.xml"

------_=_NextPart_001_01C2C875.883ED746--

From: [email-masked] (Dan Kohn)
Date: Thu, 30 Jan 2003 06:51:30 -0800
Subject: [xml2rfc] Error in entity declaration example
Message-ID: <[email-masked]>

Separately, I believe there are a couple of errors in the external
entity declaration example at <http://xml.resource.org/>.

Based on the examples at
<http://xmlwriter.net/xml_guide/entity_declaration.shtml>, I believe the
following syntax is correct:

<!DOCTYPE rfc SYSTEM "rfc2629.dtd" 
[
<!ENTITY % rfc1036 PUBLIC ''
'http://xml.resource.org/public/rfc/bibxml/reference.RFC.1036.xml'>
]>

Note that this validates for me.  But when I then try to use
"&rfc1036;", it is well-formed but XMLspy says that "This file is not
valid: DTD error- entity 'rfc1036' is undefined".

Here again, I need to have a blank reference in order to get the file to
validate against rfc2629.dtd.

Any guidance would be greatly appreciated.

          - dan
--
Dan Kohn <mailto:[email-masked]>
<http://www.dankohn.com/>  <tel:+1-650-327-2600>

From: [email-masked] (Dan Kohn)
Date: Thu, 30 Jan 2003 06:36:22 -0800
Subject: [xml2rfc] References with RFC 2629 DTD and XMLspy
Message-ID: <[email-masked]>

This is a multi-part message in MIME format.

------_=_NextPart_001_01C2C86C.F5957592
Content-Type: text/plain;
	charset="us-ascii"
Content-Transfer-Encoding: quoted-printable

I'm unable to get automated reference citations to validate against the
DTD <http://xml.resource.org/public/rfc/bibxml/rfc2629.dtd> using XMLspy
ver 5, rel 3.

The attached file validates, but then the portion that says:

		<references>
			<reference>
				<front>
					<title>ddd</title>
					<author>
=09
<organization>dddd</organization>
					</author>
					<date year=3D"1036"/>
				</front>
			</reference>
			 <?rfc include=3D"reference.RFC.1036" ?>
		</references>

produces the xml2rfc error: can't read "attrs(anchor": no such element
in array.  Context <rfc obsoletes=3D"1036" category=3D"std" =
ipr=3D"full2026">
<back> <references>

Note that I still need the empty reference to get it to validate, and
that I still have no way of creating an xref to 1036 that will validate.

Can anyone please offer a suggestion other than just copying and pasting
the content of "reference.RFC.1036" into my document?

          - dan
--
Dan Kohn <mailto:[email-masked]>
<http://www.dankohn.com/>  <tel:+1-650-327-2600>

------_=_NextPart_001_01C2C86C.F5957592
Content-Type: text/xml;
	name="news20030127.xml"
Content-Transfer-Encoding: base64
Content-Description: news20030127.xml
Content-Disposition: attachment;
	filename="news20030127.xml"

------_=_NextPart_001_01C2C86C.F5957592--

From: [email-masked] (Julian Reschke)
Date: Thu, 30 Jan 2003 15:23:22 +0100
Subject: [xml2rfc] v. 1.15 Different indentation on first line after figure
In-Reply-To: <[email-masked]>
Message-ID: <[email-masked]>

> From: [email-masked]
> [mailto:[email-masked]]On Behalf Of Henrik
> Levkowetz
> Sent: Thursday, January 30, 2003 3:11 PM
> To: [email-masked]
> Subject: [xml2rfc] v. 1.15 Different indentation on first line after
> figure
>
>
> Marshall,
>
> Bug?
>   If I don't use </t><t> after <artwork>...</artwork>, the first line
>   of text after the artwork has a 1 space extra indentation.

That's a known issue with the HTML that is being generated (it also applies
to my XSLT). AFAIR, there's a similar issue with lists.

I currently workaround it adding the "</t><t>".

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

From: [email-masked] (Henrik Levkowetz)
Date: Thu, 30 Jan 2003 15:10:59 +0100
Subject: [xml2rfc] v. 1.15 Different indentation on first line after figure
Message-ID: <[email-masked]>

Marshall,

Bug?
  If I don't use </t><t> after <artwork>...</artwork>, the first line
  of text after the artwork has a 1 space extra indentation.

		Henrik

-- 

Henrik Levkowetz +46708321608 [email-masked] www.ipunplugged.com
------------------------------------------------------------------------

  "We are ready for any unforeseen event that may or may not occur." 
    -- J. Danforth Quayle, 9/22/90

From: [email-masked] (Henrik Levkowetz)
Date: Thu, 30 Jan 2003 15:05:31 +0100
Subject: [xml2rfc] 1.15 format style list numbering does not reset
Message-ID: <[email-masked]>

Hi Marshall,

Bug?
  I'm using format style list numbering, and find that the second time I
  use the same format, the numbers continue in sequence instead of
  being reset to start from 1. I don't know if this was the intention,
  but it was not what I expected. Is this a bug, or alternatively, is
  there some way to reset the numbering sequence?

Feature query:
  There seems to be no way of using letters instead of numbers in the
  format style list. On a whim I tried style="format [%c]" and 
  style="letters format [%d]" without success; then I checked the tcl
  code and saw that there's no provisions for that. It would be nice
  to have, for now I'll use style="hanging" and label manually.

		Henrik

-- 

Henrik Levkowetz +46708321608 [email-masked] www.ipunplugged.com
------------------------------------------------------------------------

From: [email-masked] (Henrik Levkowetz)
Date: Mon, 27 Jan 2003 17:08:13 +0100
Subject: [xml2rfc] Converting text draft to xml?
Message-ID: <[email-masked]>

For the second time in as many weeks, I'm facing a situation where I
need to pick up a draft produced with some other tool (than xml2rfc)
and continue work on it - which I'd like to do with xml2rfc.

>From some of the xml sources for RFCs available at xml.resource.org
(http://xml.resource.org/public/rfc/xml/) it seems that at some time,
a tool to do at least part of such a conversion may have been available
from invisible.net, but looking there now I cannot find it.

Does anyone on the list have or know of such a tool, which could be
made available?

		Henrik

-- 

Henrik Levkowetz +46708321608 [email-masked] www.ipunplugged.com
------------------------------------------------------------------------

  "We're going to have the best-educated American people in the world."
    -- J. Danforth Quayle, 9/21/88

From: [email-masked] (Marshall Rose)
Date: Sat, 4 Jan 2003 16:49:40 -0800
Subject: [xml2rfc] Patch: Do not add two spaces after abbreviations
In-Reply-To: <[email-masked]>
References: <[email-masked]> <[email-masked]> <[email-masked]>
Message-ID: <[email-masked]>

> Marshall Rose <[email-masked]> writes:
> 
> > tell me: before the patch, was the problem with two_spaces and
> > abbreviations one of false positives or false negatives?
> 
> False negatives, I think, e.g.  <-- this was the result. :-)

ok. the problem, i guess is that i usually write "e.g.," or "cf.," but, point
taken.

> > i guess BSD style, since that's what i use for the stuff that i write.
> 
> Can you put a file called "LICENCE" in the tarball?  Then I'll package
> xml2rfc for Debian some day. :-)

okie-dokie.

/mtr

From: [email-masked] (Florian Weimer)
Date: Sun, 05 Jan 2003 00:16:33 +0100
Subject: [xml2rfc] Patch: Do not add two spaces after abbreviations
In-Reply-To: <[email-masked]> (Marshall Rose's message of "Sat, 4 Jan 2003 13:47:10 -0800")
References: <[email-masked]> <[email-masked]>
Message-ID: <[email-masked]>

Marshall Rose <[email-masked]> writes:

> tell me: before the patch, was the problem with two_spaces and
> abbreviations one of false positives or false negatives?

False negatives, I think, e.g.  <-- this was the result. :-)

> i guess BSD style, since that's what i use for the stuff that i write.

Can you put a file called "LICENCE" in the tarball?  Then I'll package
xml2rfc for Debian some day. :-)

-- 
Florian Weimer 	                  [email-masked]
University of Stuttgart           http://CERT.Uni-Stuttgart.DE/people/fw/
RUS-CERT                          fax +49-711-685-5898

From: [email-masked] (Marshall Rose)
Date: Sat, 4 Jan 2003 13:47:10 -0800
Subject: [xml2rfc] Patch: Do not add two spaces after abbreviations
In-Reply-To: <[email-masked]>
References: <[email-masked]>
Message-ID: <[email-masked]>

> This patch prevents the addition of a space character if something
> precedes the period that looks like an abbreviation:

thanks for the patch. i'll include it. the regexp is certainly robust
enough...
    
tell me: before the patch, was the problem with two_spaces and
abbreviations one of false positives or false negatives?  (in other
words, i'm trying to figure out what kinds of abbreviations you
encountered that i haven't...)

> BTW, under which license xml2rfc is released?

i guess BSD style, since that's what i use for the stuff that i write.
    
/mtr

From: [email-masked] (Florian Weimer)
Date: Sat, 04 Jan 2003 21:23:48 +0100
Subject: [xml2rfc] Patch: Do not add two spaces after abbreviations
Message-ID: <[email-masked]>

This patch prevents the addition of a space character if something
precedes the period that looks like an abbreviation:

--- xml2rfc.tcl	2003/01/04 20:12:35	1.1
+++ xml2rfc.tcl	2003/01/04 20:21:09
@@ -5700,11 +5700,18 @@
             break
         }
 
-        append post [string range $glop 0 [expr $x+1]]
-        set glop [string range $glop [expr $x+2] end]
-        if {[string first " " $glop] != 0} {
-            append post " "
-        }
+	set pre [string range $glop 0 [expr $x+1]]
+	set glop [string range $glop [expr $x+2] end]
+        append post $pre
+	
+	# Check for likely abbreviation.  Do not insert two spaces in
+	# this case.
+
+	if {[regexp {(?:[A-Z][A-Z]|[A-Z][a-z][a-z]\.)$} $pre]} {
+	    if {[string first " " $glop] != 0} {
+		append post " "
+	    }
+	}
     }
 
     return $post

BTW, under which license xml2rfc is released?

-- 
Florian Weimer 	                  [email-masked]
University of Stuttgart           http://CERT.Uni-Stuttgart.DE/people/fw/
RUS-CERT                          fax +49-711-685-5898

From: [email-masked] (Marshall Rose)
Date: Wed, 1 Jan 2003 10:35:21 -0800
Subject: [xml2rfc] xml.resource.org temporarily unavailable
Message-ID: <[email-masked]>

hi. my external server, which hosts (among other things) xml.resource.org is
developing disk problems.

so the system is going down for a while to get a clean save followed by some
other preventative action.

hopefully we're back up by 2003-01-01 1600 us/pacific.

/mtr