Re: Another modest proposal for docs formatting: catalog descriptions

On 5/5/20 7:42 PM, Tom Lane wrote:
> Here's a really quick-n-dirty prototype patch that just converts the
> pg_aggregate table to the proposed style, plus a screenshot for those
> who don't feel like actually building the docs with the patch.

Not opposed to building the docs, but the screenshot expedites things ;)

> Looking at the results, it seems like we could really use a bit more
> horizontal space between the column names and data types, and perhaps
> also between the types and the (references) annotations. Other than
> that it looks decent. I don't know what's the cleanest way to add
> some space there --- I'd rather not have the SGML text do it explicitly.

If each element (i.e. column name, data type) is wrapped in a HTML
element with its own class (e.g. a span) it's fairly easy to add that
space with CSS. I'm not sure the ramifications for the PDFs though.

> There's room for complaint that this takes up more vertical space than
> the old way, assuming you have a reasonably wide window. I'm not
> terribly bothered by that, but maybe someone else will be? I'm inclined
> to think that that's well worth the benefit that we won't feel compelled
> to keep column descriptions short.

I think for reference materials, vertical space is acceptable. It seems
to be the "mobile way" of doing things, since people are scrolling down.

(And unlike the mailing lists, we don't need to keep the font small ;)

Anyway, +1

> BTW, this being just a test hack, I repurposed the "func_table_entry" and
> "func_signature" style marker roles. If we do this for real then of
> course we'd want to use different roles, even if they happen to mark up
> the same for now.

Agreed.

Thanks,

Jonathan