Re: Website patch request: documentation style update

"Jonathan S. Katz" <jkatz(at)postgresql(dot)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