Re: Small documentation improvement for ALTER SUBSCRIPTION

On Sat, Aug 7, 2021 at 4:33 PM Amit Kapila <amit(dot)kapila16(at)gmail(dot)com> wrote:
>
> On Thu, Jul 8, 2021 at 6:31 PM Masahiko Sawada <sawada(dot)mshk(at)gmail(dot)com> wrote:
> >
> > Hi all,
> >
> > When reading the doc of ALTER SUBSCRIPTION I realized that 'refresh
> > options' in the following paragraph is not tagged:
> >
> > ---
> > Additionally, refresh options as described under REFRESH PUBLICATION
> > may be specified, except in the case of DROP PUBLICATION.
> > ---
> >
> > When I read it for the first time, I got confused because we actually
> > have the 'refresh' option and this description in the paragraph of the
> > 'refresh' option. I think we can improve it by changing to
> > '<replaceable>refresh_option</replaceable>'. Thoughts?
> >
>
> I see that one can get confused but how about changing it to
> "Additionally, refresh options as described under <literal>REFRESH
> PUBLICATION</literal> (<replaceable>refresh_option</replaceable>) may
> be specified,.."? I think keeping "refresh options" in the text would
> be good because there could be multiple such options.
>

I feel like it would be better to reword it in some way that avoids
using parentheses because they look like part of the syntax instead of
just part of the sentence.

------
Kind Regards,
Peter Smith.
Fujitsu Australia.