Here is another doc hacking task pulled from my ever growing TODO which I think would be suitable for someone keen to get started in hacking on the docs. There is an element of research here in order to propose a fix, since the best course of action is unknown (there are many possible options).
We have quite the variety in how we write examples in the docs, both within the reference manpages and in the main documentation. A few examples (pun intended) follow: * https://www.postgresql.org/docs/devel/plpgsql-trigger.html Here we use <example id=foo> to mark up the example and refer to the id attribute in the text (sometimes just right before the example itself which seems of questionable use). * https://www.postgresql.org/docs/devel/typeconv-oper.html This is similarly using <example> but no id for referencing it. There might not be much need for referencing it in text of course, in which case omitting the id is fine, but there seems to be little difference in "Some examples follow" used here and "Example XX.YY below does blah" used elsewhere. * https://www.postgresql.org/docs/devel/bloom.html#BLOOM-EXAMPLES Here the example is a <sect2> which in turn creates a TOC entry for the example. * https://www.postgresql.org/docs/devel/datatype-xml.html#DATATYPE-XML-CREATING Another variant, here we just have a plain string "Examples:" with no markup at all. * https://www.postgresql.org/docs/devel/intagg.html We only have one of this, but here we called it "Sample Uses" and made it a <sect2>. Maybe that's fine, but there are similar sections elsewhere where we use Examples so.. I'm sure there are more that I didn't see with a quick grep and skim. On top of these there are also various combinations of Example(s) vs Exmaples, Example Uses vs plain Examples etc. Standardizing how we mark up examples would improve documentation consistency and ideally make it easier to navigate and search. I have not done more than collect the variants listed above so I don't know if the correct answer is "do nothing" (which I doubt it is), but even reaching that conclusion would be a step forward. Anyone interested? -- Daniel Gustafsson
