[9fans] first capital letter in function names at man pages ¿why?

[9fans] first capital letter in function names at man pages ¿why?

[Alberto Cortes]

English uses first capital letter at after a ".". 

This convention has been used for manual pages, so when i open
strcat(2) in and acme window and right click on strdup to look for an
explanation of that function it does not find it. Thats because the
paragraph where it is explained starts by "Strdup bla bla...".

¿What are the benefits of keeping that convention for function names?.

-- 
url: http://montoya.aig.uc3m.es/~acortes/index.html

Re: [9fans] first capital letter in function names at man pages ¿why?

[Rob Pike]

Let me put it to you this way: the first letter of a sentence
is capitalized. As Doug said when we talked about this,
'the' isn't capitalized either, but we capitalize it at the
beginning of a sentence to aid the reader.

If you dislike the convention, avoid putting functions at
the beginning of a sentence.

-rob

Re: [9fans] first capital letter in function names at man pages, why?

[Alberto Cortes]

On Thu, 20 May 2004 08:22:07 +0000, Rob Pike wrote:
> Let me put it to you this way: the first letter of a sentence
> is capitalized. As Doug said when we talked about this,
> 'the' isn't capitalized either, but we capitalize it at the
> beginning of a sentence to aid the reader.

I think the real way to help the reader is "to capitalize the letter at
the beginning of a sentence" and "to avoid beginning sentences with
function names". What really hit me is why some man pages do only
half the work.

I had googled for these, but i din't get anything, was your talk with
Doug on 9fans? if it is so, sorry for waking up a dead topic. any
keyword to help on my search?

--
url: http://montoya.aig.uc3m.es/~acortes/index.html

Re: [9fans] first capital letter in function names at man pages, why?

[Russ Cox]

> I think the real way to help the reader is "to capitalize the letter at
> the beginning of a sentence" and "to avoid beginning sentences with
> function names". What really hit me is why some man pages do only
> half the work.

It's unnecessarily verbose to write "The function strdup does foo."
instead of "Strdup does foo." everywhere.

The real problem is the impedance mismatch between
the relative case-insensitivity of English convention and the
case-sensitivity of most Unix tools.  It occurs when editing
any English text (or text in most other western languages),
not just man pages.  Patching the man pages is a kludge.

Russ

Re: [9fans] first capital letter infunction names at man pages ¿why?

[matt lawless]

On Thu, 20 May 2004 16:59:25 +0200, "Alberto Cortes" <alcortes@coitt.es>
said:
> English uses first capital letter at after a ".".
>
> This convention has been used for manual pages, so when i open
> strcat(2) in and acme window and right click on strdup


when I am faced with this problem I highlight "trcat" rather than
"strcat"

and you could always use :/(S|s)trcat/

--
  matt lawless
  maht0x0r@xsmail.com

--
http://www.fastmail.fm - Access your email from home and the web

Re: [9fans] first capital letter in function names at man pages, why?

[Rob Pike]

> was your talk with
> Doug on 9fans?

it was in his office, when we were talking about the format of man pages
for one of the published unix manuals.

-rob

Re: [9fans] first capital letter in function names at man pages, why?

[Alberto Cortes]

On Thu, 20 May 2004 12:44:56 +0000, Russ Cox wrote:
> The real problem is the impedance mismatch between
> the relative case-insensitivity of English convention and the
> case-sensitivity of most Unix tools.  It occurs when editing
> any English text (or text in most other western languages),
> not just man pages.  Patching the man pages is a kludge.

I see the problem, i will give a try on these "meaning-searching"
instead of the traditional "patron-searching". i will modify the Look
command to be case-insensitive on the first letter of the word, and
use it just for fun during a test period. Maybe it will be good to
make other changes too, not just the capital first letter, but
searching for meanings is hard to implement properly.

I hate when i hit these computer-are-no-good-for-that problems.

--
url: http://montoya.aig.uc3m.es/~acortes/index.html

Re: [9fans] first capital letter in function names at man pages, why?

[rog]

> i will modify the Look command to be case-insensitive on the first
> letter of the word, and use it just for fun during a test period.

while you're about it, i've thought for a while it'd be nice to have a
"Lookw" command to look for whole words only, so I can easily search
for single-letter variable names in my programs...

the only current alternative as far as i can see is something like:

:/(^|[^\\0-9a-zA-Z_])e($|[^0-9a-zA-Z_])

to search for "e", which is a bit like hard work.

Re: [9fans] first capital letter in function names at man pages, why?

[Alberto Cortes]

On Thu, 20 May 2004 18:31:36 +0000, rog@vitanuova.com wrote:
> while you're about it, i've thought for a while it'd be nice to have a
> "Lookw" command to look for whole words only, so I can easily search
> for single-letter variable names in my programs...

That would be nice, sure i can make a new command for "meaning-search"
too, but i am more interested in how to integrate it with the "right button
click" interface.

Maybe:

1 right button click: meaning-search
2 quick right button clicks: Look
3 very quick right button clicks: Lookw

it is homogeneous, you express your required precision, with the
harsh you show on the care of the mouse, quite human thinking.

--
url: http://montoya.aig.uc3m.es/~acortes/index.html

Re: [9fans] first capital letter in function names at man pages, why?

[Fco.J.Ballesteros]

> 1 right button click: meaning-search
> 2 quick right button clicks: Look
> 3 very quick right button clicks: Lookw
>
> it is homogeneous, you express your required precision, with the
> harsh you show on the care of the mouse, quite human thinking.

That would stress me a lot. Let's don't overload things a lot.

Re: [9fans] first capital letter in function names at man pages, why?

[rog]

> 1 right button click: meaning-search
> 2 quick right button clicks: Look
> 3 very quick right button clicks: Lookw

time delays are not the way forward. they mean you can't get faster
as you get more familiar with the interface.

i wouldn't change the meaning of a right-button click - it's
already overloaded enough. just a new verb would be fine.

that way it's only there if you want it there.

Re: [9fans] first capital letter in function names at man pages, why?

[Alberto Cortes]

On Thu, 20 May 2004 18:53:01 +0000, rog@vitanuova.com wrote:
> time delays are not the way forward. they mean you can't get faster
> as you get more familiar with the interface.
>
> i wouldn't change the meaning of a right-button click - it's
> already overloaded enough. just a new verb would be fine.
>
> that way it's only there if you want it there.

Of course after the initial command is launch, only 1 click will be
necessary to repeat that command. Anyway, i get your point, i will
think about it, thanks for your comments.

--
url: http://montoya.aig.uc3m.es/~acortes/index.html

Re: [9fans] first capital letter infunction names at man pages ¿why?

[boyd, rounin]

> English uses first capital letter at after a ".".

and proper nouns etc ...

C != english

Re: [9fans] first capital letter in function names at man pages, why?

[boyd, rounin]

> i will modify the Look command to be case-insensitive on the first letter
of the word

if you want windows style searches you know where to find them.

Re: [9fans] first capital letter infunction names at man pages ¿why?

[Russ Cox]

> C != english

i'm sure glad man pages aren't written in c.

Re: [9fans] first capital letter in function names at man pages, why?

[boyd, rounin]

> i like the idea of Lookw. I was wondering if it would be nice to have a
> search facility which can search an identifier (instead of raw stream of
> characters).

well, you'd better write N parsers.

Re: [9fans] first capital letter in function names at man pages, why?

[rog]

> if you want windows style searches you know where to find them.

hmm. i kind-of agree, but then again i find myself using
grep -i quite a bit, so perhaps there's room for some ambivalence.

:/[bB][oO][yY][dD]

is really quite a hassle to type.

Re: [9fans] first capital letter in function names at man pages, why?

[vdharani]

>> i will modify the Look command to be case-insensitive on the first
>> letter of the word, and use it just for fun during a test period.
>
> while you're about it, i've thought for a while it'd be nice to have a
> "Lookw" command to look for whole words only, so I can easily search
> for single-letter variable names in my programs...
>
> the only current alternative as far as i can see is something like:
>
> :/(^|[^\\0-9a-zA-Z_])e($|[^0-9a-zA-Z_])
>
> to search for "e", which is a bit like hard work.

i like the idea of Lookw. I was wondering if it would be nice to have a
search facility which can search an identifier (instead of raw stream of
characters).

Thanks
dharani

Re: [9fans] first capital letter in function names at man pages, why?

[Brantley Coile]

> if you want windows style searches you know where to find them.

Off topic.  Dennis is quoted as saying `if you want PL/I you know where
to find it,' when someone asked for a questionable feature.  Does anyone
know what that feature was?

   Brantley

Re: [9fans] first capital letter i

[Douglas A. Gwyn]

Rob Pike wrote:
> Let me put it to you this way: the first letter of a sentence
> is capitalized. As Doug said when we talked about this,
> 'the' isn't capitalized either, but we capitalize it at the
> beginning of a sentence to aid the reader.

The counterargument is that a proper name such as
Rob is capitalized the same no matter where it appears.
Further, "Foo" and "foo" designate two distinct
functions which can both exist in the same context,
so for clarity the exact name should be used.

Re: [9fans] first capital letter in function names at man pages, why?

[Gorka Guardiola Múzquiz]

> That would be nice, sure i can make a new command for "meaning-search"
> too, but i am more interested in how to integrate it with the "right button
> click" interface.
>
> Maybe:
>
> 1 right button click: meaning-search
> 2 quick right button clicks: Look
> 3 very quick right button clicks: Lookw
>
> it is homogeneous, you express your required precision, with the
> harsh you show on the care of the mouse, quite human thinking.


Hmmm. If the problem is the first capital letter select all the word except the first letter.
It works, is fast and doesn't require a change of the interface.


						G.

Re: [9fans] first capital letter in function names at man pages, why?

[Dave Lukes]

Gorka Guardiola Múzquiz wrote:

> Hmmm. If the problem is the first capital letter select all the word except the first letter.
> It works, is fast and doesn't require a change of the interface.

Too easy.

Re: [9fans] first capital letter in function names at man pages, why?

[Alberto Cortes]

On Fri, 21 May 2004 12:28:43 +0000, Gorka Guardiola Muzquíz wrote:

> Hmmm. If the problem is the first capital letter select all the word
> except the first letter.
> It works, is fast and doesn't require a change of the interface.

Matt already suggest this, but it is not so easy, think of
hyphenation, for example, we are talking about functional semantic
searches.



-- 
url: http://montoya.aig.uc3m.es/~acortes/index.html

Re: [9fans] first capital letter in function names at man pages, why?

[Gorka Guardiola Múzquiz]

> On Fri, 21 May 2004 12:28:43 +0000, Gorka Guardiola Muzqu€z wrote:
> 
> Matt already suggest this, but it is not so easy, think of
> hyphenation, for example, we are talking about functional semantic
> searches.
> 

For me it works.  I don't think functions are hyphenated.  If they are
that is a bug, I think that, in English, proper nouns should not be
hyphenated.  In any case, if you use troff or latex, words get
hyphenated before printing, so it shouldn't be a problem.  I don't
understand what functional semantic searches are.  Can you elaborate?.


							G.

Re: [9fans] first capital letter in function names at man pages, why?

[Alberto Cortes]

On Fri, 21 May 2004 13:04:29 +0000, Gorka Guardiola Muzquíz wrote:
> I don't understand what functional semantic searches are.  Can you
> elaborate?.

When i am looking for where in a man page is the function "foobar"
explained, i don't want to care about if it is written with the first
letter in capitals, or if it has been sliced in half by an hyphenation
or if it has been pluralised... the computer should deal with these
problems, not me.

It is quite different from "Look"ing for a string in a file.

There will not be no problems if the man pages where written so you
could use "Look" for these task, as long as they are not, i will try
to implement a "semantic Look" and test it for a time, not as a
substitution of "Look" but as another verb.

-- 
url: http://montoya.aig.uc3m.es/~acortes/index.html

Re: [9fans] first capital letter in function names at man pages, why?

[Gorka Guardiola Múzquiz]

> When i am looking for where in a man page is the function "foobar"
> explained, i don't want to care about if it is written with the first
> letter in capitals, or if it has been sliced in half by an hyphenation
> or if it has been pluralised... the computer should deal with these
> problems, not me.

As I said before, I don't think function names get pluralized or hyphenated,
so the solution is really simple.

Anyway, there be dragons. You are the only one who knows what you are looking
for. If not, next you'll want Lookw to understand latex or troff commands, to translate
url escaping... Better keeping things simple and general (working by intersection, not
union).
						G.

Re: [9fans] first capital letter in function names at man pages, why?

[Alberto Cortes]

On Fri, 21 May 2004 14:30:55 +0000, Gorka Guardiola Muzquíz wrote:
> As I said before, I don't think function names get pluralized or hyphenated,
> so the solution is really simple.
>
> Anyway, there be dragons. You are the only one who knows what you
> are looking for. If not, next you'll want Lookw to understand latex
> or troff commands, to translate url escaping...

Function names was just an example, you could be searching for
anything. And i am talking about searching in English texts, not
latex, troff, C... so i don't think i will have to deal with nothing
more than English language.

> Better keeping things simple and general (working by intersection, not
> union).

Yeah, i will try to keep it simple and general, just look for an
english word and derivatives in any english text. Quite useful for
searching in web pages, manual pages or documentation in general.  

But i really don't know what do you mean by the intersection/union-thing.

-- 
url: http://montoya.aig.uc3m.es/~acortes/index.html

Re: [9fans] first capital letter in function names at man pages, why?

[boyd, rounin]

> For me it works.  I don't think functions are hyphenated.

underscore?

> If they are that is a bug, I think that, in English, proper nouns should
not be
> hyphenated.

.nh always being set?

Re: [9fans] first capital letter in function names at man pages, why?

[Fco.J.Ballesteros]

> But i really don't know what do you mean by the intersection/union-thing.

You are trying to add (union) more features:
	- search for a word
	- search for a derivative
	- search for a fortune
	- ....

Instead, you could try to see which one is the intersection of all
the cases that's most useful for most of them:
	- Look
	- Lookw ? (you know, bounded to word limits)

hth

Re: [9fans] first capital letter in function names at man pages, why?

[Fco.J.Ballesteros]

BTW, from what has been said, I think that using the function name
as-is (no caps) in the manual page would suffice to keep all of us happy.
Am I right? Or someone already discarded this fix?

Re: [9fans] first capital letter in function names at man pages, why?

[Alberto Cortes]

On Fri, 21 May 2004 16:25:16 +0000, nemo wrote:
> You are trying to add (union) more features:
> 	- search for a word
> 	- search for a derivative
> 	- search for a fortune
> 	- ....
>
> Instead, you could try to see which one is the intersection of all
> the cases that's most useful for most of them:
> 	- Look
> 	- Lookw ? (you know, bounded to word limits)
>
> hth

Now i see, gracias nemo, i will think on it.

--
url: http://montoya.aig.uc3m.es/~acortes/index.html

Re: [9fans] first capital letter in function names at man pages, why?

[splite]

On Fri, May 21, 2004 at 04:27:14PM +0200, Fco.J.Ballesteros wrote:
> BTW, from what has been said, I think that using the function name
> as-is (no caps) in the manual page would suffice to keep all of us happy.
> Am I right? Or someone already discarded this fix?

You are indeed right.  man pages are reference works, not the Canterbury
Tales.  If their usefulness as references would be impaired by slavish
adherence to formal English syntax then stuff the rules.

Re: [9fans] first capital letter in function names at man pages, why?

[boyd, rounin]

> When i am looking for where in a man page is the function "foobar"
> explained, i don't want to care about if it is written with the first
> letter in capitals, or if it has been sliced in half by an hyphenation
> or if it has been pluralised... the computer should deal with these
> problems, not me.

you figure that out for 1 human language, perfectly, and you _will_ make a
fortune.

english is easy to learn [500 words] but a nightmare to do perfectly:

    i before e, except after c, except ...

the problem is difficult enough for [a-z] based languages.  wait till you
hit ideographic based languages [chinese, japanese, ...] ...

Re: [9fans] first capital letter in function names at man pages, why?

[boyd, rounin]

> BTW, from what has been said, I think that using the function name
> as-is (no caps) in the manual page would suffice to keep all of us happy.
> Am I right? Or someone already discarded this fix?

err, .TH?

Re: [9fans] first capital letter in function names at man pages, why?

[Fco. J. Ballesteros]

[-- Attachment #1: Type: text/plain, Size: 142 bytes --]

Ok, Ok, I meant: using the object name as it is found in the code,
with no natural language rules obeyed for the object name on its own.
:-)

[-- Attachment #2: Type: message/rfc822, Size: 2714 bytes --]

From: "boyd, rounin" <boyd@insultant.net>
To: "Fans of the OS Plan 9 from Bell Labs" <9fans@cse.psu.edu>
Subject: Re: [9fans] first capital letter in function names at man pages, why?
Date: Fri, 21 May 2004 17:24:28 +0200
Message-ID: <01b001c43f47$b7ccd9a0$207e7d50@SOMA>

> BTW, from what has been said, I think that using the function name
> as-is (no caps) in the manual page would suffice to keep all of us happy.
> Am I right? Or someone already discarded this fix?

err, .TH?

Re: [9fans] first capital letter i

[Rob Pike]

> Rob Pike wrote:
> > Let me put it to you this way: the first letter of a sentence
> > is capitalized. As Doug said when we talked about this,
> > 'the' isn't capitalized either, but we capitalize it at the
> > beginning of a sentence to aid the reader.
>
> The counterargument is that a proper name such as
> Rob is capitalized the same no matter where it appears.
> Further, "Foo" and "foo" designate two distinct
> functions which can both exist in the same context,
> so for clarity the exact name should be used.
>

I answered his question.

-rob

Re: [9fans] first capital letter in function names at man pages, why?

[boyd, rounin]

>     i before e, except after c, except ...

like 'surveillance' which probably is an imported french word (rob will
correct me) from verb 'surveiller'.

Re: [9fans] first capital letter in function names at man pages, why?

[Alberto Cortes]

On Fri, 21 May 2004 17:29:20 +0000, nemo wrote:
> Ok, Ok, I meant: using the object name as it is found in the code,
> with no natural language rules obeyed for the object name on its own.
> :-)

Thats my preferred solution, and thats the reason why i have keep the
original "Subject:" through all the thread ;-P

--
url: http://montoya.aig.uc3m.es/~acortes/index.html

Re: [9fans] first capital letter in function names at man pages, why?

[Joel Salomon]

> 1 right button click: meaning-search
> 2 quick right button clicks: Look
> 3 very quick right button clicks: Lookw

http://ars.userfriendly.org/cartoons/?id=19980713
(also: http://ars.userfriendly.org/cartoons/?id=19990213 )

--Joel

Re: [9fans] first capital letter in function names at man pages, why?

[boyd, rounin]

> 1 right button click: meaning-search
> 2 quick right button clicks: Look
> 3 very quick right button clicks: Lookw

as i've said before:

    why not revert to morse keys and code?

Re: [9fans] first capital letter in function names at man pages, why?

[Jason Gurtz]

On 5/21/2004 13:46, boyd, rounin wrote:

> as i've said before:
>
>     why not revert to morse keys and code?

Carpal^H^H^H^H^H^Hstraight key or dual paddle?

~Jason

--

Re: [9fans] first capital letter in function names at man pages, why?

[boyd, rounin]

> Carpal^H^H^H^H^H^Hstraight key or dual paddle?

straight key.  only sissies use paddles or auto-keyers.

'73 de VK2BHR/P

Re: [9fans] first capital letter in function names at man pages, why?

[Micah Stetson]

> >     i before e, except after c, except ...
>
> like 'surveillance' which probably is an imported french word (rob will
> correct me) from verb 'surveiller'.

"'I' before 'E', except after 'C' and when sounding like
'A' as in 'neighbor' and 'weigh'" (or surveillance) covers
nearly all cases.  I don't think they ever told me the
second part in gradeschool, I learned that from my mom.

Micah

Re: [9fans] first capital letter in function names at man pages, why?

[Greg Pavelcak]

[-- Attachment #1: Type: text/plain, Size: 119 bytes --]

Neither leisured foreigner seized the heifer while
eating caffeine and codeine at a weird height with
a kaleidoscope.

[-- Attachment #2: Type: message/rfc822, Size: 3007 bytes --]

From: Micah Stetson <micah@cnm-vra.com>
To: Fans of the OS Plan 9 from Bell Labs <9fans@cse.psu.edu>
Subject: Re: [9fans] first capital letter in function names at man pages, why?
Date: Sun, 23 May 2004 19:10:01 -0700
Message-ID: <20040524021001.GA28057@epaphras>

> >     i before e, except after c, except ...
>
> like 'surveillance' which probably is an imported french word (rob will
> correct me) from verb 'surveiller'.

"'I' before 'E', except after 'C' and when sounding like
'A' as in 'neighbor' and 'weigh'" (or surveillance) covers
nearly all cases.  I don't think they ever told me the
second part in gradeschool, I learned that from my mom.

Micah

Re: [9fans] first capital letter in function names at man pages, why?

[Eric KD5UWL]

Well, technically,

> Neither leisured foreigner seized the heifer while
> eating caffeine and codeine at a weird height with
> a kaleidoscope.

the "ei" does come after "c" in "caffeine" and "codeine".

Do I win $10,000?

Eric

Re: [9fans] first capital letter in function names at man pages, why?

[boyd, rounin]

> the "ei" does come after "c" in "caffeine" and "codeine".
>
> Do I win $10,000?

nope, the rule covers words with c being the previous character.

Re: [9fans] first capital letter in function names at man pages, why?

[Micah Stetson]

> Neither leisured foreigner seized the heifer while
> eating caffeine and codeine at a weird height with
> a kaleidoscope.

Ok, so I'm stupid.  That'll teach me to quote rules I
don't actually use.  It does rhyme, though, that should
count for something.

Micah