Re: [Groff] tbl problems in man
Werner LEMBERG [EMAIL PROTECTED]: I doubt whether this is an acceptable solution. Hmm. You're right. Indeed. The best so far is Gunnar's solution to emulate your suggested percent keyletter extension. I think I just came up with something better, a way to compute the column widths that solves the problem. It should be in your mailbox now. -- a href=http://www.catb.org/~esr/;Eric S. Raymond/a
Re: [Groff] tbl problems in man
On 08-Feb-07 Michael(tm) Smith wrote: Tadziu Hoffmann [EMAIL PROTECTED], 2007-02-08 12:19 +0100: Nevertheless, does anybody here remember the discussion about ATT-tbl's expand column feature on this list some months back? I don't remember reading that one. Is it something that solves this problem of multi-column tbl tables coming out looking so bad? --Mike It was back on Thu, 16 Sep 2004, from Werner, Subject: Re: [Groff] Re: How to contribute tbl enhancement? Body: Can someone please explain what the ATT expanded column feature is Sorry. Here it is. A key letter may be followed by the letter X to indicate an expanded column. If the modifier is used, the width of the corresponding column will be increased to use the remainder of the line length after the widths of the other columns have been calculated. This feature is useful for a column containing text blocks where it is desired to make the column as wide as possible without exceeding the line length. Only one expanded-width column is permitted for each table, so this modifier is limited to a single column in each table. Ted. E-Mail: (Ted Harding) [EMAIL PROTECTED] Fax-to-email: +44 (0)870 094 0861 Date: 08-Feb-07 Time: 15:44:20 -- XFMail --
Re: [Groff] tbl problems in man
Ted Harding [EMAIL PROTECTED]: A key letter may be followed by the letter X to indicate an expanded column. If the modifier is used, the width of the corresponding column will be increased to use the remainder of the line length after the widths of the other columns have been calculated. This feature is useful for a column containing text blocks where it is desired to make the column as wide as possible without exceeding the line length. Only one expanded-width column is permitted for each table, so this modifier is limited to a single column in each table. Useful if you know there's only one column with block entries, but not a general solution. I think I may have a general solution. -- a href=http://www.catb.org/~esr/;Eric S. Raymond/a
Re: [Groff] tbl problems in man
Werner LEMBERG [EMAIL PROTECTED], 2007-02-06 12:35 +0100:
I still think that tables with T{...T} don't work well within man
pages.
I see the specific problem in the example man page you attached,
and I've also seen the especially bad results produced when tables
have more than two columns. So I'd really like to have a better
way of handling those cases.
But is there a backward compatible way to avoid T{...T} ? I ask
because I currently have the DocBook manpages stylesheets
generating T{...T} for all tables it outputs. Because DocBook
tables can contain block content such as itemized/ordered lists,
not just simple text.
Instead, .TP and TQ should be used, as demonstrated in the
attached file.
But on my system, with groff 1.8.1.1 installed from the current
package in Debian testing, when I view the part of that file
that's marked up with TQ, I just get this:
ArgPlacement 0 Abstract is printed on page 1 and on the
cover sheet if used in the released-paper style (MT 4),
otherwise it is printed on page 1 without a cover sheet.
1 Abstract is only printed on the cover sheet (MT 4
only). 2 Abstract is printed only on the cover sheet
(other than MT 4 only). The cover sheet is printed with‐
out a need for CS.
And looking in the Macro Index of the groff info page, I see no
mention of TQ. Where is TQ documented?
--Mike
Re: [Groff] tbl problems in man
Eric S. Raymond [EMAIL PROTECTED], 2007-02-07 11:43 -0500:
I wrote the documentation recently :-). From groff_man in CVS:
.TQThe TQ macro sets up header continuation for a .TP macro. With
it, you can stack up any number of labels (such as in a glos‐
sary, or list of commands) before beginning the indented para‐
graph. For an example, look just past the next paragraph.
This macro is not defined on legacy Unix systems running classic
troff. To be certain your page will be portable to those sys‐
tems, copy its definition from the an-ext.tmac file of a groff
installation.
I don't think it's safe for your stylesheets to use it yet. It won't be until
well after 1.19.3 ships.
What if I just have the stylesheet embed the macro definition in
the output of each page?
More generally, I disagree with Werner's position that TP/TQ is preferable
to tables with T{ T} in them. I'm going to change groff_mm in accordance
with his diktat, because it's his package and his call, but I'm not going
to like it.
Well, then I'd really like to have some general solution
(workaround) that would cause the cell widths in tables with any
arbitary number of columns to set to something more reasonable
than what tbl(1) currently does.
I don't know actually know if TQ solves that problem. But I'd sure
like to have something better -- regardless of how it it's
implemented.
--Mike
--
Michael(tm) Smith
http://people.w3.org/mike/
Re: [Groff] tbl problems in man
Michael(tm) Smith [EMAIL PROTECTED]: What if I just have the stylesheet embed the macro definition in the output of each page? That would work. Well, then I'd really like to have some general solution (workaround) that would cause the cell widths in tables with any arbitary number of columns to set to something more reasonable than what tbl(1) currently does. That change needs to be made in tbl itself. Which is, I think, where this discussion has been heading all along. -- a href=http://www.catb.org/~esr/;Eric S. Raymond/a
Re: [Groff] tbl problems in man
More generally, I disagree with Werner's position that TP/TQ is
preferable to tables with T{ T} in them.
T{ T} as implemented currently just sucks. Please have a look at this
http://lists.gnu.org/archive/html/groff/2006-09/msg00022.html
for some nasty details.
I'm going to change groff_mm in accordance with his diktat,
hehe
because it's his package and his call, but I'm not going to like it.
In this particular case (this is, simple tables which can be
sufficiently emulated with TP/TQ), I favor optical appearance over
logical structure.
Werner
Re: [Groff] tbl problems in man
Well, then I'd really like to have some general solution (workaround) that would cause the cell widths in tables with any arbitary number of columns to set to something more reasonable than what tbl(1) currently does. That change needs to be made in tbl itself. Which is, I think, where this discussion has been heading all along. As mentioned earlier, I don't object to adding a new tbl keyletter which does what we all want to do. However, it won't help with compatibility issues. Werner
Re: [Groff] tbl problems in man
In this particular case (this is, simple tables which can be sufficiently emulated with TP/TQ), I favor optical appearance over logical structure. Shouldn't we be looking for a way to fix TBL, rather than kludging around the problem? TP/TQ for the example I've given is *fully* sufficient IMHO and not a kludge at all. I'm not trying to be obstreperous here, but it seems to me that the real problem is that TBL just gets this case wrong. Yep. And no chance to fix it in a backwards compatible way. At least noone has come up yet with something, unfortunately. Is there some reason not to address that directly? Of course not. It should be rather straightforward to code such a keyletter within the macro stuff tbl emits; it's basically just a reordering of the computations: (1) Compute the width of each column which either doesn't contain a text block or uses an explicit width specifier. (2) For the other columns, use the remaining horizontal space up to the right margin and distribute it evenly. (3) Process the text block diversions. (4) Assemble the table. Currently, (3) is done before (1), IIRC. Volunteers welcome. Werner
Re: [Groff] tbl problems in man
Werner LEMBERG [EMAIL PROTECTED]:
looking again at groff_mm.man, I see that using T{...T} in tables
gives ugly results. I think that this is a limitation of tbl which
can't be worked around: For text blocks, you can't say `use the
remaining line width' because they are processed earlier than the rest
of the table.
With other words, as soon as we have table entries which need T{...T}
-- and this happens quite often if the column contains more than a few
words -- we can't use a table at all to get a decently looking result.
I see no solution to this problem. Specifying a width argument to
columns doesn't help either without a lot of troff register trickery
to compute the correct width in advance.
Please revert to the previous formatting (I suggest using .TQ instead
of .TP to avoid empty lines). Doclifter might produce good results
for HTML, but the visual degradation if formatted for other devices is
not acceptable.
Ouch!
Yes, I could go back, find tables with T} in them, and revert them to
list markup and similar kluges. But that would just bring us trouble
from another direction. Many of the weird constructs I replaced with
tables (I'm thinking, for example, of the T2 macro in groff_mm.man)
will completely break manhtml and non-groff viewers. That's why
I moved a lot of this stuff to tables to begin with.
I agree that the T{ T} items on that page and some places elsewhere
don't look very nice -- the column widths are too narrow and the
entries look lumpy. I was actually concerned about this myself.
But at least the tables will be readable everywhere. I submit that
having the content be *completely* garbled by (for example) the GNOME
help browser is a worse result than the degradation in visual quality
you are seeing. I think we actually need to either solve this problem
somehow or accept ugly-looking tables as the least-bad alternative.
Fortunately, I think I way around the problem constraints. You say
Specifying a width argument to columns doesn't help either without a
lot of troff register trickery to compute the correct width in
advance. I think I understand that. But what if we don't have to
specify the actual width?
Instead, let's steal a trick from the HTML book and implement a column
width syntax that specifies a fraction of total line width. After
all, we will know \n[.ll] at the very start of table compilation. We
can scale \n[.ll] by each specified column percentage during table
format processing, before T{ T} processing occurs. Feed that to
whatever machinery is constraining the T block widths and we're done.
This seems like an elegant solution, unless I'm misconstruing something
very basic about how TBL operates.
--
a href=http://www.catb.org/~esr/;Eric S. Raymond/a
Re: [Groff] tbl problems in man
Yes, I could go back, find tables with T} in them, and revert them to list markup and similar kluges. But that would just bring us trouble from another direction. Many of the weird constructs I replaced with tables (I'm thinking, for example, of the T2 macro in groff_mm.man) will completely break manhtml and non-groff viewers. That's why I moved a lot of this stuff to tables to begin with. What's the problem with .TQ? Most of the data in groff_mm.man can be represented with this macro in a satisfying way, I believe. Instead, let's steal a trick from the HTML book and implement a column width syntax that specifies a fraction of total line width. Example, please. It's not completely clear to me what you want to do. Werner
Re: [Groff] tbl problems in man
Werner LEMBERG [EMAIL PROTECTED]:
What's the problem with .TQ? Most of the data in groff_mm.man can be
represented with this macro in a satisfying way, I believe.
Since you say so, I assume it's possible. But I have not figured out
how yet.
Instead, let's steal a trick from the HTML book and implement a
column width syntax that specifies a fraction of total line width.
Example, please. It's not completely clear to me what you want to do.
OK. But first, even if we don't find a way to implement what I'm about
to suggest, I've experimented and verified that the lumpy tables can be
fixed by adding a w format to the bad column's format spec.
Here's the start of one of the tables that looks wrong.
Df register
0 Displays are printed at
the end of each section
(when section-page number���
ing is active) or at the
end of the document.
1 A new display is printed
on the current page if
there is enough space,
otherwise it is printed at
the end of the document.
And here's how it is set:
.TS
tab(@);
l l.
[EMAIL PROTECTED]
Displays are printed at the end of each section (when section-page
numbering is active) or at the end of the document.
T}
[EMAIL PROTECTED]
A new display is printed on the current page if there is enough space,
otherwise it is printed at the end of the document.
T}
If we say this instead:
.TS
tab(@);
l lw50.
we get this:
Df register
0 Displays are printed at the end of each section
(when section-page numbering is active) or at the
end of the document.
1 A new display is printed on the current page if
there is enough space, otherwise it is printed at
the end of the document.
So we know we can get decent-looking tables with a little
hand-hacking, and I'll go in and do that if I have to as an
alternative greatly preferable to going back to nonportable custom
macros like T2.
The only problem with using w is that the number that needs to go to go next
to it is brittle -- it may break if the table indent changes, or if the
the point size changes, or if the margins change. But even with those
limitations, it takes the pressure off this discussion. I won't have
to rip out half my port changes, and you won't have to consider tbl
desperately broken.
Instead, we can talk about how to teach tbl to be smarter about computing
width defaults, and about ways to override the width defaults that are
less fragile than an absolute column width.
If my understanding is correct, TBL picks a random value for the
maximum width of the T{ T} block because T{ }T blocks are processed
before the rest of the table, so TBL can't know how much horizontal
space is going to be left when the other columns have claimed their share.
But now imagine that the w specifier takes a percent syntax that looks like
this:
.TS
tab(@);
lw10% lw90%.
[EMAIL PROTECTED]
Displays are printed at the end of each section (when section-page
numbering is active) or at the end of the document.
T}
We have just said Give column 1 10% of the maximum available table
width. Give column 2 90% of it. The maximum available table width
is basically A = (\n[.ll] - \n[.in]). At the time we parse each
percent spec, we multiply it by A.
Now we can force good behavior without having to care about the
current indent, or point sizes, or margins, or how they might change.
This trick is shamelessly stolen from the percent-spec form of
table width in HTML.
--
a href=http://www.catb.org/~esr/;Eric S. Raymond/a
Re: [Groff] tbl problems in man
What's the problem with .TQ? Most of the data in groff_mm.man can
be represented with this macro in a satisfying way, I believe.
Since you say so, I assume it's possible. But I have not figured
out how yet.
Have a looked at the attached file.
OK. But first, even if we don't find a way to implement what I'm
about to suggest, I've experimented and verified that the lumpy
tables can be fixed by adding a w format to the bad column's format
spec. [...]
Later on you say:
The only problem with using w is that the number that needs to go to
go next to it is brittle -- it may break if the table indent
changes, or if the the point size changes, or if the margins change.
I fully agree. It can make such man pages ugly to read.
If my understanding is correct, TBL picks a random value for the
maximum width of the T{ T} block because T{ }T blocks are processed
before the rest of the table, so TBL can't know how much horizontal
space is going to be left when the other columns have claimed their
share.
It's not arbitrary. The formula can be found in the tbl man page.
But now imagine that the w specifier takes a percent syntax that
looks like this: [...]
Now we can force good behavior without having to care about the
current indent, or point sizes, or margins, or how they might
change. This trick is shamelessly stolen from the percent-spec form
of table width in HTML.
I disagree. The nice thing of tables created with tbl is that each
column gets exactly the width it deserves. Using your percent model,
this advantage is lost. Additionally, it surprises me that you are
suggesting an extension to `tbl' which won't be available with non-GNU
implementations!
It would be possible to implement a new global keyword which makes the
table use the remaining horizontal space for text blocks after the
other column widths have been computed. However, this is still a
non-portable extension...
I still think that tables with T{...T} don't work well within man
pages. Instead, .TP and TQ should be used, as demonstrated in the
attached file.
Werner
'\ t
.TH
.
.
.P
Some completely useless text to demonstrate the left and right margin
within a manual page.
.
.RS
.TS
tab(@);
lb lb
l l.
[EMAIL PROTECTED]
[EMAIL PROTECTED]
Abstract is printed on page\~1 and on the cover sheet if used in the
released-paper style (\fBMT\~4\fP),
otherwise it is printed on page\~1 without a cover sheet.
T}
[EMAIL PROTECTED]
Abstract is only printed on the cover sheet (\fBMT\~4\fP only).
T}
[EMAIL PROTECTED]
Abstract is printed only on the cover sheet (other than \fBMT\~4\fP only).
The cover sheet is printed without a need for \fBCS\fP.
T}
.TE
.RE
.
.P
Some completely useless text to demonstrate the left and right margin
within a manual page.
.
.RS
.TP
.B Arg
.B Placement
.TQ
0
Abstract is printed on page\~1 and on the cover sheet if used in the
released-paper style (\fBMT\~4\fP),
otherwise it is printed on page\~1 without a cover sheet.
.TQ
1
Abstract is only printed on the cover sheet (\fBMT\~4\fP only).
.TQ
2
Abstract is printed only on the cover sheet (other than \fBMT\~4\fP only).
The cover sheet is printed without a need for \fBCS\fP.
.TE
.RE
Re: [Groff] tbl problems in man
Werner LEMBERG [EMAIL PROTECTED]:
What's the problem with .TQ? Most of the data in groff_mm.man can
be represented with this macro in a satisfying way, I believe.
Since you say so, I assume it's possible. But I have not figured
out how yet.
Have a looked at the attached file.
I understand. This will only work for eliminating two-column tables in the
particular form that groff_mm.man uses a lot. I was puzzled because I thought
you were suggesting it as a more general solution.
The only problem with using w is that the number that needs to go to
go next to it is brittle -- it may break if the table indent
changes, or if the the point size changes, or if the margins change.
I fully agree. It can make such man pages ugly to read.
This I don't understand. Ugly to read for whom? If w is chosen well
for the indent and point size, it will look as though the table was
filled to right margin by a smart algorithm.
I disagree. The nice thing of tables created with tbl is that each
column gets exactly the width it deserves.
That's not true for T{ }T columns. If it were, we wouldn't be having
this conversation!
Using your percent model,
this advantage is lost. Additionally, it surprises me that you are
suggesting an extension to `tbl' which won't be available with non-GNU
implementations!
That, on the other hand, is a good point. I guess portability pins us
to using the existing 'w' specifier. Forget my speculations.
I still think that tables with T{...T} don't work well within man
pages. Instead, .TP and TQ should be used, as demonstrated in the
attached file.
Yes? And what do we do if the table has more than two columns?
I'll put it on my to-do list to determine which pages can be reduced
this way.But .TP/.TQ is not a general solution, and of course ,TQ
has its own portability problem. Given these circumstances, I don't
understand your objections to use of the w specifier.
--
a href=http://www.catb.org/~esr/;Eric S. Raymond/a
Re: [Groff] tbl problems in man
Eric S. Raymond wrote:
The only problem with using w is that the number that needs to go to
go next to it is brittle -- it may break if the table indent
changes, or if the the point size changes, or if the margins change.
I fully agree. It can make such man pages ugly to read.
This I don't understand. Ugly to read for whom? If w is chosen well
for the indent and point size, it will look as though the table was
filled to right margin by a smart algorithm.
What might work for nroff might not work for troff -- and then there are
things like -rS11 for people who want a little larger type. I'm fond of saying
that manpages are the first widespread example of single-sourced
documentation -- and you can't make many assumptions about how people
want to display single-sourced documents.
Outside of manpages, I'd personally welcome the percentage width unit and
expand to fill the line extensions in tbl -- my primary output targets are
PDF and HTML, and these extensions would work well for my documentation.
I just don't think they'd be quite as good in manpages. I took a stab at coding
them myself a while back, but couldn't get my head around the source.
I still think that tables with T{...T} don't work well within man
pages. Instead, .TP and TQ should be used, as demonstrated in the
attached file.
Yes? And what do we do if the table has more than two columns?
You might want to have a look at groff_ms(7). I put a lot of effort into making
those tables work well for both console print, and didn't use w at all.
-- Larry
[Groff] tbl problems in man
Eric,
looking again at groff_mm.man, I see that using T{...T} in tables
gives ugly results. I think that this is a limitation of tbl which
can't be worked around: For text blocks, you can't say `use the
remaining line width' because they are processed earlier than the rest
of the table.
With other words, as soon as we have table entries which need T{...T}
-- and this happens quite often if the column contains more than a few
words -- we can't use a table at all to get a decently looking result.
I see no solution to this problem. Specifying a width argument to
columns doesn't help either without a lot of troff register trickery
to compute the correct width in advance.
Please revert to the previous formatting (I suggest using .TQ instead
of .TP to avoid empty lines). Doclifter might produce good results
for HTML, but the visual degradation if formatted for other devices is
not acceptable.
Werner
