Re: Website patch request: documentation style update

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