Re: Doc patch, distinguish sections with an empty row in error code table - Mailing list pgsql-hackers
From | Karl O. Pinc |
---|---|
Subject | Re: Doc patch, distinguish sections with an empty row in error code table |
Date | |
Msg-id | 1352173273.29141.2@mofo Whole thread Raw |
In response to | Re: Doc patch, distinguish sections with an empty row in error code table (Tom Lane <tgl@sss.pgh.pa.us>) |
Responses |
Re: Doc patch, distinguish sections with an empty row in
error code table
("Karl O. Pinc" <kop@meme.com>)
Re: Doc patch, distinguish sections with an empty row in error code table (Robert Haas <robertmhaas@gmail.com>) |
List | pgsql-hackers |
On 11/05/2012 02:40:12 PM, Tom Lane wrote: > Robert Haas <robertmhaas@gmail.com> writes: > > On Fri, Oct 26, 2012 at 10:03 AM, Karl O. Pinc <kop@meme.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@meme.com> Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein
Attachment
pgsql-hackers by date: