Revise EXAMPLES section of mdconfig(8).

[trasz]

Summary

Revise EXAMPLES section of mdconfig(8). This removes stuff that doesn't
really belong there, and simplifies examples for the basic operations.

[wblock]

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?

[trasz]

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.

[trasz]

See https://reviews.freebsd.org/D3199.

[trasz]

Don't remove examples that might actually be useful (remove one
redundant, though) and fix some other nits.

[wblock]

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.

[trasz]

Not sure if you've noticed, but I've submitted a diff addressing your comments at about the exact same moment you wrote them. :-)

[wblock]

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?

211

The comma is not needed.

230

Needs markup for the filename:

Create a disk with
.Pa /tmp/boot.flp
as backing storage.

234

All of these examples should probably be consistent, using .Bd/.Ed instead of .Dl

237

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.

248

"currently configured" is potentially ambiguous. "existing" might be better.

250

Same as above, markup is probably not needed on "swap".

252–253

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.

[trasz]

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

[trasz]

Ping?

[wblock]

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.

[trasz]

Fixes suggested by wblock@.

[wblock]

sbin/mdconfig/mdconfig.8

249

This looks like the only comment not done. "Existing" is not great, "extant" is too obscure. How about just "current memory disks"?

[trasz]

"Current" sounds good.

[wblock]

Remember to update .Dd. Thanks!