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

Hi,

This patch adds an empty row before each section header
in the error codes table in the docs.

I tried not putting an empty row before the first
section, but it looks better to always have
an empty row. IMO.

File: errorcode_table.patch

Applies against head.

Regards,

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

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.
>
> I tried not putting an empty row before the first
> section, but it looks better to always have
> an empty row. IMO.
>
> File: errorcode_table.patch
>
> Applies against head.

This doesn't seem like a particularly good idea to me, but what do
other people think?

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

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.

regards, tom lane

On Mon, Nov 5, 2012 at 3:40 PM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> 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.

That was my thought as well.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

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

On 11/05/2012 09:41:13 PM, Karl O. Pinc wrote:
>
> The attached patch, errorcode_table_v2.patch, is an attempt to
> do it the right way.

Since I'm stuck I asked about this patch on the docbook-apps
mailing list.

https://lists.oasis-open.org/archives/docbook-apps/201211/msg00027.html

I got the following reply, and since I don't know the answer
and it seems a useful factoid am re-posting here.

--------------------------<snip>--------------------
On 11/06/2012 10:41:04 AM, Stefan Seefeld wrote:
> On 11/06/2012 11:27 AM, Karl O. Pinc wrote:
> > Hi,
> >
> > I'm trying to improve a table of PostgreSQL error codes
> > in the PostgreSQL docs.
>
> > Postgresql uses Docbook 4.2 and openjade/dsssl style sheets.
>
> Is there even a remote chance for you to migrate to XSL stylesheets ?
> I'm not sure the DSSL ones are maintained at all at this point, so
> improvements, fixes, and customizations are much easier to get with
> XSL.
--------------------------<snip>--------------------

Regards,

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

P.S. It's a shame, since I much prefer DSSL to XSL.
(And I don't know either well enough to be able to
whack out a migration of DSSL to XSL.)
(Though I do "like" working with xsltproc.)

On 11/06/2012 12:09 PM, Karl O. Pinc wrote:
>>
>>> Postgresql uses Docbook 4.2 and openjade/dsssl style sheets.
>> Is there even a remote chance for you to migrate to XSL stylesheets ?
>> I'm not sure the DSSL ones are maintained at all at this point, so
>> improvements, fixes, and customizations are much easier to get with
>> XSL.
>
> P.S. It's a shame, since I much prefer DSSL to XSL.
> (And I don't know either well enough to be able to
> whack out a migration of DSSL to XSL.)
> (Though I do "like" working with xsltproc.)

I don't recall what the arguments against moving to XML/XSL were other
than inertia.

It's surely true that the number of tools supporting XML/XSL and the
number of people capable of working on an XSL based system (e.g. me)
greatly exceeds those for SGML/DSSSL. I know certain prominent
contributors who utterly detest having to work with SGML.

cheers

andrew

Note: This email is not immediately relevant to Postgres,
although someday it may be.

On 11/06/2012 11:38:07 AM, Andrew Dunstan wrote:
>
> On 11/06/2012 12:09 PM, Karl O. Pinc wrote:
> >>
> >>> Postgresql uses Docbook 4.2 and openjade/dsssl style sheets.

> I don't recall what the arguments against moving to XML/XSL were
> other
>
> than inertia.

As long as we're on the subject of re-vamping the doc toolchain
I'll note what I can recall of what it takes to migrate from
docbook 4 to docbook 5. For no good reason...
(This has nothing to do with what it would take to go
from SGML to XML, or DSSL to XSL.)

The big deal is the introduction of a docbook namespace.
This means changing all the id attributes to xml:id.
It also means adding namespace (xmlns=) to entity
declarations.

The external link entry also changed, I forget the details
but it's an easy fix.

The part I had trouble with was using the system catalogs.
I finally punted and used a SYSTEM entity instead.
I can't say I know what I'm doing but it may be
that the common OS platforms have not yet fully caught
up with Docbook 5. Or then again maybe I'm just
blaming the system for my mistakes. :)

---

The other thing to think about is whether to use
XPath and xmlinclude or not. It's kind of nice
to avoid having to use olink and build link databases,
but you don't get the benefits of being able to
validate individual files either. All in all,
it seems simpler to avoid XPath. The barrier
to entry involved in frobbing documentation
is much lower if you avoid it because
hyperlinking between files involves a whole
new syntax. (olink instead of xref)

Regards,

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

FWIW. Attached is my link.emacs file.
Makes the hyperlinking to docbook ids much easier.
Load it with M-x, load-file, then position
point after an xml:id (foo) and M-x, link
produces <xref linkend="foo"/>, and
mark is left before the <.

On Mon, Nov 5, 2012 at 10:41 PM, Karl O. Pinc <kop(at)meme(dot)com> wrote:
> So at this point I'm out of ideas. Unless somebody
> can chime in with a clue I'm ready to give up.

Frankly, I don't view this as enough of a problem to be worth spending
time on. Actually, I'm not sure I view the formatting of that table
as a problem at all, but if it is a problem it's not a big enough one
to justify knocking ourselves out over it. There are many more
substantive issues with our documentation that IMHO are more worthy of
our attention.

On the other hand, I *would* be somewhat in favor of migrating to a
less-obsolete toolchain, as suggested elsewhere on this thread, but
(a) I don't know whether XSL is the right thing and (b) I don't want
to move until we're darn sure we know what we're moving to is gonna be
an improvement, because this promises to make back-patching of
documentation fixes really annoying for many years to come, not to
mention creating lots of knock-on work for packagers. We can't go on
forever with what we have now, I think, unless we're willing to assume
all the maintenance burden thereof. But that takes nothing away from
the fact that migration to a new system WILL be painful, and we sure
don't want to do it twice, so we had better get it right the first
time.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

On 11/06/2012 01:40:56 PM, Robert Haas wrote:
> On Mon, Nov 5, 2012 at 10:41 PM, Karl O. Pinc <kop(at)meme(dot)com> wrote:
> > So at this point I'm out of ideas. Unless somebody
> > can chime in with a clue I'm ready to give up.
>
> Frankly, I don't view this as enough of a problem to be worth
> spending
> time on.

Good by me. Reject the patch. If the build system
changes so the patch starts working somebody can worry
about it then.

> Actually, I'm not sure I view the formatting of that table
> as a problem at all, but if it is a problem it's not a big enough one
> to justify knocking ourselves out over it.

I got into it because I started to pl/pgsql RAISE error codes
and found it hard to scan the table for the section/one I wanted
while the remainder of my brain was occupied with the
code at hand. I had a feeling that my original patch,
which added an empty row, was not exactly kosher, but then
it seemed to help a lot -- and I didn't have good feelings
about the way the code presently simulates a column heading
either so I figured it wouldn't hurt to submit the
patch and get feedback.

FYI, I'm now looking the table of error codes on the
official PG 9.2 docs. It seems to be using the
website's style sheets, and the section "headings"
are not any bolder than the regular data
rows. I can't find a "bold"
style in the website's style sheets. The table,
IIRC, looks different when viewed with a file:///
url after building the docs. The sections
stand out a little more. So there's probably
a bug here, where the fix would be to update
the website's style sheets. (It's also possible
that the problem is in my browser, which is old.)

(FYI, I found the bolded section headings
viewed via a file:/// url to be not especially
helpful. That's what I was looking at when
I wrote the first patch.)

Regards,

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

On 11/06/2012 01:40:56 PM, Robert Haas wrote:

> Frankly, I don't view this as enough of a problem to be worth
> spending
> time on. Actually, I'm not sure I view the formatting of that table
> as a problem at all, but if it is a problem it's not a big enough one
> to justify knocking ourselves out over it.

The docbook-apps list sent this suggestion:

-------------------<snip>------------------------------
On 6.11.2012 17:27, Karl O. Pinc wrote:

> The problem is that the various error code classes don't stand
> out, the different "sections" of the table need distinguishing
> headings.

In your generated output I see:

<tr>
<td colspan="2"><span class="bold EMPHASIS c3">Class 00 —
Successful Completion</span></td>
</tr>

It's just matter of CSS rule like

td .EMPHASIS { font-size: 140%; }

to make such labels more visible.
-------------------<snip>------------------------------

If you have some way you'd like the css frobbed I can
do that. Or we can forget about it.

Regards,

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

P.S. Thanks for the time you've spent so far.

On Tue, Nov 6, 2012 at 5:44 PM, Karl O. Pinc <kop(at)meme(dot)com> wrote:
> In your generated output I see:
>
> <tr>
> <td colspan="2"><span class="bold EMPHASIS c3">Class 00 —
> Successful Completion</span></td>
> </tr>
>
> It's just matter of CSS rule like
>
> td .EMPHASIS { font-size: 140%; }
>
> to make such labels more visible.
> -------------------<snip>------------------------------
>
> If you have some way you'd like the css frobbed I can
> do that. Or we can forget about it.

Ah, well, as to that, I think you'd have to take that suggestion to
pgsql-www. The style sheets used for the web site are - just to make
things exciting - stored in a completely different source code
repository to which I don't have access. Some kind of CSS
frobnication along the lines you suggest might be worth discussing,
but I don't really work on that stuff.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

On 11/08/2012 11:10:39 AM, Robert Haas wrote:
> On Tue, Nov 6, 2012 at 5:44 PM, Karl O. Pinc <kop(at)meme(dot)com> wrote:
> > In your generated output I see:
> >
> > <tr>
> > <td colspan="2"><span class="bold EMPHASIS c3">Class 00 —
> > Successful Completion</span></td>
> > </tr>
> >
> > It's just matter of CSS rule like
> >
> > td .EMPHASIS { font-size: 140%; }
> >
> > to make such labels more visible.
> > -------------------<snip>------------------------------
> >
> > If you have some way you'd like the css frobbed I can
> > do that. Or we can forget about it.
>
> Ah, well, as to that, I think you'd have to take that suggestion to
> pgsql-www. The style sheets used for the web site are - just to make
> things exciting - stored in a completely different source code
> repository to which I don't have access. Some kind of CSS
> frobnication along the lines you suggest might be worth discussing,
> but I don't really work on that stuff.

Without being able to pass additional style from the source
docs through to the html it seems a bit spooky to do this.
I'd be afraid of inadvertent styling. Someone who
knows more might not be so fearful.

Regards,

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

On 11/6/12 12:09 PM, Karl O. Pinc wrote:
> --------------------------<snip>--------------------
> On 11/06/2012 10:41:04 AM, Stefan Seefeld wrote:
>> > On 11/06/2012 11:27 AM, Karl O. Pinc wrote:
>>> > > Hi,
>>> > >
>>> > > I'm trying to improve a table of PostgreSQL error codes
>>> > > in the PostgreSQL docs.
>> >
>>> > > Postgresql uses Docbook 4.2 and openjade/dsssl style sheets.
>> >
>> > Is there even a remote chance for you to migrate to XSL stylesheets ?
>> > I'm not sure the DSSL ones are maintained at all at this point, so
>> > improvements, fixes, and customizations are much easier to get with
>> > XSL.
> --------------------------<snip>--------------------

https://wiki.postgresql.org/wiki/Switching_PostgreSQL_documentation_from_SGML_to_XML

On 11/08/2012 11:55:19 AM, Karl O. Pinc wrote:
> On 11/08/2012 11:10:39 AM, Robert Haas wrote:

> > Ah, well, as to that, I think you'd have to take that suggestion to
> > pgsql-www. The style sheets used for the web site are - just to
> make
> > things exciting - stored in a completely different source code
> > repository to which I don't have access. Some kind of CSS
> > frobnication along the lines you suggest might be worth discussing,
> > but I don't really work on that stuff.
>
> Without being able to pass additional style from the source
> docs through to the html it seems a bit spooky to do this.

Since the existing style sheets aren't maintained upstream
and don't pass the necessary style through to the generated
style sheets, and since even if it did the style sheets
of the official docs on postgresql.org would not reflect
any changes made here, it seems like this patch should be
rejected.

Regards,

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