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

From: Daniel Gustafsson <[email-masked]>
Date: Wed, 4 Oct 2023 15:15:37 +0200

> On 4 Oct 2023, at 15:08, Robert Haas <[email-masked]> wrote:

> This one should be something like this:
> 
> <term><option>--sync-method=<replaceable>method</replaceable></option></term>

Shouldn't it be <replaceable class="parameter">method</replaceable> ?

--
Daniel Gustafsson

---

From: Robert Haas <[email-masked]>
Date: Wed, 4 Oct 2023 09:22:14 -0400

> Shouldn't it be <replaceable class="parameter">method</replaceable> ?

Hmm, I think you're probably right. But look at this:

      <term><option>-S <replaceable>slotname</replaceable></option></term>
      <term><option>--slot=<replaceable
class="parameter">slotname</replaceable></option></term>

But then in the very same file:

      <term><option>-r <replaceable
class="parameter">rate</replaceable></option></term>
      <term><option>--max-rate=<replaceable
class="parameter">rate</replaceable></option></term>

It doesn't look to me like we're entirely consistent about this. I
also found this in vacuumlo.sgml, and there seem to be various other
examples:

<term><option>-U <replaceable>username</replaceable></option></term>

-- 
Robert Haas
EDB: http://www.enterprisedb.com

---

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

> On 4 Oct 2023, at 15:22, Robert Haas <[email-masked]> wrote:
> 

Hmm.. that's a bit unfortunate.

> It doesn't look to me like we're entirely consistent about this.

That (sadly) applies to a fair chunk of the docs.

I can take a stab at tidying this up during breaks at the conference.  It might
not be the most important bit of markup, but for anyone building the docs who
might want to use this it seems consistency will help.

--
Daniel Gustafsson

---

From: Alvaro Herrera <[email-masked]>
Date: Wed, 4 Oct 2023 16:35:32 +0200

> might want to use this it seems consistency will help.

So for HTML, the result of the pg_basebackup lines are these two lines:

</p></dd><dt><span class="term"><code class="option">-S <em class="replaceable"><code>slotname</code></em></code><br /></span><span class="term"><code class="option">--slot=<em class="replaceable"><code>slotname</code></em></code></span></dt><dd><p>

and 

</p></dd><dt><span class="term"><code class="option">-r <em class="replaceable"><code>rate</code></em></code><br /></span><span class="term"><code class="option">--max-rate=<em class="replaceable"><code>rate</code></em></code></span></dt><dd><p>

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.

-- 
Álvaro Herrera               48°01'N 7°57'E  —  https://www.EnterpriseDB.com/