Subject: [Tools-discuss] Rfcdiff-1.40 feedback

From: Tony Li <[email-masked]>
Date: Fri, 18 Feb 2011 00:11:19 -0800

Hi,

I've found that Mac OS 10.6.6's /usr/bin/awk doesn't work with a "rfcdiff --html" directive.  However, installing gawk fixes the issue.

The challenge here is that the output basically gives no indication of any changes or other difficulties.  It just doesn't work.  ;-(

It would be good if this was at least noted someplace obvious.

Thanks,
Tony

---

From: Henrik Levkowetz <[email-masked]>
Date: Wed, 23 Feb 2011 12:42:42 +0100

Hi Tony,

On 2011-02-18 09:11 Tony Li said:
> 
> Hi,
> 
> I've found that Mac OS 10.6.6's /usr/bin/awk doesn't work with a
> "rfcdiff --html" directive.  However, installing gawk fixes the
> issue.

Hmm.  Unfortunate.

> The challenge here is that the output basically gives no indication
> of any changes or other difficulties.  It just doesn't work.  ;-(
> 

I've released v1.41, which bails out with an error message for --html
mode under OS X if awk reports 'awk version 20070501', which is what
it reports for me under 10.6.6.  It also suggests that the issue can
be fixed by installing gawk.

If I can find some more time, I might try to work out what it is that
awk doesn't like and fix it, but this release at least doesn't fail
silently.

Best,

	Henrik

---

From: "Dearlove, Christopher (UK)" <[email-masked]>
Date: Thu, 24 Feb 2011 15:56:29 -0000

I'll throw my contribution into the solicited community
comments on xml2rfc. As background I've been one of the
users of xml2rfc on half a dozen Internet Drafts (three,
shortly to be four, now RFCs). So I would guess I may be
a not atypical user. I've not used any alternative.

All I'm really hoping for from this posting is the relevant
someone to indicate "comment captured", possibly with a "we
already had this". (I have said this before on xml2rfc list,
but I wouldn't have expected that to be captured, and I'm
sure I'm not the only person, in fact I positively hope not,
it's more likely for change to happen that way.) Then it can
take its chances along with other suggestions in the process,
specifically the what changes are needed aspect.

Of course I have nits, anyone who uses software has nits.
But the only nit I'd mention would be with regard to error
messages, and the now on hold RFP discussed those I believe.
I will note that we (I and my co-authors) use file inclusion
a lot (it helps for parallel editing) so error messages need
to refer back to the original multiple files, and the last I
checked most do, a few don't.

But there's one feature that I didn't see mentioned in the RFP,
and that's top of my list of things to add to xml2rfc. And
that's regarding page control issues. Currently tables can
be split (badly) and captions of tables and figures put on
separate pages to their table or figure. Less critical, but
while I'm on a wish list, I don't like section headings at
the foot of a page while the section starts on the next page.

At the moment the only fix I know is using vspace with many
lines (I use 999 as it stands out) to force a page break.
But then make even a small change and you may need to remove
all vspace after that point, run, check for the problems of
the types described, fix the first such problem with a vspace,
re-run, and so on until the end of the document. This is time
consuming, and we've had draft versions we forgot to get this
right for, so personally it passes my tests as a reasonably
high priority for me. (It would save significant effort, it
would enable better documents.)

I would be flexible on the solution. The obvious (to me, others
may have better ideas) two possibilities are first an attribute
on some elements that says "keep all on one page" (or, probably
more precisely, start on new page if won't fit on rest of this
one) and second a "keep element on same page as next element"
(similar rewording). You might end up needing both. If I created
tables that were longer than a page I'd add to that list (split
table only between logical rows, heading row repeat on new page
options).

But to finish on a positive note, the main things any new
xml2rfc needs to be is as good as the current one which is
anything but bad, just not perfect.

-- 
Christopher Dearlove
Technology Leader, Communications Group
Communications and Networks Capability
BAE Systems Advanced Technology Centre
West Hanningfield Road, Great Baddow, Chelmsford, CM2 8HN, UK
Tel: +44 1245 242194  Fax: +44 1245 242124

BAE Systems (Operations) Limited
Registered Office: Warwick House, PO Box 87,
Farnborough Aerospace Centre, Farnborough, Hants, GU14 6YU, UK
Registered in England & Wales No: 1996687

********************************************************************
This email and any attachments are confidential to the intended
recipient and may also be privileged. If you are not the intended
recipient please delete it from your system and notify the sender.
You should not copy it or use it for any purpose nor disclose or
distribute its contents to any other person.
********************************************************************

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 24 Feb 2011 17:03:47 +0100

On Feb 24, 2011, at 16:56, Dearlove, Christopher (UK) wrote:

> the only fix I know is using vspace

needLines.  100 % more satisfying.
Also doesn't totally wreck the HTML output.

<?rfc needLines="30"?>

Gruesse, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Thu, 24 Feb 2011 17:09:06 +0100

On 24.02.2011 16:56, Dearlove, Christopher (UK) wrote:
> ...
> ...

I believe that before thinking about new markup, the developers of the 
new tool should simply try harder to make the defaults look ok. After 
all, we don't need to tell the processor that pre/postambles should 
stick to the artwork/table, or that section headings shouldn't be orphaned.

 From the practical point of view: I'd simply not worry about where page 
breaks end up in internet drafts. Let the RFC production center deal 
with it when the time is ripe.

Best regards, Julian

---

From: "Dearlove, Christopher (UK)" <[email-masked]>
Date: Thu, 24 Feb 2011 16:13:49 -0000

Julian Reschke
> with it when the time is ripe. 

I think it's appropriate to have Internet Drafts look reasonable
too, not just RFCs, for a number of reasons. (One of those, though
not the most important, is that IESG members will nit-pick far less
than that.)

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 24 Feb 2011 17:15:05 +0100

On Feb 24, 2011, at 17:09, Julian Reschke wrote:

> I'd simply not worry about where page breaks end up in internet drafts.

Doesn't work for me.
I spend way more time with I-Ds than with RFCs.
They should be readable.
(But not tweaked to the max -- I agree to about 50 %.)

Gruesse, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Thu, 24 Feb 2011 17:19:30 +0100

> (But not tweaked to the max -- I agree to about 50 %.)

...if I want something for reading, I try to find the HTML version :-) 
(both for I-Ds and RFCs)

---

From: Tony Hansen <[email-masked]>
Date: Thu, 24 Feb 2011 11:55:24 -0500

> specifically the what changes are needed aspect.

About a year ago, we started using trac to record issues and enhancement 
requests for xml2rfc.tcl and the xml.resource.org web site. It can be 
found at

     http://trac.tools.ietf.org/tools/xml2rfc/trac/

Anyone is free to look at the known issue list. And anyone with a login 
on tools.ietf.org can add issues. (And for those who are truly 
ambitious, anyone can download the code from svn and contribute to the 
code base.)

Please take a look and see if your issues are there, and if not, feel 
free to add them. See http://tools.ietf.org/newlogin if you don't have a 
login on tools.ietf.org.

> checked most do, a few don't.

There is an <rfc> PI that lets your XML define what file name and line 
number is to be used for error messages. So whatever you use to create 
the single XML for uploading xml.resource.org and emit those PIs and 
your error messages should then refer back to the original multiple files.

If you're using xml2rfc.tcl locally, the error messages should be 
generated correctly.

> would enable better documents.)

Yeah, splitting tables across pages and widow & orphan control are areas 
where the current xml2rfc.tcl could do better. See issues #14 and #24 
for some information on these issues. (Feel free to add additional 
information to them.)

> (similar rewording). You might end up needing both.

Both forms are needed at the end.

> If I created

One thought is that certain tags should automatically have the "keep 
with next" attribute. Section titles are one example.

> anything but bad, just not perfect.

Thanks for all your comments.

     Tony Hansen