Thread: Website patch request: documentation style update
In the thread at [1], we agreed to adopt a new layout for the
documentation's tables of functions/operators, which will require
a "hanging indent" layout for cells within those tables. So far
as I've found, there's no good way to specify that within the .sgml
files proper. The preferred way to do it seems to be to attach a
"role" attribute to affected <entry> tags, and then key off of that
to apply the appropriate style adjustments in CSS. So I'd like to
request that the website be updated more or less per the attached.
It's likely that I've missed something about how best to do that ---
I'm not even totally sure that main.css is the best place to
put this change. So feel free to adjust as you see fit.
regards, tom lane
[1] https://www.postgresql.org/message-id/flat/8691.1586798003%40sss.pgh.pa.us
--- main.css.orig 2020-04-16 18:46:26.040658279 -0400
+++ main.css 2020-04-16 19:18:15.689371719 -0400
@@ -791,6 +791,20 @@
word-break: unset;
}
+/* formatting for entries in tables of functions: indent all but first line */
+
+#docContent table.table th.functableentry {
+ padding-left: 5em;
+ text-indent: -5em;
+ text-align: left;
+}
+
+#docContent table.table td.functableentry {
+ padding-left: 5em;
+ text-indent: -5em;
+ text-align: left;
+}
+
/**
* Titles, Navigation
*/
On 4/17/20 4:44 PM, Tom Lane wrote: > In the thread at [1], we agreed to adopt a new layout for the > documentation's tables of functions/operators, which will require > a "hanging indent" layout for cells within those tables. So far > as I've found, there's no good way to specify that within the .sgml > files proper. The preferred way to do it seems to be to attach a > "role" attribute to affected <entry> tags, and then key off of that > to apply the appropriate style adjustments in CSS. So I'd like to > request that the website be updated more or less per the attached. > > It's likely that I've missed something about how best to do that --- > I'm not even totally sure that main.css is the best place to > put this change. So feel free to adjust as you see fit. Seems reasonable. Is the change committed yet so I can test against it? Thanks, Jonathan
Attachment
"Jonathan S. Katz" <jkatz@postgresql.org> writes:
> Seems reasonable. Is the change committed yet so I can test against it?
Just pushed it a moment ago.
regards, tom lane
On 4/17/20 8:51 PM, Tom Lane wrote: > "Jonathan S. Katz" <jkatz@postgresql.org> writes: >> Seems reasonable. Is the change committed yet so I can test against it? > > Just pushed it a moment ago. Thanks! I went ahead and tweaked it a bit (attached) to give a little bit of space between the lead line + the table edge (example screenshot attached). I've attached the update patch. I tested in Chrome, FF, Safari, and varied my window size. I then started testing on my phone, and noticed that the font is smaller in the tables than elsewhere. I believe this was done initially at first to manage the old table design, so perhaps this is an opportunity to bump the font up on it. Thoughts? Jonathan
Attachment
"Jonathan S. Katz" <jkatz@postgresql.org> writes:
> I went ahead and tweaked it a bit (attached) to give a little bit of
> space between the lead line + the table edge (example screenshot
> attached). I've attached the update patch. I tested in Chrome, FF,
> Safari, and varied my window size.
Sounds good. I have no particular allegiance to the settings I used.
> I then started testing on my phone, and noticed that the font is smaller
> in the tables than elsewhere. I believe this was done initially at first
> to manage the old table design, so perhaps this is an opportunity to
> bump the font up on it.
I'd noticed that the website style wants to render function signatures
in a very cramped way, with less inter-word spacing than normal; is that
another aspect of this? +1 for undoing it, at least in cells that are
marked functableentry.
regards, tom lane
On 4/18/20 2:46 PM, Tom Lane wrote:
> "Jonathan S. Katz" <jkatz@postgresql.org> writes:
>> I went ahead and tweaked it a bit (attached) to give a little bit of
>> space between the lead line + the table edge (example screenshot
>> attached). I've attached the update patch. I tested in Chrome, FF,
>> Safari, and varied my window size.
>
> Sounds good. I have no particular allegiance to the settings I used.
Thanks. Pushed up[1].
>> I then started testing on my phone, and noticed that the font is smaller
>> in the tables than elsewhere. I believe this was done initially at first
>> to manage the old table design, so perhaps this is an opportunity to
>> bump the font up on it.
>
> I'd noticed that the website style wants to render function signatures
> in a very cramped way, with less inter-word spacing than normal; is that
> another aspect of this?
I believe that's one of the trademarks of the monospace font family, but
we may be able to adjust it.
> +1 for undoing it, at least in cells that are
> marked functableentry.
Great, I'll experiment and see what I can come up with.
I'm not sure how much more can be done in DocBook (and if need be I'll
opine again on the other thread) but I will note that the HTML that is
generated is a bit odd to deal with. For example (simplifying it a bit):
<td class="functableentry">
<code class="function">enum_first</code> ( <code
class="type">anyenum</code> ) → <code class="returnvalue">anyenum</code>
<br>
Returns the first value of the input enum type.
<br>
<code class="literal">enum_first(null::rainbow)</code> → <code
class="returnvalue">red</code>
</td>
A few things to note:
1. The "(" seem to not be included in the "code" blocks. If they are all
together, that may help with some of the cramped/spacingness, as I can
uniformly apply rules.
2. The "<br>" in the "<td>" block is definitely an anti-pattern. The way
we were generating it before, with the multiple rowspan/colspan is "more
correct" for getting that formatting, and with the the different classes
we're applying, we could leverage that to remove the borders, etc. on
the web view. I don't know how that would take for the PDF view.
I do like the direction that this is heading, I think it's an
improvement since v1!
Thanks,
Jonathan
[1] https://www.postgresql.org/docs/devel/functions-enum.html
Attachment
"Jonathan S. Katz" <jkatz@postgresql.org> writes:
> I'm not sure how much more can be done in DocBook (and if need be I'll
> opine again on the other thread) but I will note that the HTML that is
> generated is a bit odd to deal with. For example (simplifying it a bit):
> <td class="functableentry">
> <code class="function">enum_first</code> ( <code
> class="type">anyenum</code> ) → <code class="returnvalue">anyenum</code>
> <br>
> Returns the first value of the input enum type.
> <br>
> <code class="literal">enum_first(null::rainbow)</code> → <code
> class="returnvalue">red</code>
> </td>
> A few things to note:
> 1. The "(" seem to not be included in the "code" blocks. If they are all
> together, that may help with some of the cramped/spacingness, as I can
> uniformly apply rules.
I did that intentionally, because rendering parens and brackets and
such in a different font seems helpful. In any case, it's not
very clear how to do it differently in DocBook without really
bogus markup.
> 2. The "<br>" in the "<td>" block is definitely an anti-pattern.
Yeah, I agree, it's a hack. As I mentioned in the commit message, this
is basically a way of getting a <varlistentry>-like layout without the
extra vertical space that that construct wants to add. If you have a
better idea about how to implement that, it's not too late to reconsider
the markup. But we do need to keep an eye on how it renders in PDF,
too.
regards, tom lane
"Jonathan S. Katz" <jkatz@postgresql.org> writes:
> On 4/18/20 2:46 PM, Tom Lane wrote:
>> I'd noticed that the website style wants to render function signatures
>> in a very cramped way, with less inter-word spacing than normal; is that
>> another aspect of this?
> I believe that's one of the trademarks of the monospace font family, but
> we may be able to adjust it.
BTW, as far as that goes, I *don't* see equivalent cramping when building
the docs without STYLE=website. Compare e.g. the renderings of concat_ws'
description in table 9.10 (attached). So I think it's something that is
being done intentionally somewhere in the website customization. I'm not
sure where to look though.
Also, now that I look at it, I see the website style seems to be rendering
parents and brackets in the same font as the <code> items anyway. This
does not seem like an improvement over what happens without that.
regards, tom lane
Attachment
On 4/18/20 3:34 PM, Tom Lane wrote: > "Jonathan S. Katz" <jkatz@postgresql.org> writes: >> On 4/18/20 2:46 PM, Tom Lane wrote: >>> I'd noticed that the website style wants to render function signatures >>> in a very cramped way, with less inter-word spacing than normal; is that >>> another aspect of this? > >> I believe that's one of the trademarks of the monospace font family, but >> we may be able to adjust it. > > BTW, as far as that goes, I *don't* see equivalent cramping when building > the docs without STYLE=website. Compare e.g. the renderings of concat_ws' > description in table 9.10 (attached). So I think it's something that is > being done intentionally somewhere in the website customization. I'm not > sure where to look though. I think this may be the pain of monospace, as it's browser/OS dependent, though (comments below)... > Also, now that I look at it, I see the website style seems to be rendering > parents and brackets in the same font as the <code> items anyway. This > does not seem like an improvement over what happens without that. So, it seems like it's the same font, but it's a trompe-l'oeil: it is the default font of the site (Open Sans). However, it appears the old-style docs use a different browser/OS dependent font in "verdana". When I force it to verdana, we get the attached (enum_first has verdana, enum_list has Open Sans). This seems to get the desired effect on the function definition line, but it sets the descriptions to be verdana, which seems to clash with the rest of the site. (With my other comment of "can we get said signature into its own row/block, I can make said issue go away easily :) Per your upthread comment, I believe that would entail taking a go at DocBook and ensuring it still looks good in the PDF build, which I am not ruling out trying...) Another option is to make the font large in the tables, which helps with the spacing. I'm not as much of a fan of that solution. I did try using the "letter-spacing" CSS property, but the results become fairly comical, fairly quickly. I think Door #1 would be the optimal quick/best approach for a short term resolution, pending other structural changes. Jonathan
Attachment
"Jonathan S. Katz" <jkatz@postgresql.org> writes:
> On 4/18/20 3:34 PM, Tom Lane wrote:
>> Also, now that I look at it, I see the website style seems to be rendering
>> parents and brackets in the same font as the <code> items anyway. This
>> does not seem like an improvement over what happens without that.
> So, it seems like it's the same font, but it's a trompe-l'oeil: it is
> the default font of the site (Open Sans). However, it appears the
> old-style docs use a different browser/OS dependent font in "verdana".
> When I force it to verdana, we get the attached (enum_first has verdana,
> enum_list has Open Sans). This seems to get the desired effect on the
> function definition line, but it sets the descriptions to be verdana,
> which seems to clash with the rest of the site.
Hm. Let's just leave that alone for now. I agree that rendering these
in a subtly different font would be a bit weird.
Did you determine whether we're actually forcing a smaller font in
these tables?
regards, tom lane