Re: Add docs stub for recovery.conf - Mailing list pgsql-hackers
| From | Craig Ringer |
|---|---|
| Subject | Re: Add docs stub for recovery.conf |
| Date | |
| Msg-id | CAGRY4nzPNOyYQ_1-pWYToUVqQ0ThqP5jdURnJMZPm539fdizOg@mail.gmail.com Whole thread Raw |
| In response to | Re: Add docs stub for recovery.conf (Stephen Frost <sfrost@snowman.net>) |
| Responses |
Re: Add docs stub for recovery.conf
(Stephen Frost <sfrost@snowman.net>)
|
| List | pgsql-hackers |
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)
(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.
Attachment
pgsql-hackers by date: