Subject: Re: [xml2rfc-dev] Migration to ietf.org or rfc-editor.org

From: Alice Hagens <[email-masked]>
Date: Fri, 1 Oct 2010 13:51:48 -0400

Tony,

> Also, do you do any post processing on the nroff output?

Yes. Details below.  *Notes below indicate where changes in the XML file can be used (instead of post-processing) to alter the text output as needed (or partially as needed).

This always involves:

- replace the header with the 5741 header.

- replace the Status of This Memo text with the RFC 5741 SoTM text (http://www.rfc-editor.org/rfc-style-guide/status-memos.txt).

- remove the hard page breaks and place them again (so figures and reference entries are not broken across lines. *Note: needLines in the XML does not handle all cases and does not have expected behavior.)

- update the Table of Contents, if necessary.

This sometimes involves:

- remove extra blank lines before and/or after figures.
(*Note: deleting blank lines inside figure elements in the XML handles some cases.)

- fix indentation of a list.
(e.g., when hanging lists are used and hangIndent attribute is set above a certain value, xml2rfc's nroff output sometimes is not consistent with xml2rfc's text output. This seems to be a bug.)

- tweak the format of references.
(various oddities occur, e.g., when the title or seriesInfo elements do not create the desired text output. specifically: an author has put data in the seriesInfo name attribute (without using the value attribute), then text is followed by [space][comma], so the space is removed. An author does not want a title to appear inside quotation marks, but the contents of the title element automatically enclosed in quotation marks, so the quotation marks are removed.)  *Note: authors and RFC Editor can use the elements within the reference element to attempt to get the text output correct.

- move the line break(s) in a URL in a reference.
(e.g., when xml2rfc breaks a long URL is across multiple lines or after a "-", we place the line breaks 'nicely', so there are less line breaks or it's after a "/")

- move the line break in other text. 
(e.g., if "BGP/MPLS" is broken across a line (where it shouldn't be, e.g., title of a document). *Note: &wj; can be inserted in the XML to prevent a line from breaking.

- add a space after a period. 
(when sentence ends with a capital letter (e.g., "node X.", "node A." etc.) or the string "Bob." (and sometimes other odd strings), xml2rfc inserts only one space after the period. If it is the end of the sentence, we can insert &nbsp; into the XML file to force an extra space. However, if it's not caught until the later stage, we would add the extra space during post-processing.)

- fix indentation or the width of a figure.
(when a figure is over 69 characters, xml2rfc decreases the 3-space left-hand margin (i.e., shifts everything left), rather than letting the figure run over the 72-character limit. If we spot this visually (our automated check won't catch it because it's not over 72 chars), we can see about shortening the figure.) For example, if there were 3 figures in a row that should all line up (i.e., be indented the same amount), when one figure has one line that is one character too long, the figure is moved to the left, and no longer lines up with the other 2.

> Do you need to use post processing filters that eliminate backspaces or do other odd things?

Nope.

Please let us know if you have further questions.

Thanks,

Alice 

On Sep 29, 2010, at 5:16 PM, Tony Hansen wrote:

> Thanks for the confirmation Sandy.
> 
> This is going on a slight tangent to the other questions, but is directly relevant to the question of the evolution of the xml2rfc processor.
> 
> I'd really like to understand better the differences you encounter using xml2rfc -> text vs xml2rfc -> nroff -> text.
> 
> Also, do you do any post processing on the nroff output? Do you need to use post processing filters that eliminate backspaces or do other odd things?
> 
>    Tony
> 
> On 9/29/2010 4:51 PM, Sandy Ginoza wrote:
>> Moving away from having an .nroff source file in the near future seems like a bad idea, as the output looks very different depending on whether you are using an .xml or .nroff source file.
> _______________________________________________
> xml2rfc-dev mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/xml2rfc-dev
>

---

From: Alice Hagens <[email-masked]>
Date: Fri, 1 Oct 2010 13:57:28 -0400

correction: I meant broken across pages.

---

From: Tony Hansen <[email-masked]>
Date: Sat, 02 Oct 2010 21:06:29 -0400

wow, I'm amazed. I hadn't realized there was so much post processing 
done even *after* nroff.

     Tony

On 10/1/2010 1:51 PM, Alice Hagens wrote:
> (e.g., if "BGP/MPLS" is broken across a line (where it shouldn't be, e.g., title of a document). *Note:&wj; can be inserted in the XML to prevent a line from breaking.
>
> (when sentence ends with a capital letter (e.g., "node X.", "node A." etc.) or the string "Bob." (and sometimes other odd strings), xml2rfc inserts only one space after the period. If it is the end of the sentence, we can insert&nbsp; into the XML file to force an extra space. However, if it's not caught until the later stage, we would add the extra space during post-processing.)
>

---

From: Alice Hagens <[email-masked]>
Date: Sun, 3 Oct 2010 17:20:26 -0400

Tony,

> I hadn't realized there was so much post processing done even *after* nroff.

Perhaps to clarify (apologies if I misinterpreted the question): All the changes described below are done *in* the nroff (output from xml2rfc).   We do not make any changes in the text file (generated from the nroff).

Thanks,
Alice

On Oct 2, 2010, at 9:06 PM, Tony Hansen wrote:

> wow, I'm amazed. I hadn't realized there was so much post processing done even *after* nroff.
> 
>    Tony
>