<application> vs <command> for command line tools in the docs

From: ilmari(at)ilmari(dot)org (Dagfinn Ilmari Mannsåker )
To: PostgreSQL Hackers <pgsql-hackers(at)postgresql(dot)org>
Subject: <application> vs <command> for command line tools in the docs
Date: 2020-06-21 14:45:29
Message-ID: 87r1u8o4ty.fsf@wibble.ilmari.org
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

Hi Hackers,

While I was looking at linkifying SQL commands in the system catalog
docs, I noticed that catalog.sgml uses the <command> tag to refer to
initdb, while I'd expected it to use <application>.

Looking for patterns, I grepped for the two tags with contents
consisting only of lower-case letters, numbers, hyphens and underscores,
to restrict it to things that look like shell command names, not SQL
commands or full command lines. When referring to binaries shipped with
postgres itself, <application> is by far the most common, except for
initdb, postgres, ecpg, pg_ctl, pg_resetwal, and pg_config. For
external programs it's more of a mix, but overall there are more than
twice as many instances of <application> of this form than of <command>.

I'm not proposing going throuhgh all 1500+ instances in one fell swoop,
but some consistency (and a policy going forward) would be nice.

- ilmari
--
"A disappointingly low fraction of the human race is,
at any given time, on fire." - Stig Sandbeck Mathisen

Responses

Browse pgsql-hackers by date

  From Date Subject
Next Message Alvaro Herrera 2020-06-21 15:08:02 Re: [PATCH] Missing links between system catalog documentation pages
Previous Message Tom Lane 2020-06-21 14:03:33 Re: [PATCH] Missing links between system catalog documentation pages