Subject: Automatically updated Table of Contents with Nroff

From: Stefan Santesson <[email-masked]>
Date: Tue, 14 Jul 2009 22:56:52 +0200

As I know there are quite some Nroff users still out there, this might be
welcome news.

While I quite like Nroff for its easy to use and readability. one of the
problem that always have annoyed me with Nroff is to manually update the
Table of Content.
This is something where xml2rfc have a great edge, over Nroff, or at least
had.

So the good news is that version 1.0 of NroffEdit includes a feature for an
automatically updated Table of Contents.
All you need to do is to click where you want the TOC and paste it there.
Once you done that it will automatically update as you change name of
titles, change page locations or even add or remove titles.

More information about this is no my web:
http://aaa-sec.com/nroffedit/index.html

I want to thank for the feedback I have received so far.
If you like this or have any feedback of any kind, feel free to let me know.

/Stefan

---

From: Donald Eastlake <[email-masked]>
Date: Tue, 14 Jul 2009 19:27:10 -0400

It's trivial to define nroff macros to create a Table of Contents.

Donald
=============================
 Donald E. Eastlake 3rd   +1-508-634-2066 (home)
 155 Beaver Street
 Milford, MA 01757 USA
 [email-masked]

On Tue, Jul 14, 2009 at 4:56 PM, Stefan Santesson<[email-masked]> wrote:
> _______________________________________________
> Ietf mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/ietf
>
>

---

From: Stefan Santesson <[email-masked]>
Date: Wed, 15 Jul 2009 03:03:45 +0200

Sounds interesting.

Do you by any chance have a source where this "trivial" information is
available?

All I have managed to get across are ways to generate a TOC in the end of
the document, that you have to move manually. When doing that move, your
page numbering and formatting may change.

Anyway, the trick/attempt here is to generate a TOC within a WYSIWYG editor
for instant view without ever touching a command line tool, and not having
to index all your titles with macros, but simply through letting the tool
analyze the typical Nroff I-D.

/Stefan

---

From: Stefan Santesson <[email-masked]>
Date: Wed, 15 Jul 2009 03:03:45 +0200

Sounds interesting.

/Stefan

---

From: "Randy Presuhn" <[email-masked]>
Date: Tue, 14 Jul 2009 23:04:52 -0700

Hi -

> From: "Stefan Santesson" <[email-masked]>
> To: "Donald Eastlake" <[email-masked]>
> Cc: "IETF Discussion Mailing List" <[email-masked]>
> Sent: Tuesday, July 14, 2009 6:03 PM
> Subject: Re: Automatically updated Table of Contents with Nroff
...
> page numbering and formatting may change.
...

No need to manually edit.

Use the macros or awk / sed to spit the toc into a file which can be inserted
into the correct position by the .so nroff directive.  This will result in
a table of contents in the correct position.  There is the possibility
that if the number of toc pages has changed from one iteration
to the next that the page numbers will be off by one, but that will
go away the next time the process runs.

For editing a document, particularly a largish one, the availability of
.so is for me nroff's biggest advantage over xml2rfc.

Randy

---

From: Julian Reschke <[email-masked]>
Date: Wed, 15 Jul 2009 11:13:35 +0200

> .so is for me nroff's biggest advantage over xml2rfc.

How exactly is that an advantage of xml2rfc?

BR, Julian

---

From: "Randy Presuhn" <[email-masked]>
Date: Wed, 15 Jul 2009 10:02:33 -0700

Hi -

> From: "Julian Reschke" <[email-masked]>
> To: "Randy Presuhn" <[email-masked]>
> Sent: Wednesday, July 15, 2009 2:13 AM
...
> How exactly is that an advantage of xml2rfc?

That's my point.  It's a capability xml2rfc lacked, at least the last time
I used it.  For the user to be able to split stuff up into multiple files
is a huge advantage which should be familiar to any programmer.
Examples from my own experience:  It's cleaner to be able to keep mib
modules in a separate files, rather than extracting it from a formatted
document.  This is particularly true when there are multiple MIB modules
in a document.  Common references (especially for a bundle of inter-related
I-Ds, but also for RFCs) can be handled as macros that result in mnemonic
values showing up both in the source and in the generated output.  This
is especially useful when one RFC is replaced with another: one little
edit to the file of reference macros, rather than going through the whole
bundle of source files.  Finally, it is a much cleaner way to handle boilerplate,
particularly if you want to use configuration management software for
your sources and have a "paper trail" of boilerplate changes.

Now, it is true the RFC editor wanted nroff sources in the form of a single
file.  Fortunately, this is trivial to produce at publication time using soelim
or equivalent.

Randy

---

From: Julian Reschke <[email-masked]>
Date: Wed, 15 Jul 2009 19:13:07 +0200

Hi,

>> How exactly is that an advantage of xml2rfc?

I meant "over xml2rfc"...

> is a huge advantage which should be familiar to any programmer.

xml2rfc produces TOCs automatically, and in the right place.

> document.  This is particularly true when there are multiple MIB modules

And of course you can do that with xml2rfc as well; just automate the 
process of converting the source file to something that can be included 
into the XML source using the standard XML include mechanisms.

> your sources and have a "paper trail" of boilerplate changes.

You can do that in XML as well; just define them as entities and put 
them into a file you include as external reference.

> file.  Fortunately, this is trivial to produce at publication time using soelim

But then, TOC generation will not work anymore as expected, right?

Point is: nroff and xml2rfc share the advantage that they are simple 
text based formats, which can be put under version control, and 
collaborative editing/change control just works. Missing features can 
simply implemented using automated pre- or post-processing stages.

BR, Julian

---

From: "Randy Presuhn" <[email-masked]>
Date: Wed, 15 Jul 2009 11:00:20 -0700

Hi -

> Sent: Wednesday, July 15, 2009 10:13 AM
...
...

With respect to boilerplate, xml2rfc lacks this advantage.
*It* generates the boilerplate; the user has no way of knowing whether
the option present in the source file will result in the same output
text today as it did yesterday.  From a configuration management /
revision control perspective, this is highly undesirable.  It would be
much better to be able to "#include" a versioned source file for
those bits.

Randy

---

From: Julian Reschke <[email-masked]>
Date: Wed, 15 Jul 2009 20:48:23 +0200

> text today as it did yesterday.  From a configuration management /

As far as I can tell, there never has been a change that would have 
caused the boilerplate for a given combination of @ipr attribute, RFC 
number, and publication date to change.

Did this actually occur to you? Details would be appreciated.

> much better to be able to "#include" a versioned source file for

I'm not disagreeing with that this would be good, in particular for 
archival; as a matter of fact *my* implementation of the format allows 
this via an extension element.

But as far as I can tell, most people *like* the fact that xml2rfc takes 
care of the boilerplate.

BR, Julian

---

From: [email-masked]
Date: Wed, 15 Jul 2009 12:06:30 -0700 (PDT)

> text today as it did yesterday.

I've been using xml2fc extensively since it came out, and I've *never* seen a
case where the boilerplate changed for a given combination of ipr setting and
date. Moreover, I would regard any such change as a bug, not a feature.

> From a configuration management /
> revision control perspective, this is highly undesirable.

it would be if it happened. AFAIK it does not.

> It would be

I strongly disagree. An *overwhelming* advantage of xml2rfc is that it takes
care of boilerplate and I rarely if ever have to think about it, much less
having to arrange for a set of include files to be available. Blech on that.

				Ned

---

From: "Randy Presuhn" <[email-masked]>
Date: Wed, 15 Jul 2009 10:36:41 -0700

Hi -

...
> into the XML source using the standard XML include mechanisms.
....

I couldn't find such mechanisms described anywhere the first time I used xml2rfc.
I just looked at the W3C website XML pages, and still am unable to find them.
How does one do a simple ".so" or a "#include" in XML?

Randy

---

From: Marc Petit-Huguenin <[email-masked]>
Date: Wed, 15 Jul 2009 15:40:59 -0700

> How does one do a simple ".so" or a "#include" in XML?

[...]
<references title="Normative References"
xmlns:xi="http://www.w3.org/2001/XInclude">
  <xi:include
xi:href="http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml"
/>
[...]

xml2rfc does not support xinclude, so you have to generate an
intermediate file:

xsltproc --xinclude -o ouput.xml dup.xslt input.xml

Here's the dup.xslt file:

<?xml version="1.0" ?>
<!--
   Duplicate a document, without the comments
  -->
<stylesheet version="1.0" xmlns="http://www.w3.org/1999/XSL/Transform">
  <output method="xml" version="1.0" encoding="UTF-8" indent="yes" />
  <template match="* | text() | processing-instruction('rfc') | @*">
    <copy>
      <apply-templates select="@* | * | text() |
processing-instruction('rfc') " />
    </copy>
  </template>
</stylesheet>

-- 
Marc Petit-Huguenin
Home: [email-masked]
Work: [email-masked]

---

From: Julian Reschke <[email-masked]>
Date: Thu, 16 Jul 2009 07:15:00 +0200

> How does one do a simple ".so" or a "#include" in XML?

<http://xml.resource.org>, see under "Helpful Hints / Including Files". 
That page also links to <http://tools.ietf.org/tools/templates/> with 
templates. Look, for instance, at 
<http://tools.ietf.org/tools/templates/template-edu-xml2rfc.xml>.

In the XML spec, look for "external entities" 
(<http://www.w3.org/TR/REC-xml/#sec-external-ent>).

There are other inclusion mechanisms; xml2rfc supports a processing 
instruction: 
<http://xml.resource.org/authoring/README.html#include.file.facility> (I 
don't like this one as it is specific to the xml2rfc processor).

And then, because it's XML, preprocessing is easy; such as with XInclude 
mentioned by Marc Petit-Huguenin.

Hope this helps, Julian

---

From: Stefan Santesson <[email-masked]>
Date: Thu, 16 Jul 2009 11:59:21 +0200

All of this is interesting reading indeed and reveals stuff that I did not
know about.

However, I have never regarded boilerplate issues as something that has
bothered me a lot when writing a draft. These boilerplates are pretty stable
and once you got them in place in the first draft (often by copying them
from another document) you can mostly forget about them. Id-nits will always
scream if you need to update.

What I personally has felt as the major void is an easy way to see your
finished product, not after, but during edit.

I don't want to save my current edit to a file and enter it into some kind
of tool to see what I write. I want to see it while I'm editing. E.g. what
happens if I include a page break here? Does it look better if I add an
extra line or should I keep this section on same page?, etc.

I've learned that there are trivial ways to solve many hard issues like TOC
generation in nroff. Seeing how its done it appears trivial only if you know
how to do it and if you are prepared to expand your knowledge about nroff
quite a bit. And you still won't see the result while you edit.

/Stefan

---

From: Julian Reschke <[email-masked]>
Date: Thu, 16 Jul 2009 12:15:32 +0200

> extra line or should I keep this section on same page?, etc.

I realize that different people have different preferences :-).

As a matter of fact, while editing a draft, page breaks are the least of 
my worries. I do not want to be bothered with them. I do not want to 
fine tune vertical whitespace. Keep in mind that whatever you spend your 
time on with respect to this will be undone by the RFC Editor anyway.

BR, Julian

---

From: Stefan Santesson <[email-masked]>
Date: Thu, 16 Jul 2009 12:36:29 +0200

I guess you are right about that.

And I'm mostly the same way. Still I find things when I see the finished
product that I want to tweak before submission.

Even if I like the result, I mostly end up doing at least 10 iterations of
Save -> compile -> open in viewer -> check result, before I'm done.

Page breaks is the least of the issues. What is more important is that
sections describing protocol syntax is not all messed up with wrong indent,
line breaks etc.

I guess not everyone appreciate WYSIWYG, but I do :)

/Stefan

---

From: Julian Reschke <[email-masked]>
Date: Thu, 16 Jul 2009 13:17:35 +0200

> I guess not everyone appreciate WYSIWYG, but I do :)

Did you try previewing the HTML version, by using rfc2629.xslt and just 
pressing F5 in your favorite browser?

BR, Julian

---

From: Stefan Santesson <[email-masked]>
Date: Thu, 16 Jul 2009 14:40:32 +0200

Julian,

For me this is not about nroff versus xml and I'm really not trying to
convince anyone to move away from xml.

I meant to discuss how to do TOC and other formatting for those who like to
edit in nroff.

/Stefan