Subject: [xml2rfc] use of figure numbers
From: [email-masked] (Michael Richardson)
Date: Wed, 26 Dec 2001 18:14:25 -0400

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

>>>>> "Marshall" == Marshall T Rose <[email-masked]> writes:
    >> As far as I can tell, the title isn't going anywhere either.
    >> This would suffice for me - leave the title out and you get no caption.

    Marshall> simplest is usually best. so if i read this correctly, what you're saying
    Marshall> is:

    Marshall> if the title attribute is non-null, add a couple of blank lines at the
    Marshall> bottom of the figure and add "Figure XX: title" there.

    Marshall> works for me.

  Yes. I had xref'ed a figure. Someone reading my draft asked.. "where is
figure 6"?

]       ON HUMILITY: to err is human. To moo, bovine.           |  firewalls  [
]   Michael Richardson, Sandelman Software Works, Ottawa, ON    |net architect[
] [email-masked] http://www.sandelman.ottawa.on.ca/ |device driver[
] panic("Just another NetBSD/notebook using, kernel hacking, security guy");  [

From: [email-masked] (Marshall T. Rose)
Date: Wed, 26 Dec 2001 11:31:36 -0800
Subject: [xml2rfc] handling of entities
References: <[email-masked]>
Message-ID: <007801c18e43$ef94e470$0301000a@FATORA>

> maybe this is not new to you, but i thought it could be interesting: the
> web service at http://xml.resource.org doesn't seem to handle entities
> correctly. i haven't done any systematic testing, but &amp; in the
> source shows up as &amp; in the text version. i don't know how it works
> for the other entities predefined by xml, but implementing a fully
> xml-compliant solution (including support for user-defined entities)
> will certainly be hard (in fact, then you will be starting to implement
> a full xml parser).

i don't think so.

first, rfc2629 says that you don't get to define any entities, that means
you get the minimal set that comes with xml, i.e., amp, lt, apos, and quot.
(as a convenience to rfc authors, another entity, "rfc.number" is defined
that expands to either "XXXX" for drafts or a real number.

second, when i put this:

<t>
amp=&amp;
lt=&lt;
gt=&gt;
quot=&quot;
apos=&apos;
rfc.number=&rfc.number;
</t>

in a document and use xml2rfc either stand-alone or via the web service, i
get back this:

       amp=& lt=< gt=> quot=" apos=' rfc.number=XXXX

which is exactly what i'd expect.

in future, when reporting problems, include the xml you're using.

/mtr

From: [email-masked] (Erik Wilde)
Date: Wed, 26 Dec 2001 12:18:45 +0100
Subject: [xml2rfc] handling of entities
Message-ID: <[email-masked]>

hello.

maybe this is not new to you, but i thought it could be interesting: the
web service at http://xml.resource.org doesn't seem to handle entities
correctly. i haven't done any systematic testing, but &amp; in the
source shows up as &amp; in the text version. i don't know how it works
for the other entities predefined by xml, but implementing a fully
xml-compliant solution (including support for user-defined entities)
will certainly be hard (in fact, then you will be starting to implement
a full xml parser).

cheers and a happy new year,

erik wilde  - tel:+41-1-6325132 - fax:+41-1-6321035
       mailto:[email-masked] -  http://dret.net/
       computer engineering and networks laboratory
       swiss federal institute of technology  (eth)
       * try not. do, or do not. there is no try. *

From: [email-masked] (Marshall T. Rose)
Date: Fri, 21 Dec 2001 16:09:40 -0800
Subject: [xml2rfc] xml2rfc 1.9 is out
Message-ID: <05cc01c18a7c$f36d02f0$fe0aa840@FATORA>

mostly some minor bug fixes, including handling figures better (as discussed
this week).

http://xml.resource.org/

/mtr

From: [email-masked] (Marshall T. Rose)
Date: Fri, 21 Dec 2001 15:59:41 -0800
Subject: [xml2rfc] references list
References: <[email-masked]> <[email-masked]> <050801c18a62$4b16fb70$fe0aa840@FATORA> <[email-masked]>
Message-ID: <05a401c18a7b$8ec043e0$fe0aa840@FATORA>

> the references element of the dtd, which does not have a title
> attribute, while the online service requires one. also i think that the
> dtd does not allow multiple references elements, while the online
> service accepts them.

i'll update the dtd on the web site later today.

> > ps: not everyone has nroff...
>
> yeah. i just discovered that finding a decent nroff for windows seems to
> be a bit of a problem...
>
> another question: is there a way how i can make the "network working
> group" header go away? i want to make an independent submission, but the
> header pi does not what i thought it would do. my document lloks like
> this:
>
> <?xml version="1.0"?>
> <!DOCTYPE rfc SYSTEM "rfc2629.dtd">
> <?rfc compact="yes" ?>
> <?rfc subcompact="no" ?>
> <?rfc toc="yes" ?>
> <?rfc sortrefs="yes" ?>
> <?rfc symrefs="yes" ?>
> <rfc ipr="full2026" docName="draft-wilde-sms-uri-00">

the "NETWORK WORKING GROUP" thing is pretty much a generic I-D/RFC thing.
it's supposed to be in all I-Ds and RFCs...

the fact that you're doing an independent submission is in the docName...

/mtr

From: [email-masked] (Marshall T. Rose)
Date: Fri, 21 Dec 2001 12:58:50 -0800
Subject: [xml2rfc] references list
References: <[email-masked]> <[email-masked]>
Message-ID: <050801c18a62$4b16fb70$fe0aa840@FATORA>

> sure, but for example, the archive i downloaded yesterday contains a dtd
> which is not accepted by the online service, so i was a bit worried
> about the tool's consistency. having everything on my computer using
> just xml, xslt, and nroff would make me feel more comfortable. maybe i
> did not phrase it right. what i meant is that producing html and nroff
> from the xml source and then the text version from the generated nroff
> would be the way to go, given the current state of the art.

err, what part of which dtd were you concerned about?

/mtr

ps: not everyone has nroff...

From: [email-masked] (Marshall T. Rose)
Date: Fri, 21 Dec 2001 12:57:59 -0800
Subject: [xml2rfc] use of figure numbers
References: <[email-masked]>
Message-ID: <050001c18a62$2cbb1210$fe0aa840@FATORA>

>   As far as I can tell, the title isn't going anywhere either.
>   This would suffice for me - leave the title out and you get no caption.

simplest is usually best. so if i read this correctly, what you're saying
is:

if the title attribute is non-null, add a couple of blank lines at the
bottom of the figure and add "Figure XX: title" there.

works for me.

/mtr

From: [email-masked] (Erik Wilde)
Date: Fri, 21 Dec 2001 11:40:21 +0100
Subject: [xml2rfc] references list
References: <[email-masked]>
Message-ID: <[email-masked]>

> > you're both right that xslt is *not* the right tool to produce formatted
> > output, but it *is* the right tool to produce formatter input, such as
> > html and nroff, and then the nroff formatter could be used to generate
> > the text version, so nothing would have to be done by hand.
> What do you mean "by hand"? xml2rfc produces text files programatically,
> right?

sure, but for example, the archive i downloaded yesterday contains a dtd
which is not accepted by the online service, so i was a bit worried
about the tool's consistency. having everything on my computer using
just xml, xslt, and nroff would make me feel more comfortable. maybe i
did not phrase it right. what i meant is that producing html and nroff
from the xml source and then the text version from the generated nroff
would be the way to go, given the current state of the art.

> And yes, producing the NROFF version using XSLT shouldn't be hard. I may
> look at it in the next weeks.

sounds great. please keep me posted.

cheers,

dret.

From: [email-masked] (Julian Reschke)
Date: Fri, 21 Dec 2001 11:06:14 +0100
Subject: [xml2rfc] references list
In-Reply-To: <[email-masked]>
Message-ID: <[email-masked]>

> From: Erik Wilde [mailto:[email-masked]]
> Sent: Friday, December 21, 2001 10:53 AM
> To: Julian Reschke
> Cc: [email-masked]; Marshall Rose
> Subject: Re: [xml2rfc] references list
>
>
> Julian Reschke wrote:
> > > i don't think it's feasible to produce an .xslt to produce txt
> > > that conforms
> > > to rfc2223. if it is, it's unlikely that the pain is worth
> it. of course,
> > > folks are free to try.
> > It would really be a pain. It's simply not the thing at which
> XSLT is good
> > at. XSLT 2.0 may help a bit, though (see Michael Kay's
> announcment of the
> > first WD).
>
> you're both right that xslt is *not* the right tool to produce formatted
> output, but it *is* the right tool to produce formatter input, such as
> html and nroff, and then the nroff formatter could be used to generate
> the text version, so nothing would have to be done by hand.

What do you mean "by hand"? xml2rfc produces text files programatically,
right?

And yes, producing the NROFF version using XSLT shouldn't be hard. I may
look at it in the next weeks.

From: [email-masked] (Erik Wilde)
Date: Fri, 21 Dec 2001 10:52:42 +0100
Subject: [xml2rfc] references list
References: <[email-masked]>
Message-ID: <[email-masked]>

Julian Reschke wrote:
> > i don't think it's feasible to produce an .xslt to produce txt
> > that conforms
> > to rfc2223. if it is, it's unlikely that the pain is worth it. of course,
> > folks are free to try.
> It would really be a pain. It's simply not the thing at which XSLT is good
> at. XSLT 2.0 may help a bit, though (see Michael Kay's announcment of the
> first WD).

you're both right that xslt is *not* the right tool to produce formatted
output, but it *is* the right tool to produce formatter input, such as
html and nroff, and then the nroff formatter could be used to generate
the text version, so nothing would have to be done by hand.

cheers,

erik wilde  - tel:+41-1-6325132 - fax:+41-1-6321035
       mailto:[email-masked] -  http://dret.net/
       computer engineering and networks laboratory
       swiss federal institute of technology  (eth)
       * try not. do, or do not. there is no try. *

From: [email-masked] (Michael Richardson)
Date: Thu, 20 Dec 2001 18:07:45 -0500
Subject: [xml2rfc] use of figure numbers
In-Reply-To: Your message of "Thu, 20 Dec 2001 11:08:50 PST." <016d01c18989$c30a46c0$fe0aa840@FATORA>
Message-ID: <[email-masked]>

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

>>>>> "Marshall" == Marshall T Rose <[email-masked]> writes:
    Marshall> 3. if the <figure> tag does have a title attribute, then the
    Marshall> caption will read "FigureX : title..."

  As far as I can tell, the title isn't going anywhere either.
  This would suffice for me - leave the title out and you get no caption.

]       ON HUMILITY: to err is human. To moo, bovine.           |  firewalls  [
]   Michael Richardson, Sandelman Software Works, Ottawa, ON    |net architect[
] [email-masked] http://www.sandelman.ottawa.on.ca/ |device driver[
] panic("Just another NetBSD/notebook using, kernel hacking, security guy");  [

From: [email-masked] (Julian Reschke)
Date: Thu, 20 Dec 2001 20:41:02 +0100
Subject: [xml2rfc] references list
In-Reply-To: <01d001c1898c$d6cc8940$fe0aa840@FATORA>
Message-ID: <[email-masked]>

> From: [email-masked]
> [mailto:[email-masked]]On Behalf Of Marshall T.
> Rose
> Sent: Thursday, December 20, 2001 8:31 PM
> To: Erik Wilde; [email-masked]
> Cc: Marshall Rose
> Subject: Re: [xml2rfc] references list
>
>
> > - is there any "official" plan to move to xslt?
>
> not with xml2rfc.
>
> you've already seen julian's .xslt to produce html.
>
> i believe that someone could produce another .xslt to produce nroff.
>
> i don't think it's feasible to produce an .xslt to produce txt
> that conforms
> to rfc2223. if it is, it's unlikely that the pain is worth it. of course,
> folks are free to try.

It would really be a pain. It's simply not the thing at which XSLT is good
at. XSLT 2.0 may help a bit, though (see Michael Kay's announcment of the
first WD).

From: [email-masked] (Marshall T. Rose)
Date: Thu, 20 Dec 2001 11:30:53 -0800
Subject: [xml2rfc] references list
References: <[email-masked]>
Message-ID: <01d001c1898c$d6cc8940$fe0aa840@FATORA>

> - is there any "official" plan to move to xslt?

not with xml2rfc.

you've already seen julian's .xslt to produce html.

i believe that someone could produce another .xslt to produce nroff.

i don't think it's feasible to produce an .xslt to produce txt that conforms
to rfc2223. if it is, it's unlikely that the pain is worth it. of course,
folks are free to try.

> ... references ...

first, the majority of your frustration will probably disappear if you use
the bibxml databases available at http://xml.resource.org/ , every RFC, I-D,
and a few other specifications are already there.

the thing that folks need to keep in mind about markup is that while it's
easy to throw things away (why would i ever need an email address in a
reference), it's impossible to get information back.

in terms of things like organizations authoring documents, you can do things
like this:

<author>
<organization abbrev="W3C">World Wide Web Consortium</organization>

<address>
<postal>
<street>MIT Laboratory for Computer Science</street>
<street>545 Technology Square</street>
<city>Cambridge</city> <region>MA</region> <code>02139</code>
<country>US</country>
</postal>

<phone>+ 1 617 253 2613</phone>
<facsimile>+ 1 617 258 5999</facsimile>
<email>[email-masked]</email>
<uri>http://www.w3c.org</uri>
</address>
</author>

/mtr

From: [email-masked] (Marshall T. Rose)
Date: Thu, 20 Dec 2001 11:08:50 -0800
Subject: [xml2rfc] use of figure numbers
References: <[email-masked]>
Message-ID: <016d01c18989$c30a46c0$fe0aa840@FATORA>

> If I create a figure, a la:
>
>     <figure anchor="txtfqdnformat" title="FQDN format of TXT record">
>            <artwork><![CDATA[
> X-IPsec-Server(P)=@FQDN KEY
>           ]]></artwork>
>     </figure>
>
> and later refer to it:
>
>       See <xref target="txtfqdnformat" />
>
>
> I get:
>   "See Figure 6"
>
> The problem is that I don't know how to indicate that I actually want my
> figures numbered.

this is an interesting problem.

Solution A:

1. add a processing option like this

        <?rfc captions='yes'?>

if present, then when xml2rfc is i text/nroff mode, it will put a border
around the figure and add a couple of extra lines at the bottom for a
caption.

2. if the <figure> tag doesn't have a title attribute, then the caption will
read "Figure X"

3. if the <figure> tag does have a title attribute, then the caption will
read "FigureX : title..."

Solution B:

1. if the preamble/postamble elements are empty, then always put a border
around the figure and always have a caption. use rules 2/3 above to decide
what the caption is.

there are other possible solutions, but a key design conflict is the fact
that some folks want figures but never want any captions.

comments?

From: [email-masked] (Erik Wilde)
Date: Thu, 20 Dec 2001 11:48:09 +0100
Subject: [xml2rfc] references list
Message-ID: <[email-masked]>

hello.

first of all, i am happy to have discovered a tool like xml2rfc, it
makes life much easier. however, three questions (from an absolute
beginner with xml2rfc):

- is there any "official" plan to move to xslt? i have seen that there
is an ->html converter, but clearly ascii and nroff converters also are
required, and xslt clearly would be the best way to go. i just feel a
bit uncomfortable with the tcl stuff, in particular because i have
noticed that the dtd distributed on the web site does not match the dtd
required by the tcl service (the references title attribute, which
according to the mailing list will get fixed soon). xslt would be the
more transparent and logical choice for transforming xml.

- the syntax of the reference element is terrible, why do i need to give
all the author information in the reference, the dtd even requires me to
specify each author's organization? this is awkward, to say the least.
wouldn't it be better to allow for clear text references (maybe
title/author/date structure)? e.g., how do i reference a document
authored by an organization? i would be glad to simply paste my bibtex
generated references into the reference element. to me, this burden of
having to type in the lengthy references  is the biggest disadvantage of
xml2rfc.

- the reference i was generating for an rfc reads "Hoffmann, P.,
Masinter, L. and J. Zawinski, "The mailto URL scheme", RFC 2368, June
1998.", which does not print the names consistently (i used the tcl web
service). my reference (trying to be as terse as the dtd allows me to
be) reads:

<reference anchor="rfc2368">
<front>
<title>The mailto URL scheme</title>
<author initials="P. E." surname="Hoffmann" fullname="Paul E.
Hoffmann"><organization/></author>
<author initials="L." surname="Masinter" fullname="Larry
Masinter"><organization/></author>
<author initials="J." surname="Zawinski" fullname="Jamie
Zawinski"><organization/></author>
<date month="June" year="1998"/>
</front>
<seriesInfo name="RFC" value="2368"/>
</reference>

what am i doing wrong? and as i said before, is there any hope that
using references can be made less cumbersome?

thanks for your help,

erik wilde  - tel:+41-1-6325132 - fax:+41-1-6321035
       mailto:[email-masked] -  http://dret.net/
       computer engineering and networks laboratory
       swiss federal institute of technology  (eth)
       * try not. do, or do not. there is no try. *

From: [email-masked] (Michael Richardson)
Date: Wed, 19 Dec 2001 23:38:12 -0500
Subject: [xml2rfc] use of figure numbers
Message-ID: <[email-masked]>

If I create a figure, a la:

    <figure anchor="txtfqdnformat" title="FQDN format of TXT record">
           <artwork><![CDATA[
X-IPsec-Server(P)=@FQDN KEY
          ]]></artwork>
    </figure>

and later refer to it:

      See <xref target="txtfqdnformat" />

I get:
  "See Figure 6"

The problem is that I don't know how to indicate that I actually want my
figures numbered.

]       ON HUMILITY: to err is human. To moo, bovine.           |  firewalls  [
]   Michael Richardson, Sandelman Software Works, Ottawa, ON    |net architect[
] [email-masked] http://www.sandelman.ottawa.on.ca/ |device driver[
] panic("Just another NetBSD/notebook using, kernel hacking, security guy");  [

   

From: [email-masked] (Marshall T. Rose)
Date: Mon, 17 Dec 2001 11:46:03 -0800
Subject: [xml2rfc] a few points of info...
References: <[email-masked]>
Message-ID: <019701c18733$76acea10$fe0aa840@FATORA>

> That sounds useful, because many RFCs I've seen use this distinction.
>
> However I just tried both the DTD and the online service, and both reject
> the document because "references" may only occur once in <back>, and the
> title attribute isn't declared.
>
> Are you going to update these?

oops!

mostly fixed. i just found a problem in the toc-generator that i need to
fix. i'll get to that this evening...

/mtr

From: [email-masked] (Julian Reschke)
Date: Mon, 17 Dec 2001 09:53:46 +0100
Subject: [xml2rfc] a few points of info...
In-Reply-To: <044c01c18602$ae82f880$fe0aa840@FATORA>
Message-ID: <[email-masked]>

> From: [email-masked]
> [mailto:[email-masked]]On Behalf Of Marshall T.
> Rose
> Sent: Sunday, December 16, 2001 8:24 AM
> To: [email-masked]
> Cc: Marshall Rose
> Subject: [xml2rfc] a few points of info...
>
> ...
>
> 4. if you want to have multiple references sections in your
> documents (e.g.,
> for normative and non-normative references), you can! it turns
> out that you
> can have zero, one, or more <references> elements. just use the
> undocumented
> "title" attribute to name each, e.g.,
>
>     <back>
>     <references title="Normative References">
>     <reference> ... </reference>
>     ...
>     </references>
>     <references title="Non-normative References">
>     ...
>     </references>
>     </back>
>
> enjoy!

That sounds useful, because many RFCs I've seen use this distinction.

However I just tried both the DTD and the online service, and both reject
the document because "references" may only occur once in <back>, and the
title attribute isn't declared.

Are you going to update these?

Julian

From: [email-masked] (Marshall T. Rose)
Date: Sat, 15 Dec 2001 23:24:21 -0800
Subject: [xml2rfc] a few points of info...
Message-ID: <044c01c18602$ae82f880$fe0aa840@FATORA>

hi.

1. if you're using xml2rfc to generate I-Ds, then when your I-D is approved
for RFC publication, be sure to send the RFC editor both the Text and nroff
versions.

2. similarly, once your RFC is published, be sure to update your XML source
with any changes made by the RFC editor, and then please send the updated
version to [email-masked] - the reason is that the citation
library gets generated from both rfc-index.txt and any xml files that are
available. the xml files make for better results.

3. if you're using the web-based service and having difficulty submitting
I-Ds because a "Save As..." from your browser results in the ^L's being
stripped out, there's a new "Output Result" option on the form at
http://xml.resource.org/ - just select "File" and when you click "Submit"
you'll automatically get a dialog box to save the results as a "binary"
file.

4. if you want to have multiple references sections in your documents (e.g.,
for normative and non-normative references), you can! it turns out that you
can have zero, one, or more <references> elements. just use the undocumented
"title" attribute to name each, e.g.,

    <back>
    <references title="Normative References">
    <reference> ... </reference>
    ...
    </references>
    <references title="Non-normative References">
    ...
    </references>
    </back>

enjoy!

/mtr

From: [email-masked] (Scott Brim)
Date: Wed, 12 Dec 2001 19:00:32 -0500
Subject: [xml2rfc] xml2rfc startup faq
In-Reply-To: <[email-masked]>; from [email-masked] on Sun, Dec 09, 2001 at 10:24:26PM -0500
References: <[email-masked]>
Message-ID: <20011212190032.F1492@SBRIM-W2K>

I've been successful on Windows 2000.  I know I did something
"interesting" as part of the installation but I don't remember what.  If
no one else responds by next week I'll explore a bit and reply then.

From: [email-masked] (Stephen McHenry)
Date: Sun, 09 Dec 2001 22:25:43 -0800
Subject: [xml2rfc] xml2rfc startup faq
In-Reply-To: <[email-masked] amicsoft.com>
Message-ID: <[email-masked]>

--=====================_307185950==_.REL
Content-Type: multipart/alternative;
	boundary="=====================_307185960==_.ALT"

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

At 07:24 PM 12/9/2001, Robert Sparks wrote:
>If you've
>been unsuccessful, send me a note so I know there's
>interest for your platform.

Windows 2000.

Stephen

[email-masked]
us-flag-small.jpg

--=====================_307185960==_.ALT
Content-Type: text/html; charset="us-ascii"

<html>
At 07:24 PM 12/9/2001, Robert Sparks wrote:<br>
<blockquote type=cite class=cite cite>If you've<br>
been unsuccessful, send me a note so I know there's <br>
interest for your platform.</blockquote><br>
Windows 2000.<br><br>
<x-sigsep><p></x-sigsep>
Stephen<br><br>
[email-masked]<br>
<img src="cid:[email-masked]" width=72 height=40 alt="us-flag-small.jpg"><br>
</html>

--=====================_307185960==_.ALT--

--=====================_307185950==_.REL
Content-Type: image/jpeg; name="us-flag-small.jpg";
 x-mac-type="4A504547"; x-mac-creator="4A565752"
Content-ID: <[email-masked]>
Content-Transfer-Encoding: base64
Content-Disposition: inline; filename="us-flag-small.jpg"

--=====================_307185950==_.REL--

From: [email-masked] (Robert Sparks)
Date: Sun, 9 Dec 2001 22:24:26 -0500
Subject: [xml2rfc] xml2rfc startup faq
Message-ID: <[email-masked]>

Greetings -

I'm starting to pull together a faq covering
getting xml2rfc to run in various environments -
So far, I've got linux (redhat), solaris, freebsd,
cygwin, and MacOS9 (thanks to an earlier post from
Ned) covered.

If you've gotten it to go in your favorite environment,
please send me a sketch of what you had to do. If you've
been unsuccessful, send me a note so I know there's 
interest for your platform.

Thanks,
RjS