Re: Add docs stub for recovery.conf

Greetings,

* Craig Ringer (craig.ringer@enterprisedb.com) wrote:
> Pretty good to me. Thanks so much for your help and support with this.

Thanks for helping me move it forward!

> 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.

Nice, yes, that does look better.

> 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.

Awesome, attached is just a rebase (not that anything really changed).
Unless someone wants to speak up, I'll commit this soonish (hopefully
tomorrow, but at least sometime later this week).

Thanks!

Stephen