Subject: [xml2rfc] Referencing dead trees
From: [email-masked] (Graham Klyne)
Date: Wed, 16 Oct 2002 20:16:59 +0100

I'm looking for a quick answer to how best construct a reference to a 
dead-tree book, with edition, publisher, ISBN, etc, as opposed to an RFC or 
standards organization document.

Currently, I'm looking to get something like this:

[x] Schneier, B., Applied Cryptography, Second edition, John Wiley and 
Sons, 1996, ISBN 0-471-11709-9.

So far, I'm doing this:

       <reference anchor="ref.Applied-Crypto">
         <front>
           <title>Applied Crypography</title>
           <author initials="B." surname="Schneier" fullname="Bruce Schneier">
             <organization></organization>
           </author>
           <date month='' year="1996"/>
         </front>
         <seriesInfo name="John Wiley and Sons" value="ISBN 0-471-11709-9"/>
       </reference>

which comes out like this:

[x] Schneier, B., Applied Cryptography, Second edition, John Wiley and Sons 
ISBN 0-471-11709-9, 1996.

Any better ideas?

#g

-------------------
Graham Klyne
<[email-masked]>

From: [email-masked] (Randy Bush)
Date: Sun, 13 Oct 2002 10:30:12 -0700
Subject: [xml2rfc] Questions about the design of the DTD etc.
References: <[email-masked]> <[email-masked]>
Message-ID: <[email-masked]>

> people who know how to write rfcs, in general, aren't all that enamoured with xml's syntactic sugar. hence, given a choice of putting something in an attribute value or a child element, taste dictates use of the former. xml experts will disagree with this, and that's fine. however, xml experts aren't the audience for 2629. xml experts should use docbook.

as an occasional internet draft author, i have to agree.  moving
from what feels like two decades of nroff was daunting, but sussing
out xml2rpc to the extent needed to hack an i-d took about a day.
and finding that spare day took some months.

now if we could get you to turn on line wrap ... :-)

randy

From: [email-masked] (Marshall Rose)
Date: Sun, 13 Oct 2002 09:19:57 -0700
Subject: [xml2rfc] Questions about the design of the DTD etc.
In-Reply-To: <[email-masked]>
References: <[email-masked]>
Message-ID: <[email-masked]>

> To be more specific, I have the following questions:
> 
>     1. Is there a public ID that should be used with the DTD?

no.

>     2. Why the author name is given in attributes and not
>        as optional elements?  This makes it unnecessarily hard
>        to use XML editors, also others than Framemaker.  I would
>        understand if the initials and surname were attributes,
>        following the design of the abbrev attribute in the title
>        element, but having full name as an attribute appears
>        awkward.
> 
>     3. Again, I don't understand why the contents of the date
>        and seriesInfo elements are given in attributes instead of
>        (optional) elements.  What's the reason behind this?
> 
>     4. Why do the note, section, and figure elements contain the
>        title as an attribute and not as an element, following e.g.
>        DocBook?

the answer to questions 2-4 is simple: the audience for rfc2629 is for people who know how to write rfcs, not people who know about xml. (the intersection of the two was essentially nil back in 1999).

people who know how to write rfcs, in general, aren't all that enamoured with xml's syntactic sugar. hence, given a choice of putting something in an attribute value or a child element, taste dictates use of the former. xml experts will disagree with this, and that's fine. however, xml experts aren't the audience for 2629. xml experts should use docbook.

and so, the obvious question is: why not use docbook? the answer is that i can explain 2629 to a competent rfc writer (who knows nothing about xml) in about 15 minutes. in order to get that same person to use docbook, i have to ask them to go out and buy the excellent ora book on docbook, and then spend a month studying it.

the key point here is that there's nothing wrong with docbook. quite the opposite. however, it's total overkill for the task at hand and would be, at best, a paper solution for experienced rfc authors.

> I also saw that there had been some discussion about updating
> RFC2629.  What's the status of that?

the person who was making the noise on it went quiet and no one else started making noise.

> Furthermore, if RFC2629
> is updated, is there any chance to move some of the attributes
> into optional elements?  If backward compatibility is a concern,
> the DTD could still allow the attribute versions in addition to
> the element ones.  Furthermore, it shouldn't be too hard to
> write an automated script that would convert the attributes
> contents into element contents.  (Effectively, I have to do
> exactly that for FrameMaker.  I just have to make a choice
> whether I do it in within the FrameMaker XML import/export
> filter or as an external script.)

as long as i'm the guy with change control on 2629, there will be no changes that are not backwards-compatible. adding new, optional, elements is fine. deprecating the use of existing mandatory things is not.

/mtr

From: [email-masked] (Pekka Nikander)
Date: Sun, 13 Oct 2002 16:17:20 +0300
Subject: [xml2rfc] Questions about the design of the DTD etc.
Message-ID: <[email-masked]>

I am trying to make FrameMaker 7.0 to work with the RFC DTD.
However, the DTD design seems to make this harder than necessary.
Therefore I'd like to understand better the design ideas behind
the DTD.  I have read RFC2629 and some of the discussion in the
mailing list archieves, but there are still lots that I don't
understand.

To be more specific, I have the following questions:

    1. Is there a public ID that should be used with the DTD?

    2. Why the author name is given in attributes and not
       as optional elements?  This makes it unnecessarily hard
       to use XML editors, also others than Framemaker.  I would
       understand if the initials and surname were attributes,
       following the design of the abbrev attribute in the title
       element, but having full name as an attribute appears
       awkward.

    3. Again, I don't understand why the contents of the date
       and seriesInfo elements are given in attributes instead of
       (optional) elements.  What's the reason behind this?

    4. Why do the note, section, and figure elements contain the
       title as an attribute and not as an element, following e.g.
       DocBook?

I also saw that there had been some discussion about updating
RFC2629.  What's the status of that?  Furthermore, if RFC2629
is updated, is there any chance to move some of the attributes
into optional elements?  If backward compatibility is a concern,
the DTD could still allow the attribute versions in addition to
the element ones.  Furthermore, it shouldn't be too hard to
write an automated script that would convert the attributes
contents into element contents.  (Effectively, I have to do
exactly that for FrameMaker.  I just have to make a choice
whether I do it in within the FrameMaker XML import/export
filter or as an external script.)

Yours,

--Pekka Nikander