Re: Add docs stub for recovery.conf

On Wed, 20 Jan 2021 at 02:45, Stephen Frost <sfrost@snowman.net> wrote:

> Greetings,
>
> * Stephen Frost (sfrost@snowman.net) wrote:
> > * Craig Ringer (craig.ringer@enterprisedb.com) wrote:
> > > On Thu, 14 Jan 2021 at 03:44, Stephen Frost <sfrost@snowman.net>
> wrote:
> > > > Alright, how does this look?  The new entries are all under the
> > > > 'obsolete' section to keep it out of the main line, but should work
> to
> > > > 'fix' the links that currently 404 and provide a bit of a 'softer'
> > > > landing for the other cases that currently just forcibly redirect
> using
> > > > the website doc alias capability.
> > >
> > > Thanks for expanding the change to other high profile obsoleted or
> renamed
> > > features and tools.
> >
> > Thanks for taking the time to review it and comment on it!
> >
> > > One minor point. I'm not sure this is quite the best way to spell the
> index
> > > entries:
> > >
> > > +   <indexterm>
> > > +     <primary>obsolete</primary>
> > > +     <secondary>pg_receivexlog</secondary>
> > > +   </indexterm>
> > >
> > > as it will produce an index term "obsolete" with a list of various
> > > components under it. While that concentrates them nicely, it means
> people
> > > won't actually find them if they're using the index alphabetically.
> >
> > Ah, yeah, that's definitely a good point and one that I hadn't really
> > spent much time thinking about.
> >
> > > I'd slightly prefer
> > >
> > > +   <indexterm>
> > > +     <primary>pg_receivexlog</primary>
> > > +     <seealso>pg_receivewal</secondary>
> > > +   </indexterm>
> > >
> > > even though that bulks the index up a little, because then people are
> a bit
> > > more likely to find it.
> >
> > Yup, makes sense, updated patch attached which makes that change.
> >
> > > > I ended up not actually doing this for the catalog -> view change of
> > > > pg_replication_slots simply because I don't really think folks will
> > > > misunderstand or be confused by that redirect since it's still the
> same
> > > > relation.  If others disagree though, we could certainly change that
> > > > too.
> > >
> > > I agree with you.
> >
> > Ok, great.
> >
> > How does the attached look then?
>

Pretty good to me. Thanks so much for your help and support with this.


Index entries render as e.g.

    pg_xlogdump, The pg_xlogdump command
        (see also pg_waldump)

wheras with the obsolete subhead they would render as something like:

    obsolete, Obsolete or renamed features, settings and files
        pg_xlogdump, The pg_xlogdump command

The see also spelling is much easier to find in the index but doesn't make
it as obvious that it's obsoleted/replaced.

A look at the doxygen docs suggest we should use <see> not <seealso> for
these.

A quick

    sed -i -e 's/<seealso>/<see>/g' -e 's/<\/seealso>/<\/see>/g'
doc/src/sgml/appendix-obsolete*

causes them to render much better:

    pg_receivexlog, The pg_receivexlog command (see pg_receivewal)

It might be worth changing the <title/>s too, so I've done so in the
attached. The terms now render as:

    pg_receivexlog, pg_receivexlog renamed to pg_recievewal (see
pg_receivewal)

which is good enough in my opinion. The duplication is messy but an
expected artifact of index generation. I don't see any docbook <indexterm>
attribute that lets you suppress insertion of the <title> of the section
containing the <indexterm>, and it's not worth fiddling to try to eliminate
it with structural hacks.

The attached changes the titles, changes <seealso> to <see>, and also
updates the comments in the obsolete entries SGML docs to specify that the
id must be unchanged + give a recommended index term format.