Hi Branden, > The Version 7 Unix pages are a wonderful thing but they are not the > final word on current or best practice.
They show that OPTIONS was not in 7th Ed.'s section 1, despite some commands, like ls(1) having many options. > Implement the system documented there and you'll be rooted in > seconds[1], among other problems. I wasn't suggesting we wind back the world to 7th Ed. Tenth was much nicer. > ...in favor of elevating one from 1979 as the final word. Again, I wasn't suggesting they were the final word. They were hand-written, not machine produced, by a small set of people with overarching editing. That gives them value as a well-considered example. > > Not a good example since they're a standards committee and put > > standardisation that above a good man page, e.g. `OPTIONS None. > > OPERANDS None. STDIN Not used. INPUT FILES None...' for true(1p). > > I regard the Austin Group as worthy of consideration as the Bell Labs > CSRC. Why shouldn't I? Because the Labs employed subjective decisions, unlike a standards committee that decides to stick to the letter. BL appreciated style. Whether Strunk and White's, or Kernighan and Plauger's. I still notice this in all the little tweaks Rob Pike makes to Go's documentation. > > I also agree with Igno that there's no need to split the option > > description off from the preceding text that then becomes too short > > to deserve its own DESCRIPTION section. Something else the POSIX > > committee doesn't care about. > > Quantify "too short". Where is the _standard_ that defines this? There doesn't need to be one. It can be it's obvious it's too short, or sometimes it's borderline. Would you define the standard in lines, words, or runes? > It is best to describe what the command is up to, and let that > discussion motivate the existence of options. By adhering to a rule > of one terse paragraph You keep stating positions to argue against that are further away from my position. I'm not advocating a single paragraph. I favour terseness, but not to excess. For a complex command the DESCRIPTION is a high overview to put the options in context and allow further detail to be sought. > > The list of options is typically near the start of the man page and > > stands out by itself. > > ...depending on how it's typeset. As a list. That's what makes it stand out. :-) -- Cheers, Ralph. https://plus.google.com/+RalphCorderoy
