[rfc-i] Will we have what we need for reviewing and referencing text in drafts?

Paul Kyzivat pkyzivat at alum.mit.edu
Tue Jun 24 09:17:33 PDT 2014

On 6/24/14 10:52 AM, Joe Touch wrote:
> On 6/24/2014 7:49 AM, Paul Kyzivat wrote:
>> On 6/24/14 10:38 AM, Joe Touch wrote:
>>> On 6/24/2014 5:54 AM, Paul Kyzivat wrote:
>>>> As an alternative to page numbers, some doc formats use line or
>>>> paragraph numbers, that are positioned in margin.  A TOC could
>>>> reference
>>>> these. Of course this would be yet another format.
>>> At least one argument I heard for going to new formats is to allow
>>> "reflow" of paragraphs for easier reading on various devices.
>>> That would destroy the utility of line numbers.
>> But not paragraph numbers. (Assuming we could come up with a canonical
>> way to assign paragraph numbers that is independent of format.
> That's the trick, but agreed.
> My view is that section numbers are sufficient to pin things down
> roughly; the rest is better done by direct context (quote a portion of
> the text) than by a count-based reference.

I review a lot of drafts, and often have a lot of comments.

Today I use a mixture of techniques to reference specific portions of a 
draft when commenting. The comments are almost always in the body of an 
email. (I write plaintext emails, not html, because I hate the way 
deeply nested threads come out in html emails.)

When a section number is close at hand (small sections, or issues with 
the beginning of a section) I will typically use the section number and 
then either:
- paste in a section of the paragraph, with its indentation.
   This works well when I'm reading the txt or html'ized form,
   because the line breaks and indentation are preserved, which
   sets it off.

- show a substitution: s/the old text/the new text/.
   This is precise if there is unique old text within the section.
   But it's a pain to verify that it is unique in a large section.
   And it forces the reader to do a text search to find what I'm
   talking about. Often I combine it with the above: copy a paragraph
   from the old text and then give a substitution to do within it.

But when sections are big those techniques get harder to apply. If the 
section number isn't immediately visible to me in my window, I'll scroll 
back. If I get to a page number before a section number then I'm 
inclined to reference that rather than keep looking for the section 
number. I'm guaranteed to find a page number without going very far, 
while I might have to go a *long* way to find a section number.

Another technique I use for reviewing is to mark up a PDF. For something 
big I will often start out that way. It is very good for making notes 
while reading. But I don't find it very good for discussing issues with 
a draft. It is very hard to have an email discussion about things that 
have been captured in that form. So if I start by marking up a document 
that way then I will typically make another pass and transcribe the 
important issues from the markup into an email, using a technique such 
as I describe above. Unfortunately copying text out of a pdf into an 
email doesn't work nearly as well as doing so from plain text or 
html'ized format.

I don't expect that everybody works the way that I do. And I'm willing 
to change my mode of operation, but I hope things don't get worse, for 
me the reviewer or for the recipient who needs to find exactly what I am 
talking about.


More information about the rfc-interest mailing list