ietf
[Top] [All Lists]

Re: spec gen tools, was: Automatically updated Table of Contents with Nroff

2010-12-30 09:03:46
Yes, that's why I always recommend not to use that style.

But hardwiring the references in the XML leads to manual updating (and 
forgetting that).
Having a tool for that is useful here (which is why kramdown-rfc2629 does this).

BTW, if you are on a Mac, get one of the package managers "macports" or 
"homebrew", and do

     port install xml2rfc

or

     brew install xml2rfc

Interesting. Does this get you a current version, though?

Both are at 1.35 -- not surprising since that version hasn't changed in a while.
One of the advantages of homebrew is that it makes editing the recipe very 
simple, so in a pinch you don't have to wait for the maintainer to update.  And 
the really adventurous ones can always ask for the bleeding edge direct from 
SVN:

        brew install xml2rfc --HEAD

Finally, don't run xml2rfc until you need to; to preview while editing, 
just use the XSLT and open the XML file in a web browser.

Indeed -- thanks Julian for this wonderful tool.
Get it from<http://greenbytes.de/tech/webdav/rfc2629xslt.zip>.
Just put the line

  <?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>

as the second line of the xml, and open the xml in a browser.
(The only caveat I'm aware of is that you cannot really use the ugly 
vspace-999 hack for page break tweaks any more.  Good riddance.  Switch to 
the needLines PI.  That one appears to be acting a bit strange in xml2rfc, 
though.  It usually works for me with<?rfc needLines="30"?>.)

If you educate me what it's supposed to do (force a page break?),

Sometimes, it is worthwhile to add tweaks to the source files to get a page 
break.

Method one: abuse the non-semantic element vspace, which eats excessive blank 
lines when it causes a page break.  
RFC 2629 2.3.1.7 actually recommends this: 
  "This
   allows authors to "force" a pagebreak by using an arbitrarily large
   value, e.g., "blankLines='100'"."

What rfc2629.xslt could do is recognize unreasonably*) large values and do a 
page break instead of emitting tons of <br> elements.
*) Some AI required.  Maybe "more than 60".

Method two: use the needLines PI, which is "documented" only in 
http://xml.resource.org/authoring/README.html -- it is a hint how many lines 
are needed to be able to continue on the current page (as opposed to starting a 
new one).  Those formatters producing continuous output should of course ignore 
it, so rfc2629.xslt already does the right thing.  It's less clear what exactly 
a print stylesheet should do here, as the concept of "lines" is not 
well-defined.

Gruesse, Carsten

_______________________________________________
Ietf mailing list
Ietf(_at_)ietf(_dot_)org
https://www.ietf.org/mailman/listinfo/ietf