Thread: Re: pgsql: Doc: add XML ID attributes to and tags.

Peter Eisentraut <peter.eisentraut@enterprisedb.com> writes:
> On 09.01.23 21:08, Tom Lane wrote:
>> Doc: add XML ID attributes to <sectN> and <varlistentry> tags.

> Any reason the new ids in create_database.sgml deviate from the normal
> naming schemes used everywhere else?  Is it to preserve the existing
> create-database-strategy?  Maybe we should rename that one and make the
> new ones consistent?

You'd have to ask Brar that, I didn't question his choices too much.

I have no objection to changing things as you suggest.  I'm hesitant to
rename very many pre-existing IDs for fear of breaking peoples' bookmarks,
but changing create-database-strategy doesn't seem like a big deal.

That reminds me that I was going to suggest fixing the few existing
variances from the "use '-' not '_'" policy:

$ grep 'id="[a-zA-Z0-9-]*_' *sgml ref/*sgml
config.sgml:     <varlistentry id="guc-plan-cache_mode" xreflabel="plan_cache_mode">
libpq.sgml:        <varlistentry id="libpq-PQpingParams-PQPING_OK">
libpq.sgml:        <varlistentry id="libpq-PQpingParams-PQPING_REJECT">
libpq.sgml:        <varlistentry id="libpq-PQpingParams-PQPING_NO_RESPONSE">
libpq.sgml:        <varlistentry id="libpq-PQpingParams-PQPING_NO_ATTEMPT">
pgbuffercache.sgml:  <table id="pgbuffercache_summary-columns">
ref/pg_checksums.sgml: <refsect1 id="r1-app-pg_checksums-1">

As you say, this isn't required by the toolchain any longer, but it
seems like a good idea to have consistent tag spelling.  I'm particularly
annoyed by guc-plan-cache_mode, which isn't even consistent with itself
let alone every other guc-XXX tag.

            regards, tom lane

On 12.01.2023 at 00:05, Tom Lane wrote:
> Peter Eisentraut <peter.eisentraut@enterprisedb.com> writes:
>> Any reason the new ids in create_database.sgml deviate from the normal
>> naming schemes used everywhere else?  Is it to preserve the existing
>> create-database-strategy?  Maybe we should rename that one and make the
>> new ones consistent?

I don't remember every single choice I made but the general goal was to
at least stay consistent within a varlist/[sub]section/file/chapter and
*never* change pre-existing ids since somebody may already be pointing
to them.

After all it is just an identifier that is supposed to be unique and
should not hurt our aesthetic feelings too much.

The consistency is mostly because we tend to like it and maybe also to
avoid collisions when making up new ids but I doubt that anybody will
ever try to remember an id or infer one form knowledge about the thing
it should be pointing at. I consider it a pretty opaque string that is
meant for copy-paste from a browser to some editing window.

It is all in our head and as a matter of fact we could be using UUIDs as
Ids and save us from any further consistency issues. It's just that they
look so ugly.

> You'd have to ask Brar that, I didn't question his choices too much.
>
> I have no objection to changing things as you suggest.I'm hesitant to
> rename very many pre-existing IDs for fear of breaking peoples' bookmarks,
> but changing create-database-strategy doesn't seem like a big deal.

Personally I'd only d this for ids that haven't been "released" as
official documentation (even as "devel" since the new things tend to
attract more discussions and probably linking). I very much consider
URLs as UI and go long ways to keep them consistent (HTTP 3xx is a
friend of mine) as you never know who might be pointing at them from
where and making them a moving target defeats their purpose and probably
hurt more than some inconsistency.

Regards,

Brar

On 12.01.23 00:05, Tom Lane wrote:
> That reminds me that I was going to suggest fixing the few existing
> variances from the "use '-' not '_'" policy:
> 
> $ grep 'id="[a-zA-Z0-9-]*_' *sgml ref/*sgml
> config.sgml:     <varlistentry id="guc-plan-cache_mode" xreflabel="plan_cache_mode">

should be fixed

> libpq.sgml:        <varlistentry id="libpq-PQpingParams-PQPING_OK">
> libpq.sgml:        <varlistentry id="libpq-PQpingParams-PQPING_REJECT">
> libpq.sgml:        <varlistentry id="libpq-PQpingParams-PQPING_NO_RESPONSE">
> libpq.sgml:        <varlistentry id="libpq-PQpingParams-PQPING_NO_ATTEMPT">

I think we can leave these.  They are internally consistent.

> pgbuffercache.sgml:  <table id="pgbuffercache_summary-columns">

should be fixed

> ref/pg_checksums.sgml: <refsect1 id="r1-app-pg_checksums-1">

pretty bogus

Peter Eisentraut <peter.eisentraut@enterprisedb.com> writes:
> On 12.01.23 00:05, Tom Lane wrote:
>> That reminds me that I was going to suggest fixing the few existing
>> variances from the "use '-' not '_'" policy:
>>
>> $ grep 'id="[a-zA-Z0-9-]*_' *sgml ref/*sgml
>> config.sgml:     <varlistentry id="guc-plan-cache_mode" xreflabel="plan_cache_mode">

> should be fixed

>> libpq.sgml:        <varlistentry id="libpq-PQpingParams-PQPING_OK">
>> libpq.sgml:        <varlistentry id="libpq-PQpingParams-PQPING_REJECT">
>> libpq.sgml:        <varlistentry id="libpq-PQpingParams-PQPING_NO_RESPONSE">
>> libpq.sgml:        <varlistentry id="libpq-PQpingParams-PQPING_NO_ATTEMPT">

> I think we can leave these.  They are internally consistent.

>> pgbuffercache.sgml:  <table id="pgbuffercache_summary-columns">

> should be fixed

>> ref/pg_checksums.sgml: <refsect1 id="r1-app-pg_checksums-1">

> pretty bogus

OK, done like that.

            regards, tom lane