[rfc-i] draft-crocker-rfc-media-00

Alfred =?hp-roman8?B?SM5uZXM=?= ah at tr-sys.de
Fri Aug 29 01:06:55 PDT 2008


Dave,
thanks for the slight generalization performed by your I-D,
draft-crocker-rfc-media-00.

Allowing to Split *the* image file into several files per 'image'
will certainly further alleviate the task of RFC authors, the RFC
Editor, and tools authors.

However, for the latter folks it would perhaps be *much* easier
if the draft posed the requirement that the content of each
image file must be 'contiguous' and anchored at a single place
in the base document, to be able to insert the whole image file
there.  (Isn't that what xml2rfc already does?)  Hence, I suggest
to *require* multiple image files if multiple anchors are needed.

Also, adding  Section 1.2, "Goals", is an important step,
in general, and to avoid endless circular discussions.
(The lack of similar rationale is a major deficiency in the
other current RFC-Ed I-D, the RFC Errata draft, for instance.)

Unfortunately, the time pressure in generating this -00 version
is very much visible, and the notes below are intended to help
get rid of the inconsistencies and textual flaws.
(BTW: Most nits have been faithfully inherited ...)


(1)  General: running page titles

  s/Email Architecture/Images in RFCs/         :-)


(2)  General: image file --> image file(s)

The generalization has not been performed consistently.
Many parts of the text still refer to "the image file" (in
singular form) where "the image files" or "the image file(s)"
or "an image file" should be mentioned insted.

For brevity, I do not list all instances of this flaw, but
only some important ones, nearby to other changes proposed.


(3)  General: PDF --> {standard format}

The generalization for the standard format has not been
performed consistently.  Some phrases still quote PDF,
or the specifications for PDF, or perhaps PDF specific tools.

Furthermore: If more than one such format is going to be allowed,
should we really request that all image files for an RFC use the
*same* format, or is that a needless restriction?
The present text seems to generally assume a single format.


(4)  Section 1, 3rd paragraph

The draft says:

   The three versions of an RFC using .txt+.pdf+.ps encoding are in
   separate files in the primary RFC repository
|  (http://www.rfc-editor.org/rfc/"), with suffixes ".txt", ".pdf", and
   ".ps".  The RFC Editor search engine returns links to all three
   versions when they are present in the repository.

This is misleading and wrong.

The primary RFC repository still is the RFC-Editor FTP site,
and the RFC Editor search engine in fact eventually returns links
to that site:
   ftp://ftp.rfc-editor.org/in-notes/
   ^^^   ^^^                ^^^^^^^^


(5)  Section 2

(5.1)  1st paragraph

Mismatched curly braces:    {{standard image}
                            ^^              ^
For consistency with later text, please remove one '{'.

(5.2)  2nd paragraph

I suggest to add more precision to the internal reference,
by changing:

   The base file may be formatted exactly like current ASCII RFCs, with
   three minor exceptions described below.  [...]
---                                 ^^^^^
   The base file may be formatted exactly like current ASCII RFCs, with
   three minor exceptions described in Section 4.  [...]
                                    ^^^^^^^^^^^^

The idea of optionally using xml2rfc format requires more thought.
For instance, placing such files as .txt into the RFC repository
(Section 7) will certainly confuse readers and break tools.

(5.3)  3rd paragraph

An instance of (2) above:

   The intellectual property boilerplate in the base file ("Rights in
|  Contributions BCP 78, RFC 4748 [RFC4748] ) would apply equally to the
            vv                             ^
|  image file.  [...]
---
   The intellectual property boilerplate in the base file ("Rights in
|  Contributions BCP 78, RFC 4748 [RFC4748]) would apply equally to the
            vvvvv                          ^
|  image file(s).  [...]


(5.4)  5th paragraph -- issue (3)

The final conclusion there has been left unchanged, still arguing
in favor of PDF (only).
This should be modified to actually allow PNG, GIF, etc., instead,
as apparently has been intended by the introduction of the meta-
identifiers "{image format}" / "{standard image}" (etc.).


(6)  Section 3

(6.1)  1st paragraph -- issue (3)

The draft says:

   Each image would be in a single {image format} file, containing only
|  that image and consistent with the description in [RFC3778] and
              vvvvvvvvvvvv                           ^^^^^^^^^
|  defined in [ISO32000-1].  [...]

These references are for PDF only.
Hence, that text needs amendments.

(6.2)  2nd paragraph -- issue (3)

Similarly, ...
                                                         vvv
|  Future experience may require published guidelines on PDF-generating
   software that claims to satisfy {image format}{image format} but does
   not.

... is inconsistent internally and with the generalization .

(6.3)  3rd paragraph -- nit

Please add the missing final period to this paragraph.

(6.4)  5th paragraph -- issue (2), plus wrong pointer

                     [...].  The page number of the end-of-RFC
   boilerplate (in the base RFC file) would be the first page number
|  after those in the image file.  Each page of the image file would
   contain the same headers and footers as the base file, except for one
|  change in the footer, suggested below.
---              ^^^^^^
                     [...].  The page number of the end-of-RFC
   boilerplate (in the base RFC file) would be the first page number
|  after those in the image file(s).  Each page of the image file(s)
                                ^^^                              ^^^
   would contain the same headers and footers as the base file, except
|  for one change in the header, suggested below.
                         ^^^^^^

[ See item (7.1) below for rationale! ]

(6.5)  6th paragraph -- issue (2), plus poor language

"They may be ... or it may use ..." seems to be ppor language.

Proposal:

   Figures included in the image file would have to be labeled in a
   fashion that facilitated referencing from the base RFC.  They may be
   numeric and monotonic or it may use textual image names.  [...]
---
   Figures included in the image file would have to be labeled in a
|  fashion that facilitated referencing from the base RFC.  The labels
                                   vvvvvvvvvv               ^^^^^^^^^^
|  may be numeric and monotonic or consist of textual image names.
   [...]


(7)  Section 4.2

(7.1)  1st paragraph -- grammar

   ... should immediately following the Table of Contents, ...
---                             ^^^
|  ... should immediately follow the Table of Contents, ...

(7.2)  Example for ToC + list of Figures

RFC page numbering starts with no. 1 for the front page, and the
word "follows" is rather questionable for page 1 when used in the
Figures section (perhaps also on page 1, or even on page 2).

Therefore, using page 1 for Section 1 in the example seems to be
rather unusual, and perhaps even confusing.
Therfore, I suggest using page 2 (at least) instead:

   Table of Contents

|  1. Introduction ............................................... 1
---                                                                ^
   Table of Contents

|  1. Introduction ............................................... 2
                                                                   ^

... and (at the bottom) ...

|  (Page 1 follows)
---      ^
|  (Page 2 follows)
         ^

(8)  Section 4.3

(8.1)  1st paragraph

As already noted in a post to rfc-interest at rfc-editor.org,
the "RFC nnnn" appears in the upper left corner of RFC pages,
not in the footer.  Also, the quotes do not match, and white
space introduced irregularly after the second '/'.

Therefore, the text should be corrected:

   The header line "Request for Comments: nnnn" in the base file could
   be changed to "Request for Comments: nnnn/Base".  For consistency,
|  the lefthand footer could become "RFC nnnn/Base".  The lefthand
                ^^^^^^
|  footer in the image file could then be: "RFC nnnn/ {Image Name}.
---^^^^^^                                           ^^^          ^^
   The header line "Request for Comments: nnnn" in the base file could
   be changed to "Request for Comments: nnnn/Base".  For consistency,
|  the lefthand running header could become "RFC nnnn/Base".  The
                ^^^^^^^^^^^^^^
|  lefthand running header in the image file could then be:
            ^^^^^^^^^^^^^^
|  "RFC nnnn/{Image Name}".
            ^^          ^^^

[ Note: the final string in quotes should be forced into one line
  for clarity. ]

(8.2)  3rd paragraph -- improvement

I suggest the following improvement for clarity and precision:

   The following sentence could be placed in the "Status of this Memo"
   section: "This RFC is a composite of this base file and {image
   format} image files."
---
   The following sentence could be placed in the "Status of this Memo"
|  section: "This RFC is a composite of this base file and M {image
|  format} image file[s]."
                     ^^^                                  ^^^
... where 'M' denotes the actual number of image files for that RFC,
and '[s]' is to be omitted iff M==1.

Further, it might be more versatile to allow a mix of file type for
the image files; to support this, the text should be simplified:

   The following sentence could be placed in the "Status of this Memo"
|  section: "This RFC is a composite of this base file and M image
|  file[s]."
       ^^^                                                ^^^^^^^^

(9)  Section 5 -- item (2)

In the last sentence, please change:

         ... figures in the image file, ...
---
|        ... figures in an image file, ...
                        ^^

(10)  Section 6 -- nits

Please add a trailing period to implication #2.

Please remove the double trailing period after implication #7.


(11)  Section 7, 2nd paragraph -- item (2)

Minimal change:

   If a {image format} image file exists along with a base ASCII RFC,
   then RFCs in any other format (e.g., complete {image format} files,
   HTML, or Postscript) remain supplemental, with the reader taking
   responsibility for assuring that they are equivalent to the base RFC
   and image file.  [...]
---  v                         v
)  If {image format} image files exists along with a base ASCII RFC,
   then RFCs in any other format (e.g., complete {image format} files,
   HTML, or Postscript) remain supplemental, with the reader taking
   responsibility for assuring that they are equivalent to the base RFC
   and image file.  [...]

Further, the considerations at the end of (3) and (8.2) above might
be applicable as well.


(12)  Discussion

It would be nice to have a note included in the draft (near the
front matter or the Authors section), pointing to the
rfc-interest at rfc-editor.org mailing list for discussion of the draft.


Kind regards,
  Alfred HÎnes.

-- 

+------------------------+--------------------------------------------+
| TR-Sys Alfred Hoenes   |  Alfred Hoenes   Dipl.-Math., Dipl.-Phys.  |
| Gerlinger Strasse 12   |  Phone: (+49)7156/9635-0, Fax: -18         |
| D-71254  Ditzingen     |  E-Mail:  ah at TR-Sys.de                     |
+------------------------+--------------------------------------------+



More information about the rfc-interest mailing list