* [9fans] irc answers - man and memmove @ 2005-12-05 12:07 Russ Cox 2005-12-05 19:07 ` Sascha Retzki 2005-12-06 1:09 ` Paul Lalonde 0 siblings, 2 replies; 37+ messages in thread From: Russ Cox @ 2005-12-05 12:07 UTC (permalink / raw) To: 9fans (Sorry, don't have email addresses for these people.) sretzki interesting, one of the biggest problems I have with plan9 is that functions in manpages are handled as normal words, instead of e.g. postfixing every function with () but I guess that is just me and personal taste fgb ah, yes I think it's because the manuals are intended to be printed too sretzki Well, it is not that awfull, most times, it is clear. There is no such English word like "alloctree". Just that they are capitalized at the start of sentences, but you look at the prototype at the beginning of the manpage, anyway it becomes interesting if the function is a valid English word, like "respond" in 9p(2) :) If you read the pages with man -P, which shows you the typeset version, these names will be in italics, which should make them easier for you to recognize as function names. The manual is, as fgb and man(1) point out, intended to be typeset. equuelus which file(s) do i need to include when i want to use memcpy in the kernel, tried #include "libc.h", but that didn't work. anyideas? Use memmove instead, which has the same definition on all systems. See memory(3): BUGS ANSI C does not require memcpy to handle overlapping source and destination; on Plan 9, it does, so memmove and memcpy behave identically. Russ ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] irc answers - man and memmove 2005-12-05 12:07 [9fans] irc answers - man and memmove Russ Cox @ 2005-12-05 19:07 ` Sascha Retzki 2005-12-06 1:09 ` Paul Lalonde 1 sibling, 0 replies; 37+ messages in thread From: Sascha Retzki @ 2005-12-05 19:07 UTC (permalink / raw) To: 9fans On Mon, Dec 05, 2005 at 07:07:25AM -0500, Russ Cox wrote: > If you read the pages with man -P, which shows you the typeset > version, these names will be in italics, which should make them > easier for you to recognize as function names. The manual is, > as fgb and man(1) point out, intended to be typeset. Thanks! Thanks for your mailing 9fans (thus, caring enough to point it out to all of us) Sascha > Russ > ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] irc answers - man and memmove 2005-12-05 12:07 [9fans] irc answers - man and memmove Russ Cox 2005-12-05 19:07 ` Sascha Retzki @ 2005-12-06 1:09 ` Paul Lalonde 2005-12-06 1:14 ` Rob Pike 1 sibling, 1 reply; 37+ messages in thread From: Paul Lalonde @ 2005-12-06 1:09 UTC (permalink / raw) To: Fans of the OS Plan 9 from Bell Labs On 5-Dec-05, at 4:07 AM, Russ Cox wrote: > If you read the pages with man -P, which shows you the typeset > version, these names will be in italics, which should make them > easier for you to recognize as function names. The manual is, > as fgb and man(1) point out, intended to be typeset. Actually, my biggest man page complaint is the capitalization of the symbols at the front of a sentence. I usually B3 to find the particular function I care about, and it is frequently capitalized, breaking the search. Paul ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] irc answers - man and memmove 2005-12-06 1:09 ` Paul Lalonde @ 2005-12-06 1:14 ` Rob Pike 2005-12-06 1:17 ` Paul Lalonde ` (2 more replies) 0 siblings, 3 replies; 37+ messages in thread From: Rob Pike @ 2005-12-06 1:14 UTC (permalink / raw) To: Fans of the OS Plan 9 from Bell Labs Sentences begin with capital letters. -rob On 12/5/05, Paul Lalonde <plalonde@telus.net> wrote: > > On 5-Dec-05, at 4:07 AM, Russ Cox wrote: > > If you read the pages with man -P, which shows you the typeset > > version, these names will be in italics, which should make them > > easier for you to recognize as function names. The manual is, > > as fgb and man(1) point out, intended to be typeset. > > Actually, my biggest man page complaint is the capitalization of the > symbols at the front of a sentence. I usually B3 to find the > particular function I care about, and it is frequently capitalized, > breaking the search. > > Paul > > ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] irc answers - man and memmove 2005-12-06 1:14 ` Rob Pike @ 2005-12-06 1:17 ` Paul Lalonde 2005-12-06 1:48 ` Russ Cox 2005-12-06 1:22 ` erik quanstrom 2005-12-06 6:31 ` [9fans] Capitalization in man pages Lyndon Nerenberg 2 siblings, 1 reply; 37+ messages in thread From: Paul Lalonde @ 2005-12-06 1:17 UTC (permalink / raw) To: Fans of the OS Plan 9 from Bell Labs I'm in complete agreement. I just loathe the plumber hack to do case- insensitive first-letter in man pages. I should just spend the 3 minutes and do it. Paul On 5-Dec-05, at 5:14 PM, Rob Pike wrote: > Sentences begin with capital letters. > > -rob > > On 12/5/05, Paul Lalonde <plalonde@telus.net> wrote: >> >> On 5-Dec-05, at 4:07 AM, Russ Cox wrote: >>> If you read the pages with man -P, which shows you the typeset >>> version, these names will be in italics, which should make them >>> easier for you to recognize as function names. The manual is, >>> as fgb and man(1) point out, intended to be typeset. >> >> Actually, my biggest man page complaint is the capitalization of the >> symbols at the front of a sentence. I usually B3 to find the >> particular function I care about, and it is frequently capitalized, >> breaking the search. >> >> Paul >> >> ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] irc answers - man and memmove 2005-12-06 1:17 ` Paul Lalonde @ 2005-12-06 1:48 ` Russ Cox 2005-12-07 9:57 ` Gorka guardiola 0 siblings, 1 reply; 37+ messages in thread From: Russ Cox @ 2005-12-06 1:48 UTC (permalink / raw) To: Fans of the OS Plan 9 from Bell Labs > I'm in complete agreement. I just loathe the plumber hack to do case- > insensitive first-letter in man pages. I should just spend the 3 > minutes and do it. It is not too hard to highlight all but the first letter. Even easier if you type it in the tag, select it with b1, and then b3 to search. Russ ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] irc answers - man and memmove 2005-12-06 1:48 ` Russ Cox @ 2005-12-07 9:57 ` Gorka guardiola 2005-12-07 10:41 ` Lucio De Re 0 siblings, 1 reply; 37+ messages in thread From: Gorka guardiola @ 2005-12-07 9:57 UTC (permalink / raw) To: Fans of the OS Plan 9 from Bell Labs If this isnt in the Faq it should be. It comes now and then to the mail list... On 12/6/05, Russ Cox <rsc@swtch.com> wrote: > > I'm in complete agreement. I just loathe the plumber hack to do case- > > insensitive first-letter in man pages. I should just spend the 3 > > minutes and do it. > > It is not too hard to highlight all but the first letter. > Even easier if you type it in the tag, select it with b1, > and then b3 to search. > > Russ > -- - curiosity sKilled the cat ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] irc answers - man and memmove 2005-12-07 9:57 ` Gorka guardiola @ 2005-12-07 10:41 ` Lucio De Re 0 siblings, 0 replies; 37+ messages in thread From: Lucio De Re @ 2005-12-07 10:41 UTC (permalink / raw) To: 9fans > If this isnt in the Faq it should be. It comes now and then to the mail list... We've forgotten about the "hint of the day" already? ++L ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] irc answers - man and memmove 2005-12-06 1:14 ` Rob Pike 2005-12-06 1:17 ` Paul Lalonde @ 2005-12-06 1:22 ` erik quanstrom 2005-12-06 6:31 ` [9fans] Capitalization in man pages Lyndon Nerenberg 2 siblings, 0 replies; 37+ messages in thread From: erik quanstrom @ 2005-12-06 1:22 UTC (permalink / raw) To: 9fans, Rob Pike they do? ☺ dispite my own disregard for the convention, i was about to reply that i think that the software should conform to human standards and not the other way around. but rob beat me to it. - erik Rob Pike <robpike@gmail.com> writes | | Sentences begin with capital letters. | | -rob | | On 12/5/05, Paul Lalonde <plalonde@telus.net> wrote: | > | > On 5-Dec-05, at 4:07 AM, Russ Cox wrote: | > > If you read the pages with man -P, which shows you the typeset | > > version, these names will be in italics, which should make them | > > easier for you to recognize as function names. The manual is, | > > as fgb and man(1) point out, intended to be typeset. | > | > Actually, my biggest man page complaint is the capitalization of the | > symbols at the front of a sentence. I usually B3 to find the | > particular function I care about, and it is frequently capitalized, | > breaking the search. | > | > Paul | > | > ^ permalink raw reply [flat|nested] 37+ messages in thread
* [9fans] Capitalization in man pages. 2005-12-06 1:14 ` Rob Pike 2005-12-06 1:17 ` Paul Lalonde 2005-12-06 1:22 ` erik quanstrom @ 2005-12-06 6:31 ` Lyndon Nerenberg 2005-12-06 7:01 ` Rob Pike 2 siblings, 1 reply; 37+ messages in thread From: Lyndon Nerenberg @ 2005-12-06 6:31 UTC (permalink / raw) To: Fans of the OS Plan 9 from Bell Labs On Dec 5, 2005, at 5:14 PM, Rob Pike wrote: > Sentences begin with capital letters. But not all proper names do. These are man pages, not novels. I think consistency (accuracy, really) wins here. --lyndon ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] Capitalization in man pages. 2005-12-06 6:31 ` [9fans] Capitalization in man pages Lyndon Nerenberg @ 2005-12-06 7:01 ` Rob Pike 2005-12-06 9:44 ` Charles Forsyth ` (4 more replies) 0 siblings, 5 replies; 37+ messages in thread From: Rob Pike @ 2005-12-06 7:01 UTC (permalink / raw) To: Fans of the OS Plan 9 from Bell Labs They are English text and English text has rules. Accuracy and consistency counts for English, too. The word 'the' is not capitlized unless it begins a sentence. Why should any other word behave differently? I know, because programs are special. Well, they're not - at least within the context of English text. I spent most of my time for two years editing these pages for publication. To avoid the confusion that can be introduced by capitalizing a magic word, where possible I rewrote the sentence to avoid the problem. Not Qsort sorts data but The qsort function sorts data If you see many instances that sow such confusion, either I missed them the first time or, more likely, they've been edited since by someone less focused. Fix the text. -rob On 12/5/05, Lyndon Nerenberg <lyndon@orthanc.ca> wrote: > > On Dec 5, 2005, at 5:14 PM, Rob Pike wrote: > > > Sentences begin with capital letters. > > But not all proper names do. > > These are man pages, not novels. I think consistency (accuracy, > really) wins here. > > --lyndon > ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] Capitalization in man pages. 2005-12-06 7:01 ` Rob Pike @ 2005-12-06 9:44 ` Charles Forsyth 2005-12-06 11:01 ` Lyndon Nerenberg ` (3 subsequent siblings) 4 siblings, 0 replies; 37+ messages in thread From: Charles Forsyth @ 2005-12-06 9:44 UTC (permalink / raw) To: 9fans following the rules of English text in manual pages was followed reasonably consistently in later versions of Unix, and in all the years i've worked with any of the systems, i cannot recall an instance where i was stumped, and certainly was never so perplexed that i couldn't invoke the command or write the code to call the function. (the content of manual pages in some other Unix-like systems is quite another matter, but i refer only to Unix and its relatives.) as with the `obfuscated X' contests (where X is a variable, but obviously includes the window system), no doubt one can construct a manual page that provokes a mixture of humour and head-scratching, but that's art or artifice not documentation. ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] Capitalization in man pages. 2005-12-06 7:01 ` Rob Pike 2005-12-06 9:44 ` Charles Forsyth @ 2005-12-06 11:01 ` Lyndon Nerenberg 2005-12-06 11:17 ` Charles Forsyth 2005-12-06 11:12 ` Lyndon Nerenberg ` (2 subsequent siblings) 4 siblings, 1 reply; 37+ messages in thread From: Lyndon Nerenberg @ 2005-12-06 11:01 UTC (permalink / raw) To: Fans of the OS Plan 9 from Bell Labs On Dec 5, 2005, at 11:01 PM, Rob Pike wrote: > Fix the text. Okay, Mr. Grumpy :-) The nice thing about standards is there are so many to choose from. So which of the 15 style manuals sitting on my shelf should I follow for the rewrite :-) My philosophy is that man pages describe code. I don't capitalize function names, etc., in my code, and likewise in my man pages. Ymmv. --lyndon P.S. I think "Nasa" is an abomination as well, but who am I to fight the New York Times? ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] Capitalization in man pages. 2005-12-06 11:01 ` Lyndon Nerenberg @ 2005-12-06 11:17 ` Charles Forsyth 2005-12-06 11:27 ` Lyndon Nerenberg 0 siblings, 1 reply; 37+ messages in thread From: Charles Forsyth @ 2005-12-06 11:17 UTC (permalink / raw) To: 9fans > My philosophy is that man pages describe code. I don't capitalize Code??! well, there's a thought for us all. ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] Capitalization in man pages. 2005-12-06 11:17 ` Charles Forsyth @ 2005-12-06 11:27 ` Lyndon Nerenberg 0 siblings, 0 replies; 37+ messages in thread From: Lyndon Nerenberg @ 2005-12-06 11:27 UTC (permalink / raw) To: Fans of the OS Plan 9 from Bell Labs On Dec 6, 2005, at 3:17 AM, Charles Forsyth wrote: > Code??! well, there's a thought for us all. Writing code is easy. Writing the man page for it is the part that always gives me ulcers. And what pisses me off the most is that nobody else in the company even gives a f*** about the quality of the documentation. The number of times I've tried to explain the difference between a man page and a user manual, well ... I guess what bugs me about this whole topic is that the man pages I ship with my code are the visible representation of my work, therefore I put a lot of effort into writing something that *I* would want to read, as the end user. These days, nobody seems to understand why that's important ... --lyndon (frustrated writer?) ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] Capitalization in man pages. 2005-12-06 7:01 ` Rob Pike 2005-12-06 9:44 ` Charles Forsyth 2005-12-06 11:01 ` Lyndon Nerenberg @ 2005-12-06 11:12 ` Lyndon Nerenberg 2005-12-06 11:18 ` Lucio De Re 2005-12-06 12:22 ` Lyndon Nerenberg 2005-12-06 12:46 ` erik quanstrom 4 siblings, 1 reply; 37+ messages in thread From: Lyndon Nerenberg @ 2005-12-06 11:12 UTC (permalink / raw) To: Fans of the OS Plan 9 from Bell Labs On Dec 5, 2005, at 11:01 PM, Rob Pike wrote: > To avoid the confusion that can be introduced > by capitalizing a magic word, where possible I rewrote the > sentence to avoid the problem. With the nice side effect of making the pages more readable in general. Maintaining a balance between tech-geek and understandable descriptions of functionality in man pages is an art. There aren't many people who can do it, let alone do it well. It's a dilemma Shakespeare would have appreciated, I think. (Oh lord, do I see a Monty Python skit looming?) --lyndon ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] Capitalization in man pages. 2005-12-06 11:12 ` Lyndon Nerenberg @ 2005-12-06 11:18 ` Lucio De Re 0 siblings, 0 replies; 37+ messages in thread From: Lucio De Re @ 2005-12-06 11:18 UTC (permalink / raw) To: 9fans > Maintaining a balance between tech-geek and understandable > descriptions of functionality in man pages is an art. Poetry, in fact. :-) ++L ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] Capitalization in man pages. 2005-12-06 7:01 ` Rob Pike ` (2 preceding siblings ...) 2005-12-06 11:12 ` Lyndon Nerenberg @ 2005-12-06 12:22 ` Lyndon Nerenberg 2005-12-06 12:32 ` Charles Forsyth 2005-12-06 12:46 ` erik quanstrom 4 siblings, 1 reply; 37+ messages in thread From: Lyndon Nerenberg @ 2005-12-06 12:22 UTC (permalink / raw) To: Fans of the OS Plan 9 from Bell Labs On Dec 5, 2005, at 11:01 PM, Rob Pike wrote: > If you see many instances that sow such confusion, either > I missed them the first time or, more likely, they've been > edited since by someone less focused. Or perhaps the underlying conflict is that between the grammars of C and English. C's grammar is concise, and does not suffer ambiguity (ANSI notwithstanding), whereas English thrives on ambiguity. For man (6) authors this is the pit of dispair. I confess to being a fan of the BSD mdoc macros. They recommend a writing style that strikes a reasonable balance between the goals of prose vs. precise. But most importantly, they try to ensure consistency throughout the documentation set. When it comes to laying out documentation -- especially reference documentation -- consistency of style is critical to making it easy for the reader to find what they need. The correct use of layout and typefaces will quickly draw the reader to the information they are scanning for. Using an offsetting typeface to highlight (only) function names will immediately draw the eye to that information; mixing case just stalls the rapid scanning process, as the brain has to pause to assimilate the "almost" pattern match in the context of the search. And it's this visual scanning process that concerns me. Mixed case for grep is easily solved with -i. --lyndon ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] Capitalization in man pages. 2005-12-06 12:22 ` Lyndon Nerenberg @ 2005-12-06 12:32 ` Charles Forsyth 2005-12-06 12:40 ` Lyndon Nerenberg 2005-12-06 13:02 ` Lyndon Nerenberg 0 siblings, 2 replies; 37+ messages in thread From: Charles Forsyth @ 2005-12-06 12:32 UTC (permalink / raw) To: 9fans > But most importantly, they try to ensure > consistency throughout the documentation set. so does Plan 9; it just doesn't use your rules. ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] Capitalization in man pages. 2005-12-06 12:32 ` Charles Forsyth @ 2005-12-06 12:40 ` Lyndon Nerenberg 2005-12-06 13:02 ` Lyndon Nerenberg 1 sibling, 0 replies; 37+ messages in thread From: Lyndon Nerenberg @ 2005-12-06 12:40 UTC (permalink / raw) To: Fans of the OS Plan 9 from Bell Labs On Dec 6, 2005, at 4:32 AM, Charles Forsyth wrote: > so does Plan 9; it just doesn't use your rules. So the discussion of different ways of doing things is out of bounds? Isn't that what moved us beyond UNIX? Relax, folks. I'm just trying to exchange some ideas here. ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] Capitalization in man pages. 2005-12-06 12:32 ` Charles Forsyth 2005-12-06 12:40 ` Lyndon Nerenberg @ 2005-12-06 13:02 ` Lyndon Nerenberg 2005-12-06 13:41 ` Charles Forsyth 2005-12-06 15:57 ` jmk 1 sibling, 2 replies; 37+ messages in thread From: Lyndon Nerenberg @ 2005-12-06 13:02 UTC (permalink / raw) To: Fans of the OS Plan 9 from Bell Labs On Dec 6, 2005, at 4:32 AM, Charles Forsyth wrote: >> But most importantly, they try to ensure >> consistency throughout the documentation set. > > so does Plan 9; it just doesn't use your rules. I'm curious about this comment. man(6) describes the macros it makes available, but it says nothing about how they should be used in the context of writing the man page itself. There is no mention whatsoever of style or usage. (USG derived UNIXen suffered this malady as well, to varying degrees.) So how is an author to know how to write something that is congruent with the current style? They can read existing man pages and try to glean from them, but inevitably errors will creep in. And those errors will become input to the next generation of authors, and so it goes. Wasn't it Steve Johnson who did the original sweep through the UNIX man pages, editing out inconsistent usage and rationalizing the layout? In the 1970s? --lyndon P.S. And no, I am not in any way pissing on Rob's work! ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] Capitalization in man pages. 2005-12-06 13:02 ` Lyndon Nerenberg @ 2005-12-06 13:41 ` Charles Forsyth 2005-12-06 13:54 ` Lyndon Nerenberg 2005-12-06 15:57 ` jmk 1 sibling, 1 reply; 37+ messages in thread From: Charles Forsyth @ 2005-12-06 13:41 UTC (permalink / raw) To: 9fans >> so does Plan 9; it just doesn't use your rules. > > I'm curious about this comment. man(6) describes the macros it makes > available, but it says nothing about how they should be used in the > context of writing the man page itself. There is no mention > whatsoever of style or usage. (USG derived UNIXen suffered this > malady as well, to varying degrees.) sorry, i meant only that the pages themselves are reasonably consistent in their style and usually in the way they use man(6), though that's less visible. you're quite right, though, that neither is codified. i probably just misunderstood the following, or read it too quickly, and thought you were implying there was no (real) consistency. >I confess to being a fan of the BSD mdoc macros. They recommend a >writing style that strikes a reasonable balance between the goals of >prose vs. precise. But most importantly, they try to ensure >consistency throughout the documentation set. When it comes to >laying out documentation -- especially reference documentation -- >consistency of style is critical to making it easy for the reader to >find what they need. The correct use of layout and typeface ... i took it to mean that the 9 man pages didn't do (enough) of that; i was asserting the contrary, but as i've just said, i was referring to the style on the page, not to the underlying macro usage or whether guidance or templates were provided anywhere. i did look at mdoc(7) and mdoc.samples(7) but although the latter provided a useful tutorial on using mdoc, it didn't seem to touch significantly on writing style. ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] Capitalization in man pages. 2005-12-06 13:41 ` Charles Forsyth @ 2005-12-06 13:54 ` Lyndon Nerenberg 2005-12-06 14:30 ` John Stalker 0 siblings, 1 reply; 37+ messages in thread From: Lyndon Nerenberg @ 2005-12-06 13:54 UTC (permalink / raw) To: Fans of the OS Plan 9 from Bell Labs On Dec 6, 2005, at 5:41 AM, Charles Forsyth wrote: > i did look at mdoc(7) and mdoc.samples(7) > but although the latter provided a useful tutorial on using mdoc, > it didn't seem to touch significantly on writing style. They do avoid talking about writing style. What I was getting at was the macros themselves try to enforce a consistent design (i.e. consistent use of unique typefaces to highlight function names vs. parameters vs. manifest constants, etc.), thus enforcing the visual cues I mentioned before. (And they even work to a limited extent with nroffed pages, although most of what I'm alluding to is based on the typeset pages.) But the unwritten style guide for BSD man pages says function names (and almost everything else) are case preserved. --lyndon ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] Capitalization in man pages. 2005-12-06 13:54 ` Lyndon Nerenberg @ 2005-12-06 14:30 ` John Stalker 2005-12-06 18:11 ` Charles Forsyth 0 siblings, 1 reply; 37+ messages in thread From: John Stalker @ 2005-12-06 14:30 UTC (permalink / raw) To: Fans of the OS Plan 9 from Bell Labs > the typeset pages.) But the unwritten style guide for BSD man pages > says function names (and almost everything else) are case preserved. > > --lyndon Are you sure? I just looked at Rob's example, qsort(3), on my FreeBSD system. It mostly follows his usage, but there was Mergesort() is optimized for data with pre-existing order I think FreeBSD generally follows the traditional UNIX usage in this regard. The traditional usage worked quite well when identifiers were all short and lower case. The problems begin when people name their functions things like i2d_PKCS8PrivateKey_nid_bio. -- John Stalker University of Dublin, Trinity College School of Mathematics ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] Capitalization in man pages. 2005-12-06 14:30 ` John Stalker @ 2005-12-06 18:11 ` Charles Forsyth 2005-12-06 18:31 ` Rob Pike 2005-12-07 3:56 ` Jeff Sickel 0 siblings, 2 replies; 37+ messages in thread From: Charles Forsyth @ 2005-12-06 18:11 UTC (permalink / raw) To: 9fans >> the typeset pages.) But the unwritten style guide for BSD man pages >> says function names (and almost everything else) are case preserved. >> >> --lyndon > > Are you sure? I just looked at Rob's example, qsort(3), on my FreeBSD > system. It mostly follows his usage, but there was > > Mergesort() is optimized for data with pre-existing order actually, the amusing thing for me is that most pages in plan 9's section 2 use the latter style: Open opens, Create creates, Lalloc allocates a Layer, Read reads, Write writes, Seek sets an offset, and so on. Qsort sorts an array. few pages use `the function ...', although some do when it makes sense. outside section 2, Cat reads each file, Clock draws a clock, ... one can see why, when there are many functions. with the `Lalloc allocates' style, the function name is often the start of a paragraph describing the function. when several are discussed in one paragraph, and a function name is just the start of a line not a paragraph, the capital helps it stand out from the preceding sentence. of course, i don't write my own throwaway e-mail following any of those conventions! i'm anyway currently stuck in a grim world of public abstract SocketChannel extends java.nio.channels.spi.AbstractSelectableChannel implements ByteChannel, GatheringByteChannel, ScatteringByteChannel where clearly no names are used lightly; and there are many. ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] Capitalization in man pages. 2005-12-06 18:11 ` Charles Forsyth @ 2005-12-06 18:31 ` Rob Pike 2005-12-08 3:58 ` Lyndon Nerenberg 2005-12-07 3:56 ` Jeff Sickel 1 sibling, 1 reply; 37+ messages in thread From: Rob Pike @ 2005-12-06 18:31 UTC (permalink / raw) To: Fans of the OS Plan 9 from Bell Labs My memory is clearly faulty, but the point remains that if the writing is inadequate, rewrite. -rob On 12/6/05, Charles Forsyth <forsyth@terzarima.net> wrote: > >> the typeset pages.) But the unwritten style guide for BSD man pages > >> says function names (and almost everything else) are case preserved. > >> > >> --lyndon > > > > Are you sure? I just looked at Rob's example, qsort(3), on my FreeBSD > > system. It mostly follows his usage, but there was > > > > Mergesort() is optimized for data with pre-existing order > > actually, the amusing thing for me is that most pages in plan 9's section 2 > use the latter style: Open opens, Create creates, Lalloc allocates a Layer, > Read reads, Write writes, Seek sets an offset, and so on. Qsort sorts an array. > few pages use `the function ...', although some do when it makes sense. > outside section 2, Cat reads each file, Clock draws a clock, ... > > one can see why, when there are many functions. > with the `Lalloc allocates' style, the function name is often the start > of a paragraph describing the function. when several are > discussed in one paragraph, and a function name is just the start of a line not a paragraph, the > capital helps it stand out from the preceding sentence. > > of course, i don't write my own throwaway e-mail following any of those conventions! > i'm anyway currently stuck in a grim world of > public abstract SocketChannel extends java.nio.channels.spi.AbstractSelectableChannel > implements ByteChannel, GatheringByteChannel, ScatteringByteChannel > where clearly no names are used lightly; and there are many. > > ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] Capitalization in man pages. 2005-12-06 18:31 ` Rob Pike @ 2005-12-08 3:58 ` Lyndon Nerenberg 2005-12-08 4:10 ` Russ Cox 0 siblings, 1 reply; 37+ messages in thread From: Lyndon Nerenberg @ 2005-12-08 3:58 UTC (permalink / raw) To: Fans of the OS Plan 9 from Bell Labs On Dec 6, 2005, at 10:31 AM, Rob Pike wrote: > My memory is clearly faulty, but the point remains that if the writing > is inadequate, rewrite. If things were rewritten to mdoc, would that be accepted? As you say, it's a hell of a lot of work. I will do it, but not if it's going to be thrown out for NIH. --lyndon ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] Capitalization in man pages. 2005-12-08 3:58 ` Lyndon Nerenberg @ 2005-12-08 4:10 ` Russ Cox 2005-12-08 4:55 ` Uriel 0 siblings, 1 reply; 37+ messages in thread From: Russ Cox @ 2005-12-08 4:10 UTC (permalink / raw) To: Fans of the OS Plan 9 from Bell Labs Please don't rewrite all the man pages unless you first establish the value in doing so. Converting from one troff macro package to another does not on first glance seem to offer any benefit at all. In fact, things like man2html would then have to be updated, and no doubt all the errors introduced would have to be tracked down, and so on. It hardly seems worth it, especially considering that the outward appearance would remain the same. On the other hand, checking that the man pages reflect reality (command line arguments, function signatures, and so on) would be genuinely useful. I encouraged some others to do this a few years ago and they formed a group called the Plan 9 Documentation Task Force and fixed a few man pages but then I think they lost interest. I made a bunch of updates to the plan9port man pages when I did the "first fully documented release" a year ago. Diffing those against the Plan 9 ones would be a good start. Russ ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] Capitalization in man pages. 2005-12-08 4:10 ` Russ Cox @ 2005-12-08 4:55 ` Uriel 0 siblings, 0 replies; 37+ messages in thread From: Uriel @ 2005-12-08 4:55 UTC (permalink / raw) To: Fans of the OS Plan 9 from Bell Labs On Wed, Dec 07, 2005 at 11:10:22PM -0500, Russ Cox wrote: > Please don't rewrite all the man pages unless you first establish the > value in doing so. Converting from one troff macro package to another > does not on first glance seem to offer any benefit at all. In fact, > things like man2html would then have to be updated, and no doubt all > the errors introduced would have to be tracked down, and so on. It > hardly seems worth it, especially considering that the outward > appearance would remain the same. I partially agree, I see no reason to change macro package, but I do think the outward appearance has to be changed and made consistent. > On the other hand, checking that the man pages reflect > reality (command line arguments, function signatures, > and so on) would be genuinely useful. I encouraged some > others to do this a few years ago and they formed a group > called the Plan 9 Documentation Task Force and fixed a > few man pages but then I think they lost interest. We looked at this some time ago, it's a rather tedious and long task, but I still think it's worth doing(and it's in my TODO, maybe for when I retire...) One of the issues we found was that while the quality of the man pages in general was very good, the way they structured information was very inconsistent, with for example at least four different ways of listing command line flags. When we asked about this russ considered it overambitious to reword every man page to have the same format and that it might "unnecessarily remove the original authors style". The style certainly deserves preserving because it's clear and to the point, hats off to Rob that did an excellent job. But I think it would be very good to have a set of clear guidelines blessed by the original(or current) authors, for how pages belonging to each section should be structured, and then make sure that every page follows them. Some macros that help enforce this wouldn't hurt either, but IMHO are optional. For details about this effort see: http://plan9.bell-labs.com/wiki/plan9/Man_pages_review/ > I made a bunch of updates to the plan9port man pages > when I did the "first fully documented release" a year ago. > Diffing those against the Plan 9 ones would be a good start. Oksel did quite a bit of work on this, but I think he found it rather frustrating. It was my hope that further deviations would be avoided in the future, but I don't know what is the current state of things. My suggestion at the time was to have identical man pages for p9p and Plan 9, having an extra section describing p9p-only components, and having a "PLAN 9 FROM USER SPACE" header describing any other differences in individual man pages. Russ didn't like this. uriel P.S.: Some relevant quotes from email russ sent when this was being discussed(BTW, I just double checked cfs(4) and the dashes for the options are still missing both with man and man -P): --- > We have not started the man pages review because we are unsure how much > we should change, it would be nice to make the formating and structure > of all man page more clear, consistent and uniform, but maybe we should > limit ourselves to only fix obvious errors and omisions instead? what about the formatting and structure do you believe is not clear, consistent, and uniform? (i can think of things, but i'd like to hear what you think they are.) i think it doesn't make sense to rewrite the man pages. instead i think the effort is much better spent making sure that everything is documented and that the docs are up to date. one good start would be to diff the plan9port and the plan 9 man pages. where they differ, the plan9port ones are newer and should probably be copied back to plan 9. there are lots of conventions for the writing of man pages, about formatting and structure. checkman.awk checks some of these, in particular the ordering of sections, making sure that cross-referenced pages actually exist, and so on. other conventions are harder to check, like which names are in which fonts, but those are pretty consistent. see man(6) for details. --- > most obviously: options (or flags). some pages list flags in orderly > fashion such as ls(1). others do it likewise, but have no dash in > front of the flags (e.g. cfs(4)). this might be related to > authorship. huh? cfs(4) has all the appropriate dashes. i think maybe you are looking at some crappy html version of the pages that occasionally omits dashes. try using man -P instead. > yet other pages have no list of options but mention their meaning > somewhere in the text (and then some even without dashes like > tail(1)). > the cfs(4) case is mostly aesthetic, for the tail(1) case it is hard > to see the option you're looking for at a glance. i agree that in some egregious cases, the options should be made more obvious. the f and r flags in tail(1) are a good example of this. all pages should explicitly list all the options in the SYNOPSIS section or should at least say [ options ] if the list is too long. > but, it is better to just concentrate on accurate man pages. we'll > also look into plan9ports man pages (have not really used plan9ports). yes. i'd definitely prefer to concentrate on getting the man pages accurate, and then as a second thing maybe worry about things like how the options are presented. --- ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] Capitalization in man pages. 2005-12-06 18:11 ` Charles Forsyth 2005-12-06 18:31 ` Rob Pike @ 2005-12-07 3:56 ` Jeff Sickel 1 sibling, 0 replies; 37+ messages in thread From: Jeff Sickel @ 2005-12-07 3:56 UTC (permalink / raw) To: Fans of the OS Plan 9 from Bell Labs On Dec 6, 2005, at 12:11 PM, Charles Forsyth wrote: > i'm anyway currently stuck in a grim world of > public abstract SocketChannel extends > java.nio.channels.spi.AbstractSelectableChannel > implements ByteChannel, GatheringByteChannel, ScatteringByteChannel > where clearly no names are used lightly; and there are many. I'd say "run away!", but I'm sure there's a reason to the insanity of all the Java class hierarchies. That said, I'm still all for following the mantra: deleted code is debugged code. And there are is a lot of source code in the above space that deserves to be debugged through deletion. Though JStyx opens up the concepts from Plan 9 and Inferno into the Java space, there's still a lot left to be desired. So much so that from the seat I'm sitting in, it's really difficult justifying going down that road when using Inferno or plan9port would at least keep some of the architecture a little more sane. Granted, it would be nice to see Inferno piggy back on the JDBC layer since ODBC has even more constraints these days (hard to believe). But I'd still like to see a new Inferno release and documentation, properly capitalized of course, before more Java classes I'll never get the opportunity to use see the light of day. jas ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] Capitalization in man pages. 2005-12-06 13:02 ` Lyndon Nerenberg 2005-12-06 13:41 ` Charles Forsyth @ 2005-12-06 15:57 ` jmk 2005-12-07 0:11 ` geoff 2005-12-08 3:55 ` Lyndon Nerenberg 1 sibling, 2 replies; 37+ messages in thread From: jmk @ 2005-12-06 15:57 UTC (permalink / raw) To: 9fans Seems to me you could satisfy both your desire for consistency and that of being a frustrated writer by writing the man page that details how to write a man page in the accepted Plan 9 style. --jim On Tue Dec 6 08:03:30 EST 2005, lyndon@orthanc.ca wrote: > > On Dec 6, 2005, at 4:32 AM, Charles Forsyth wrote: > > >> But most importantly, they try to ensure > >> consistency throughout the documentation set. > > > > so does Plan 9; it just doesn't use your rules. > > I'm curious about this comment. man(6) describes the macros it makes > available, but it says nothing about how they should be used in the > context of writing the man page itself. There is no mention > whatsoever of style or usage. (USG derived UNIXen suffered this > malady as well, to varying degrees.) > > So how is an author to know how to write something that is congruent > with the current style? They can read existing man pages and try to > glean from them, but inevitably errors will creep in. And those > errors will become input to the next generation of authors, and so it > goes. > > Wasn't it Steve Johnson who did the original sweep through the UNIX > man pages, editing out inconsistent usage and rationalizing the > layout? In the 1970s? > > --lyndon > > P.S. And no, I am not in any way pissing on Rob's work! ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] Capitalization in man pages. 2005-12-06 15:57 ` jmk @ 2005-12-07 0:11 ` geoff 2005-12-07 0:17 ` Francisco J Ballesteros 2005-12-07 0:22 ` Steve Simon 2005-12-08 3:55 ` Lyndon Nerenberg 1 sibling, 2 replies; 37+ messages in thread From: geoff @ 2005-12-07 0:11 UTC (permalink / raw) To: 9fans I could distribute Henry Spencer's paper on how to write a manual page, touched up for Plan 9, if people really feel the need for guidance. ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] Capitalization in man pages. 2005-12-07 0:11 ` geoff @ 2005-12-07 0:17 ` Francisco J Ballesteros 2005-12-07 0:22 ` Steve Simon 1 sibling, 0 replies; 37+ messages in thread From: Francisco J Ballesteros @ 2005-12-07 0:17 UTC (permalink / raw) To: Fans of the OS Plan 9 from Bell Labs I´d like to read that. On 12/7/05, geoff@collyer.net <geoff@collyer.net> wrote: > I could distribute Henry Spencer's paper on how to write a manual > page, touched up for Plan 9, if people really feel the need for > guidance. > ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] Capitalization in man pages. 2005-12-07 0:11 ` geoff 2005-12-07 0:17 ` Francisco J Ballesteros @ 2005-12-07 0:22 ` Steve Simon 1 sibling, 0 replies; 37+ messages in thread From: Steve Simon @ 2005-12-07 0:22 UTC (permalink / raw) To: 9fans > I could distribute Henry Spencer's paper on how to write a manual > page, touched up for Plan 9, if people really feel the need for > guidance. My poor manual pages are notorious, I'm sure I ought to read it. -Steve ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] Capitalization in man pages. 2005-12-06 15:57 ` jmk 2005-12-07 0:11 ` geoff @ 2005-12-08 3:55 ` Lyndon Nerenberg 1 sibling, 0 replies; 37+ messages in thread From: Lyndon Nerenberg @ 2005-12-08 3:55 UTC (permalink / raw) To: Fans of the OS Plan 9 from Bell Labs On Dec 6, 2005, at 7:57 AM, jmk@plan9.bell-labs.com wrote: > Seems to me you could satisfy both your desire for consistency > and that of being a frustrated writer by writing the man page that > details how to write a man page in the accepted Plan 9 style. Fair enough. I'll try to find some time over the Christmas holidays to work on that. --lyndon ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] Capitalization in man pages. 2005-12-06 7:01 ` Rob Pike ` (3 preceding siblings ...) 2005-12-06 12:22 ` Lyndon Nerenberg @ 2005-12-06 12:46 ` erik quanstrom 2005-12-06 15:02 ` Brantley Coile 4 siblings, 1 reply; 37+ messages in thread From: erik quanstrom @ 2005-12-06 12:46 UTC (permalink / raw) To: 9fans, Rob Pike thanks for the effort. the plan 9 (and antecedent unix) papers and man pages really made the systems' influence great. - erik Rob Pike <robpike@gmail.com> writes | I spent most of my time for two years editing these pages | for publication. To avoid the confusion that can be introduced | by capitalizing a magic word, where possible I rewrote the | sentence to avoid the problem. Not | Qsort sorts data | but | The qsort function sorts data ^ permalink raw reply [flat|nested] 37+ messages in thread
* Re: [9fans] Capitalization in man pages. 2005-12-06 12:46 ` erik quanstrom @ 2005-12-06 15:02 ` Brantley Coile 0 siblings, 0 replies; 37+ messages in thread From: Brantley Coile @ 2005-12-06 15:02 UTC (permalink / raw) To: quanstro, 9fans > thanks for the effort. Here, here! > > the plan 9 (and antecedent unix) papers and man pages really made the systems' > influence great. What Plan 9 needed was for Brian Kernighan to be 15 years younger. bc ^ permalink raw reply [flat|nested] 37+ messages in thread
end of thread, other threads:[~2005-12-08 4:55 UTC | newest] Thread overview: 37+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2005-12-05 12:07 [9fans] irc answers - man and memmove Russ Cox 2005-12-05 19:07 ` Sascha Retzki 2005-12-06 1:09 ` Paul Lalonde 2005-12-06 1:14 ` Rob Pike 2005-12-06 1:17 ` Paul Lalonde 2005-12-06 1:48 ` Russ Cox 2005-12-07 9:57 ` Gorka guardiola 2005-12-07 10:41 ` Lucio De Re 2005-12-06 1:22 ` erik quanstrom 2005-12-06 6:31 ` [9fans] Capitalization in man pages Lyndon Nerenberg 2005-12-06 7:01 ` Rob Pike 2005-12-06 9:44 ` Charles Forsyth 2005-12-06 11:01 ` Lyndon Nerenberg 2005-12-06 11:17 ` Charles Forsyth 2005-12-06 11:27 ` Lyndon Nerenberg 2005-12-06 11:12 ` Lyndon Nerenberg 2005-12-06 11:18 ` Lucio De Re 2005-12-06 12:22 ` Lyndon Nerenberg 2005-12-06 12:32 ` Charles Forsyth 2005-12-06 12:40 ` Lyndon Nerenberg 2005-12-06 13:02 ` Lyndon Nerenberg 2005-12-06 13:41 ` Charles Forsyth 2005-12-06 13:54 ` Lyndon Nerenberg 2005-12-06 14:30 ` John Stalker 2005-12-06 18:11 ` Charles Forsyth 2005-12-06 18:31 ` Rob Pike 2005-12-08 3:58 ` Lyndon Nerenberg 2005-12-08 4:10 ` Russ Cox 2005-12-08 4:55 ` Uriel 2005-12-07 3:56 ` Jeff Sickel 2005-12-06 15:57 ` jmk 2005-12-07 0:11 ` geoff 2005-12-07 0:17 ` Francisco J Ballesteros 2005-12-07 0:22 ` Steve Simon 2005-12-08 3:55 ` Lyndon Nerenberg 2005-12-06 12:46 ` erik quanstrom 2005-12-06 15:02 ` Brantley Coile
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).