pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedSplitting up release.sgml
8+ messages / 5 participants
[nested] [flat]
Commits from this thread:
2020-08-31 f6679e0b4b aa02d352b5 11d0ed6a05 851e0f07a1 0d447ba962 70e791f47e 1bb41c6ad7 docs: replace "stable storage" with "durable" in descriptions
* Splitting up release.sgml
@ 2009-04-25 19:28 Tom Lane <tgl@sss.pgh.pa.us>
2009-04-26 07:08 ` Re: Splitting up release.sgml Guillaume Lelarge <guillaume@lelarge.info>
2009-04-26 20:26 ` Re: Splitting up release.sgml Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 2 replies; 8+ messages in thread
From: Tom Lane @ 2009-04-25 19:28 UTC (permalink / raw)
To: pgsql-docs
(I'm sure this has come up before, but it hasn't got done for some
reason...)
I think it's time for $SUBJECT. release.sgml is growing at a rate
of several thousand lines per major release and several hundred for
each group of minor releases. It's getting to be a pain to edit,
and I don't even want to think about how large the underlying RCS
file must be. This clearly doesn't scale for the long term.
What I propose we do is:
Create a separate file for each major release branch, eg
release-8.3.sgml for the 8.3.x series. This will contain exactly
the <sect1> ... </sect1> material that is currently in release.sgml
for that branch.
It's probably not worth carrying out the above split back beyond 8.0.
I suggest throwing 7.4 and all prior branches into one file
release-old.sgml.
This will leave release.sgml containing just the chapter header
material and include directives for the release-xxx.sgml files.
In the future it will change only to add a new include line
when a new major branch is started.
I propose making this change in the active back branches, not only HEAD.
This will mean that the process for updating back-branch release notes
reduces to copying the appropriate release-xxx.sgml files into each
older branch; we won't need the major_release_split script, which is
rather dangerous because it doesn't understand that the header material
has to be different in the oldest branches. (In this scheme, the link
difference is still located in the release.sgml file, but that doesn't
change anymore in back branches so there's no risk of overwriting it.)
Thoughts?
regards, tom lane
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Splitting up release.sgml
2009-04-25 19:28 Splitting up release.sgml Tom Lane <tgl@sss.pgh.pa.us>
@ 2009-04-26 07:08 ` Guillaume Lelarge <guillaume@lelarge.info>
1 sibling, 0 replies; 8+ messages in thread
From: Guillaume Lelarge @ 2009-04-26 07:08 UTC (permalink / raw)
To: pgsql-docs; +Cc: Tom Lane <tgl@sss.pgh.pa.us>
Le samedi 25 avril 2009 à 21:28:46, Tom Lane a écrit :
> [...]
> What I propose we do is:
>
> Create a separate file for each major release branch, eg
> release-8.3.sgml for the 8.3.x series. This will contain exactly
> the <sect1> ... </sect1> material that is currently in release.sgml
> for that branch.
>
I completely agree. This huge file is also really painful for translators.
Splitting it will make the job easier.
> It's probably not worth carrying out the above split back beyond 8.0.
> I suggest throwing 7.4 and all prior branches into one file
> release-old.sgml.
>
I would have included 7.4 branch in this, but that's not really a big issue.
> This will leave release.sgml containing just the chapter header
> material and include directives for the release-xxx.sgml files.
> In the future it will change only to add a new include line
> when a new major branch is started.
>
> I propose making this change in the active back branches, not only HEAD.
> This will mean that the process for updating back-branch release notes
> reduces to copying the appropriate release-xxx.sgml files into each
> older branch; we won't need the major_release_split script, which is
> rather dangerous because it doesn't understand that the header material
> has to be different in the oldest branches. (In this scheme, the link
> difference is still located in the release.sgml file, but that doesn't
> change anymore in back branches so there's no risk of overwriting it.)
>
I'm also OK with this.
--
Guillaume.
http://www.postgresqlfr.org
http://dalibo.com
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Splitting up release.sgml
2009-04-25 19:28 Splitting up release.sgml Tom Lane <tgl@sss.pgh.pa.us>
@ 2009-04-26 20:26 ` Tom Lane <tgl@sss.pgh.pa.us>
1 sibling, 0 replies; 8+ messages in thread
From: Tom Lane @ 2009-04-26 20:26 UTC (permalink / raw)
To: pgsql-docs
I wrote:
> I think it's time for $SUBJECT.
I started to play with this and found out that there's one roadblock in
the way; it's doc/src/sgml/Makefile's method for building the plain-text
HISTORY file. That starts out with
# remove links to main documentation
HISTORY.html: release.sgml
( echo '<!doctype appendix PUBLIC "-//OASIS//DTD DocBook V4.2//EN">'; \
cat $< ) | \
$(PERL) -p -0 -e 's/<link\s+linkend[^>]*>//g' | \
$(PERL) -p -e 's/<\/link>//g' >tempfile_HISTORY.sgml
$(JADE.text) -V nochunks tempfile_HISTORY.sgml >$@
rm tempfile_HISTORY.sgml
which will not work to remove links from files that are included into
release.sgml. The best answer is probably to expand the inclusions
before the Perl processing, but I can't think of any reasonably simple
way to do that. Any ideas?
The Make dependency on release.sgml alone wouldn't be adequate either,
given that it won't change nearly as fast as the included files.
regards, tom lane
^ permalink raw reply [nested|flat] 8+ messages in thread
* "stable storage"
@ 2020-08-17 16:52 Bruce Momjian <bruce@momjian.us>
2020-08-21 22:12 ` Re: "stable storage" Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 8+ messages in thread
From: Bruce Momjian @ 2020-08-17 16:52 UTC (permalink / raw)
To: pgsql-docs
I know we talk about durability a lot, but it seems we mention "stable
storage" much more often than "durable storage" in our docs:
$ grep 'stable storage' *.sgml
config.sgml: necessarily reached stable storage on the standby.
monitoring.sgml: stable storage.</entry>
monitoring.sgml: to reach stable storage.</entry>
monitoring.sgml: <entry>Waiting for a relation data file to reach stable storage.</entry>
monitoring.sgml: stable storage.</entry>
monitoring.sgml: <entry>Waiting for changes to a relation data file to reach stable storage.</entry>
monitoring.sgml: <entry>Waiting for data to reach stable storage while adding a line to the
monitoring.sgml: <entry>Waiting for data to reach stable storage while creating the data
monitoring.sgml: <entry>Waiting for logical rewrite mappings to reach stable storage
monitoring.sgml: <entry>Waiting for mapping data to reach stable storage during a logical
monitoring.sgml: <entry>Waiting for the relation map file to reach stable storage.</entry>
monitoring.sgml: <entry>Waiting for a replication slot control file to reach stable storage
monitoring.sgml: <entry>Waiting for SLRU data to reach stable storage during a checkpoint
monitoring.sgml: <entry>Waiting for SLRU data to reach stable storage following a page
monitoring.sgml: stable storage.</entry>
monitoring.sgml: replication to reach stable storage.</entry>
monitoring.sgml: <entry>Waiting for a two phase state file to reach stable storage.</entry>
monitoring.sgml: <entry>Waiting for WAL to reach stable storage during
monitoring.sgml: reach stable storage.</entry>
monitoring.sgml: <entry>Waiting for a WAL file to reach stable storage.</entry>
monitoring.sgml: <entry>Waiting for data to reach stable storage while assigning a new
$ grep 'durable storage' *.sgml
config.sgml: kernel to durable storage. This can be done while the cluster
func.sgml: location known to be written to durable storage. The write location is the
Is "stable storage" the same as "durable storage"? Should we rename
"stable storage" mentions to "durable storage"?
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com
The usefulness of a cup is in its emptiness, Bruce Lee
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: "stable storage"
2020-08-17 16:52 "stable storage" Bruce Momjian <bruce@momjian.us>
@ 2020-08-21 22:12 ` Bruce Momjian <bruce@momjian.us>
2020-08-21 22:22 ` Re: "stable storage" Peter Geoghegan <pg@bowt.ie>
0 siblings, 1 reply; 8+ messages in thread
From: Bruce Momjian @ 2020-08-21 22:12 UTC (permalink / raw)
To: pgsql-docs
On Mon, Aug 17, 2020 at 12:52:22PM -0400, Bruce Momjian wrote:
> I know we talk about durability a lot, but it seems we mention "stable
> storage" much more often than "durable storage" in our docs:
...
> Is "stable storage" the same as "durable storage"? Should we rename
> "stable storage" mentions to "durable storage"?
I have developed the attached doc patch to change "stable storage" to
"durable storage".
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com
The usefulness of a cup is in its emptiness, Bruce Lee
Attachments:
stable.diff (text/x-diff, 9.7K) download
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 7a7177c550..218aa5ae04 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -2740,7 +2740,7 @@ include_dir 'conf.d'
ensure data preservation even if a standby instance of
<productname>PostgreSQL</productname> were to crash, but not if the standby
suffers an operating-system-level crash, since the data has not
- necessarily reached stable storage on the standby.
+ necessarily reached durable storage on the standby.
Finally, the setting <literal>local</literal> causes commits to wait for
local flush to disk, but not for replication. This is not usually
desirable when synchronous replication is in use, but is provided for
diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index 304c49f07b..cf3b80c1d7 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -1210,12 +1210,12 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
<row>
<entry><literal>ControlFileSync</literal></entry>
<entry>Waiting for the <filename>pg_control</filename> file to reach
- stable storage.</entry>
+ durable storage.</entry>
</row>
<row>
<entry><literal>ControlFileSyncUpdate</literal></entry>
<entry>Waiting for an update to the <filename>pg_control</filename> file
- to reach stable storage.</entry>
+ to reach durable storage.</entry>
</row>
<row>
<entry><literal>ControlFileWrite</literal></entry>
@@ -1246,12 +1246,12 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
</row>
<row>
<entry><literal>DataFileFlush</literal></entry>
- <entry>Waiting for a relation data file to reach stable storage.</entry>
+ <entry>Waiting for a relation data file to reach durable storage.</entry>
</row>
<row>
<entry><literal>DataFileImmediateSync</literal></entry>
<entry>Waiting for an immediate synchronization of a relation data file to
- stable storage.</entry>
+ durable storage.</entry>
</row>
<row>
<entry><literal>DataFilePrefetch</literal></entry>
@@ -1264,7 +1264,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
</row>
<row>
<entry><literal>DataFileSync</literal></entry>
- <entry>Waiting for changes to a relation data file to reach stable storage.</entry>
+ <entry>Waiting for changes to a relation data file to reach durable storage.</entry>
</row>
<row>
<entry><literal>DataFileTruncate</literal></entry>
@@ -1281,7 +1281,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
</row>
<row>
<entry><literal>LockFileAddToDataDirSync</literal></entry>
- <entry>Waiting for data to reach stable storage while adding a line to the
+ <entry>Waiting for data to reach durable storage while adding a line to the
data directory lock file.</entry>
</row>
<row>
@@ -1296,7 +1296,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
</row>
<row>
<entry><literal>LockFileCreateSync</literal></entry>
- <entry>Waiting for data to reach stable storage while creating the data
+ <entry>Waiting for data to reach durable storage while creating the data
directory lock file.</entry>
</row>
<row>
@@ -1311,12 +1311,12 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
</row>
<row>
<entry><literal>LogicalRewriteCheckpointSync</literal></entry>
- <entry>Waiting for logical rewrite mappings to reach stable storage
+ <entry>Waiting for logical rewrite mappings to reach durable storage
during a checkpoint.</entry>
</row>
<row>
<entry><literal>LogicalRewriteMappingSync</literal></entry>
- <entry>Waiting for mapping data to reach stable storage during a logical
+ <entry>Waiting for mapping data to reach durable storage during a logical
rewrite.</entry>
</row>
<row>
@@ -1326,7 +1326,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
</row>
<row>
<entry><literal>LogicalRewriteSync</literal></entry>
- <entry>Waiting for logical rewrite mappings to reach stable
+ <entry>Waiting for logical rewrite mappings to reach durable
storage.</entry>
</row>
<row>
@@ -1344,7 +1344,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
</row>
<row>
<entry><literal>RelationMapSync</literal></entry>
- <entry>Waiting for the relation map file to reach stable storage.</entry>
+ <entry>Waiting for the relation map file to reach durable storage.</entry>
</row>
<row>
<entry><literal>RelationMapWrite</literal></entry>
@@ -1369,12 +1369,12 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
</row>
<row>
<entry><literal>ReplicationSlotRestoreSync</literal></entry>
- <entry>Waiting for a replication slot control file to reach stable storage
+ <entry>Waiting for a replication slot control file to reach durable storage
while restoring it to memory.</entry>
</row>
<row>
<entry><literal>ReplicationSlotSync</literal></entry>
- <entry>Waiting for a replication slot control file to reach stable
+ <entry>Waiting for a replication slot control file to reach durable
storage.</entry>
</row>
<row>
@@ -1383,7 +1383,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
</row>
<row>
<entry><literal>SLRUFlushSync</literal></entry>
- <entry>Waiting for SLRU data to reach stable storage during a checkpoint
+ <entry>Waiting for SLRU data to reach durable storage during a checkpoint
or database shutdown.</entry>
</row>
<row>
@@ -1392,7 +1392,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
</row>
<row>
<entry><literal>SLRUSync</literal></entry>
- <entry>Waiting for SLRU data to reach stable storage following a page
+ <entry>Waiting for SLRU data to reach durable storage following a page
write.</entry>
</row>
<row>
@@ -1407,7 +1407,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
<row>
<entry><literal>SnapbuildSync</literal></entry>
<entry>Waiting for a serialized historical catalog snapshot to reach
- stable storage.</entry>
+ durable storage.</entry>
</row>
<row>
<entry><literal>SnapbuildWrite</literal></entry>
@@ -1417,7 +1417,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
<row>
<entry><literal>TimelineHistoryFileSync</literal></entry>
<entry>Waiting for a timeline history file received via streaming
- replication to reach stable storage.</entry>
+ replication to reach durable storage.</entry>
</row>
<row>
<entry><literal>TimelineHistoryFileWrite</literal></entry>
@@ -1430,7 +1430,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
</row>
<row>
<entry><literal>TimelineHistorySync</literal></entry>
- <entry>Waiting for a newly created timeline history file to reach stable
+ <entry>Waiting for a newly created timeline history file to reach durable
storage.</entry>
</row>
<row>
@@ -1444,7 +1444,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
</row>
<row>
<entry><literal>TwophaseFileSync</literal></entry>
- <entry>Waiting for a two phase state file to reach stable storage.</entry>
+ <entry>Waiting for a two phase state file to reach durable storage.</entry>
</row>
<row>
<entry><literal>TwophaseFileWrite</literal></entry>
@@ -1452,7 +1452,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
</row>
<row>
<entry><literal>WALBootstrapSync</literal></entry>
- <entry>Waiting for WAL to reach stable storage during
+ <entry>Waiting for WAL to reach durable storage during
bootstrapping.</entry>
</row>
<row>
@@ -1467,7 +1467,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
<row>
<entry><literal>WALCopySync</literal></entry>
<entry>Waiting for a new WAL segment created by copying an existing one to
- reach stable storage.</entry>
+ reach durable storage.</entry>
</row>
<row>
<entry><literal>WALCopyWrite</literal></entry>
@@ -1476,7 +1476,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
</row>
<row>
<entry><literal>WALInitSync</literal></entry>
- <entry>Waiting for a newly initialized WAL file to reach stable
+ <entry>Waiting for a newly initialized WAL file to reach durable
storage.</entry>
</row>
<row>
@@ -1494,11 +1494,11 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser
</row>
<row>
<entry><literal>WALSync</literal></entry>
- <entry>Waiting for a WAL file to reach stable storage.</entry>
+ <entry>Waiting for a WAL file to reach durable storage.</entry>
</row>
<row>
<entry><literal>WALSyncMethodAssign</literal></entry>
- <entry>Waiting for data to reach stable storage while assigning a new
+ <entry>Waiting for data to reach durable storage while assigning a new
WAL sync method.</entry>
</row>
<row>
* Re: "stable storage"
2020-08-17 16:52 "stable storage" Bruce Momjian <bruce@momjian.us>
2020-08-21 22:12 ` Re: "stable storage" Bruce Momjian <bruce@momjian.us>
@ 2020-08-21 22:22 ` Peter Geoghegan <pg@bowt.ie>
2020-08-22 03:44 ` Re: "stable storage" Stephen Frost <sfrost@snowman.net>
0 siblings, 1 reply; 8+ messages in thread
From: Peter Geoghegan @ 2020-08-21 22:22 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: pgsql-docs
On Fri, Aug 21, 2020 at 3:12 PM Bruce Momjian <bruce@momjian.us> wrote:
> > Is "stable storage" the same as "durable storage"? Should we rename
> > "stable storage" mentions to "durable storage"?
>
> I have developed the attached doc patch to change "stable storage" to
> "durable storage".
I agree that this is an improvement. The word "durable" is more
descriptive than "stable". (The word "stable" might be more
recognizable, but that in itself doesn't make the text any clearer.)
--
Peter Geoghegan
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: "stable storage"
2020-08-17 16:52 "stable storage" Bruce Momjian <bruce@momjian.us>
2020-08-21 22:12 ` Re: "stable storage" Bruce Momjian <bruce@momjian.us>
2020-08-21 22:22 ` Re: "stable storage" Peter Geoghegan <pg@bowt.ie>
@ 2020-08-22 03:44 ` Stephen Frost <sfrost@snowman.net>
2020-08-31 19:23 ` Re: "stable storage" Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 8+ messages in thread
From: Stephen Frost @ 2020-08-22 03:44 UTC (permalink / raw)
To: Peter Geoghegan <pg@bowt.ie>; +Cc: Bruce Momjian <bruce@momjian.us>; pgsql-docs
Greetings,
* Peter Geoghegan (pg@bowt.ie) wrote:
> On Fri, Aug 21, 2020 at 3:12 PM Bruce Momjian <bruce@momjian.us> wrote:
> > > Is "stable storage" the same as "durable storage"? Should we rename
> > > "stable storage" mentions to "durable storage"?
> >
> > I have developed the attached doc patch to change "stable storage" to
> > "durable storage".
>
> I agree that this is an improvement. The word "durable" is more
> descriptive than "stable". (The word "stable" might be more
> recognizable, but that in itself doesn't make the text any clearer.)
+1.
Thanks,
Stephen
Attachments:
signature.asc (application/pgp-signature, 818B) download
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: "stable storage"
2020-08-17 16:52 "stable storage" Bruce Momjian <bruce@momjian.us>
2020-08-21 22:12 ` Re: "stable storage" Bruce Momjian <bruce@momjian.us>
2020-08-21 22:22 ` Re: "stable storage" Peter Geoghegan <pg@bowt.ie>
2020-08-22 03:44 ` Re: "stable storage" Stephen Frost <sfrost@snowman.net>
@ 2020-08-31 19:23 ` Bruce Momjian <bruce@momjian.us>
0 siblings, 0 replies; 8+ messages in thread
From: Bruce Momjian @ 2020-08-31 19:23 UTC (permalink / raw)
To: Stephen Frost <sfrost@snowman.net>; +Cc: Peter Geoghegan <pg@bowt.ie>; pgsql-docs
On Fri, Aug 21, 2020 at 11:44:44PM -0400, Stephen Frost wrote:
> Greetings,
>
> * Peter Geoghegan (pg@bowt.ie) wrote:
> > On Fri, Aug 21, 2020 at 3:12 PM Bruce Momjian <bruce@momjian.us> wrote:
> > > > Is "stable storage" the same as "durable storage"? Should we rename
> > > > "stable storage" mentions to "durable storage"?
> > >
> > > I have developed the attached doc patch to change "stable storage" to
> > > "durable storage".
> >
> > I agree that this is an improvement. The word "durable" is more
> > descriptive than "stable". (The word "stable" might be more
> > recognizable, but that in itself doesn't make the text any clearer.)
>
> +1.
>
> Thanks,
Applied.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com
The usefulness of a cup is in its emptiness, Bruce Lee
^ permalink raw reply [nested|flat] 8+ messages in thread
end of thread, other threads:[~2020-08-31 19:23 UTC | newest]
Thread overview: 8+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2009-04-25 19:28 Splitting up release.sgml Tom Lane <tgl@sss.pgh.pa.us>
2009-04-26 07:08 ` Guillaume Lelarge <guillaume@lelarge.info>
2009-04-26 20:26 ` Tom Lane <tgl@sss.pgh.pa.us>
2020-08-17 16:52 "stable storage" Bruce Momjian <bruce@momjian.us>
2020-08-21 22:12 ` Re: "stable storage" Bruce Momjian <bruce@momjian.us>
2020-08-21 22:22 ` Re: "stable storage" Peter Geoghegan <pg@bowt.ie>
2020-08-22 03:44 ` Re: "stable storage" Stephen Frost <sfrost@snowman.net>
2020-08-31 19:23 ` Re: "stable storage" Bruce Momjian <bruce@momjian.us>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox