Re: Small documentation improvement for ALTER SUBSCRIPTION

On Sun, Aug 8, 2021 at 10:21 AM Peter Smith <smithpb2250@gmail.com> wrote:
>
> On Sat, Aug 7, 2021 at 4:33 PM Amit Kapila <amit.kapila16@gmail.com> wrote:
> >
> > On Thu, Jul 8, 2021 at 6:31 PM Masahiko Sawada <sawada.mshk@gmail.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.
>

Fair enough, feel free to propose if you find something better or if
you think the current text in the docs is good.

-- 
With Regards,
Amit Kapila.