Subject: Re: Automatically updated Table of Contents with Nroff

From: John C Klensin <[email-masked]>
Date: Fri, 25 Mar 2011 12:45:40 -0400

--On Thursday, March 24, 2011 02:14 +0100 Stefan Santesson
<[email-masked]> wrote:

> I can't escape the feeling that this discussion of using
> markup language editing to produce RFCs, is a bit upside down.
> 
> I'm much more concerned with draft writers having to deal with
> markup syntax than I am about drafters trying to put a page
> break in a sensible location, or format their text in a
> readable fashion.
>...

Stefan,

Parts of this are just a matter of taste.    While I have
learned to prefer generic markup approaches over formatting
markup, I certainly started with the latter (if you know nroff's
history, I used runoff on CTSS).   And I've done a good many
Internet Drafts (including several that evolved into RFCs) in
emacs and its clones: fancy formatting, page headers and
footers, etc., have never been requirements for I-Ds.   I used
TeX and LaTeX for a while, still prefer them for some
applications, and miss a few of their features for some
Internet-Drafts and RFCs.

I actually tried to be neutral about the issue in my note, but
let me be more explicit.  If nroff works for you, please use it.
My first priority in these discussions is to push back on any
effort to require a particular formatting tool or set of macros
for I-Ds, regardless of what that tool might be.

> The latter is not a problem that consumes a lot of energy,
> neither do I believe that drafters concern with readability is
> a matter that causes the RFC production center a lot of
> headache. So why is this a matter of concern?
> 
> I honestly think people waste a lot more time trying to figure
> out how to properly form correct markup syntax, than they do
> with format tweaking.

I think it depends on the person and sometimes on the document.
As I said, I've gradually learned to prefer generic markup, but
I'm definitely not inclined to impose that on anyone else.
What I'm opposed to, and what prompted my note, was purely what
I consider a misguided effort to turn the xml2rfc model from
generic markup into a formatting language.  My own intuition,
based on some experience with more traditional publications but
without having discussed this with either the RFC Production
Center or the RSE (the latter because we still don't have one),
is that we are actually better off having roughly-formatted and
roughly-edited documents passed off to the RFC Editor staff and
letting them do final technical and copy editing and page
layout.  From my point of view, that is called "letting the
professionals do their jobs".

I agree with John Levine's comment that whatever you know
already and are used to using is better.  What I think of his
"dead end" option is irrelevant.  You should use what works for
you.  I will probably admire your nroff tools but am unlikely to
use them.   I will use what works for me and won't try to
convince you that you should switch.  And we both should oppose
anything that forces everyone into a single set of tools for
preparing I-Ds.

> In my ideal world, where XML would work at its best, drafters
> would concentrate on writing text in a fashion that could be
> captured into XML (or any functional markup language), making
> XML the output of the editing process rather than the input.

Well, then, we agree almost completely.  In my ideal world,
people doing drafts would do as little markup as possible.  I
think there are still advantages to identifying some things,
especially comments and placeholders) as what they are.  YMMD on
that subject, or you may have a different list.  I don't think
xml2rfc is ideally designed from that standpoint, for some
reasons that are inherited from XML and some that are exclusive
to it.  I don't have the time or energy to redesign it and I'm
not sure I could do much better (although I'd probably make a
different set of what are, IMO, mistakes).

However, if carried to anything near its limit, that gets one
back to the "edit in emacs (or another plain-text editor of your
choice) and then hand things off to the RFC Editor staff" model.
If I were posting a few I-Ds a year --too few for me to remember
how to use xml2rfc efficiently-- and were not doing many of them
in collaboration with others, I'd probably go back to it.
 
> That way it would not hurt the drafters if the XML syntax was
> extended to capture both content and format, making it a
> complete input to the rendering process.
> 
> Given the rather primitive structure of RFCs, writing such
> editor seem not to be such a grim task. I'm even tempted to
> provide one in the next major version of NroffEdit, where you
> could choose nroff and/or XML as markup, but never bother with
> it when writing your draft.
> 
> If the XML syntax was expanded to capture formatting then that
> could indeed render nroff obsolete . Right now I would have to
> keep relying on nroff to ensure that the document is rendered
> as written.

Again, if the XML2RFC syntax were "expanded" to specify
formatting, it would seriously break the generic markup model
that inspired XML and its main predecessor.  That would not,
IMO, be an improvement.  

   john

---

From: "Andrew G. Malis" <[email-masked]>
Date: Fri, 25 Mar 2011 13:06:15 -0400

I know that XML is the wave of the future, but I just want to give
Stefan a plug as a happy user that NroffEdit makes the mechanical and
formatting part of writing drafts almost effortless.

Cheers,
Andy

---

From: John C Klensin <[email-masked]>
Date: Fri, 25 Mar 2011 14:21:44 -0400

--On Friday, March 25, 2011 13:06 -0400 "Andrew G. Malis"
<[email-masked]> wrote:

> I know that XML is the wave of the future, but I just want to
> give Stefan a plug as a happy user that NroffEdit makes the
> mechanical and formatting part of writing drafts almost
> effortless.

And, had it appeared a decade ago, I might be using it too.  As
it is, it would require my learning something new when I have a
pair of adequate (for me) solutions... and I'm at least as
vunerable to "what I know is better" as anyone else.  "Wave of
the future" doesn't interest me nearly as much as being sure
that whatever tools people find convenient and are willing to
support as needed remain usable and, in particular,  that we
don't find ourselves requiring the use of one particular tool...
no matter what it is.

     john

---

From: "John Levine" <[email-masked]>
Date: 25 Mar 2011 19:55:39 -0000

> What I'm opposed to, and what prompted my note, was purely what I
> consider a misguided effort to turn the xml2rfc model from generic
> markup into a formatting language.

For the record, I entirely agree.  The reason I've proposed adding
formatting twiddles to xml2rfc is so that the RFC Ed can use the
same tools as everyone else.  The idea to put the twiddlage into
a different namespace so we can discourage I-D authors from using
it is a reasonable one.

R's,
John

PS: One of the reasons nroff is so dead is that it's nearly impossible
to avoid coding format twiddles into your documents.

---

From: Stefan Santesson <[email-masked]>
Date: Sat, 26 Mar 2011 01:13:56 +0100

Great thoughts from many people.

I just want to clarify a few things as I see that my message is slightly
misunderstood.

Firstly:
The core of my opinion is NOT that I think people should convert to nroff
encoding or XML coding or XHTML encoding or whatever encoding as editing
language.
I don't think that authors in the future should have to deal with any
markup language at all. That is a task for the editing application, not
the drafter.

The only way that can happen is if we can provide the missing link between
draft editing and markup. The current formats as they are specified and
used today are both crippled.

Nroff can capture exact formatting but can't capture more advanced content
building metadata very well. I had to add a directive layer (only
understood by NroffEdit) inside Nroff comments to make that happen. The
output is still compatible with any nroff compiler, but such compiler will
not understand how to use the NroffEdit directives to alter e.g. Table of
content as the document evolves (the actual subject of this thread).

XML as it is used can capture content building metadata but not format.

That means that I can't build an editing tool that can capture the editing
process in standardized markup.
As long as this is the case, no editing tools free of markup hacking can
be developed that can interoperate with other editing tools on a full
scale.

Secondly:
The reason why I personally use Nroff as edit format is:

1) That how I started off and I have seen no compelling reason yet to
switch.
2) I find it personally the least evil format for the text writing process.
3) I managed to overcome many of the backsides with nroff (Table of
content building, reference generation etc) in my NroffEdit tool.
4) I like the WYSIWYG experience in my tool. To always be able to
immediately see the result of my editing makes me a better writer.

I have no reason to try to convince anyone to use anything but what works
best for you.

The most I can which for by making NroffEdit available is to put up a
viable darn-easy-to-use alternative to xml editing to inspire further
development of better tools.
Kudos to Julian and others involved with xml2rfc for you efforts!

/Stefan