Re: inet(3) man page: remove extra verbiage

2012-05-31 Thread Ingo Schwarze 
Hi,

Lawrence Teo wrote on Thu, May 31, 2012 at 12:14:54AM -0400:

  .Pp
 -The
  .Fn inet_aton
 -routine interprets the specified character string as an Internet address,
 +interprets the specified character string as an Internet address,
  placing the address into the structure provided.

I dislike macros at the beginnings of sentences, they prevent proper
capitalization.  Properly capitalized sentences read better and are
easier to find in the text.  When i revise a manual (for unrelated,
more important reasons), i often do the reverse of what you are
proposing here.

Finding the functions names is not really an issue, they are
set in bold face and stick out well from the text.

Consistency with respect to routine and function can't hurt,
in particular when writing a new manual or when revising an
existing one (and i'd probably slightly prefer function), but
i'm not sure it will be worth the effort to try to find and fix
all these cases.  Certainly, it shouldn't be done mechanically,
there might be exceptions.

Yours,
  Ingo

Re: inet(3) man page: remove extra verbiage

2012-05-31 Thread Mark Kettenis 
 Date: Thu, 31 May 2012 06:09:25 +0100
 From: Jason McIntyre j...@kerhand.co.uk
 
 On Thu, May 31, 2012 at 12:14:54AM -0400, Lawrence Teo wrote:
  The inet(3) man page has always felt messy to me, where the words
  function and routine are used interchangeably to describe the
  various functions in inconsistent ways.  This extra verbiage makes it
  somewhat harder to look up the descriptions of functions.
  
  Since it is understood that this man page describes functions, I have
  created a diff that removes those words to make it easier and quicker
  for programmers to find the info they need.
  
  Comments? Ok?
  
  Lawrence
  
 
 bit of a slippery slope, this one. the man pages in general use the
 terms function and routine interchangeably. you can fix one page, but
 it will have little overall difference.
 
 not that i'm against your diff. i'm just not sure it will have the
 overall effect you want.

Dunno, feels like a change just for the sake of change.  Some people
prefer the slightly more verbose style, where the descriptions are
proper sentences that start with a capital letter.  Some prefer the
slightly more compact style.  I don't think we are ever going to
achieve consistency in style issues like that, and frankly speaking I
don't think why we should.

In cases like this I tend to say: if it ain't broken, don't fix it.

Re: inet(3) man page: remove extra verbiage

2012-05-30 Thread Jason McIntyre 
On Thu, May 31, 2012 at 12:14:54AM -0400, Lawrence Teo wrote:
 The inet(3) man page has always felt messy to me, where the words
 function and routine are used interchangeably to describe the
 various functions in inconsistent ways.  This extra verbiage makes it
 somewhat harder to look up the descriptions of functions.
 
 Since it is understood that this man page describes functions, I have
 created a diff that removes those words to make it easier and quicker
 for programmers to find the info they need.
 
 Comments? Ok?
 
 Lawrence
 

bit of a slippery slope, this one. the man pages in general use the
terms function and routine interchangeably. you can fix one page, but
it will have little overall difference.

not that i'm against your diff. i'm just not sure it will have the
overall effect you want.

note also the Nd of this (and other) pages.

jmc

 
 Index: inet.3
 ===
 RCS file: /cvs/src/lib/libc/net/inet.3,v
 retrieving revision 1.23
 diff -u -p -r1.23 inet.3
 --- inet.320 Apr 2012 07:00:21 -  1.23
 +++ inet.331 May 2012 03:39:50 -
 @@ -68,7 +68,6 @@
  .Ft in_addr_t
  .Fn inet_lnaof struct in_addr in
  .Sh DESCRIPTION
 -The routines
  .Fn inet_aton ,
  .Fn inet_addr ,
  and
 @@ -78,27 +77,24 @@ numbers expressed in the Internet standa
  .Dq dot
  notation.
  .Pp
 -The
  .Fn inet_aton
 -routine interprets the specified character string as an Internet address,
 +interprets the specified character string as an Internet address,
  placing the address into the structure provided.
  It returns 1 if the string was successfully interpreted,
  or 0 if the string was invalid.
  .Pp
 -The
  .Fn inet_addr
  and
  .Fn inet_network
 -functions return numbers suitable for use
 +return numbers suitable for use
  as Internet addresses and Internet network
  numbers, respectively.
  Both functions return the constant
  .Dv INADDR_NONE
  if the specified character string is malformed.
  .Pp
 -The
  .Fn inet_pton
 -function converts a presentation format address (that is, printable form
 +converts a presentation format address (that is, printable form
  as held in a character string) to network format (usually a
  .Li struct in_addr
  or some other internal binary representation, in network byte order).
 @@ -112,7 +108,6 @@ This function is presently valid for
  and
  .Dv AF_INET6 .
  .Pp
 -The function
  .Fn inet_ntop
  converts an address from network format (usually a
  .Li struct in_addr
 @@ -125,18 +120,15 @@ error occurs (in which case,
  .Va errno
  will have been set), or it returns a pointer to the destination string.
  .Pp
 -The routine
  .Fn inet_ntoa
  takes an Internet address and returns an
  ASCII string representing the address in dot notation.
  .Pp
 -The routine
  .Fn inet_makeaddr
  takes an Internet network number and a local
  network address and constructs an Internet address
  from it.
  .Pp
 -The routines
  .Fn inet_netof
  and
  .Fn inet_lnaof