Subject: Re: Automatically updated Table of Contents with Nroff

From: Julian Reschke <[email-masked]>
Date: Tue, 21 Dec 2010 17:43:22 +0100

On 15.07.2009 11:13, Julian Reschke wrote:
> Randy Presuhn wrote:
>> ...
>> No need to manually edit.
>>
>> Use the macros or awk / sed to spit the toc into a file which can be
>> inserted
>> into the correct position by the .so nroff directive. This will result in
>> a table of contents in the correct position. There is the possibility
>> that if the number of toc pages has changed from one iteration
>> to the next that the page numbers will be off by one, but that will
>> go away the next time the process runs.
>>
>> For editing a document, particularly a largish one, the availability of
>> .so is for me nroff's biggest advantage over xml2rfc.
>> ...
> ...

Randy,

I've been spending some time looking at the feasibility of using NROFF 
for IDs while retaining features like automatics generation of the TOC 
in the *right* place.

Funny enough, googling for this topic leads me back to this thread (and 
nowhere else, it seems).

So, I do understand how generate the ToC at the end, and I'll probably 
grok .so, but what is needed to extract the ToC into a separate file? Is 
there anything in nroff supporting that, or were you just referring to a 
set of homegrown tools? Also, as far as I can tell, the generated ToC 
will already be paginated, so do you post-process it again so it can be 
inserted properly?

Best regards, Julian

---

From: John Levine <[email-masked]>
Date: 21 Dec 2010 18:59:10 -0000

>set of homegrown tools?

Nroff isn't a document formatter, it's an interpretive programming
language in which one can write document formatters.  Everything is
either home grown, or borrowed from someone else who homegrew it.  As
you might expect, there is a great deal of folklore in the nroff
community about the ways you implement stuff using the stone axes and
chisels that nroff provides. (I guess I qualify, having been using it
since about 1973.)

The usual way to generate a TOC is to use .tm directives which write
the TOC to the standard error, which you capture in a file using
the usual Unix shell redirection.  Then you rerun nroff using .so
to include that file up at the front where the TOC goes.

Rather than trying to format the TOC as it's generated, I always write
out macro calls which will be expanded as the included file is read,
e.g.:

  .Tc 2 4.2 12 "Efficient lossless packet compression"

In this example, this is second level heading 4.2 on page 12.  It's
easy enough to generate whatever sort of TOC you want, and the usual
nroff page break stuff does the pagination.

Now, of course, this means that the TOC in your ouput is actually the
TOC from the last time you ran nroff, so there's the possibility of
version skew.  It's not hard to have your script or makefile compare
the old and new TOC files, notice that the current TOC is different
from the one you used, and tell you to run it again.

If this all seems like a gross complicated crock, well, yeah, what do
you expect from something designed to run on PDP-11s in the 1970s?
That's why we love it so.

R's,
John

PS: When I write books, I write and proof them in nroff and use a
little perl script to translate it to docbook before sending it off
to the publisher.

---

From: "Randy Presuhn" <[email-masked]>
Date: Tue, 21 Dec 2010 11:22:11 -0800

Hi -

> From: "Julian Reschke" <[email-masked]>
> To: "Randy Presuhn" <[email-masked]>
> Cc: "IETF Discussion Mailing List" <[email-masked]>
> Sent: Tuesday, December 21, 2010 8:43 AM
> Subject: Re: Automatically updated Table of Contents with Nroff
...
> will already be paginated, so do you post-process it again so it can be

Here's one incarnation of what I used:

Along with the other macro definitions (for six-month expiration date
generation and so on) I define a custom ".Nh" macro for section headings,
which just turns around an invokes the ms macros for section headers and
for table of contents entry generation.

.\" ****************************************************
.\" * section numbering - built on the  ms macro       *
.\" ****************************************************
.de Nh
.in 0
.NH \\$1
\\$2
.XS
\\*(SN \\$2
.XE
.in 3

Then, at the point in the document where we actually want the table
of contents to appear:

.\"
.\" Table of contents - we cheat, using the table of contents
.\" file generated on the last pass through nroff.
.\"
.sp
.ne 5
.ti 0
Table of Contents
.sp
.so toc.ms
.bp

Then, at the very end, we spit out the current table of contents:

.\"
.\" Table of contents here
.\"
.TC yes

To process all this, use the following script to invoke nroff, and peel off the most recently
generated table of contents from the end.  This means that the table of contents that shows
up in the formatted document is actually that from the previous run.  Running the script
twice resolves pagination inconsistencies.  "Bootstrapping" the very first run (empty "txt"
file) will start out with an empty table of contents, but it will be fine the next time around (for
a single page ToC, second time around for a multi-page ToC.)  This also handles the
FormFeed insertion.

#
# Files used:
#  document.ms = input
#  txt = intermediate table of contents extracted from previous nroff run
#  toc.ms = table of contents data (updated)
#  stdout = "real" output
#

#
# extract table of contents from previous run
#
awk < txt 'BEGIN{skipping=1;}
          /    Table of Contents/{skipping=0;}
          /\.\.\.\./{if (skipping) next; print; printf(".br\n");}'  |
sed '1,$s/\.\.\.//' >toc.ms

#
# now run nroff using that old table of contents
#
nroff -ms document.ms       |
awk '/FORMFEED/{DoFF=1; print; next;}
     /^$/{if (DoFF) next; else print; next;}
               {if (DoFF) {DoFF = 0; printf("\n");} print;}' |
sed '1,$s/.//g'      |
sed '1,$s/FORMFEED/        /' >txt

#
# Strip off the trailing table of contents and we're through
#
awk <txt '/   Table of Contents/{exit;} \
          {print;}'

Obviously, this is a little hacky, and there are a zillion other ways to do
it, but this works well and requires no "manual" intervention.  If I were
going to turn this into "production" code, I think I'd parameterize it
and the intermediate file names.

Randy

---

From: Julian Reschke <[email-masked]>
Date: Tue, 21 Dec 2010 20:38:11 +0100

Hi John,

thanks a *lot* for the explanations. More below.

> to include that file up at the front where the TOC goes.

That's what I understood from previous threads, but I had no idea how to 
get that second output stream (I was staring at ".open" earlier today).

> nroff page break stuff does the pagination.

So is .TC plain nroff or in some package?

> from the one you used, and tell you to run it again.

Understood (been there with Tex a few decades ago).

> That's why we love it so.

And that's why I'm so totally excited that people seriously consider 
writing new code to *produce* NROFF output, instead of simply formatting 
directly to plain text.

Best regards, Julian

---

From: "John R. Levine" <[email-masked]>
Date: 21 Dec 2010 14:50:12 -0500

> So is .TC plain nroff or in some package?

It's a macro.  Plain nroff formatting is all very low level, e.g., skip a 
line, switch to font 3, set line length to N picas.

I have a bad habit of writing my own nroff/troff macros so you're welcome 
to whatever I have lying around, but I doubt it'll be directly useful.

Regards,
John Levine, [email-masked], Primary Perpetrator of "The Internet for Dummies",
Please consider the environment before reading this e-mail. http://jl.ly

---

From: "John R. Levine" <[email-masked]>
Date: 21 Dec 2010 14:55:23 -0500

> That's what I understood from previous threads, but I had no idea how to get 
> that second output stream (I was staring at ".open" earlier today).

PS: You could use .open and .write but they are a recent (circa 1990) 
addition so I haven't gotten around to using them yet.

Regards,

---

From: Julian Reschke <[email-masked]>
Date: Tue, 21 Dec 2010 22:17:59 +0100

On 21.12.2010 20:22, Randy Presuhn wrote:
> Hi -
>
>> From: "Julian Reschke"<[email-masked]>
>> To: "Randy Presuhn"<[email-masked]>
>> Cc: "IETF Discussion Mailing List"<[email-masked]>

Thanks a lot. This seems to be a bit less elegant compared to what John 
was hinting at, but it *is* running code. I'll probably try this.

Best regards, Julian

---

From: "Randy Presuhn" <[email-masked]>
Date: Tue, 21 Dec 2010 13:38:47 -0800

Hi -

> Sent: Tuesday, December 21, 2010 1:17 PM
...
> was hinting at, but it *is* running code. I'll probably try this.

If you *know* you'll be using a more modern version of, say, groff,
then writing to a file (and *not* instantiating the TOC within the
document) is definitely more elegant.  However, some installations
of groff disable that feature, since it introduces additional security
risks.

Randy

---

From: Tony Hansen <[email-masked]>
Date: Tue, 21 Dec 2010 18:22:42 -0500

The magic directive is .tm:

     .tm string   After skipping initial blanks, string (rest of the 
line) is read in
                         copy mode and written on the standard error.

For anything you want in the table of contents, put in this line at the 
proper place (or include it in a header macro):

     .tm header level and title . . . . . . \n%

Stick in a line that says

     .so toc.input

where you want the table of contents to go.

     # empty out toc.input
 > toc.input
     # run once to get a sample ToC, but page numbers will be off
     nroff file > /dev/null 2> toc.input
     # run again to get proper page numbers into toc.input
     nroff file > /dev/null 2> toc.input
     # run a 3rd time to get the right output, ignoring stderr this time
     nroff file 2>/dev/null

And your output will have a table of contents in the proper place with 
the proper page numbers.

Note: At least on my linux box, this won't work because nroff is a shell 
script that calls groff internally and redirects stderr to /dev/null. So 
you have to use groff directly.

     Tony Hansen

On 12/21/2010 11:43 AM, Julian Reschke wrote:
> Funny enough, googling for this topic leads me back to this thread 
> (and nowhere else, it seems).
>
> grok .so, but what is needed to extract the ToC into a separate file? 
> Is there anything in nroff supporting that, or were you just referring 
> to a set of homegrown tools? Also, as far as I can tell, the generated 
> ToC will already be paginated, so do you post-process it again so it 
> can be inserted properly?

---

From: Barry Leiba <[email-masked]>
Date: Wed, 22 Dec 2010 12:21:37 -0500

>    # run a 3rd time to get the right output, ignoring stderr this time

You know, this whole discussion renews my total puzzlement at why
anyone would use nroff instead of something else... anything else.

Yow!

I know that not everyone likes xml2rfc, but I don't even want to think
about nroff.

Barry

---

From: John Levine <[email-masked]>
Date: 22 Dec 2010 18:18:15 -0000

>anyone would use nroff instead of something else... anything else.

The good thing about nroff or troff is that with enough fiddling, you
can get it to do anything,

The bad thing about nroff or troff is that with enough fiddling, you
can get it to do anything,

R's,
John

---

From: Julian Reschke <[email-masked]>
Date: Wed, 22 Dec 2010 20:26:27 +0100

On 22.12.2010 18:21, Barry Leiba wrote:
>>     nroff file>  /dev/null 2>  toc.input
>>     nroff file>  /dev/null 2>  toc.input

Clarifying: the reason why I'm researching is that apparently some 
people think it would be good to have a replacement for xml2rfc.tcl that 
*emits* nroff (only - as opposed to plain text/nroff/html as the TCL 
code does today).

Best regards, Julian

---

From: "Randy Presuhn" <[email-masked]>
Date: Wed, 22 Dec 2010 11:36:25 -0800

Hi -

> To: "Barry Leiba" <[email-masked]>
> Sent: Wednesday, December 22, 2010 11:26 AM
...
...

Though I happen to like nroff  (I also like anchovies) please don't count
me among those who think the replacement for sml2rfc.tcl should have
nroff format as its *only* output format.   Good luck with your research!

Randy

---

From: Barry Leiba <[email-masked]>
Date: Wed, 22 Dec 2010 18:26:10 -0500

> nroff format as its *only* output format.   Good luck with your research!

What Randy says.
Indeed, I understand why the RFC-Ed folks might want to have nroff
versions of things for their use (manipulation/editing, archival,
whatever).  Having nroff output as an *option* is surely important.
But the rest of us will always need the txt, html, pdf, and whatever.

Barry

---

From: Martin Rex <[email-masked]>
Date: Tue, 28 Dec 2010 18:26:49 +0100 (MET)

> anyone would use nroff instead of something else... anything else.

Everyone who looks at writing I-Ds should seriously consider looking
at NRoffEdit before deciding which document format and tool to use.

   http://aaa-sec.com/nroffedit/

It is currently the 5th entry in the section "Prepare Documents"
on this page:

 http://tools.ietf.org/

NRoffEdit is an all-in-one wysiwyg tool in Java that maintains
the TOC for you (within the .nroff source itself).

NO need to call nroff on the command line (no seperate nroff tool),
no seperate Editor and no seperate Viewer necessary,
and a spell checker is conveniently included as well.

One nice feature of NRoffEdit is the capability to easily convert
a formatted ASCII I-D or RFC back into nroff authoring format.

-Martin

---

From: Julian Reschke <[email-masked]>
Date: Tue, 28 Dec 2010 19:28:46 +0100

> at NRoffEdit before deciding which document format and tool to use.

Everyone who looks at writing I-Ds should also seriously consider 
xml2rfc. :-)

> the TOC for you (within the .nroff source itself).

Which will only work properly as long the output isn't run through 
standard NROFF, and page breaks change. Just saying.

And yes, xml2rfc also maintains the TOC.

Best regards, Julian

---

From: Phillip Hallam-Baker <[email-masked]>
Date: Wed, 29 Dec 2010 10:29:39 +0000

Gosh, we managed to have that entire discussion without a single person
comparing it to emacs vs vi.

oopsie.

On Tue, Dec 28, 2010 at 6:28 PM, Julian Reschke <[email-masked]>wrote:

> Everyone who looks at writing I-Ds should also seriously consider xml2rfc.
> :-)
>
>
> Which will only work properly as long the output isn't run through standard
> NROFF, and page breaks change. Just saying.
>
> _______________________________________________
> Ietf mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/ietf
>

-- 
Website: http://hallambaker.com/

---

From: Martin Rex <[email-masked]>
Date: Thu, 30 Dec 2010 03:25:09 +0100 (MET)

> Everyone who looks at writing I-Ds should also seriously consider 

Only if he is in for a lot of pain and trouble.

I tried to use xml2rfc once and gave up after 3 hours of getting NOWHERE,
not even _running_ xml2rfc.

I've been using cygwin for ~10 years (primarily as X-Server tunneling
through SSH and a few unix shell utilities, but the subset of what I
had installed wasn't capable of running xml2rfc.  Trying to update
my existing (>3 year old) cygwin installation to get the necessary
tools hosed my entire cygwin installation, so I had to restore that
part from backup later on).  My productive Linux installation (~5 year old)
wasn't capable of running xml2rfc and my Live distro I tried
(Knoppix5) neither.

With NRoffEdit I was busy writing my first I-D 30 minutes after
downloading the software.  It just worked intuitively and hazzle-free
on _all_ of my Windows machines.

Out of curiosity, I just tried it on my productive Linux machine.
Starting it took me ~5 minutes (copying the stuff over from Windows,
finding the java binary and figuring out that I have to
type "/some/where/bin/java -jar /tmp/NroffEdit/NroffEdit.jar"

I haven't figured out how to make it/Java use fixed width fonts on
Linux yet, though (a problem that I didn't have on Windows).

> standard NROFF, and page breaks change. Just saying.

Huh?  That problem simply does not exist.

NRoffEdit creates the same result as nroff used by the RFC Editor,
so there is not going to be any different page breaks.

With most I-Ds you can tell when authors are using xml2rfc instead
of NRoffEdit, because the documents often contain awkward page breaks
positionas within sections such as Authors and References and more
typos.

> And yes, xml2rfc also maintains the TOC.

That is a funny way to put it.

I-Ds created with xml2rfc often contain stale section references
because section numbering is "automatic" while section referencing
appears to be manual (and the latter therefore regularly forgotten).

NRoffEdit updates the TOC while you're editing the document
and press <F3> and you immediately see the result in the preview
window.

Every xml2rfc operation is a manual operation on the commandline
completely seperate from you Editor, and you need another manual
intervention a to see the result (which you might need in order
to create/update section cross-references).

To me "xml2rfc maintains the TOC" sound like a slight exxageration
of the significant complexity of the underlying workflow
(an issue whose solution is left up entirely to the xml2rfc user).

-Martin

---

From: "Randy Presuhn" <[email-masked]>
Date: Tue, 28 Dec 2010 21:12:38 -0800

Hi -

> From: "Martin Rex" <[email-masked]>
> To: "Julian Reschke" <[email-masked]>
> Cc: <[email-masked]>; <[email-masked]>
> Sent: Wednesday, December 29, 2010 6:25 PM
...
> not even _running_ xml2rfc.

FWIW, I've never been able to get xml3rfc to run on any of my computers.
Something horrible usually happens in the process of getting the TCL stuff
working. So, I just use the on-line one at http://xml.resource.org/  Getting
groff to run, on the other hand, has been fairly easy on every platform
I've tried.

...
> positionas within sections such as Authors and References and more

It's easier to control widows / orphans / page breaks with nroff, but I don't
usually worry about them because I know the RFC editor is going to
fine-tune the layout anyway.

Randy

---

From: "Doug Ewell" <[email-masked]>
Date: Wed, 29 Dec 2010 22:31:58 -0700

Martin Rex wrote:

> Only if he is in for a lot of pain and trouble...

I used xml2rfc (the online version, not installing it) to write RFC 4645 
and 5646, including numerous drafts, without any significant pain or 
difficulty getting the desired results.  Then again, I write code for a 
living, so writing XML by hand isn't my idea of pain.

--
Doug Ewell | Thornton, Colorado, USA | http://www.ewellic.org
RFC 5645, 4645, UTN #14 | ietf-languages @ is dot gd slash 2kf0s

---

From: Julian Reschke <[email-masked]>
Date: Thu, 30 Dec 2010 09:36:57 +0100

> living, so writing XML by hand isn't my idea of pain.

We had that discussion before :-); not sure why it got into this thread 
(which wasn't about preferences, but how to generate what the RFC 
Production Center wants from xml2rfc source).

But while we're at the topic of *running* xml2rfc: I always advise 
people to run it locally; it's faster, more easily automated, and gives 
you better diagnostics. On Windows I use Cygwin (*), which has been 
running xml2rfc.tcl flawlessly for me for something like the past 7 years.

Finally, don't run xml2rfc until you need to; to preview while editing, 
just use the XSLT and open the XML file in a web browser.

Best regards, Julian

(*) Martin; yes, upgrading Cygwin is a pain. It's a one-time cost. Many 
people are on MacOS anyway, where things are even easier, I hear.

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 30 Dec 2010 10:50:40 +0100

> But while we're at the topic of *running* xml2rfc: I always advise people to run it locally;

One problem is that the "default" way of doing references in RFC 2629 XML appears to perform an online fetch of the reference information for each build, with no caching whatsoever.  If you do have to look at the ASCII (yes, sometimes tables etc. need some tweaking), this is a pain.

(My markdown-to-RFC2629 workflow does some caching here, but life becomes painful again when interacting with XML-only co-authors.)

BTW, if you are on a Mac, get one of the package managers "macports" or "homebrew", and do

	port install xml2rfc

or

	brew install xml2rfc

> Finally, don't run xml2rfc until you need to; to preview while editing, just use the XSLT and open the XML file in a web browser.

Indeed -- thanks Julian for this wonderful tool.
Get it from <http://greenbytes.de/tech/webdav/rfc2629xslt.zip>.
Just put the line

  <?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>

as the second line of the xml, and open the xml in a browser.
(The only caveat I'm aware of is that you cannot really use the ugly vspace-999 hack for page break tweaks any more.  Good riddance.  Switch to the needLines PI.  That one appears to be acting a bit strange in xml2rfc, though.  It usually works for me with <?rfc needLines="30"?>.)

Gruesse, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Thu, 30 Dec 2010 10:58:56 +0100

> One problem is that the "default" way of doing references in RFC 2629 XML appears to perform an online fetch of the reference information for each build, with no caching whatsoever.  If you do have…

Yes, that's why I always recommend not to use that style.

> BTW, if you are on a Mac, get one of the package managers "macports" or "homebrew", and do

Interesting. Does this get you a current version, though?

> Get it from<http://greenbytes.de/tech/webdav/rfc2629xslt.zip>.
> Just put the line
>
> (The only caveat I'm aware of is that you cannot really use the ugly vspace-999 hack for page break tweaks any more.  Good riddance.  Switch to the needLines PI.  That one appears to be acting a bit strange in xml2rfc, though.  It usually works for me with<?rfc needLines="30"?>.)

If you educate me what it's supposed to do (force a page break?), I can 
look into adding it to the XSLT (it would only have an effect for print 
preview, but I assume that would be ok?).

Best regards, Julian

---

From: Phillip Hallam-Baker <[email-masked]>
Date: Thu, 30 Dec 2010 11:43:12 +0000

My personal preference would be for Google docs to change their HTML
generator so that it preserves the structure of the layout (H1, H2 etc)
rather than just the presentation.

That way we could have multiple people edit the same doc without having to
swap files about in email.

As a document format, the XML2RFC format is terrible. It uses all the
abominable features of SGML. Rather disappointingly for a format intended
for use by a standards organization it is different to HTML in ways that
serve no purpose other than to prevent the use of widely available tools.

One improvement that we could realize with little effort would be to simply
replace the individual entity declaration files for the RFC references with
one great big honking file containing all of them. That way it would only be
necessary to maintain citations in two places rather than three as at
present.

It would be much better if the references could be generated automatically
though.

On Thu, Dec 30, 2010 at 9:58 AM, Julian Reschke <[email-masked]>wrote:

>> One problem is that the "default" way of doing references in RFC 2629 XML
>> appears to perform an online fetch of the reference information for each
>> build, with no caching whatsoever.  If you do have to look at the ASCII
>> (yes, sometimes tables etc. need some tweaking), this is a pain.
>>
>
>  (My markdown-to-RFC2629 workflow does some caching here, but life becomes
>> painful again when interacting with XML-only co-authors.)
>>
>> (The only caveat I'm aware of is that you cannot really use the ugly
>> vspace-999 hack for page break tweaks any more.  Good riddance.  Switch to
>> the needLines PI.  That one appears to be acting a bit strange in xml2rfc,
>> though.  It usually works for me with<?rfc needLines="30"?>.)
>>
>

---

From: Julian Reschke <[email-masked]>
Date: Thu, 30 Dec 2010 12:57:24 +0100

On 30.12.2010 12:43, Phillip Hallam-Baker wrote:
> That way we could have multiple people edit the same doc without having
> to swap files about in email.

And lose metadata, automatic checking of references, cross-references, etc.

BTW: swapping files in email is indeed bad. It has nothing to do with 
format. Why don't you use a public source control repository? (svn on 
tools.ietf.org for WG stuff, or github...)

> abominable features of SGML. Rather disappointingly for a format

Sorry? Which?

> intended for use by a standards organization it is different to HTML in
> ways that serve no purpose other than to prevent the use of widely
> available tools.

It appears you're missing the benefits over HTML :-)

> One improvement that we could realize with little effort would be to
> simply replace the individual entity declaration files for the RFC
> references with one great big honking file containing all of them. That
> way it would only be necessary to maintain citations in two places
> rather than three as at present.

Could you elaborate where you need to maintain them?

> It would be much better if the references could be generated
> automatically though.

Like just saying <xref target="RFC2616"/> and then the reference being 
added at the end?

It's certainly possible to write a tool for that. How do you decide 
whether the reference is Normative of Informative, though?

Anyway, a benefit of an XML-based format is that you can invent any kind 
of extensions and write a simple-preprocessor implementing them. How do 
you do that with Google Docs?

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 30 Dec 2010 16:03:12 +0100

> Yes, that's why I always recommend not to use that style.

But hardwiring the references in the XML leads to manual updating (and forgetting that).
Having a tool for that is useful here (which is why kramdown-rfc2629 does this).

> Interesting. Does this get you a current version, though?

Both are at 1.35 -- not surprising since that version hasn't changed in a while.
One of the advantages of homebrew is that it makes editing the recipe very simple, so in a pinch you don't have to wait for the maintainer to update.  And the really adventurous ones can always ask for the bleeding edge direct from SVN:

	brew install xml2rfc --HEAD

> If you educate me what it's supposed to do (force a page break?),

Sometimes, it is worthwhile to add tweaks to the source files to get a page break.

Method one: abuse the non-semantic element vspace, which eats excessive blank lines when it causes a page break.  
RFC 2629 2.3.1.7 actually recommends this: 
  "This
   allows authors to "force" a pagebreak by using an arbitrarily large
   value, e.g., "blankLines='100'"."

What rfc2629.xslt could do is recognize unreasonably*) large values and do a page break instead of emitting tons of <br> elements.
*) Some AI required.  Maybe "more than 60".

Method two: use the needLines PI, which is "documented" only in http://xml.resource.org/authoring/README.html -- it is a hint how many lines are needed to be able to continue on the current page (as opposed to starting a new one).  Those formatters producing continuous output should of course ignore it, so rfc2629.xslt already does the right thing.  It's less clear what exactly a print stylesheet should do here, as the concept of "lines" is not well-defined.

Gruesse, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Thu, 30 Dec 2010 16:10:52 +0100

> Having a tool for that is useful here (which is why kramdown-rfc2629 does this).

I dislike automatic updates for IDs, because I may miss something that's 
important (such as a Section number of ABNF term changing). Thus I 
prefer running a checker for up-to-date references.

For RFCs, the citations should be immutable anyway.

> What rfc2629.xslt could do is recognize unreasonably*) large values and do a page break instead of emitting tons of<br>  elements.

I'm in the process of adding this; although I'm not going to generate a 
page break (it's likely to be a micro-optimization for the text output, 
right?). Instead, I'll treat these <vspace> elements as a request for a 
single line break, so that the HTML output doesn't get messed up.

> Method two: use the needLines PI, which is "documented" only in http://xml.resource.org/authoring/README.html -- it is a hint how many lines are needed to be able to continue on the current page (a…

Indeed.

rfc2629.xslt *could* try to add CSS hints, but it's not really clear how 
this is going to help. After all, the generated HTML+CSS already 
contains the necessary data to keep things together that belong together 
(you can test that with the PrinceXML formatter).

Best regards, Julian

---

From: Tony Finch <[email-masked]>
Date: Thu, 30 Dec 2010 20:25:55 +0000

On 30 Dec 2010, at 11:43, Phillip Hallam-Baker <[email-masked]> wrote:
> 
> As a document format, the XML2RFC format is terrible. It uses all the abominable features of SGML. Rather disappointingly for a format intended for use by a standards organization it is different to HTML in ways that serve no purpose other than to prevent the use of widely available tools.

Two key features that xml2rfc provides that HTML does not are automatic tables of contents and expansion of references from a central bibliography. You seem to think the latter is at least worth keeping and improving.

> One improvement that we could realize with little effort would be to simply replace the individual entity declaration files for the RFC references with one great big honking file containing all of them. That way it would only be necessary to maintain citations in two places rather than three as at present.
> 
> It would be much better if the references could be generated automatically though.

Tony.
--
f.anthony.n.finch  <[email-masked]>  http://dotat.at/

---

From: Julian Reschke <[email-masked]>
Date: Thu, 30 Dec 2010 21:34:56 +0100

On 30.12.2010 21:25, Tony Finch wrote:
> On 30 Dec 2010, at 11:43, Phillip Hallam-Baker<[email-masked]>  wrote:
>>

- (checked) cross-references

- index generation

- boilerplate generation

...

Best regards, Julian