When referring to columns within catalog/views, I found it annoying that 
they were not linkable. You could only link to something higher level 
and then the reader was left to scroll and search for the column 
definition.

I think adding IDs to column definitions would be a good idea. In this 
initial patch, I've only decided to change pg_stat_statements 
documentation. It should make it easier to view necessary changes and 
visualize the impact of this change within the documentation.

Things that have changed:

- Octothorope is now visible when hovering a column within the column 
  definitions of pg_stat_statements and pg_stat_statements_info views
- Copying that link and pasting it in a new tab will take you directly 
  to the row of the column definition with a background color change to 
  highlight what was linked to. I understand that the CSS we use in-tree 
  is not the same CSS that is used on postgresql.org. I could make 
  a similar CSS change there as well if this seems like a good 
  direction.

I think there is discussion to be had about ID names. For instance, 
I used the format <view>-view.<column>. Should we do that for all views? 
How should IDs for catalog columns look? For pg_stat_statements 
specifically, should I have used an ID like 
pgstatstatements-<view>.<column>? Maybe there isn't a one size fits all 
solution.

I'm happy to extend this to the rest of the documented catalogs/views if 
this seems like a good idea to others. Question for a committer: would 
you like the patch series for everything to look a certain way?

In the future, we could extend this concept to functions and operators 
like in https://www.postgresql.org/docs/current/functions-json.html for 
example.

-- 
Tristan Partin
PostgreSQL Contributors Team
AWS (https://aws.amazon.com)


Reply via email to