Revise EXAMPLES section of mdconfig(8). This removes stuff that doesn't
really belong there, and simplifies examples for the basic operations.
Details
Details
- Reviewers
wblock - Group Reviewers
manpages - Commits
- rS286360: Tweak mdconfig(8) manual page, in particular revise the EXAMPLES
Diff Detail
Diff Detail
- Repository
- rS FreeBSD src repository - subversion
- Lint
Lint Passed - Unit
No Test Coverage
Event Timeline
Comment Actions
Where else can a user see or find these examples? None of them are exactly obvious, and I'm fairly sure that the last one is not documented anywhere else (having added it myself).
Why not just add the new examples?
Comment Actions
I've removed four examples. First one, the one with newfs/mount/chmod, was removed, because it doesn't really belong there - its only connection with md(4) is that it's possible to use it with any GEOM provider, including md(4). One could as well add it to ada(4) manual page, and it would make as little sense as it does here.
Second one - with dd and bsdlabel - is similar. It's a general administration stuff; it pretty much duplicates https://www.freebsd.org/doc/handbook/disks-adding.html, except it's worse.
Third one - with mount_cd9660 - same.
As for the gnop one - it could belong to gnop(8) manual page. That said... For me, the EXAMPLES section is for quickly looking up common stuff, it's supposed to be short and clear. The existing one is anything but - it shows some rarely-used scenarios, and the ones that are commonly used are shown in a clunky, overly verbose way.
Comment Actions
Don't remove examples that might actually be useful (remove one
redundant, though) and fix some other nits.
Comment Actions
Second one - with dd and bsdlabel - is similar. It's a general administration stuff; it pretty much duplicates https://www.freebsd.org/doc/handbook/disks-adding.html, except it's worse.
Third one - with mount_cd9660 - same.
I cut-and-paste that one all the time, rather than try to remember the options and combinations.
As for the gnop one - it could belong to gnop(8) manual page.
The problem is that gnop(8) is counterintuitive to this. When I needed to skip over a header while mounting a disk image, gnop(8) did not even occur to me. It's supposed to be a nop, as in the name.
That said... For me, the EXAMPLES section is for quickly looking up common stuff, it's supposed to be short and clear. The existing one is anything but - it shows some rarely-used scenarios, and the ones that are commonly used are shown in a clunky, overly verbose way.
I can agree with that somewhat, but think there is room for a range of examples that show the different capabilities and also document some of the problems that can be solved with these utilities. Without the iso9660 example, it takes some looking. Without the gnop example, there is nothing suggesting the use of gnop with md.
Sorting examples in order of simple to complex is reasonable, which is kind of how this is. But we aren't short on space, and as long as the examples are clear and do not detract from the rest of the page, removing them does not seem to be an improvement. I'm all for improving clarity in these examples, though.
Comment Actions
Not sure if you've noticed, but I've submitted a diff addressing your comments at about the exact same moment you wrote them. :-)
| sbin/mdconfig/mdconfig.8 | ||
|---|---|---|
| 45 | See below, I think this should be: .Nd configure and create memory disks | |
| 78 | This can be just: utility configures But I think the original wording was trying to say that this program does not just configure memory disks, but creates them: utility configures and creates | |
| 106 | The original is kind of an idiomatic way of saying it in English, but this works also. | |
| 171 | Why remove these? | |
| 213 | The comma is not needed. | |
| 236–237 | Needs markup for the filename: Create a disk with | |
| 236–237 | All of these examples should probably be consistent, using .Bd/.Ed instead of .Dl | |
| 240 | I'm not sure about .Cm (command modifier) as markup for swap. Probably it is fine without markup at all, since "swap" is not a special word. | |
| 257 | "currently configured" is potentially ambiguous. "existing" might be better. | |
| 273 | Same as above, markup is probably not needed on "swap". | |
| 296 | Rearranging the arguments to use the implied -f kind of makes it look like the filename is expected as the last argument to mdconfig, which does not agree with the synopsis. It does no real harm to leave the -f, as examples are often more strict and more explicit than real-life usage because that provides the reader with more information. Same thing on the cdimage example. | |
| sbin/mdconfig/mdconfig.8 | ||
|---|---|---|
| 78 | Well, actually, it creates and destroys them, the only non-destructive thing it can do with an existing memory disk is resizing. But I kind of thought "configure" includes creation and destruction. Doesn't it? If not - how about "utility creates, destroys, and configures"? | |
| 106 | Erm, but which one is better? | |
| 171 | I thought it was a copy-paste error, but now I've read this again, it's ok, but unclear. What this should be saying, is something like this: "When used without the -r option, the -a and -t swap options are implied if not specified". Which means, they will be implied when used like this: mdconfig -s1g which translates to "mdconfig -a -t swap -s 1g", but not when used like this: mdconfig -rs1g | |
| sbin/mdconfig/mdconfig.8 | ||
|---|---|---|
| 78 | Trying to think of a less redundant way to say this. How about "creates and controls"? The point of this sentence is to communicate that this one command is the one that does everything needed for md devices. "Destroys" is just a negative form of creation, if want to look at it like that. | |
| 106 | They are about equal. "panic the system" is okay. | |
| sbin/mdconfig/mdconfig.8 | ||
|---|---|---|
| 258 | This looks like the only comment not done. "Existing" is not great, "extant" is too obscure. How about just "current memory disks"? | |