polishing up mdadm manpages: mdassemble(8), mdmon(8)

polishing up mdadm manpages: mdassemble(8), mdmon(8)

am 08.03.2011 04:08:11 von Christoph Anton Mitterer

--=_785ecf8bce91d5df913e7d10e93600dd
Content-Transfer-Encoding: 8bit
Content-Type: text/plain; charset=UTF-8

Hi.

Recently I've started to read into MD/mdadm and what started then as
maintaining a quilt patch with several typos and so ended up in a somewhat
"bigger" rework.

- The text iself is (hopefully) largely the same, perhaps apart from some
wording, or ordering.
- More consistent usage of markup:
-bold for programs, options, files, manpage references (except in the
SEE ALSO section) and text the is somehow set or "entered"
-italitcs (which is typically displayed as underlined) for any
non-terminals.
- Consistent writing of words like Linux, RAID, program names (which were
previously off mixed) apart from those places where they're options (e.g.
raid1 is still raid1 and not RAID1 for the --level option).
- Completely rewritten the formatting of the manpage (the dozens of .B, .I
.... just to format one word made the source file really unreadable IMHO).

In mdmon(8) there were some places where changed things that could
possibly changing the semantics:
- mdadm --remove => mdadm --remove CONTAINER
DEVICE
- with a metadata version string "external:" => with a
metadata format string "external:format"
- .pid and .sock files => PID and socket files

I wasn't sure about the following so didn't change it:
- /state - faulty
Is a non-terminal for a device (and thus should I replace it with
an italics "device"?
- (for example, the metadata version has been set to "external:-dev/md127"
instead of "external:/dev/md127")
Is the "version" correct here?


I've also started to rewrite md(4), mdadm(8) and mdadm.conf(5) manpges...
- unifying many further writings of words like "read-only/readonly",
"read-write/readwrite", etc. pp.
- etc.
but I'm not sure if/when I can finish them.


Sorry for not sending a (easily reviewable) patch, but there were so many
changes (in the line wrapping and so), that this did not make much sense.
Please tell me whether you like and will apply it, so that I can continue
with the remaining manpages.
Anyway, if you merge them, please _really_ read them again for
mistakes/typos I might have accidentally added...!


Thanks,
Chris.
--=_785ecf8bce91d5df913e7d10e93600dd
Content-Transfer-Encoding: base64
Content-Type: application/octet-stream; charset=UTF-8;
name=mdassemble.8;
Content-Disposition: attachment;
filename=mdassemble.8;

LlRIIE1EQVNTRU1CTEUgOCAiIiB2My4yCgoKCgouU0ggTkFNRQptZGFzc2Vt YmxlIFwtIGFzc2Vt
YmxlIE1EIGRldmljZXMKCgouU0ggU1lOT1BTSVMKXGZCbWRhc3NlbWJsZVxm UgoKCi5TSCBERVND
UklQVElPTiAKXGZCbWRhc3NlbWJsZVxmUiBpcyBhIHRpbnkgcHJvZ3JhbSB0 aGF0IGNhbiBiZSB1
c2VkIHRvIGFzc2VtYmxlIE1EIGRldmljZXMKaW5zaWRlIGFuIGluaXRpYWwg cmFtZGlzayAoaW5p
dHJkKSBvciBhbiBpbml0cmFtZnMuCi5icgpJdCBpcyBtZWFudCB0byByZXBs YWNlIHRoZSBpbi1r
ZXJuZWwgYXV0b21hdGljIFJBSUQgZGV0ZWN0aW9uIGFuZCBhY3RpdmF0aW9u LgouUApJdCBjYW4g
YmUgYnVpbHQgc3RhdGljYWxseSBhbmQgbGlua2VkIGFnYWluc3QgbGlnaHR3 ZWlnaHQgbGliYyBp
bXBsZW1lbnRhdGlvbnMKbGlrZSBcZkJrbGliY1xmUiwgXGZCdUNsaWJjXGZS IG9yIFxmQmRpZXRs
aWJjXGZSLgoKCi5TSCBVU0FHRQpJbnZva2luZyBcZkJtZGFzc2VtYmxlXGZS IGhhcyB0aGUgc2Ft
ZSBlZmZlY3QgYXMgaW52b2tpbmcgXGZCbWRhZG0gXC1cLWFzc2VtYmxlClwt XC1zY2FuXGZSLgou
UApJbnZva2luZyBcZkJtZGFzc2VtYmxlXGZSIGEgc2Vjb25kIHRpbWUgd2ls bCBtYXJrIGFsbCBk
ZWZpbmVkIGFycmF5cyBhcwoicmVhZC13cml0ZSIuCi5icgpUaGlzIGlzIHVz ZWZ1bCB3aGVuIHVz
aW5nIHRoZSBcZkJzdGFydF9yb1xmUiBwYXJhbWV0ZXIgdG8gdGhlIFxmQm1k X21vZFxmUgprZXJu
ZWwgbW9kdWxlLgoKCi5TSCBPUFRJT05TClRoZXJlIGFyZSBubyBvcHRpb25z IHRvIFxmQm1kYXNz
ZW1ibGVcZlIuCgoKLlNIIEZJTEVTCi5TUyAvZXRjL21kYWRtLmNvbmYKVGhp cyBmaWxlIGxpc3Rz
IHRoZSBkZXZpY2VzIHdoaWNoIG1heSBiZSBzY2FubmVkIHRvIHNlZSBpZiB0 aGV5IGNvbnRhaW4g
TUQKc3VwZXJibG9ja3MgYW5kIGdpdmVzIGlkZW50aWZ5aW5nIGluZm9ybWF0 aW9uIChlLmcuIGFu
IFVVSUQpIGFib3V0IGtub3duIE1ECmFycmF5cy4KLlAKXGZCbWRhc3NlbWJs ZVxmUiBzdXBwb3J0
cyBhbGwgY29uZmlndXJhdGlvbiBwYXJhbWV0ZXJzIGRlZmluZWQgaW4KXGZC bWRhZG0uY29uZlxm
UiB3aXRoIHRoZSBleGNlcHRpb24gb2YgdGhlIFxmQmF1dG89XGZSIHRhZyB3 aGljaCBpcyBvbmx5
CnN1cHBvcnRlZCBpZiBcZkJtZGFkbVxmUiB3YXMgYnVpbHQgd2l0aCBcZkJN REFTU0VNQkxFX0FV
VE9cZlIgYmVpbmcgZGVmaW5lZC4KLlAKU2VlIHRoZSBcZkJtZGFkbS5jb25m XGZSKDUpIG1hbnBh
Z2UgZm9yIG1vcmUgZGV0YWlscy4KCgouU0ggU0VFIEFMU08KbWRhZG0oOCks Cm1kYWRtLmNvbmYo
NSksCm1kKDQpLgo=
--=_785ecf8bce91d5df913e7d10e93600dd
Content-Transfer-Encoding: base64
Content-Type: application/octet-stream; charset=UTF-8;
name=mdmon.8;
Content-Disposition: attachment;
filename=mdmon.8;

LlRIIE1ETU9OIDggIiIgdjMuMgoKCgoKLlNIIE5BTUUKbWRtb24gXC0gbW9u aXRvciBNRCBleHRl
cm5hbCBtZXRhZGF0YSBhcnJheXMKCgouU0ggU1lOT1BTSVMKXGZCbWRtb24g XGZJW1xmQi0tYWxs
XGZJXSBbXGZCLS10YWtlb3ZlclxmSV0gQ09OVEFJTkVSXGZSCgoKLlNIIE9W RVJWSUVXCkxpbnV4
IDIuNi4yNyBicmluZ3MgdGhlIGFiaWxpdHkgdG8gc3VwcG9ydCBleHRlcm5h bCBtZXRhZGF0YSBh
cnJheXMuICBFeHRlcm5hbAptZXRhZGF0YSBpbXBsaWVzIHRoYXQgdGhlIHVz ZXItc3BhY2UgaGFu
ZGxlcyBhbGwgdXBkYXRlcyB0byB0aGUgbWV0YWRhdGEuCi5QClRoZSBrZXJu ZWwncyByZXNwb25z
aWJpbGl0eSBpcyB0byBub3RpZnkgdGhlIHVzZXItc3BhY2Ugd2hlbiBhICJt ZXRhZGF0YSBldmVu
dCIKKGxpa2UgZGlzayBmYWlsdXJlcyBhbmQgY2xlYW4tdG8tZGlydHkgdHJh bnNpdGlvbnMpIG9j
Y3Vycy4KLmJyCkluIGltcG9ydGFudCBjYXNlcyB0aGUga2VybmVsIHdhaXRz IGZvciB0aGUgdXNl
ci1zcGFjZSB0byB0YWtlIGFjdGlvbiBvbiB0aGVzZQpub3RpZmljYXRpb25z LgoKCi5TSCBERVND
UklQVElPTgouU1MgTWV0YWRhdGEgdXBkYXRlczoKVG8gc2VydmUgbWV0YWRh dGEgdXBkYXRlIHJl
cXVlc3RzIGEgZGFlbW9uIChcZkJtZG1vblxmUikgaXMgaW50cm9kdWNlZC4K XGZCbWRtb25cZlIg
aXMgdGFza2VkIHdpdGggcG9sbGluZyB0aGUgc3lzZnMgbmFtZXNwYWNlLCBs b29raW5nIGZvciBj
aGFuZ2VzIGluClxmQmFycmF5X3N0YXRlXGZSLCBcZkJzeW5jX2FjdGlvblxm UiwgYW5kIHBlci1k
ZXZpY2UgXGZCc3RhdGVcZlIgYXR0cmlidXRlcy4KV2hlbiBhIGNoYW5nZSBp cyBkZXRlY3RlZCBp
dCBjYWxscyBhIHBlci1tZXRhZGF0YSB0eXBlIGhhbmRsZXIgdG8gbWFrZQpt b2RpZmljYXRpb25z
IHRvIHRoZSBtZXRhZGF0YS4KLlAKVGhlIGZvbGxvd2luZyBhY3Rpb25zIGFy ZSB0YWtlbjoKLlJT
Ci5UUAouQiBhcnJheV9zdGF0ZSBcLSBpbmFjdGl2ZQpDbGVhciB0aGUgZGly dHkgYml0IGZvciB0
aGUgdm9sdW1lIGFuZCBsZXQgdGhlIGFycmF5IGJlIHN0b3BwZWQuCi5UUAou QiBhcnJheV9zdGF0
ZSBcLSB3cml0ZSBwZW5kaW5nClNldCB0aGUgZGlydHkgYml0IGZvciB0aGUg YXJyYXkgYW5kIHRo
ZW4gc2V0IFxmQmFycmF5X3N0YXRlXGZSIHRvIFxmQmFjdGl2ZVxmUi4KV3Jp dGVzIGFyZSBibG9j
a2VkIHVudGlsIHRoZSB1c2VyLXNwYWNlIHdyaXRlcyBcZkJhY3RpdmVcZlIu Ci5UUAouQiBhcnJh
eV9zdGF0ZSBcLSBhY3RpdmVcLWlkbGUKVGhlIHNhZmUgbW9kZSB0aW1lciBo YXMgZXhwaXJlZCBz
byBzZXQgYXJyYXkgc3RhdGUgdG8gY2xlYW4gdG8gYmxvY2sgd3JpdGVzIHRv CnRoZSBhcnJheS4K
LlRQCi5CIGFycmF5X3N0YXRlIFwtIGNsZWFuCkNsZWFyIHRoZSBkaXJ0eSBi aXQgZm9yIHRoZSB2
b2x1bWUuCi5UUAouQiBhcnJheV9zdGF0ZSBcLSByZWFkXC1vbmx5ClRoaXMg aXMgdGhlIGluaXRp
YWwgc3RhdGUgdGhhdCBhbGwgYXJyYXlzIHN0YXJ0IGF0LgouUlMKLlRQClxm Qm1kbW9uXGZSIHRh
a2VzIG9uZSBvZiB0aGVzZSB0aHJlZSBhY3Rpb25zOgouVFAKMS4KVHJhbnNp dGlvbiB0aGUgYXJy
YXkgdG8gcmVhZFwtYXV0byBrZWVwaW5nIHRoZSBkaXJ0eSBiaXQgY2xlYXIg aWYgdGhlIG1ldGFk
YXRhCmhhbmRsZXIgZGV0ZXJtaW5lcyB0aGF0IHRoZSBhcnJheSBkb2VzIG5v dCBuZWVkIHJlc3lu
Y2luZyBvciBvdGhlciBtb2RpZmljYXRpb24uCi5UUAoyLgpUcmFuc2l0aW9u IHRoZSBhcnJheSB0
byBhY3RpdmUgaWYgdGhlIG1ldGFkYXRhIGhhbmRsZXIgZGV0ZXJtaW5lcyBh IHJlc3luYyBvcgpz
b21lIG90aGVyIG1hbmlwdWxhdGlvbiBpcyBuZWNlc3NhcnkuCi5UUAozLgpM ZWF2ZSB0aGUgYXJy
YXkgcmVhZFwtb25seSBpZiB0aGUgdm9sdW1lIGlzIG1hcmtlZCBub3QgdG8g YmUgbW9uaXRvcmVk
IChmb3IKZXhhbXBsZSwgdGhlIG1ldGFkYXRhIHZlcnNpb24gaGFzIGJlZW4g c2V0IHRvICJcZkJl
eHRlcm5hbDpcLWRldi9tZDEyN1xmUiIKaW5zdGVhZCBvZiAiXGZCZXh0ZXJu YWw6L2Rldi9tZDEy
N1xmUiIpLgouUkUKLlRQCi5CIHN5bmNfYWN0aW9uIFwtIHJlc3luY1wtdG9c LWlkbGUKTm90aWZ5
IHRoZSBtZXRhZGF0YSBoYW5kbGVyIHRoYXQgYSByZXN5bmMgbWF5IGhhdmUg Y29tcGxldGVkLiAg
SWYgYSByZXN5bmMKcHJvY2VzcyBoYXMgaWRsZWQgYmVmb3JlIGl0IGNvbXBs ZXRlcyB0aGlzIGV2
ZW50IGFsbG93cyB0aGUgbWV0YWRhdGEgaGFuZGxlciB0bwpjaGVja3BvaW50 IHJlc3luYy4KLlRQ
Ci5CIHN5bmNfYWN0aW9uIFwtIHJlY292ZXJcLXRvXC1pZGxlCkEgc3BhcmUg ZGlzayBtYXkgaGF2
ZSBjb21wbGV0ZWQgcmVidWlsZGluZyBzbyB0ZWxsIHRoZSBtZXRhZGF0YSBo YW5kbGVyIGFib3V0
CnRoZSBzdGF0ZSBvZiBlYWNoIGRpc2suICBUaGlzIGlzIHRoZSBtZXRhZGF0 YSBoYW5kbGVyJ3Mg
b3Bwb3J0dW5pdHkgdG8gY2xlYXIgYW55CiJvdXRcLW9mXC1zeW5jIiBiaXRz IGFuZCBjbGVhciB0
aGUgdm9sdW1lJ3MgZGVncmFkZWQgc3RhdHVzLiAgSWYgYSByZWNvdmVyeQpw cm9jZXNzIGhhcyBp
ZGxlZCBiZWZvcmUgaXQgY29tcGxldGVzIHRoaXMgZXZlbnQgYWxsb3dzIHRo ZSBtZXRhZGF0YSBo
YW5kbGVyIHRvCmNoZWNrcG9pbnQgcmVjb3ZlcnkuCi5UUAouQiA8ZGlzaz4v c3RhdGUgXC0gZmF1
bHR5CkEgZGlzayBmYWlsdXJlIGtpY2tzIG9mZiBhIHNlcmllcyBvZiBldmVu dHM6Ci5icgpGaXJz
dCBub3RpZnkgdGhlIG1ldGFkYXRhIGhhbmRsZXIgdGhhdCBhIGRpc2sgaGFz IGZhaWxlZCBhbmQg
dGhlbiBub3RpZnkgdGhlCmtlcm5lbCB0aGF0IGl0IGNhbiB1bmJsb2NrIHdy aXRlcyB0aGF0IHdl
cmUgZGVwZW5kZW50IG9uIHRoaXMgZGlzay4KLmJyCkFmdGVyIHVuYmxvY2tp bmcgdGhlIGtlcm5l
bCB0aGlzIGRpc2sgaXMgc2V0IHRvIGJlIHJlbW92ZWQoKikgZnJvbSB0aGUg bWVtYmVyCmFycmF5
LgouYnIKRmluYWxseSB0aGUgZGlzayBpcyBtYXJrZWQgYXMgZmFpbGVkIGlu IGFsbCBvdGhlciBt
ZW1iZXIgYXJyYXlzIGluIHRoZQpjb250YWluZXIuCi5SUwouSVAgKCopClRo aXMgYmVoYXZpb3Ig
ZGlmZmVycyBzbGlnaHRseSBmcm9tIG5hdGl2ZSBNRCBhcnJheXMgd2hlcmUg cmVtb3ZhbCBpcyBy
ZXNlcnZlZApmb3IgYSBcZkJtZGFkbSAtLXJlbW92ZVxmUiBldmVudC4gIElu IHRoZSBleHRlcm5h
bCBtZXRhZGF0YSBjYXNlIHRoZSBjb250YWluZXIKaG9sZHMgdGhlIGZpbmFs IHJlZmVyZW5jZSBv
biBhIGJsb2NrIGRldmljZSBhbmQgYSBcZkJtZGFkbSAtLXJlbW92ZQpcZklD T05UQUlORVIgREVW
SUNFXGZSIGNhbGwgaXMgc3RpbGwgcmVxdWlyZWQuCi5SRQoKLlNTIENvbnRh aW5lcnM6CkV4dGVy
bmFsIG1ldGFkYXRhIGZvcm1hdHMsIGxpa2UgRERGLCBkaWZmZXIgZnJvbSB0 aGUgbmF0aXZlIE1E
IG1ldGFkYXRhIGZvcm1hdHMKaW4gdGhhdCB0aGV5IGRlZmluZSBhIHNldCBv ZiBkaXNrcyBhbmQg
YSBzZXJpZXMgb2Ygc3ViLWFycmF5cyB3aXRoaW4gdGhvc2UKZGlza3MuICBN RCBtZXRhZGF0YSBp
biBjb21wYXJpc29uIGRlZmluZXMgYSAxOjEgcmVsYXRpb25zaGlwIGJldHdl ZW4gYSBzZXQgb2YK
YmxvY2sgZGV2aWNlcyBhbmQgYSBSQUlEIGFycmF5LgouYnIKRm9yIGV4YW1w bGUgdG8gY3JlYXRl
IDIgYXJyYXlzIGF0IGRpZmZlcmVudCBSQUlEIGxldmVscyBvbiBhIHNpbmds ZSBzZXQgb2YKZGlz
a3MsIE1EIG1ldGFkYXRhIHJlcXVpcmVzIHRoZSBkaXNrcyB0byBiZSBwYXJ0 aXRpb25lZCBhbmQg
dGhlbiBlYWNoIGFycmF5IGNhbgpiZSBjcmVhdGVkIHdpdGggYSBzdWJzZXQg b2YgdGhvc2UgcGFy
dGl0aW9ucy4KLmJyClRoZSBzdXBwb3J0ZWQgZXh0ZXJuYWwgZm9ybWF0cyBw ZXJmb3JtIHRoaXMg
ZGlzayBjYXJ2aW5nIGludGVybmFsbHkuCi5QCkNvbnRhaW5lciBkZXZpY2Vz IHNpbXBseSBob2xk
IHJlZmVyZW5jZXMgdG8gYWxsIG1lbWJlciBkaXNrcyBhbmQgYWxsb3cKdG9v bHMgbGlrZSBcZkJt
ZG1vblxmUiB0byBkZXRlcm1pbmUgd2hpY2ggYWN0aXZlIGFycmF5cyBiZWxv bmcgdG8gd2hpY2gK
Y29udGFpbmVyLiAgU29tZSBhcnJheSBtYW5hZ2VtZW50IGNvbW1hbmRzIChs aWtlIGRpc2sgcmVt
b3ZhbCBvciBkaXNrIGFkZGl0aW9uKQphcmUgbm93IG9ubHkgdmFsaWQgYXQg dGhlIGNvbnRhaW5l
ciBsZXZlbC4KLmJyCkF0dGVtcHRzIHRvIHBlcmZvcm0gdGhlc2UgYWN0aW9u cyBvbiBtZW1iZXIg
YXJyYXlzIGFyZSBibG9ja2VkIHdpdGggZXJyb3IKbWVzc2FnZXMgbGlrZToK LklQCm1kYWRtOiBD
YW5ub3QgcmVtb3ZlIGRpc2tzIGZyb20gYSBcJ21lbWJlclwnIGFycmF5LCBw ZXJmb3JtIHRoaXMg
b3BlcmF0aW9uIG9uCnRoZSBwYXJlbnQgY29udGFpbmVyCi5QCkNvbnRhaW5l cnMgYXJlIGlkZW50
aWZpZWQgaW4gXGZCL3Byb2MvbWRzdGF0XGZSIHdpdGggYSBtZXRhZGF0YSBm b3JtYXQgc3RyaW5n
CiJcZkJleHRlcm5hbDpcZklmb3JtYXRcZlIiLgouYnIKTWVtYmVyIGRldmlj ZXMgYXJlIGlkZW50
aWZpZWQgYnkKIlxmQmV4dGVybmFsOi9cZkljb250YWluZXItZGV2aWNlXGZC L1xmSW1lbWJlci1p
bmRleFxmUiIgb3IKIlxmQmV4dGVybmFsOi1cZkljb250YWluZXItZGV2aWNl XGZCL1xmSW1lbWJl
ci1pbmRleFxmUiIgaWYgdGhlIGFycmF5IGlzIHRvCnJlbWFpbiByZWFkLW9u bHkuCgoKLlNIIE9Q
VElPTlMKLlRQCi5JIENPTlRBSU5FUgpUaGUgY29udGFpbmVyIGRldmljZSB0 byBtb25pdG9yLgou
YnIKSXQgY2FuIGJlIGEgZnVsbCBwYXRoIGxpa2UgIlxmQi9kZXYvbWQvY29u dGFpbmVyXGZSIiBv
ciBhIHNpbXBsZSBNRCBkZXZpY2UgbmFtZQpsaWtlICJcZkJtZDEyN1xmUiIu Ci5UUAouQiBcLVwt
dGFrZW92ZXIKVGhpcyBpbnN0cnVjdHMgXGZCbWRtb25cZlIgdG8gcmVwbGFj ZSBhbnkgYWN0aXZl
IFxmQm1kbW9uXGZSIHdoaWNoIGlzIGN1cnJlbnRseQptb25pdG9yaW5nIHRo ZSBhcnJheS4KLklQ
ClRoaXMgaXMgcHJpbWFyaWx5IHVzZWQgaW4gdGhlIGxhdGUgYm9vdCBwcm9j ZXNzIHRvIHJlcGxh
Y2UgYW55IFxmQm1kbW9uXGZSIHdoaWNoCndhcyBzdGFydGVkIGZyb20gYW4g aW5pdHJhbWZzIGJl
Zm9yZSB0aGUgcm9vdCBmaWxlc3lzdGVtIHdhcyBtb3VudGVkLiAgVGhpcwph dm9pZHMgaG9sZGlu
ZyBhIHJlZmVyZW5jZSBvbiB0aGF0IGluaXRyYW1mcyBpbmRlZmluaXRlbHkg YW5kIGVuc3VyZXMg
dGhhdCB0aGUKUElEIGFuZCBzb2NrZXQgZmlsZXMgdXNlZCB0byBjb21tdW5p Y2F0ZSB3aXRoIFxm
Qm1kbW9uXGZSIGFyZSBpbiBhIHN0YW5kYXJkCnBsYWNlLgouVFAKLkIgXC1c LWFsbApUaGlzIHRl
bGxzIFxmQm1kbW9uXGZSIHRvIGZpbmQgYW55IGFjdGl2ZSBjb250YWluZXJz IGFuZCBzdGFydCBt
b25pdG9yaW5nIGVhY2gKb2YgdGhlbSBpZiBhcHByb3ByaWF0ZS4gIFRoaXMg aXMgbm9ybWFsbHkg
dXNlZCB3aXRoIFxmQlwtXC10YWtlb3ZlclxmUiBpbiB0aGUKbGF0ZSBib290 IHByb2Nlc3MuCi5J
UApBIHNlcGFyYXRlIFxmQm1kbW9uXGZSIHByb2Nlc3MgaXMgc3RhcnRlZCBm b3IgZWFjaCBjb250
YWluZXIgd2l0aCB0aGUKXGZCXC1cLWFsbFxmUiBhcmd1bWVudCBiZWluZyBy ZXBsYWNlZCBieSB0
aGUgbmFtZSBvZiB0aGUgcmVzcGVjdGl2ZSBjb250YWluZXIuCi5icgpUbyBh bGxvdyBmb3IgY29u
dGFpbmVycyB3aXRoIG5hbWVzIGxvbmdlciB0aGFuIDUgY2hhcmFjdGVycyB0 aGlzIGFyZ3VtZW50
IGNhbiBiZQphcmJpdHJhcmlseSBleHRlbmRlZCwgZS5nLiB0byBcZkJcLVwt YWxsLWFjdGl2ZS1h
cnJheXNcZlIuCi5QCk5vdGUgdGhhdCBcZkJtZG1vblxmUiBpcyBhdXRvbWF0 aWNhbGx5IHN0YXJ0
ZWQgYnkgXGZCbWRhZG1cZlIgd2hlbiBuZWVkZWQgYW5kIHNvCmRvZXMgbm90 IG5lZWQgdG8gYmUg
Y29uc2lkZXJlZCB3aGVuIHdvcmtpbmcgd2l0aCBSQUlEIGFycmF5cy4gIFRo ZSBvbmx5IHRpbWVz
IGl0CmlzIHJ1biBvdGhlciB0aGFuIGJ5IFxmQm1kYWRtXGZSIGlzIHdoZW4g dGhlIGJvb3Qgc2Ny
aXB0cyBuZWVkIHRvIHJlc3RhcnQgaXQKYWZ0ZXIgbW91bnRpbmcgdGhlIG5l dyByb290IGZpbGVz
eXN0ZW0uCgoKLlNIIFNUQVJUIFVQIEFORCBTSFVURE9XTgpBcyBcZkJtZG1v blxmUiBuZWVkcyB0
byBiZSBydW5uaW5nIHdoZW5ldmVyIGFueSBmaWxlc3lzdGVtIG9uIHRoZSBt b25pdG9yZWQKZGV2
aWNlIGlzIG1vdW50ZWQgdGhlcmUgYXJlIHNwZWNpYWwgY29uc2lkZXJhdGlv bnMgd2hlbiB0aGUg
cm9vdCBmaWxlc3lzdGVtIGlzCm1vdW50ZWQgZnJvbSBhbiBcZkJtZG1vblxm UiBtb25pdG9yZWQg
ZGV2aWNlLgouUApOb3RlIHRoYXQgaW4gZ2VuZXJhbCBcZkJtZG1vblxmUiBp cyBuZWVkZWQgZXZl
biBpZiB0aGUgZmlsZXN5c3RlbSBpcyBtb3VudGVkCnJlYWQtb25seSBhcyBz b21lIGZpbGVzeXN0
ZW1zIGNhbiBzdGlsbCB3cml0ZSB0byB0aGUgZGV2aWNlIGluIHRob3NlCmNp cmN1bXN0YW5jZXMs
IGZvciBleGFtcGxlIHRvIHJlcGxheSBhIGpvdXJuYWwgYWZ0ZXIgYW4gdW5j bGVhbiBzaHV0ZG93
bi4KLlAKV2hlbiB0aGUgYXJyYXkgaXMgYXNzZW1ibGVkIGJ5IHRoZSBpbml0 cmFtZnMgY29kZSwg
XGZCbWRhZG1cZlIgd2lsbAphdXRvbWF0aWNhbGx5IHN0YXJ0IFxmQm1kbW9u XGZSIGFzIHJlcXVp
cmVkLiAgVGhpcyBtZWFucyB0aGF0IFxmQm1kbW9uXGZSIG11c3QKYmUgaW5z dGFsbGVkIHdpdGhp
biB0aGUgaW5pdHJhbWZzIGFuZCB0aGVyZSBtdXN0IGJlIGEgd3JpdGFibGUg ZmlsZXN5c3RlbQoo
dHlwaWNhbGx5IHRtcGZzKSBpbiB3aGljaCBcZkJtZG1vblxmUiBjYW4gY3Jl YXRlIGEgUElEIGFu
ZCBzb2NrZXQgZmlsZS4KLmJyClRoZSBwYXJ0aWN1bGFyIGZpbGVzeXN0ZW0g dG8gdXNlIGlzIGdp
dmVuIHRvIFxmQm1kbW9uXGZSIGF0IGNvbXBpbGUgdGltZSBhbmQKZGVmYXVs dHMgdG8gXGZCL2Rl
di8ubWRhZG1cZlIuICBUaGlzIGZpbGVzeXN0ZW0gbXVzdCBwZXJzaXN0IHRo cm91Z2ggdG8Kc2h1
dGRvd24gdGltZS4KLmJyCkFmdGVyIHRoZSBmaW5hbCByb290IGZpbGVzeXN0 ZW0gaGFzIGJlIGlu
c3RhbnRpYXRlZCAodXN1YWxseSB3aXRoClxmQnBpdm90X3Jvb3RcZlIpIFxm Qm1kbW9uXGZSIHNo
b3VsZCBiZSBydW4gd2l0aCBcZkJcLVwtYWxsIFwtXC10YWtlb3ZlclxmUiBz bwp0aGF0IHRoZSBc
ZkJtZG1vblxmUiBydW5uaW5nIGZyb20gdGhlIGluaXRyYW1mcyBjYW4gYmUg cmVwbGFjZWQgd2l0
aCBvbmUgcnVubmluZwppbiB0aGUgbWFpbiByb290IHNvIHRoYXQgdGhlIG1l bW9yeSB1c2VkIGJ5
IHRoZSBpbml0cmFtZnMgY2FuIGJlIHJlbGVhc2VkLgouUApBdCBzaHV0ZG93 biB0aW1lLCBcZkJt
ZG1vblxmUiBzaG91bGQgbm90IGJlIGtpbGxlZCBhbG9uZyB3aXRoIG90aGVy IHByb2Nlc3Nlcy4K
LmJyCkFsc28sIGFzIGl0IGhvbGRzIGEgZmlsZSAob2YgdHlwZSBzb2NrZXQp IG9wZW4gaW4gXGZC
L2RldlxmUiAoYnkgZGVmYXVsdCkgaXQKd2lsbCBub3QgYmUgcG9zc2libGUg dG8gdW5tb3VudCBc
ZkIvZGV2XGZSIGlmIGl0IGlzIG9uIGEgc2VwYXJhdGUgZmlsZXN5c3RlbS4K CgouU0ggRVhBTVBM
RVMKXGZCbWRtb24gXC1cLWFsbC1hY3RpdmUtYXJyYXlzIFwtXC10YWtlb3Zl clxmUgouUApBbnkg
XGZCbWRtb25cZlIgd2hpY2ggaXMgY3VycmVudGx5IHJ1bm5pbmcgaXMga2ls bGVkIGFuZCBhIG5l
dyBpbnN0YW5jZSBpcwpzdGFydGVkLgouYnIKVGhpcyBzaG91bGQgYmUgcnVu IGR1cmluZyBpbiB0
aGUgYm9vdCBzZXF1ZW5jZSBpZiBhbiBpbml0cmFtZnMgd2FzIHVzZWQsIHNv IHRoYXQKYW55IFxm
Qm1kbW9uXGZSIHJ1bm5pbmcgZnJvbSB0aGUgaW5pdHJhbWZzIHdpbGwgbm90 IGhvbGQgdGhlIGlu
aXRyYW1mcyBhY3RpdmUuCgoKLlNIIFNFRSBBTFNPCm1kYWRtKDgpLAptZCg0 KS4K
--=_785ecf8bce91d5df913e7d10e93600dd--

--
To unsubscribe from this list: send the line "unsubscribe linux-raid" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html

Re: polishing up mdadm manpages: mdassemble(8), mdmon(8)

am 10.03.2011 06:18:27 von NeilBrown

On Tue, 08 Mar 2011 03:08:11 +0000 Christoph Anton Mitterer
wrote:

> Hi.
>
> Recently I've started to read into MD/mdadm and what started then as
> maintaining a quilt patch with several typos and so ended up in a somewhat
> "bigger" rework.

Thanks for putting this effort in...
However just getting a new copy of the file isn't much use.
Patches are really required. Preferably several patches if there
are several different sorts of changes, as I might want to accept
some but not others.

Of course I could create the patch my - it looks like you
start from the verison in the 3.2 release - correct?
>
> - The text iself is (hopefully) largely the same, perhaps apart from some
> wording, or ordering.
> - More consistent usage of markup:
> -bold for programs, options, files, manpage references (except in the
> SEE ALSO section) and text the is somehow set or "entered"
> -italitcs (which is typically displayed as underlined) for any
> non-terminals.

Being consistent is good, but using \fB \fI etc is not.
Convention (as I understand it) prefers .B .I etc.
There are a variety of programs around which convert man pages to
other formats and I trust the ".B" tags to be handled more reliably.


> - Consistent writing of words like Linux, RAID, program names (which were
> previously off mixed) apart from those places where they're options (e.g.
> raid1 is still raid1 and not RAID1 for the --level option).

A patch which just made a change like this would certainly be appreciated.

> - Completely rewritten the formatting of the manpage (the dozens of .B, .I
> ... just to format one word made the source file really unreadable IMHO).
>
> In mdmon(8) there were some places where changed things that could
> possibly changing the semantics:
> - mdadm --remove => mdadm --remove CONTAINER
> DEVICE

That looks OK.

> - with a metadata version string "external:" => with a
> metadata format string "external:format"
> - .pid and .sock files => PID and socket files
>

Maybe... The ".pid" and ".sock" are file name extensions. If your change
were made (which quite possibly improves readability) it might then me
necessary to say something explicit about extensions.

> I wasn't sure about the following so didn't change it:
> - /state - faulty
> Is a non-terminal for a device (and thus should I replace it with
> an italics "device"?

here is a non-terminal. Actually it probably should be

rdNN/state
where NN is the slot number in the array.

> - (for example, the metadata version has been set to "external:-dev/md127"
> instead of "external:/dev/md127")
> Is the "version" correct here?

It should be "metadata_version" which is a literal file name.

>
>
> I've also started to rewrite md(4), mdadm(8) and mdadm.conf(5) manpges...
> - unifying many further writings of words like "read-only/readonly",
> "read-write/readwrite", etc. pp.
> - etc.
> but I'm not sure if/when I can finish them.

If you have discrete patches for each change, then feel free to send what
you manage, whether it is finished or not.


>
>
> Sorry for not sending a (easily reviewable) patch, but there were so many
> changes (in the line wrapping and so), that this did not make much sense.
> Please tell me whether you like and will apply it, so that I can continue
> with the remaining manpages.
> Anyway, if you merge them, please _really_ read them again for
> mistakes/typos I might have accidentally added...!
>
>
> Thanks,
> Chris.

NeilBrown

--
To unsubscribe from this list: send the line "unsubscribe linux-raid" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html

Re: polishing up mdadm manpages: mdassemble(8), mdmon(8)

am 10.03.2011 14:57:29 von Christoph Anton Mitterer

On Thu, 10 Mar 2011 16:18:27 +1100, NeilBrown wrote:
> Of course I could create the patch my - it looks like you
> start from the verison in the 3.2 release - correct?
Yes.


> Being consistent is good, but using \fB \fI etc is not.
> Convention (as I understand it) prefers .B .I etc.
Is this convention? I've seen many manpages using it,.. and it seems to be
part of the standard format?

> There are a variety of programs around which convert man pages to
> other formats and I trust the ".B" tags to be handled more reliably.
Well if they don't handle \f* they should be fixed IMHO....

Anyway,.. the reason for me arguing so strong agains .B .I etc. is that it
really makes the (raw) manpage nearly unreadable/unmaintainable IMHO.
Especially polishing up everything is made rather impossible so (IMHO)...
so do you insist on this?.


> Maybe... The ".pid" and ".sock" are file name extensions. If your
change
> were made (which quite possibly improves readability) it might then me
> necessary to say something explicit about extensions.
Well that's up to you then,.. I don't have enough knowledge about the
containers to do that =)


Cheers,
Chris.
--
To unsubscribe from this list: send the line "unsubscribe linux-raid" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html