[rfc-i] RFC "source" format

Sandy Ginoza ginoza at ISI.EDU
Thu Oct 9 15:17:41 PDT 2008

A few comments inline...

> Date: Thu, 09 Oct 2008 08:25:22 -0700
> From: Dave CROCKER <dhc2 at dcrocker.net>
> To: Joe Touch <touch at ISI.EDU>
> Cc: rfc-interest at rfc-editor.org
> Subject: [rfc-i] RFC "source" format
> Joe Touch wrote:
> > source format: the format the author uses to write the doc. this has
> > been .nr, .xml, .doc in the past; I'm sure there have been other
> > sources, but I'm not aware of authors writing the .txt output  
> directly
> > (though that would clearly be possible).
> >
> > - -- I'm claiming that *I* don't care what the source format is.
> >
> > authoritative archive format: this is .txt (ASCII, with  
> limitations),
> > i.e., this is the authoritative version the RFC Editor maintains
> >
> > - -- the proposal appears to change only this to include UTF-8 with
> > limitations.
> Officially, the RFC Editor continues to use only .nr as its format for
> generating published documents.  Its toolset permits it to accept  
> submissions in
> xml2rfc or txt, but it then converts to .nr.  (.ps is a peculiar  
> exception to
> the entire model and probably best ignored for most of these  
> discussions, except
> for noting that it exists...)

When the RFC Editor receives a protocol/document announcement from  
the IESG Secretariat, we ask the authors if they have an NROFF or XML  
source file available.  We also attempt to retrieve XML files from  
the internet-drafts repository.  We use the XML source file to  
prepare the document for publication (formatting and inserting  
edits), and then create a final NROFF file as a final step in the  
publication process.  We use the NROFF source to do some final page  
breaking and sometimes include other tweaks to the document that we  
are unable to do using xml2rfc.

> The fact that the .nr version is not part of the public archive is  
> theoretically
> problematic for revision efforts.  However since .nr has such a  
> tiny user base,
> at this point, it would not help to change its publication.

For revision efforts, the nroff source files are archived and  
available by request -- by dropping a line to rfc-editor at rfc-editor.org.

> Conversion of .xml (xml2rfc) to .nr is claimed to be necessary  
> because of a few
> formatting issues that are not (or cannot be) performed by  
> xml2rfc.  I think it
> would be quite helpful to resolve this, so that all publication  
> formatting can
> be automated and no conversion to .nr is needed, but that is an  
> entirely
> separate issue from the current discussion.)

While this is true, please note that we do edit documents using the  
XML source file throughout the production process.  The NROFF file is  
created as a final step in the process, after all AUTH48 changes have  
been incorporated into the XML file.  Most often, the content of the  
XML file is up-to-date.

Our issues with using xml2rfc for final formatting are documented in  
our communications with <rt+rfced-xml at rtg.ietf.org>, which was set up  
by Bill Fenner for addressing the RFC Editor's use of xml2rfc. The  
main issue that persists is page breaking.

> Hence, unfortunately, we have to distinguish between "submission"  
> formats" and
> "publication input" format, as well as input vs. output. And the  
> process of
> going from submission to publication input is not fully automated  
> and often is
> quite labor-intensive.
> My interest in having the RFC Editor more formally and thoroughly  
> embrace
> xml2rfc is that it permits generation of multiple presentation  
> formats from a
> single source.  (Some of us already use it that way and the  
> different formats
> really are more useful, each for their intended venue.)  But the  
> key is a single
> source format, able to be generated from universally supported and  
> primitive
> tools (as well as more specialized ones) where that format can also  
> be usefully
> viewed with universally supported and primitive tools.  .xml might  
> not be the
> prettiest text format to read, but with reasonable formatting  
> rules, it *is*
> readable.

We have been trying to create the lowest barrier to entry in terms of  
the type of source file we can work with (.txt, .nroff, .xml).  There  
are a number of authors who are not familiar/comfortable using XML;  
we don't want to restrict their ability to submit an RFC for  
publication, or raise the difficulty for them to submit a document  
for publication.

> It turns out that .xml submissions as Internet-Drafts do make the .xml
> automatically available. Although announcements of drafts don't say  
> whether
> there is an xml version, simply substituting .xml for .txt will  
> deliver it, if
> it is available.

Right; if the .xml files have been submitted, we retrieve these files  
and use it to prepare the document for publication.

> Wouldn't it be helpful for revision efforts of RFCs (or derivative  
> efforts
> seeking to incorporate portions and build on them) if this same  
> capability were
> available for RFCs?

In addition to archiving NROFF as the official source file, we have  
started to archive the XML files (around January 2007) for revision  
purposes.  When an author is ready to write a bis document, we are  
happy to supply them with the .nroff/.xml file (if one is available)  
upon request.  However, because we do make final tweaks in the .nroff  
file, we do not claim .xml as an official source file; it is archived  
as a service to the community.  Jari pointed this out to the  
community on the IETF Discussion list (http://www.ietf.org/mail- 
archive/web/ietf/current/msg51214.html) earlier this year (March).


> d/
> --
>    Dave Crocker
>    Brandenburg InternetWorking
>    bbiw.net
> _______________________________________________
> rfc-interest mailing list
> rfc-interest at rfc-editor.org
> http://mailman.rfc-editor.org/mailman/listinfo/rfc-interest

More information about the rfc-interest mailing list