Add docs stub for recovery.conf

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
45 messages Options
123
Reply | Threaded
Open this post in threaded view
|

Re: Add docs stub for recovery.conf

Stephen Frost
Greetings,

* Bruce Momjian ([hidden email]) wrote:

> On Fri, Dec  4, 2020 at 02:00:23PM -0500, Stephen Frost wrote:
> > * Bruce Momjian ([hidden email]) wrote:
> > > Yes, that is pretty much the same thing I was suggesting, except that
> > > each rename has its own _original_ URL link, which I think is also
> > > acceptable.  My desire is for these items to all exist in one place, and
> > > an appendix of them seems fine.
> >
> > Alright, so, to try and move this forward I'll list out (again) the
> > renames that we have in pgweb:
> >
> > catalog-pg-replication-slots.html <-> view-pg-replication-slots.html
> > pgxlogdump.html <-> pgwaldump.html
> > app-pgresetxlog.html <-> app-pgresetwal.html
> > app-pgreceivexlog.html <-> app-pgreceivewal.html
> >
> > (excluding the 'legal notice' one)
> >
> > Bruce, are you saying that we need to take Craig's patch and then add to
> > it entries for all of the above, effectively removing the need for the
> > web page aliases and redirects?  If that was done, would that be
>
> Yes, I think putting the compatibility section headings in our main
> documentation flow will make it too hard to read and cause unnecessary
> complexity, but if we have a separate section for them, adding the
> section headings seems fine.  This way, we don't have to add a redirect
> every time we add a new entry.
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.

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.

> > sufficient to get this committed?  Are there other things that people
> > can think of off-hand that we should include, I think Craig might have
> > mentioned something else earlier on..?  I don't think we should require
> > that someone troll through everything that ever existed, just to be
> > clear, as we can always add to this later if other things come up.  If
> > that's the expectation though, then someone needs to say so, in which
> > case I'll assume it's status quo unless/until someone steps up to do
> > that.
>
> Agreed.  I just wanted something that could scale going forward, and be
> easily identified as compatibility, so maybe one day we can remove them.
> However, if they are in a separate section, we might never do that.
Sure, seems like this approach addresses that.

If we have agreement from folks on this then I'll commit it and then
rework the change from default roles to predefined roles to use this
approach and then we can move forward with that too.

Thanks,

Stephen

doc-rename-cleanup.patch (14K) Download Attachment
signature.asc (836 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Add docs stub for recovery.conf

Craig Ringer-5

On Thu, 14 Jan 2021 at 03:44, Stephen Frost <[hidden email]> 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.

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.

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.

Your extended and revised patch retains the above style for

+   <indexterm>
+     <primary>trigger_file</primary>
+     <seealso>promote_trigger_file</seealso>
+    </indexterm>
...
+    <indexterm>
+     <primary>standby_mode</primary>
+     <seealso>standby.signal</seealso>
+    </indexterm>

so if you intend to change it, that entry needs changing too.


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.


Reply | Threaded
Open this post in threaded view
|

Re: Add docs stub for recovery.conf

Stephen Frost
Greetings,

* Craig Ringer ([hidden email]) wrote:
> On Thu, 14 Jan 2021 at 03:44, Stephen Frost <[hidden email]> 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?

Bruce, did you want to review or comment on this as to if it addresses
your concerns appropriately?  Would be great to get this in as there's
the follow-on for default roles.

Thanks!

Stephen

signature.asc (836 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Add docs stub for recovery.conf

Stephen Frost
Greetings,

* Stephen Frost ([hidden email]) wrote:

> * Craig Ringer ([hidden email]) wrote:
> > On Thu, 14 Jan 2021 at 03:44, Stephen Frost <[hidden email]> 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?
>
> Bruce, did you want to review or comment on this as to if it addresses
> your concerns appropriately?  Would be great to get this in as there's
> the follow-on for default roles.
... really attached now, sorry about that. :)

Thanks,

Stephen

doc-rename-cleanup_v2.patch (12K) Download Attachment
signature.asc (836 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Add docs stub for recovery.conf

Craig Ringer-5
On Wed, 20 Jan 2021 at 02:45, Stephen Frost <[hidden email]> wrote:
Greetings,

* Stephen Frost ([hidden email]) wrote:
> * Craig Ringer ([hidden email]) wrote:
> > On Thu, 14 Jan 2021 at 03:44, Stephen Frost <[hidden email]> 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.



v3-0001-Add-a-docs-section-for-obsoleted-and-renamed-func.patch (19K) Download Attachment
123