Subject: Re: --sync-method isn't documented to take an argument

From: Daniel Gustafsson <[email-masked]>
Date: Wed, 4 Oct 2023 16:49:30 +0200

> On 4 Oct 2023, at 16:39, Tom Lane <[email-masked]> wrote:
> 
> Alvaro Herrera <[email-masked]> writes:
>> So I'm not sure that specifying the class="parameter" bit does anything in
>> reality, or that changing lines to add or remove it will have any effect.
> 
> I concluded a long time ago that it does nothing.

It does nothing in our current doc rendering, but if someone would like to
render docs with another style where it does make a difference it seems
unhelpful to not be consistent.

--
Daniel Gustafsson

---

From: Tom Lane <[email-masked]>
Date: Wed, 04 Oct 2023 10:51:59 -0400

> unhelpful to not be consistent.

To do that, we'd need some sort of agreement on what the possible
"class" values are and when to use each one.  I've never seen any
documentation about that.

			regards, tom lane

---

From: Nathan Bossart <[email-masked]>
Date: Wed, 4 Oct 2023 09:56:35 -0500

On Wed, Oct 04, 2023 at 09:08:57AM -0400, Robert Haas wrote:
> The various command-line utilities that have recently acquired a
> --sync-method option document it like this:
>
> <term><option>--sync-method</option></term>
>
> But that is not how we document options which take an argument. We do
> it like this:
>
> <term><option>--pgdata=<replaceable>directory</replaceable></option></term>
> <term><option>--filenode=<replaceable>filenode</replaceable></option></term>
>
> etc.
>
> This one should be something like this:
>
> <term><option>--sync-method=<replaceable>method</replaceable></option></term>

Whoops.  Thanks for pointing this out.  I'll get this fixed.

-- 
Nathan Bossart
Amazon Web Services: https://aws.amazon.com

---

From: Daniel Gustafsson <[email-masked]>
Date: Wed, 4 Oct 2023 16:56:54 +0200

> On 4 Oct 2023, at 16:51, Tom Lane <[email-masked]> wrote:
> 

Thats fair.  The 4.5 docbook guide isn't terribly helpful on what the
attributes mean and how they should be used:

	https://tdg.docbook.org/tdg/4.5/replaceable

In the 5.2 version the text is slightly expanded but not by all that much:

	https://tdg.docbook.org/tdg/5.2/replaceable

--
Daniel Gustafsson

---

From: Tom Lane <[email-masked]>
Date: Wed, 04 Oct 2023 11:07:07 -0400

> 	https://tdg.docbook.org/tdg/5.2/replaceable

OK, so now I know what the possible values of "class" are, but
I'm still not seeing a reason why we shouldn't just assume that
"parameter" is the only one of interest.  We don't really have
places where "command" or "function" would be appropriate AFAIR.
As for "option", what's the distinction between that and
"parameter"?  And why wouldn't I use "<option>" instead?

Even if we did have uses for the other class values, I'm skeptical
that we'd ever use them consistently enough that there'd be
value in rendering them differently.

			regards, tom lane

---

From: Daniel Gustafsson <[email-masked]>
Date: Wed, 4 Oct 2023 17:16:48 +0200

> On 4 Oct 2023, at 17:07, Tom Lane <[email-masked]> wrote:

> "parameter" is the only one of interest.

I think "parameter" is the only one of interest for this usecase (params to
application options), but it might not necessarily be applicable to other uses
of <replaceable /> we have in the tree, like for example in bki.sgml:

	<replaceable>oprname(lefttype,righttype)</replaceable>

But since we don't know if anyone is rendering our docs with a custom style, or
ever will, this is all very theoretical.  Maybe skipping the class attribute is
the right choice for consistency?

--
Daniel Gustafsson