ietf
[Top] [All Lists]

Re: Automatically updated Table of Contents with Nroff

2010-12-29 20:25:34
Julian Reschke wrote:

On 28.12.2010 18:26, Martin Rex wrote:
...
Everyone who looks at writing I-Ds should seriously consider looking
at NRoffEdit before deciding which document format and tool to use.
...

Everyone who looks at writing I-Ds should also seriously consider 
xml2rfc. :-)

Only if he is in for a lot of pain and trouble.

I tried to use xml2rfc once and gave up after 3 hours of getting NOWHERE,
not even _running_ xml2rfc.

I've been using cygwin for ~10 years (primarily as X-Server tunneling
through SSH and a few unix shell utilities, but the subset of what I
had installed wasn't capable of running xml2rfc.  Trying to update
my existing (>3 year old) cygwin installation to get the necessary
tools hosed my entire cygwin installation, so I had to restore that
part from backup later on).  My productive Linux installation (~5 year old)
wasn't capable of running xml2rfc and my Live distro I tried
(Knoppix5) neither.

With NRoffEdit I was busy writing my first I-D 30 minutes after
downloading the software.  It just worked intuitively and hazzle-free
on _all_ of my Windows machines.

Out of curiosity, I just tried it on my productive Linux machine.
Starting it took me ~5 minutes (copying the stuff over from Windows,
finding the java binary and figuring out that I have to
type "/some/where/bin/java -jar /tmp/NroffEdit/NroffEdit.jar"

I haven't figured out how to make it/Java use fixed width fonts on
Linux yet, though (a problem that I didn't have on Windows).



    http://aaa-sec.com/nroffedit/

It is currently the 5th entry in the section "Prepare Documents"
on this page:

  http://tools.ietf.org/


NRoffEdit is an all-in-one wysiwyg tool in Java that maintains
the TOC for you (within the .nroff source itself).

Which will only work properly as long the output isn't run through 
standard NROFF, and page breaks change. Just saying.


Huh?  That problem simply does not exist.

NRoffEdit creates the same result as nroff used by the RFC Editor,
so there is not going to be any different page breaks.


With most I-Ds you can tell when authors are using xml2rfc instead
of NRoffEdit, because the documents often contain awkward page breaks
positionas within sections such as Authors and References and more
typos.




And yes, xml2rfc also maintains the TOC.

That is a funny way to put it.

I-Ds created with xml2rfc often contain stale section references
because section numbering is "automatic" while section referencing
appears to be manual (and the latter therefore regularly forgotten).

NRoffEdit updates the TOC while you're editing the document
and press <F3> and you immediately see the result in the preview
window.

Every xml2rfc operation is a manual operation on the commandline
completely seperate from you Editor, and you need another manual
intervention a to see the result (which you might need in order
to create/update section cross-references).

To me "xml2rfc maintains the TOC" sound like a slight exxageration
of the significant complexity of the underlying workflow
(an issue whose solution is left up entirely to the xml2rfc user).


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

<Prev in Thread] Current Thread [Next in Thread>