pgsql: Move documentation of all recovery.conf option to a new chapter.
in [PgSql]
|
From: Fujii Masao on 23 Feb 2010 23:58 On Wed, Feb 24, 2010 at 8:24 AM, Simon Riggs <simon(a)2ndquadrant.com> wrote: > On Mon, 2010-02-22 at 11:47 +0000, Heikki Linnakangas wrote: >> Log Message: >> ----------- >> Move documentation of all recovery.conf option to a new chapter. >> They used to be scattered between the "backup and restore" and "streaming >> replication" chapters. > > It's just taken me 15 minutes to locate the settings for > primary_conninfo to better understand Stefan's recent post. We would need to expose recovery configuration parameters as indexterm, as well as GUC. > The commit referred to here is an extremely bad change. > > If you intended this to be a heading within the "High Availability" > chapter then I would agree. This is what I thought you had done. > > Having Streaming Rep described in HA and then describing the parameters > that make it work in a separate chapter is ridiculous. Plus, wherever > they are, they need cross references between them. > > This is the last straw for me. The Streaming Rep docs are now truly > appalling. They were thin before, but tieing them in knots and splitting > them into disconnected pieces is just too much. If I can't find the damn > things, we've gone too far. > > SR is a big feature and deserves proper docs. Yeah, we need to improve the SR document. So I began modifying it in my git repository. * git://git.postgresql.org/git/users/fujii/postgres.git * branch: replication-doc Regards, -- Fujii Masao NIPPON TELEGRAPH AND TELEPHONE CORPORATION NTT Open Source Software Center -- Sent via pgsql-hackers mailing list (pgsql-hackers(a)postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
From: Robert Haas on 24 Feb 2010 03:11 On Wed, Feb 24, 2010 at 2:31 AM, Simon Riggs <simon(a)2ndquadrant.com> wrote: > On Wed, 2010-02-24 at 08:30 +0200, Heikki Linnakangas wrote: >> Simon Riggs wrote: >> > On Mon, 2010-02-22 at 11:47 +0000, Heikki Linnakangas wrote: >> >> Log Message: >> >> ----------- >> >> Move documentation of all recovery.conf option to a new chapter. >> >> They used to be scattered between the "backup and restore" and "streaming >> >> replication" chapters. >> > >> > It's just taken me 15 minutes to locate the settings for >> > primary_conninfo to better understand Stefan's recent post. >> > >> > The commit referred to here is an extremely bad change. >> > >> > If you intended this to be a heading within the "High Availability" >> > chapter then I would agree. This is what I thought you had done. >> >> The idea was to have one chapter that describes all the options in >> recovery.conf. Some of them are specific to streaming replication >> (primary_conninfo), some are specific to PITR (recovery_target_*), some >> are common (restore_command, restore_end_command). We need a reference >> page to list them all. > > We need a section, not a new chapter, if at all. A chapter on its own > for this makes no sense at all. The new section should either be in the > Backup, HA or Server Config chapters. > > Please revert the change to create a new chapter. Just to mention it, this change was discussed and apparently agreed to 5 days ago on hackers. That's not to say that it necessarily shouldn't be reverted, but I think that will take some discussion (and more than 1 vote). Looking at it, I think I do agree that this shouldn't be a whole chapter by itself. It's not nearly as high-level a concept as the chapters that surround it. But I do think it's good to list all the recovery.conf settings in one central place. The server config chapter looks like the best fit to me on first glance, but I wonder what others think? ....Robert -- Sent via pgsql-hackers mailing list (pgsql-hackers(a)postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
From: Simon Riggs on 24 Feb 2010 03:26 On Wed, 2010-02-24 at 03:11 -0500, Robert Haas wrote: > But I do think it's good to list all the > recovery.conf settings in one central place. That part is fine, as long as we have links to it from necessary places. The reason why these docs must be within a related chapter is that it then shows up on the chapter TOC, allowing you to quickly answer the "where were the docs for that?" question. If you go back up to the main TOC there are way too many other chapters to be able to see which one you should go to, even if you are used to the manual. -- Simon Riggs www.2ndQuadrant.com -- Sent via pgsql-hackers mailing list (pgsql-hackers(a)postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
From: Fujii Masao on 24 Feb 2010 04:59 On Wed, Feb 24, 2010 at 5:11 PM, Robert Haas <robertmhaas(a)gmail.com> wrote: > Looking at it, I think I do agree that this shouldn't be a whole > chapter by itself. It's not nearly as high-level a concept as the > chapters that surround it. But I do think it's good to list all the > recovery.conf settings in one central place. The server config > chapter looks like the best fit to me on first glance, but I wonder > what others think? Umm... how about the following layout (just merge the server config and the recovery config)? Since the way to specify a parameter is different from postgresql.conf and recovery.conf, the section "Server Parameters" would be required in both. 18. Server Configuration 18.1. Server Parameters 18.1.1. Setting Parameters 18.1.2. File Locations 18.1.3. Connections and Authentication <snip> 18.1.16. Short Options 18.2. Recovery Parameters 18.2.1. Setting Parameters 18.2.2. Archive Recovery 18.2.3. Recovery Target 18.2.4. Standby Server Regards, -- Fujii Masao NIPPON TELEGRAPH AND TELEPHONE CORPORATION NTT Open Source Software Center -- Sent via pgsql-hackers mailing list (pgsql-hackers(a)postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
From: Simon Riggs on 24 Feb 2010 12:52 On Wed, 2010-02-24 at 18:59 +0900, Fujii Masao wrote: > On Wed, Feb 24, 2010 at 5:11 PM, Robert Haas <robertmhaas(a)gmail.com> wrote: > > Looking at it, I think I do agree that this shouldn't be a whole > > chapter by itself. It's not nearly as high-level a concept as the > > chapters that surround it. But I do think it's good to list all the > > recovery.conf settings in one central place. The server config > > chapter looks like the best fit to me on first glance, but I wonder > > what others think? > > Umm... how about the following layout (just merge the server config and > the recovery config)? Since the way to specify a parameter is different > from postgresql.conf and recovery.conf, the section "Server Parameters" > would be required in both. > > 18. Server Configuration > 18.1. Server Parameters > 18.1.1. Setting Parameters > 18.1.2. File Locations > 18.1.3. Connections and Authentication > <snip> > 18.1.16. Short Options > 18.2. Recovery Parameters > 18.2.1. Setting Parameters > 18.2.2. Archive Recovery > 18.2.3. Recovery Target > 18.2.4. Standby Server That would be OK too, but you'd need to add lots and lots of links to ensure that each mention of the parameter goes to the definition. -- Simon Riggs www.2ndQuadrant.com -- Sent via pgsql-hackers mailing list (pgsql-hackers(a)postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
|
Next
|
Last
Pages: 1 2 Prev: [PATCH] backend: compare word-at-a-time in bcTruelen Next: [HACKERS] Alpha4 Available Now |