User Tools

Site Tools


design:text-requirements

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
design:text-requirements [2013/09/24 16:13]
paul Added unpaginated requirements
design:text-requirements [2013/10/15 19:52] (current)
paul
Line 1: Line 1:
- ==== Requirements for Text Output ====+==== Requirements for Text Output ====
  
-Policy requirements: +The following assumes that the text-only non-canonical format intended consumer is people who like the current format but want to be able to get all the semantic content out of the new canonical format, and that the HTML format will be done in a way where copy-and-paste of text will be easy and predictable.
-  * an RFC may include ASCII art OR SVG, but not both +
-    * Paul asks: Why? The term "ASCII art" is under-specified. The IETF community does not agree what is and is not "ASCII art". For instance, in RFC 5996, Figure 1 is clearly "art". However, the exchanges starting on page 10 might be considered art or not. If this RFC were in the new format and the authors wanted to make Figure 1 in SVG, why should they be forced to make the exchanges into SVG? And what about the text figures on page 48? I propose that this requirement be dropped. +
-  * the .txt publication output will include links to the info pages where there are images +
-    * we could potentially include direct links to the HTML anchors, but Heather is concerned about future failure of links; info page links are likely to be more stable +
-    * Paul says he is not at all concerned as long as the URLs are structured to be long-lived. He thinks that having direct links makes much more sense for someone who is going to process the text format using tools. +
-  * non-ASCII characters in the Author's Address section only (for now - this will expand in the future) +
-    * Wasn't this supposed to be "with exceptions allowed by the RSE"?+
  
-Technical requirements: +The text-only format must have the same page height limitations as the current RFC format.  It must contain the same headers and footers and page break character as the current RFC format.  There is no requirement that the text-only format use widow and orphan control; the use case for this is to allow similar referencing of paragraphs from the text-only format to the canonical format and non-canonical HTML format.
-The paginated .txt publication format must +
-  * use classic/branded headers on the first page +
-  * have paginated output +
-  * use classic/branded footers on each page +
-  * support UTF-8 encoding +
-  * max of 80 character width for images+
  
-The unpaginated .txt publication format must +The text-only format must allow for preformatted text and art to be 80 characters wide without wrapping those lines.  This is due to the relaxation of the 72-character restriction on preformatted text and art in the new canonical format.
-  * use classic/branded headers on the first page +
-  * have no page breaks at all +
-  * support UTF-8 encoding +
-  * max of 80 character width for images+
  
-Current requirements re: page breaking for xml2rfc v2+The text-only format must represent all SVG-based artwork as a "see reference" that goes to a stable URL, hosted on the RFC Editor's web site, that is part of the RFC's information page.  The use case here is someone who is reading the text-only document with a modern text editor that can follow URLs.  For example, if Figure 3 in the canonical version of RFC 7890 is a piece of SVG art, the text-only format would say something like "See http://www.rfc-editor.org/info/rfc7890/figure3.svg for this art".
  
-  #172: page-breaking enhancements +The RFC Editor must list all of the changes from the current RFC format to the new text format in a single document that can be used by people who have written text-processing tools.
-  Improve the PI autobreaks="yes". Currently, it seems to be "yes" by default but has no effect. It should prevent a page break from appearing in +
-  - the middle of a figure (see Figure 1 in the attached file) +
-  - in the middle of reference (see Section 10.2 in the attached file) +
-  - between a section title and the first sentence (see Section 5 in the attached file). This is the same as #72, which is marked fixed, but doesn't seem to be for this case. +
-  If there is an Appendix A, insert a page break before it. (This could be tied to rfcedstyle="yes", as it's RFC Editor style.) Or, improve the ability to insert a page break -- vspace blankLines="100" +
-doesn't always work. +
- +
-Ticket URL: <http://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/172>+
- +
- +
-Current internal guidance to the RPC: +
- +
-  "3+ lines held together"  i.e., at the bottom of a page, there is not a single line or 2 lines (unless they are their own paragraph). +
-  Keep a section title with the first 3 lines of the section. +
-  Keep a figure on one page. This includes its title (if any). +
-   - if figure does not fit on one page, break between discrete items in the figure.  +
-  Keep a table on one page. This includes its title (if any). +
-   - if table does not fit on one page, break between rows. +
-  Keep a term with its definition. +
-   - if definition is long (over 5 lines), keep at least the first 3 lines of the definition with the term. +
-  Keep a given reference on one page. +
-  Start Appendix A on a new page. +
- +
-  More subjective: +
-  Keep intro text with what it's introducing. (Example: text that introduces a list, an equation, or a piece of pseudocode) +
-  Break pseudocode nicely.+
  
 +After the RFC Editor has made the cut-over to the new canonical format (and thus the new non-canonical text-only format), all RFCs with a higher number must be in the new format.  This will allow tool makers to have a clear demarcation for knowing which text documents are in the old format, and which are in the new format.
design/text-requirements.1380064398.txt.gz · Last modified: 2013/09/24 16:13 by paul