A pool is not a zpool. Avoid creating confusion around the command. <https://docs.freebsd.org/en/books/handbook/zfs/#zfs-zpool-create> > Creating a ZFS storage pool (zpool) … – should be: > Creating a pool … – and so on.
Please elaborate on why this is important.
It's simply wrong. zpool is a command. I recall (years ago, before I began using FreeBSD) when I first began learning about ZFS, it was sometimes horribly confusing where the word was misused to describe things other than the command. "the storage zpool"; "a zpool"; "grow the zpool"; "zpool administration"; these phrases are wrong. (It's as wrong as writing, for example, "grow the gpart".)
Just sticking my nose in here :-) Whilst debian refers to them as zpools ( https://wiki.ubuntu.com/ZFS/ZPool ), it seems they are wrong too - Oracle/Sun refer to them as pools: https://docs.oracle.com/cd/E19253-01/819-5461/gaynr/index.html as does openzfs: https://openzfs.github.io/openzfs-docs/man/8/zpool-import.8.html
Thanks, (In reply to Jamie Landeg-Jones from comment #3) There are numerous other examples. <https://github.com/openzfs/openzfs-docs/blob/master/docs/Project%20and%20Community/FAQ.rst> <https://openzfs.github.io/openzfs-docs/man/7/zpoolconcepts.7.html> … and so on; OpenZFS documentation is extraordinarily careful to not misuse the word zpool.
https://docs.freebsd.org/en/books/handbook/zfs/#zfs-zpool-create In section 20.3.1: "Creating a ZFS storage pool (zpool) requires permanent decisions, as the pool structure cannot change after creation." Should read: "Creating a ZFS storage pools requires permanent decisions, as the pool structure cannot change after creation." Is this a correct way to word the sentence?
Created attachment 233303 [details] zpool-wording-257405 https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=257405 This diff references the above bug - 3 changes.
Comment on attachment 233303 [details] zpool-wording-257405 >diff --git a/documentation/content/en/books/handbook/zfs/_index.adoc b/documentation/content/en/books/handbook/zfs/_index.adoc >index 3f9a2a457d..e290708091 100644 >--- a/documentation/content/en/books/handbook/zfs/_index.adoc >+++ b/documentation/content/en/books/handbook/zfs/_index.adoc >@@ -488,7 +488,7 @@ The <<zfs-zfs,`zfs`>> utility allows creating, destroying, and managing datasets > [[zfs-zpool-create]] > === Creating and Destroying Storage Pools > >-Creating a ZFS storage pool (_zpool_) requires permanent decisions, as the pool structure cannot change after creation. >+Creating a ZFS storage pools requires permanent decisions, as the pool structure cannot change after creation. s/pools/pool/ >@@ -1786,7 +1786,7 @@ mypool/var/tmp@my_recursive_snapshot 0 - 152K - > .... > > Snapshots are not shown by a normal `zfs list` operation. >-To list snapshots, append `-t snapshot` to `zfs list`. >+To list snapshots, append `-t snapshot` to `zfs list` I think the final "." should stay there.
Created attachment 233328 [details] changed pools to pool and added period Per suggestion, I have changed "pools" to "pool" as well as re-added the period.
(In reply to John Darrah from comment #8) LGTM now. Over to a committer for build testing.
A commit in branch main references this bug: URL: https://cgit.FreeBSD.org/doc/commit/?id=1fb34fa0530a7cd0554371f0b5c0b6bdf8a9507d commit 1fb34fa0530a7cd0554371f0b5c0b6bdf8a9507d Author: John Darrah <johntdarrah@gmail.com> AuthorDate: 2022-11-06 20:25:07 +0000 Commit: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> CommitDate: 2022-11-06 20:25:07 +0000 Fix misuse of the phrase zpool in ZFS chapter handbook PR: 257405 Reviewed by: grahamperrin@, pauamma@ documentation/content/en/books/handbook/zfs/_index.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
Fixed. Thanks for the patch!
(In reply to Sergio Carlavilla Delgado from comment #11) Ah, thanks! This was to be next on my list. A handful of occurrences have been overlooked (I find it difficult to work with diff files alone), I'll draft something then open a review in Phabricator.
Preview: <https://github.com/grahamperrin/freebsd-doc/blob/bug-257405/documentation/content/en/books/handbook/zfs/_index.adoc> (branch bug-257405 in my fork). A question at <https://github.com/grahamperrin/freebsd-doc/commit/4096c11de52689a342d810404d2a0afd61186d1d#r89145152>: > If tagged pool, then must we retain the zpool tag?
(In reply to John Darrah from comment #5) Try <https://github.com/grahamperrin/freebsd-doc/commit/cd9ce1ac3418e1e71a7d347f3bf1e49d601da95b>
Triage, batch edit (just one): * for twenty-eight FreeBSD Handbook-related reports that had gained a personal assignee, prior group/list assignee doc@ was missing from the CC list. Gentle hint: <https://wiki.freebsd.org/Bugzilla/> ▶ do, don't …