pg.ddx.io  pgsql-committers@postgresql.org mailing list archive  
help / color / mirror / Atom feed
pgsql: Doc: add XML ID attributes to <sectN> and <varlistentry> tags.
6+ messages / 3 participants
[nested] [flat]

Commits from this thread:
  2023-01-17 09d465c397  Doc: fix a few oddly-spelled SGML ID attributes.
* pgsql: Doc: add XML ID attributes to <sectN> and <varlistentry> tags.
@ 2023-01-09 20:08 Tom Lane <tgl@sss.pgh.pa.us>
  2023-01-11 22:10 ` Re: pgsql: Doc: add XML ID attributes to <sectN> and <varlistentry> tags. Peter Eisentraut <peter.eisentraut@enterprisedb.com>
  0 siblings, 1 reply; 6+ messages in thread

From: Tom Lane @ 2023-01-09 20:08 UTC (permalink / raw)
  To: pgsql-committers@lists.postgresql.org

Doc: add XML ID attributes to <sectN> and <varlistentry> tags.

This doesn't have any external effect at the moment, but it
will allow adding useful link-discoverability features later.

Brar Piening, reviewed by Karl Pinc.

Discussion: https://postgr.es/m/CAB8KJ=jpuQU9QJe4+RgWENrK5g9jhoysMw2nvTN_esoOU0=a_w@mail.gmail.com

Branch
------
master

Details
-------
https://git.postgresql.org/pg/commitdiff/78ee60ed84bb3a1cf0b6bd9a715dcbcf252a90f5

Modified Files
--------------
doc/src/sgml/amcheck.sgml             |   8 +-
doc/src/sgml/arch-dev.sgml            |   6 +-
doc/src/sgml/auth-delay.sgml          |   4 +-
doc/src/sgml/auto-explain.sgml        |  32 +--
doc/src/sgml/basebackup-to-shell.sgml |   4 +-
doc/src/sgml/basic-archive.sgml       |   6 +-
doc/src/sgml/bloom.sgml               |  10 +-
doc/src/sgml/btree-gin.sgml           |   4 +-
doc/src/sgml/btree-gist.sgml          |   4 +-
doc/src/sgml/charset.sgml             |  48 ++--
doc/src/sgml/citext.sgml              |  10 +-
doc/src/sgml/config.sgml              |  18 +-
doc/src/sgml/contrib-spi.sgml         |   8 +-
doc/src/sgml/cube.sgml                |  12 +-
doc/src/sgml/datatype.sgml            |  30 +-
doc/src/sgml/ddl.sgml                 |  58 ++--
doc/src/sgml/dict-int.sgml            |   4 +-
doc/src/sgml/dict-xsyn.sgml           |   4 +-
doc/src/sgml/docguide.sgml            |  60 ++--
doc/src/sgml/earthdistance.sgml       |   4 +-
doc/src/sgml/ecpg.sgml                | 516 +++++++++++++++++-----------------
doc/src/sgml/extend.sgml              |  88 +++---
doc/src/sgml/features.sgml            |   8 +-
doc/src/sgml/func.sgml                |  24 +-
doc/src/sgml/fuzzystrmatch.sgml       |   8 +-
doc/src/sgml/geqo.sgml                |   2 +-
doc/src/sgml/history.sgml             |   2 +-
doc/src/sgml/hstore.sgml              |  16 +-
doc/src/sgml/install-windows.sgml     |  10 +-
doc/src/sgml/installation.sgml        | 274 +++++++++---------
doc/src/sgml/intagg.sgml              |   4 +-
doc/src/sgml/intarray.sgml            |  10 +-
doc/src/sgml/isn.sgml                 |  12 +-
doc/src/sgml/jit.sgml                 |   2 +-
doc/src/sgml/json.sgml                |   2 +-
doc/src/sgml/libpq.sgml               |   4 +-
doc/src/sgml/lo.sgml                  |   8 +-
doc/src/sgml/logicaldecoding.sgml     |   8 +-
doc/src/sgml/ltree.sgml               |  12 +-
doc/src/sgml/nls.sgml                 |   8 +-
doc/src/sgml/oldsnapshot.sgml         |   2 +-
doc/src/sgml/pageinspect.sgml         |  14 +-
doc/src/sgml/perform.sgml             |  10 +-
doc/src/sgml/pgbuffercache.sgml       |   8 +-
doc/src/sgml/pgcrypto.sgml            |  74 ++---
doc/src/sgml/pgfreespacemap.sgml      |   6 +-
doc/src/sgml/pgprewarm.sgml           |   6 +-
doc/src/sgml/pgrowlocks.sgml          |   6 +-
doc/src/sgml/pgstatstatements.sgml    |  12 +-
doc/src/sgml/pgstattuple.sgml         |   4 +-
doc/src/sgml/pgsurgery.sgml           |   4 +-
doc/src/sgml/pgtrgm.sgml              |  14 +-
doc/src/sgml/pgvisibility.sgml        |   4 +-
doc/src/sgml/pgwalinspect.sgml        |  14 +-
doc/src/sgml/plpgsql.sgml             |  92 +++---
doc/src/sgml/plpython.sgml            |  12 +-
doc/src/sgml/postgres-fdw.sgml        |  40 +--
doc/src/sgml/problems.sgml            |   6 +-
doc/src/sgml/protocol.sgml            |  14 +-
doc/src/sgml/queries.sgml             |   2 +-
doc/src/sgml/ref/alter_role.sgml      |  26 +-
doc/src/sgml/ref/alter_table.sgml     | 126 ++++-----
doc/src/sgml/ref/commit.sgml          |   2 +-
doc/src/sgml/ref/create_database.sgml |  30 +-
doc/src/sgml/ref/create_table.sgml    |  90 +++---
doc/src/sgml/ref/initdb.sgml          |  56 ++--
doc/src/sgml/ref/pgbench.sgml         | 116 ++++----
doc/src/sgml/ref/psql-ref.sgml        | 424 ++++++++++++++--------------
doc/src/sgml/ref/rollback.sgml        |   2 +-
doc/src/sgml/regress.sgml             |  26 +-
doc/src/sgml/rowtypes.sgml            |   4 +-
doc/src/sgml/rules.sgml               |   8 +-
doc/src/sgml/runtime.sgml             |   2 +-
doc/src/sgml/seg.sgml                 |  12 +-
doc/src/sgml/sepgsql.sgml             |  12 +-
doc/src/sgml/sources.sgml             |  40 +--
doc/src/sgml/sslinfo.sgml             |   4 +-
doc/src/sgml/tablefunc.sgml           |  14 +-
doc/src/sgml/tsm-system-rows.sgml     |   2 +-
doc/src/sgml/tsm-system-time.sgml     |   2 +-
doc/src/sgml/unaccent.sgml            |   6 +-
doc/src/sgml/uuid-ossp.sgml           |   6 +-
doc/src/sgml/xfunc.sgml               |  12 +-
doc/src/sgml/xml2.sgml                |  14 +-
doc/src/sgml/xoper.sgml               |  12 +-
85 files changed, 1372 insertions(+), 1372 deletions(-)



^ permalink  raw  reply  [nested|flat] 6+ messages in thread

* Re: pgsql: Doc: add XML ID attributes to <sectN> and <varlistentry> tags.
  2023-01-09 20:08 pgsql: Doc: add XML ID attributes to <sectN> and <varlistentry> tags. Tom Lane <tgl@sss.pgh.pa.us>
@ 2023-01-11 22:10 ` Peter Eisentraut <peter.eisentraut@enterprisedb.com>
  2023-01-11 23:05   ` Re: pgsql: Doc: add XML ID attributes to <sectN> and <varlistentry> tags. Tom Lane <tgl@sss.pgh.pa.us>
  0 siblings, 1 reply; 6+ messages in thread

From: Peter Eisentraut @ 2023-01-11 22:10 UTC (permalink / raw)
  To: Tom Lane <tgl@sss.pgh.pa.us>; pgsql-committers@lists.postgresql.org

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?





^ permalink  raw  reply  [nested|flat] 6+ messages in thread

* Re: pgsql: Doc: add XML ID attributes to <sectN> and <varlistentry> tags.
  2023-01-09 20:08 pgsql: Doc: add XML ID attributes to <sectN> and <varlistentry> tags. Tom Lane <tgl@sss.pgh.pa.us>
  2023-01-11 22:10 ` Re: pgsql: Doc: add XML ID attributes to <sectN> and <varlistentry> tags. Peter Eisentraut <peter.eisentraut@enterprisedb.com>
@ 2023-01-11 23:05   ` Tom Lane <tgl@sss.pgh.pa.us>
  2023-01-12 05:34     ` Re: pgsql: Doc: add XML ID attributes to <sectN> and <varlistentry> tags. Brar Piening <brar@gmx.de>
  2023-01-16 11:12     ` Re: pgsql: Doc: add XML ID attributes to <sectN> and <varlistentry> tags. Peter Eisentraut <peter.eisentraut@enterprisedb.com>
  0 siblings, 2 replies; 6+ messages in thread

From: Tom Lane @ 2023-01-11 23:05 UTC (permalink / raw)
  To: Peter Eisentraut <peter.eisentraut@enterprisedb.com>; +Cc: Brar Piening <brar@gmx.de>; pgsql-hackers@lists.postgresql.org

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





^ permalink  raw  reply  [nested|flat] 6+ messages in thread

* Re: pgsql: Doc: add XML ID attributes to <sectN> and <varlistentry> tags.
  2023-01-09 20:08 pgsql: Doc: add XML ID attributes to <sectN> and <varlistentry> tags. Tom Lane <tgl@sss.pgh.pa.us>
  2023-01-11 22:10 ` Re: pgsql: Doc: add XML ID attributes to <sectN> and <varlistentry> tags. Peter Eisentraut <peter.eisentraut@enterprisedb.com>
  2023-01-11 23:05   ` Re: pgsql: Doc: add XML ID attributes to <sectN> and <varlistentry> tags. Tom Lane <tgl@sss.pgh.pa.us>
@ 2023-01-12 05:34     ` Brar Piening <brar@gmx.de>
  1 sibling, 0 replies; 6+ messages in thread

From: Brar Piening @ 2023-01-12 05:34 UTC (permalink / raw)
  To: Tom Lane <tgl@sss.pgh.pa.us>; Peter Eisentraut <peter.eisentraut@enterprisedb.com>; +Cc: pgsql-hackers@lists.postgresql.org

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






^ permalink  raw  reply  [nested|flat] 6+ messages in thread

* Re: pgsql: Doc: add XML ID attributes to <sectN> and <varlistentry> tags.
  2023-01-09 20:08 pgsql: Doc: add XML ID attributes to <sectN> and <varlistentry> tags. Tom Lane <tgl@sss.pgh.pa.us>
  2023-01-11 22:10 ` Re: pgsql: Doc: add XML ID attributes to <sectN> and <varlistentry> tags. Peter Eisentraut <peter.eisentraut@enterprisedb.com>
  2023-01-11 23:05   ` Re: pgsql: Doc: add XML ID attributes to <sectN> and <varlistentry> tags. Tom Lane <tgl@sss.pgh.pa.us>
@ 2023-01-16 11:12     ` Peter Eisentraut <peter.eisentraut@enterprisedb.com>
  2023-01-17 22:13       ` Re: pgsql: Doc: add XML ID attributes to <sectN> and <varlistentry> tags. Tom Lane <tgl@sss.pgh.pa.us>
  1 sibling, 1 reply; 6+ messages in thread

From: Peter Eisentraut @ 2023-01-16 11:12 UTC (permalink / raw)
  To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Brar Piening <brar@gmx.de>; pgsql-hackers@lists.postgresql.org

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






^ permalink  raw  reply  [nested|flat] 6+ messages in thread

* Re: pgsql: Doc: add XML ID attributes to <sectN> and <varlistentry> tags.
  2023-01-09 20:08 pgsql: Doc: add XML ID attributes to <sectN> and <varlistentry> tags. Tom Lane <tgl@sss.pgh.pa.us>
  2023-01-11 22:10 ` Re: pgsql: Doc: add XML ID attributes to <sectN> and <varlistentry> tags. Peter Eisentraut <peter.eisentraut@enterprisedb.com>
  2023-01-11 23:05   ` Re: pgsql: Doc: add XML ID attributes to <sectN> and <varlistentry> tags. Tom Lane <tgl@sss.pgh.pa.us>
  2023-01-16 11:12     ` Re: pgsql: Doc: add XML ID attributes to <sectN> and <varlistentry> tags. Peter Eisentraut <peter.eisentraut@enterprisedb.com>
@ 2023-01-17 22:13       ` Tom Lane <tgl@sss.pgh.pa.us>
  0 siblings, 0 replies; 6+ messages in thread

From: Tom Lane @ 2023-01-17 22:13 UTC (permalink / raw)
  To: Peter Eisentraut <peter.eisentraut@enterprisedb.com>; +Cc: Brar Piening <brar@gmx.de>; pgsql-hackers@lists.postgresql.org

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





^ permalink  raw  reply  [nested|flat] 6+ messages in thread


end of thread, other threads:[~2023-01-17 22:13 UTC | newest]

Thread overview: 6+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2023-01-09 20:08 pgsql: Doc: add XML ID attributes to <sectN> and <varlistentry> tags. Tom Lane <tgl@sss.pgh.pa.us>
2023-01-11 22:10 ` Peter Eisentraut <peter.eisentraut@enterprisedb.com>
2023-01-11 23:05   ` Tom Lane <tgl@sss.pgh.pa.us>
2023-01-12 05:34     ` Brar Piening <brar@gmx.de>
2023-01-16 11:12     ` Peter Eisentraut <peter.eisentraut@enterprisedb.com>
2023-01-17 22:13       ` Tom Lane <tgl@sss.pgh.pa.us>

This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox