Subject: [xml2rfc] Novice bad user on device, or Catch-22?

From: "David R. Oran" <[email-masked]>
Date: Mon, 20 Jan 2020 15:00:26 -0500

I have a new Internet Draft to write, so I decided to bite the bullet 
and do it in V3. Rather than write in V2 and try the converter, I 
started out right away with V3 syntax. I didn’t get very far. I tried 
both the most recent xml2rfc by installing it on my machine, and the web 
tool and got identical errors.

If I follow the described syntax in RFC7991, the RFC Editor FAQ in 
https://ftp.ripe.net/rfc/v3test/FAQ-2019-02.html and the example in 
draft-hoffman-rfcexamples-latest as below:

	<?xml version="1.0" encoding="US-ASCII"?>
	<!DOCTYPE rfc SYSTEM 'rfc2629.dtd'>

	<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
	<?rfc strict="yes" ?>
	<?rfc toc="yes"?>
	<?rfc tocdepth="4"?>
	<?rfc symrefs="yes" ?>
	<?rfc sortrefs="yes" ?>
	<?rfc compact="yes" ?>
	<?rfc subcompact="no" ?>
	<rfc
		version=‘3’
		ipr='trust200902'
		category='exp'
		submissionType='IRTF'
		docName='draft-oran-icnrg-reflexive-forwarding-00'
		xml:lang='en' xmlns:xi="https://www.w3.org/2001/XInclude">

	<front>
		<seriesInfo name='Internet-Draft' 
value='draft-oran-icnrg-reflexive-forwarding-00'/>
	    <title abbrev='ICN Reflexive Forwarding'>Reflexive Forwarding for 
CCNx and NDN Protocols
	    </title>

I get

	% xml2rfc draft-oran-icnrg-reflexive-forwarding.xml
	Incompatible schema information: found "rfc2629.dtd" in <DOCTYPE> of a 
version 3 file.

If I leave off the “version=‘3’, as below

	<?xml version="1.0" encoding="US-ASCII"?>
	<!DOCTYPE rfc SYSTEM 'rfc2629.dtd'>
	<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
	<?rfc strict="yes" ?>
	<?rfc toc="yes"?>
	<?rfc tocdepth="4"?>
	<?rfc symrefs="yes" ?>
	<?rfc sortrefs="yes" ?>
	<?rfc compact="yes" ?>
	<?rfc subcompact="no" ?>

	<rfc
		ipr='trust200902'
		category='exp'
		submissionType='IRTF'
		docName='draft-oran-icnrg-reflexive-forwarding-00'
		xml:lang='en' xmlns:xi="https://www.w3.org/2001/XInclude">

	<front>
		<seriesInfo name='Internet-Draft' 
value='draft-oran-icnrg-reflexive-forwarding-00'/>
	    <title abbrev='ICN Reflexive Forwarding'>Reflexive Forwarding for 
CCNx and NDN Protocols
	    </title>

I get:

		xml2rfc draft-oran-icnrg-reflexive-forwarding.xml
		Error: Unable to validate the XML document: 
draft-oran-icnrg-reflexive-forwarding.xml
		 <string>: Line 23: No declaration for attribute xmlns:xi of element 
rfc
		 <string>: Line 25: Element front content does not follow the DTD, 
expecting (title , author+ , date , area* , workgroup* , keyword* , 
abstract? , note*), got (seriesInfo title author author date area 
workgroup keyword keyword abstract )
		 <string>: Line 81: Element section content does not follow the DTD, 
expecting ((t | figure | texttable | iref)* , section*), got (name t )
		 <string>: Line 81: Element section does not carry attribute title
		 <string>: Line 81: No declaration for element name
		 <string>: Line 85: Element section content does not follow the DTD, 
expecting ((t | figure | texttable | iref)* , section*), got (name t )
		 <string>: Line 85: Element section does not carry attribute title
		 <string>: Line 85: No declaration for element name
		 <string>: Line 94: Element section content does not follow the DTD, 
expecting ((t | figure | texttable | iref)* , section*), got (name t 
section section )
		 <string>: Line 94: Element section does not carry attribute title
		 <string>: Line 94: No declaration for element name
		 <string>: Line 97: Element section content does not follow the DTD, 
expecting ((t | figure | texttable | iref)* , section*), got (name t 
table )
		 <string>: Line 97: Element section does not carry attribute title
		 <string>: Line 97: No declaration for element name
		 <string>: Line 98: No declaration for attribute keepWithNext of 
element t
		 <string>: Line 99: No declaration for element table
		 <string>: Line 99: No declaration for attribute title of element 
table

Clue bat please?

DaveO

---

From: Henrik Levkowetz <[email-masked]>
Date: Mon, 20 Jan 2020 21:10:58 +0100

Hi David,

You should simply remove "<!DOCTYPE rfc SYSTEM 'rfc2629.dtd'>" if your
<rfc/> element contains the "version='3'" attribute.

Regards,

	Henrik

On 2020-01-20 21:00, David R. Oran wrote:
> _______________________________________________
> xml2rfc mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/xml2rfc
>

---

From: Julian Reschke <[email-masked]>
Date: Mon, 20 Jan 2020 21:54:35 +0100

On 20.01.2020 21:00, David R. Oran wrote:
> |<?xml version="1.0" encoding="US-ASCII"?> <!DOCTYPE rfc SYSTEM
> 'rfc2629.dtd'> <?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
> <?rfc strict="yes" ?> <?rfc toc="yes"?> <?rfc tocdepth="4"?> <?rfc
> symrefs="yes" ?> <?rfc sortrefs="yes" ?> <?rfc compact="yes" ?> <?rfc
> subcompact="no" ?> <rfc version=‘3’ ipr='trust200902' category='exp'
> submissionType='IRTF' docName='draft-oran-icnrg-reflexive-forwarding-00'
> xml:lang='en' xmlns:xi="https://www.w3.org/2001/XInclude"> <front>
> value='draft-oran-icnrg-reflexive-forwarding-00'/> <title abbrev='ICN
> Reflexive Forwarding'>Reflexive Forwarding for CCNx and NDN Protocols
> </title> |
>
> I get
>
> |% xml2rfc draft-oran-icnrg-reflexive-forwarding.xml Incompatible schema
> information: found "rfc2629.dtd" in <DOCTYPE> of a version 3 file. |
> ...

That message is indeed not very helpful. First of all, it doesn't say
what to do; and then, it *assumes* what the contents of rfc2629.dtd
might be, without really knowing.

FWIW, you don't need a DTD declaration; just get rid of it (the same was
already true in v2 times).

Best regards, Julian

---

From: "David R. Oran" <[email-masked]>
Date: Mon, 20 Jan 2020 16:03:53 -0500

> <rfc/> element contains the "version='3'" attribute.
If I do that xml2rfc crashes (both the one on my machine and the web tool:

xml2rfc draft-oran-icnrg-reflexive-forwarding.xml
Traceback (most recent call last):
  File "/usr/local/bin/xml2rfc", line 8, in <module>
    sys.exit(main())
  File "/usr/local/lib/python2.7/site-packages/xml2rfc/run.py", line 612, in main
    xmlrfc = parser.parse(remove_comments=False, quiet=True, add_xmlns=True)
  File "/usr/local/lib/python2.7/site-packages/xml2rfc/parser.py", line 548, in parse
    for action, element in context:
  File "src/lxml/iterparse.pxi", line 208, in lxml.etree.iterparse.__next__ (src/lxml/lxml.etree.c:148588)
  File "<string>", line 22
lxml.etree.XMLSyntaxError: Attribute xmlns:xi redefined, line 22, column 59

DaveO

---

From: Henrik Levkowetz <[email-masked]>
Date: Mon, 20 Jan 2020 22:25:17 +0100

Hi David,

> If I do that xml2rfc crashes (both the one on my machine and the web tool:

Oh, wow.  Ok, I'll fix that in the next release.  Could you send the full
xml file, please?  It's not obvious from your snippet where the superfluous
other definition of xmlns:xi is.

Now, you say that instead of trying the converter, you stared out right
away with v3 syntax, but neither the DOCTYPE above, nor the <?rfc ... ?>
PIs visible in your snippet are appropriate for a v3 document.  Did you
grab a v2 template to start with?  I think really going to lead you into
a number of problems if you start with a v2 template and declare it to be
v3.

Using the v2v3 converter on a v2 document, even on a v2 template, on the
other hand, should give you a proper v3 starting point, without the issues
you've run into so far.

Regards,

	Henrik

---

From: "David R. Oran" <[email-masked]>
Date: Tue, 21 Jan 2020 00:51:01 -0500

Thanks a ton for the help. I puzzled around some more in the FAQ and RFC7991, getting rid of suspicious V2-ish stuff that used to be adorning all my draft source files and replacing the essentials with the right V3 constructs. However, among those was not the xmlns:ni, which I had copied from one of the examples in draft-hoffman-rfcexamples. Once that was gone the crash disappeared.

One unsolicited piece of advice is that in addition to the FAQ and RFC7991 itself, some templates in native V3 for people to start from would have saved me the pain you see in this thread. The example in Paul Hoffman’s draft (which I found googling “xml2rfc v3 examples” of course) was generated using the converter and wound up being extremely misleading for a “native” V3 source file.

Best, DaveO.

P.S. I did get another crash when I put my own <date> element in the <front> element as per “<date month='January' year='2020' /> When I let the converter insert the date in the output itself, no problem.

	xml2rfc draft-oran-icnrg-reflexive-forwarding.xml
	draft-oran-icnrg-reflexive-forwarding.xml(63): Warning: The document date (2020-01-01) is more than 3 days away from today's date
	Traceback (most recent call last):
	  File "/usr/local/bin/xml2rfc", line 8, in <module>
	    sys.exit(main())
	  File "/usr/local/lib/python2.7/site-packages/xml2rfc/run.py", line 620, in main
	    xmlrfc.tree = prep.prep()
	  File "/usr/local/lib/python2.7/site-packages/xml2rfc/writers/preptool.py", line 342, in prep
	    func(e, e.getparent())
	  File "/usr/local/lib/python2.7/site-packages/xml2rfc/writers/preptool.py", line 1123, in boilerplate_insert_status_of_memo
	    exp = datetime.date(year=year, month=month, day=day) + datetime.timedelta(days=185)
	TypeError: an integer is required

On 20 Jan 2020, at 18:20, Henrik Levkowetz wrote:

> Hi again David,
>
> The issue is triggered by the code trying to insert the XInclude namespace
> if it isn't defined, but your file defines the 'xi' namespace prefix not
> as the XInclude namespace (http://www.w3.org/2001/XInclude), but as something
> that's very close to it:  (https://www.w3.org/2001/XInclude).  The code
> then tries to insert xmlns:xi="http://www.w3.org/2001/XInclude" which fails.
>
> The code should handle this better.  It's clearly a bug.  Menawhile, if you
> change the https:// to http:// in the xmlns:xi attribute value, you should
> be able to get further.
>
> Once you've fixed that, you'll find that using XInclude doesn't permit
> any inaccuracies in the specification of the href, so you'll have to add
> https:// to the <xi:include/> entries around line 140.  The v2 processor
> is much more forgiving about this, but the XInclude specification doesn't
> permit a processor to be lenient in the manner xml2rfc is for v2 input.
>
> Then you'll find that <tbody> isn't optional in v3 the way it is in html,
> and other issues that should be easier to sort out.
>
>
> Best,
>
> 	Henrik
>
> On 2020-01-20 23:59, Henrik Levkowetz wrote:
>> Hi David,
>>
>> On 2020-01-20 23:25, David R. Oran wrote:
>>> Thanks much. See below.
>>
>> Ack.  Will reply further once I've looked at the xml.  One point inline
>> now:
>>
>>> On 20 Jan 2020, at 16:25, Henrik Levkowetz wrote:
>>>
>>>> Hi David,
>>>>
>>> attached.
>>> No, I started from scratch…but cut a pasted a few things from an
>>> earlier draft after checking (I thought correctly) that I was
>>> following the strict V3 definitions. Possibly not…
>>>
>>> For yucks, I got rid of all that and started right off with the <rfc>
>>> element and xml2rfc still crashes.
>>>
>>> I believe that. But the output of the converter on
>>> draft-hoffman-rfcexamples-latest left the DOCTYPE declaration in
>>> there…
>>
>> I think you'll find that the DOCTYPE doesn't mention a dtd in that case,
>> just a file which (if available) provides entity definitions.
>>
>> More in a moment.
>>
>>
>> Best regards,
>>
>> 	Henrik
>>
>>>
>>>>
>>>>
>>>> Regards,
>>>>
>>>> 	Henrik
>>>>
>>>>>

DaveO

---

From: "David R. Oran" <[email-masked]>
Date: Tue, 21 Jan 2020 00:59:46 -0500

Oh, one more thing I noticed that puzzled me briefly…

RFC7991 says:

	2.45.3.  "docName" Attribute

	   Deprecated; instead, use the "value" attribute in <seriesInfo>.

but your draft won’t compile unless you include it as an attribute of the <rfc> element.

DaveO

---

From: Julian Reschke <[email-masked]>
Date: Tue, 21 Jan 2020 07:13:13 +0100

On 21.01.2020 06:51, David R. Oran wrote:
 > ...
> Thanks a ton for the help. I puzzled around some more in the FAQ and
> RFC7991, getting rid of suspicious V2-ish stuff that used to be adorning
> all my draft source files and replacing the essentials with the right V3
> constructs. However, among those was not the xmlns:ni, which I had
> copied from one of the examples in draft-hoffman-rfcexamples. Once that
> was gone the crash disappeared.
 > ...

Extra namespace declarations should not cause any problems. They are
allowed in XML.

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Tue, 21 Jan 2020 07:14:45 +0100

On 21.01.2020 06:59, David R. Oran wrote:
> |2.45.3. "docName" Attribute Deprecated; instead, use the "value"
> attribute in <seriesInfo>. |
>

We currently do not have a spec that describes v3-as-implemented.

You will *also* have to look at
<https://tools.ietf.org/html/draft-levkowetz-xml2rfc-v3-implementation-notes-10>,
and even that will not give you the full picture.

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 21 Jan 2020 09:26:22 +0100

Hi Dave,

On 2020-01-21 06:51, David R. Oran wrote:
> RFC7991, getting rid of suspicious V2-ish stuff that used to be
> adorning all my draft source files and replacing the essentials with
> the right V3 constructs. However, among those was not the xmlns:ni,
> which I had copied from one of the examples in
> draft-hoffman-rfcexamples. Once that was gone the crash disappeared.
> 
> One unsolicited piece of advice is that in addition to the FAQ and
> RFC7991 itself, some templates in native V3 for people to start from
> would have saved me the pain you see in this thread. The example in
> Paul Hoffman’s draft (which I found googling “xml2rfc v3 examples” of
> course) was generated using the converter and wound up being
> extremely misleading for a “native” V3 source file.
> 
> Best, DaveO.
> 
> P.S. I did get another crash when I put my own <date> element in the
> <front> element as per “<date month='January' year='2020' /> When I
> let the converter insert the date in the output itself, no problem.

Thanks for the data and traceback; will fix the issue in the next release :-)

And yes, having v3 templates would be helpful.  I'll see if I can fix that
too.  Where would you normally grab a template?

	Henrik

---

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 21 Jan 2020 09:27:56 +0100

> but your draft won’t compile unless you include it as an attribute of

Yes.  There are a number of changes after RFC7991; a -bis is definitely
needed.

Best regards,

	Henrik

---

From: "David R. Oran" <[email-masked]>
Date: Tue, 21 Jan 2020 08:30:20 -0500

On 21 Jan 2020, at 1:14, Julian Reschke wrote:

>> but your draft won’t compile unless you include it as an attribute 
>> of
>> the <rfc> element.
>> ...
>
Thanks, I had looked a that a while back when I was just perusing 
RFC-editor related drafts, but had forgotten it. Will keep it handy 
going forward.

DaveO

---

From: "David R. Oran" <[email-masked]>
Date: Tue, 21 Jan 2020 08:37:17 -0500

> Hi Dave,
[snipping out to get to your question]

> too.  Where would you normally grab a template?
well, by googling :-)
Probably the home ought to be off the tools home page at tools.ietf.org. There’s already a “templates” link on that page - it’s to Elwyn Davies examples, and ought to have a V3 template.

A pointer in the RFC Editor xml2rfc FAQ would also be useful.

DaveO.

---

From: Paul Kyzivat <[email-masked]>
Date: Tue, 21 Jan 2020 11:34:52 -0500

> Probably the home ought to be off the tools home page at tools.ietf.org. There’s already a “templates” link on that page - it’s to Elwyn Davies examples, and ought to have a V3 template.

I've just been lurking, but seems like a good time to comment...

I normally get my "template" by starting with some similar document, 
either one of my own if I have a suitable one, or from some document I 
am generally aware of.

But that doesn't work well now when there aren't many v3 documents to 
crib from.

I guess I would be inclined to grab the v2 for some similar document and 
convert it. But I guess maybe that won't give optimal style for the new 
document. So maybe having a recommended source of pure templates and 
also some "real" documents that are judged to be "good" examples would 
be helpful.

	Thanks,
	Paul

---

From: Sandy Ginoza <[email-masked]>
Date: Tue, 21 Jan 2020 09:02:52 -0800

Hi all,

You may find some of the XML files in <https://www.rfc-editor.org/rfc/prerelease/> helpful.  These are the v3 XML files for the RFCs before they are run through the final “prep” tool (see https://tools.ietf.org/html/rfc7998). 

I suggest reviewing some of the more recently published RFCs for better examples.  

Thanks,
Sandy 

> On Jan 21, 2020, at 8:34 AM, Paul Kyzivat <[email-masked]> wrote:
> 
> I normally get my "template" by starting with some similar document, either one of my own if I have a suitable one, or from some document I am generally aware of.
> 
> But that doesn't work well now when there aren't many v3 documents to crib from.
> 
> I guess I would be inclined to grab the v2 for some similar document and convert it. But I guess maybe that won't give optimal style for the new document. So maybe having a recommended source of pure templates and also some "real" documents that are judged to be "good" examples would be helpful.
> 
> 	Thanks,
> 	Paul
>

---

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 21 Jan 2020 18:03:01 +0100

Hi Paul,

> also some "real" documents that are judged to be "good" examples would 

The RPC might have some prepublication files that have been edited to
their standards.

For a schema v3 template, I've now run the converter on Elwyn's template
to produce a v3 version, and linked to that from https://tools.ietf.org/.

	Henrik

---

From: Paul Kyzivat <[email-masked]>
Date: Wed, 22 Jan 2020 09:54:07 -0500

I don't have a new draft on the horizon right now, so it will probably 
be awhile till I need a template.

Is there a way to search for drafts with v3 xml posted?
Other than that, I think a pointer to some templates from the tools page 
would be most easily found.

Otherwise, I'd probably be inclined to find a similar document with v2 
xml and convert that as a starting point.

	Thanks,
	Paul