Page MenuHomeFreeBSD

Revise EXAMPLES section of mdconfig(8).
ClosedPublic

Authored by trasz on Jul 25 2015, 1:22 PM.

Details

Summary

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

Diff Detail

Repository
rS FreeBSD src repository - subversion
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

trasz retitled this revision from to Revise EXAMPLES section of mdconfig(8)..
trasz updated this object.
trasz edited the test plan for this revision. (Show Details)

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?

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 edited edge metadata.

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

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.

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 ↗(On Diff #7299)

See below, I think this should be:

.Nd configure and create memory disks

78 ↗(On Diff #7299)

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 ↗(On Diff #7299)

The original is kind of an idiomatic way of saying it in English, but this works also.

171 ↗(On Diff #7299)

Why remove these?

206 ↗(On Diff #7299)

The comma is not needed.

230 ↗(On Diff #7299)

Needs markup for the filename:

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

234 ↗(On Diff #7299)

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

237 ↗(On Diff #7299)

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 ↗(On Diff #7299)

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

259 ↗(On Diff #7299)

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

286 ↗(On Diff #7299)

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 ↗(On Diff #7299)

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 ↗(On Diff #7299)

Erm, but which one is better?

171 ↗(On Diff #7299)

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 ↗(On Diff #7299)

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 ↗(On Diff #7299)

They are about equal. "panic the system" is okay.

Fixes suggested by wblock@.

sbin/mdconfig/mdconfig.8
258 ↗(On Diff #7653)

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

trasz edited edge metadata.

"Current" sounds good.

wblock added a reviewer: wblock.

Remember to update .Dd. Thanks!

This revision is now accepted and ready to land.Aug 5 2015, 3:29 PM
This revision was automatically updated to reflect the committed changes.