Re: Doc patch, distinguish sections with an empty row in error code table

On 11/05/2012 02:40:12 PM, Tom Lane wrote:
> Robert Haas <robertmhaas(at)gmail(dot)com> writes:
> > On Fri, Oct 26, 2012 at 10:03 AM, Karl O. Pinc <kop(at)meme(dot)com>
> wrote:
> >> This patch adds an empty row before each section header
> >> in the error codes table in the docs.
>
> > This doesn't seem like a particularly good idea to me, but what do
> > other people think?
>
> It seems like a kluge. If the vertical spacing isn't nice looking,
> the
> place to fix that is in the stylesheet or formatting macros, not by
> hacking table contents.

The attached patch, errorcode_table_v2.patch, is an attempt to
do it the right way.

IMO the right way, instead of attempting to manually style
table data rows into column headers as the code presently does,
is to use multiple <tgroup>s, each
of which has it's own header. This results in
a single table, with multiple "sub-tables"
and lets the toolchain style the headers as
appropriate. Using multiple <tgroup>s is the
approach taken in this patch.

In my very limited experience alternate output formats,
formats other than html (like PDF), output tables containing
multiple tgroups format sensibly, the output is as a single table
with sub-headings and consistent column widths throughout.
So, this new patch does not attempt to apply any additional
style to the multi-tgroup table for non-html formats.

However, this new patch does not work for html. Or, rather,
it works but produces ugly html output. The html output
consists of multiple tables, one for each tgroup, each of which,
by default, might be (and is) a different width.

Ugly.

Normally this can be fixed by styling the html with css.
However in this case there are 2 problems. The first is
the serious one.

I'd expect to be able to set %entry-propagates-style%,
or at least %phrase-propagates-style%, and use a role="style"
attribute to style all the columns to a consistent width.
But neither %entry-propagates-style% nor
%phrase-propagates-style% works, so the styling info
never makes it through the toolchain into
the html.

(The patch as submitted to you attempts to use
%phrase-propagates-style%. I believe this
is true by default and I shouldn't have to
set it in the stylesheet.dsl, but there's
code in this patch to do this anyway.)

I don't know why the styling does not make it
through to the html. There's dsssl stylesheets
on my box that purport to handle %phrase-propagates-style%,
but I didn't check to be sure that these were the stylesheets
actually in use. Perhaps the docbook version used by the pg
docs is not new enough to use a stylesheet which supports
this. I don't think the custom navbar heading styling
done in stylesheet.dsl is the problem, but I suppose it's
possible. Or maybe I've a typo. In short, I've no clue
why this patch fails.

(Someday I imagine that pg will want to move to Docbook 5,
and I don't even know if there's dsssl stylesheets for
Docbook 5.)

I could hack the doc/src/sgml/stylesheet.dsl file and
put in the code that processes %phrase-propagates-style%,
but that seems a little crazy.

The second problem is that there's a make variable
(STYLE=website) which causes the generated html to use
the css found on the pg website. This patch does not
frob the website's css so even if this patch otherwise
worked somebody would have to change the pg website's
css.

So at this point I'm out of ideas. Unless somebody
can chime in with a clue I'm ready to give up.

It might be possible to improve the look of the
current output by throwing some xsl/dsssl styling at the
box edges of the faked table headers or do something
else along those lines. IMHO the right way forward
is to get tgroups working.

Regards,

Karl <kop(at)meme(dot)com>
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein