RE: [Groff] Page classes in groff output to support reordering o

[Ted Harding]

Thanks, Bernd, it is much clearer now.

On 22-Jul-00 Bernd Salbrechter wrote:
> I want to go this way, but the essence of my question was to improve
> the "%%Page:" comment grops leave for this tools in it's output.
> The DSC (Document Structuring Conventions) describe the "%%Page:"
> entry as "%%Page: <label> <sequence>". Where the <label> is a free
> formatted page description and the <sequence> is a strict sequential
> numbering of the pages. grops actually use the same value for <label>
> and <sequence>. A psutils-like utility could be much more powerful,
> if it can identify several classes of pages (i.e. Cover, Body, Table
> of Contence, ...), thats was what I ask for. For an example look
> in my original message.

In fact, grops in certain cases will have a different <label> and
<sequence>. For instance, you can very straightforwardly create
a source file which starts with "front matter", with page numbers
formatted as i, ii, iii, , ... beginning the document with the command

.af PN i

(for ms macros) and then later continue with main text pages formatted
as 1, 2, 3, ... beginning this section with the commands

.af PN 1
.bp 1

In that case, the %%Page: comments would be like

%%Page: 1 1
%%Page: 2 2
...
%%Page: 9 9
%%Page: 1 10
%%Page: 2 11
...

and this, for instance, is how the page numbers would show in
the "gv" page-panel (i.e. as 1 2 ... 9 1 2 ... ).

If you look at the source code in grops.cc, you will find

void ps_printer::begin_page(int n)
{
  out.begin_comment("Page:").comment_arg(itoa(n));
  out.comment_arg(itoa(++pages_output)).end_comment();

showing that the first comment_arg is "n" (the value of \n%, the
logical page number), i.e. the <label>, while the second is
++pages_output, i.e. a count of the number of physical pages output,
the <sequence>.

Nevertheless, as can be seen from the code in /libgroff/itoa.c,
the <label> is still formatted by groff as "arabic" (1, 2, 3, ... ),
and not (as one would probably wish) as i, ii, iii, ... .

So this is a shortcoming of grops to start with, independently of
your wish to use <label> to distinguish page classes.

Therefore there would seems to be a case for extending the functionality
of the way grops creates the %%Page: <label> <sequence> comment.
However, at present there is no specific mechanism for gtroff to
communicate its "%%Page:" wishes to grops. The gtroff output language
(see man groff_out) does not describe any extension to ditroff output in
this respect, so that the only relevant output is ditroff's "pn", meaning
"new page n begins" where n is the ASCII decimal representation of
the next page number (i.e. "arabic"). So <label> is computed as the
ASCII decimal representation of n, while <sequence> is computed as the
ASCII decimal representation of the physical page count.

Possibly the most straightforward mechanism would be to extend the
\X'ps: ...' mechanism (with corresponding implementation code in grops).

In that case, the following suggestions seem to me to be feasible:

1. A new \X'ps: ...' command like
   \X'ps: pagenumformat F' where F may be as in troff .af, namely
   1 001 i I a A

   This would at least require the void ps_printer::begin_page(int n)
   function (above) to be re-written so that the formatting of n
   is done by a different routing (capable of achieving format F)
   instead of itoa(n).

2. A new X'ps: ...' command like
   \X'ps: pagelabel F text' where F is as above and "text" is
   whatever the user wants (e.g. TOC, Author Index, Bibliography ... ).
   This could presumably be used instead of or in addition to the
   suggestion in (1).

   This would require an additional re-writing of the function
   ps_printer::begin_page(int n) to be something like
   ps_printer::begin_page(int n, char *F, char *text)
   with appropriate support code.

Meanwhile, I think for practical purposes it should not be too
difficult to simply do what you are now doing, namely determining
independently what page-numbers correspond to the different classes,
and using say pstops to extract these when the page-list is submitted
via an argument to pstops.

However, you have raised an interesting and by no means entirely
cosmetic issue about groff. It would be good to see other users'
comments on these questions.

Best wishes to all,
Ted.

--------------------------------------------------------------------
E-Mail: (Ted Harding) <address@hidden>
Fax-to-email: +44 (0)870 284 7749
Date: 22-Jul-00                                       Time: 12:39:44
------------------------------ XFMail ------------------------------