Subject: [xml2rfc] RFC-like documents

From: John C Klensin <[email-masked]>
Date: Mon, 23 Jul 2012 13:32:07 -0400

Hi.

When XML2RFC was first designed, the target audience was RFCs,
I-Ds, and other documents "like" them.  It was used to produce
several such documents of some utility to the IETF community.
It appears that the new version now has enough checks for I-D
and RFC formats that there is no more "like" -- one gets either
I-D format or RFC format with all of the associated front and
back boilerplate or one gets nothing at all?

Perhaps there is a processing directive to overcome that, but,
if so, I can't find it.

So...

(1) Is the elimination of RFC-like documents that are neither
RFCs nor I-Ds intentional or was it an accidental side-effect of
putting in additional checking?

(2) Is there a processing directive that would permit more
general documents that follow the general RFC/I-D style but are
neither.

(3) As a generalization of (2), is there a comprehensive list of
available processing directives and what they do (other than
scattered through various templates) and, if so, where is it and
can we get a prominent link to it from the
http://xml.resource.org/ home page?

   best,
    john

p.s. For anyone who can't answer or understand the above
questions without a use case, I decided to try to render the
latest IESG "shepherd write up" form into something that could
be processed and read properly.  Since much of the relevant part
of the community is familiar with xml2rfc, it seemed like an
obvious candidate.  But that apparently cannot be done without
faking an RFC and then post-processing the document to eliminate
a lot of irrelevant material in the front and back.

---

From: Nico Williams <[email-masked]>
Date: Mon, 23 Jul 2012 12:40:51 -0500

> Perhaps there is a processing directive to overcome that, but,

The old version had a "private" PI for this.  Is that gone in the new version?

I've used it before for docs that have nothing to do with the IETF,
due to my [then] liking the xml2rfc schema well enough.  Nowadays I
seem to have a mild love affair with LyX, so I've been using
lyx2xml2rfc to format I-Ds, and formatting private docs directly is
trivial.

> general documents that follow the general RFC/I-D style but are

Did you try the private PI?

> http://xml.resource.org/ home page?

The list of PIs is here:

http://xml.resource.org/authoring/README.html#anchor7

> a lot of irrelevant material in the front and back.

It's worth having a private mode (within reason, by which I mean just
not including any boilerplate) in any case because it's a useful tool,
and more users -> improved tooling.

Nico
--

---

From: "Martin J. Dürst" <[email-masked]>
Date: Tue, 24 Jul 2012 10:29:24 +0900

> lyx2xml2rfc to format I-Ds, and formatting private docs directly is

I have tried to find  lyx2xml2rfc, but google says "Your search - 
lyx2xml2rfc - did not match any documents.".

Any hints?

Regards,   Martin.

---

From: Nico Williams <[email-masked]>
Date: Mon, 23 Jul 2012 20:37:30 -0500

> lyx2xml2rfc - did not match any documents.".

I misremembered the name of the script, which is lyx2rfc.  Heh.

https://github.com/nicowilliams/lyx2rfc

You need LyX 2.0.0 or higher (2.0.4 has a fix for a bug that I work
around in the XSLT; I've not tested 2.0.4 but I expect it to work).
You also need Saxon or some other XSLT 2.0 processor.  You may need to
play with the lyx2rfc script to get it to work for you.

Anyways, there's a test I-D and output in that git repo.  Larger,
actual I-Ds written with LyX can be found here:

https://github.com/nicowilliams/httpbisIDs

Nico
--

---

From: Brian E Carpenter <[email-masked]>
Date: Tue, 24 Jul 2012 08:19:51 +0100

John,

I don't know exactly which features you want to eliminate, but the page at
http://www.ietf.org/about/process-docs.html
is produced using xml2rfc, and I just checked that the source file
works with the pre-release at http://xml.resource.org/experimental.html

The special bits I see in the source are:

<?rfc topblock="no"?>        <!-- Don't want the RFC boilerplate -->
<?rfc private="procdocs"?>

<!-- This line seems to be required but is irrelevant since it isn't an RFC -->
<rfc ipr="trust200902" docName=" ">

<!-- We don't want an Author's Address section but this element is compulsory in the DTD. -->
<!-- You will need to delete the string "Author's Address" from the output file (twice).  -->
<author initials=" " surname=" " fullname=" "/>

And between </abstract> and  </front> :

 <note title="Administrivia">
 <t><list>
  <t>Date: 2012-06-12</t>
  <t>Document editor: Brian Carpenter</t>
  <t>Discussion forum: [email-masked]</t>
 </list></t>
 </note>

which is a remnant of the ad hoc format invented for IONs a few years ago.

Regards
   Brian

On 23/07/2012 18:32, John C Klensin wrote:
> _______________________________________________
> xml2rfc mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/xml2rfc
> .
>

---

From: John C Klensin <[email-masked]>
Date: Tue, 24 Jul 2012 11:24:58 -0400

Brian,

Huge help -- thank you.  I've verified this with a few
additional tweaks against both the installed version of xml2rfc
(in "Strict" mode) and with the experimental one.  A few
comments inline below.

--On Tuesday, July 24, 2012 08:19 +0100 Brian E Carpenter
<[email-masked]> wrote:

> John,
> 
> I don't know exactly which features you want to eliminate, but
> the page at http://www.ietf.org/about/process-docs.html
> is produced using xml2rfc, and I just checked that the source
> file works with the pre-release at
> http://xml.resource.org/experimental.html
> 

Of course, this points out (again) the importance of having a
list of processing directives and explanations of their actions
as part of the xml2rfc document set.

> <!-- This line seems to be required but is irrelevant since it
> isn't an RFC --> <rfc ipr="trust200902" docName=" ">
> 
> <!-- We don't want an Author's Address section but this
> element is compulsory in the DTD. --> <!-- You will need to
> delete the string "Author's Address" from the output file
> (twice).  --> <author initials=" " surname=" " fullname=" "/>

A <title> element is also needed, but an <abstract> is not.  I
found it worked more smoothly to put content in the title
element and then to make the title attribute in <note> empty.

> which is a remnant of the ad hoc format invented for IONs a

I've now got a working Shepherd Report template based on the
IESG's latest form.  If others would find it useful and someone
from the xml2rfc or Tools teams wants to post it somewhere, I'll
be happy to supply it (I'll repeat this offer on the WGChairs
list).

best,
    john

---

From: Nico Williams <[email-masked]>
Date: Tue, 24 Jul 2012 10:32:51 -0500

But yeah, they ought to be listed here instead:

http://xml.resource.org/authoring/draft-mrose-writing-rfcs.html

---

From: Julian Reschke <[email-masked]>
Date: Tue, 24 Jul 2012 17:43:18 +0200

> http://xml.resource.org/authoring/draft-mrose-writing-rfcs.html

Processing directives are not part of the vocabulary; they are just a 
way to influence the behavior of specific implementations. As such, they 
need to be describes separately from the vocabulary.

If we find that some PIs are so valuable that they should be "standard" 
then we ought to extend the vocabulary accordingly.

Best regards, Julian

---

From: John C Klensin <[email-masked]>
Date: Tue, 24 Jul 2012 11:45:18 -0400

--On Tuesday, July 24, 2012 10:32 -0500 Nico Williams
<[email-masked]> wrote:

>> list of processing directives and explanations of their
>> actions as part of the xml2rfc document set.
> 

Or, at least, http://xml.resource.org/ and
http://xml.resource.org/experimental.html should clearly
indicate that the README file isn't just information about a
specific version (which is what the language implies) but also
contains significant documentation.  Of course, the README file
for the experimental version isn't even that -- it points back
to the production version's file and more or less starts by
saying "You need to have Tcl/Tk version 8 running on your
system".   My mind may just be getting fuzzy, but it didn't
occur to me to look there.  Using this tool should not be a
maze-navigation test.

thanks.
    john

---

From: Nico Williams <[email-masked]>
Date: Tue, 24 Jul 2012 11:15:33 -0500

On Tue, Jul 24, 2012 at 10:43 AM, Julian Reschke <[email-masked]> wrote:
> Processing directives are not part of the vocabulary; they are just a way to
> influence the behavior of specific implementations. As such, they need to be
> describes separately from the vocabulary.

Well, users could care less whether PIs are part of the schema,
vocabulary, whatever.  Users shouldn't have to think like developers
in order to find answers to questions.  What this means is that there
should be a link from one document to the other, or an FAQ, or some
sort of breadcrumb if the developer insists on purity in the
documentation (which is quite fair).

> If we find that some PIs are so valuable that they should be "standard" then
> we ought to extend the vocabulary accordingly.

Certainly for boilerplate!  I think it'd be a lot better to have
<boilerplate> tags that we could use to include standard and
user-defined boilerplate.  The ToC control PIs could probably be moved
into a <toc> tag.  Other PIs like artworkdelimiter, say, docmapping,
needLines, and so on should remain PIs.

A complete list of PIs that should move into the schema would take a
little more work, but not much.  Implementing that should -surely-
require a lot more work.

Nico
--

---

From: John C Klensin <[email-masked]>
Date: Tue, 24 Jul 2012 12:39:31 -0400

--On Tuesday, July 24, 2012 11:15 -0500 Nico Williams
<[email-masked]> wrote:

>...
>> Processing directives are not part of the vocabulary; they
>> are just a way to influence the behavior of specific
>> implementations. As such, they need to be describes
>> separately from the vocabulary.
> 
> vocabulary, whatever.  Users shouldn't have to think like
> developers in order to find answers to questions.  What this
> means is that there should be a link from one document to the
> other, or an FAQ, or some sort of breadcrumb if the developer
> insists on purity in the documentation (which is quite fair).

Nico, I actually agree with Julian that some purity is in order.
Using your terminology, I think the problem is with the
breadcrumbs.  As something that wouldn't require touching code
and that would presumably take five minutes for someone with the
needed access, the home page now says:

	"...(using the format defined in RFC 2629 and its
	unofficial successor) and see how the results...
	look-and-feel."
	
and

	"...Version 1.36 is available. Here's the README file."
	
If those two statements were changed to, e.g.,

	"...(using the format and XML vocabulary defined in the
	successor to the original specification in RFC 2629, and
	see how the results... look-and-feel.  Information on
	using the program, including a description of processing
	directives, appears in a README file."

That is, IMO, roughly a 90% solution to the problem.  Would I
like to see release notes, program compilation and operation
hints, and those processing directives in separate files?  Could
the above be made much more clear by rearranging the page format
somewhat?  Yes to both.  But, if there is a choice, I'd rather
see energy put into getting the "experimental" version working
than into that sort of cosmetic work.  

Put differently "that could be organized better" is, IMO, a
feature enhancement request, while "I can't find a clue as to
where to find that particular critical information" is a bug.

And yes, Julian, I suspect that belongs in the tracker, except
it still won't let me log in.

    john

best,
  john