I’m proofreading Doc/library/struct.rst. I see this in the text:
This refers to objects that implement the :ref:bufferobjects and
provide either a readable or read-writable buffer.
and this in the displayed HTML:
This refers to objects that implement the Buffer Protocol and provide either a readable or read-writable buffer.
The text for the reference is substituted from the reference target. In this particular case, it drops right into the surrounding text, but I wonder if that’s a good idea. If the section (or page) heading of a reference target changes, the text may no longer be grammatical. Is this a case of explicit being better than implicit?
(Apologies if I’m beating a long dead horse. I saw nothing in the devguide section on documentation. Just let me know and I’ll disappear until I find another horse which needs to be flogged.)
Good question. Like most things in the real world, whether it is a good or a bad thing depends on the context.
If the context of the reference text is to refer to the name of the section, e.g. “As described in the Buffer Protocol section…”, then it is a good thing that the section title is auto-substituted, as the section title will be automatically updated with the current name of the section.
If the section title merely happens to coincide with the desired link target, which is somewhat more the case here, then it is not ideal if the section title ever changes, for the reasons you mention, and ideally it should be given an explicit title.
Of course, I don’t think we should expect people to be Spanish Inquisition about it, but if you’re looking for guidance on what’s best, that would be my advice.