Bug 27209

Summary: [PATCH] ascii.7 table rearrangement and uppercase specials
Product: Documentation Reporter: Gerhard Sittig <Gerhard.Sittig>
Component: Books & ArticlesAssignee: freebsd-doc (Nobody) <doc>
Status: Closed FIXED    
Severity: Affects Only Me    
Priority: Normal    
Version: Latest   
Hardware: Any   
OS: Any   

Description Gerhard Sittig 2001-05-08 19:00:01 UTC 
The tables' layout in the ascii(7) manpage are hard to read since
indices are incremented "sideways" (looking like fmt(1) output).

There has been confusion about the missing capitalization of the
special characters (0x01 to 0x1F).  All the literature refers to
them in uppercase letters.  The manpage differs from this
convention.

Fix: The below patch changes the tables a to column oriented layout
(like `ls -C` does) and changes the specials characters' names to
uppercase.

It should apply cleanly to -STABLE, while for -CURRENT the first
hunk is expected to fail (because of its context and the RCS Id
therein).  Feel free to remove the first hunk in case the .Dd
update is not appropriate.



virtually yours   82D1 9B9C 01DC 4FB4 D7B4  61BE 3F49 4F77 72DE DA76
Gerhard Sittig   true | mail -s "get gpg key" Gerhard.Sittig@gmx.net
-- 
     If you don't understand or are scared by any of the above
             ask your parents or an adult to help you.--HHV4yn8DmMgR77ql7xOCtWIklhgSMdfu4x3ZByC8PsFGoKmt
Content-Type: text/plain; name="file.shar"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment; filename="file.shar"

# This is a shell archive.  Save it in a file, remove anything before
# this line, and then unpack it by entering "sh file".  Note, it may
# create directories; files and directories will be owned by you and
# have default permissions.
#
# This archive contains:
#
#	ascii.7.diff
#
echo x - ascii.7.diff
sed 's/^X//' >ascii.7.diff << 'END-of-ascii.7.diff'
XIndex: share/man/man7/ascii.7
X===================================================================
XRCS file: /CVSREPO/FreeBSD/src/share/man/man7/ascii.7,v
Xretrieving revision 1.3.2.1
Xdiff -u -r1.3.2.1 ascii.7
X--- share/man/man7/ascii.7	2000/12/08 14:59:18	1.3.2.1
X+++ share/man/man7/ascii.7	2001/05/08 17:37:36
X@@ -32,7 +32,7 @@
X .\"	@(#)ascii.7	8.1 (Berkeley) 6/5/93
X .\" $FreeBSD: src/share/man/man7/ascii.7,v 1.3.2.1 2000/12/08 14:59:18 ru Exp $
X .\"
X-.Dd June 5, 1993
X+.Dd May 7, 2001
X .Dt ASCII 7
X .Os
X .Sh NAME
X@@ -45,66 +45,66 @@
X .Nm octal
X set:
X .Bd -literal -offset left
X-000 nul  001 soh  002 stx  003 etx  004 eot  005 enq  006 ack  007 bel
X-010 bs   011 ht   012 nl   013 vt   014 np   015 cr   016 so   017 si
X-020 dle  021 dc1  022 dc2  023 dc3  024 dc4  025 nak  026 syn  027 etb
X-030 can  031 em   032 sub  033 esc  034 fs   035 gs   036 rs   037 us 
X-040 sp   041  !   042  "   043  #   044  $   045  %   046  &   047  ' 
X-050  (   051  )   052  *   053  +   054  ,   055  -   056  .   057  / 
X-060  0   061  1   062  2   063  3   064  4   065  5   066  6   067  7 
X-070  8   071  9   072  :   073  ;   074  <   075  =   076  >   077  ? 
X-100  @   101  A   102  B   103  C   104  D   105  E   106  F   107  G 
X-110  H   111  I   112  J   113  K   114  L   115  M   116  N   117  O 
X-120  P   121  Q   122  R   123  S   124  T   125  U   126  V   127  W 
X-130  X   131  Y   132  Z   133  [   134  \e\   135  ]   136  ^   137  _ 
X-140  `   141  a   142  b   143  c   144  d   145  e   146  f   147  g 
X-150  h   151  i   152  j   153  k   154  l   155  m   156  n   157  o 
X-160  p   161  q   162  r   163  s   164  t   165  u   166  v   167  w 
X-170  x   171  y   172  z   173  {   174  |   175  }   176  ~   177 del
X+000 NUL  020 DLE  040 sp   060  0   100  @   120  P   140  `   160  p   
X+001 SOH  021 DC1  041  !   061  1   101  A   121  Q   141  a   161  q   
X+002 STX  022 DC2  042  "   062  2   102  B   122  R   142  b   162  r   
X+003 ETX  023 DC3  043  #   063  3   103  C   123  S   143  c   163  s   
X+004 EOT  024 DC4  044  $   064  4   104  D   124  T   144  d   164  t   
X+005 ENQ  025 NAK  045  %   065  5   105  E   125  U   145  e   165  u   
X+006 ACK  026 SYN  046  &   066  6   106  F   126  V   146  f   166  v   
X+007 BEL  027 ETB  047  '   067  7   107  G   127  W   147  g   167  w 
X+010 BS   030 CAN  050  (   070  8   110  H   130  X   150  h   170  x   
X+011 HT   031 EM   051  )   071  9   111  I   131  Y   151  i   171  y   
X+012 NL   032 SUB  052  *   072  :   112  J   132  Z   152  j   172  z   
X+013 VT   033 ESC  053  +   073  ;   113  K   133  [   153  k   173  {   
X+014 NP   034 FS   054  ,   074  <   114  L   134  \e\   154  l   174  |   
X+015 CR   035 GS   055  -   075  =   115  M   135  ]   155  m   175  }   
X+016 SO   036 RS   056  .   076  >   116  N   136  ^   156  n   176  ~   
X+017 SI   037 US   057  /   077  ?   117  O   137  _   157  o   177 DEL
X .Ed
X .Pp
X The
X .Nm hexadecimal
X set:
X .Bd -literal -offset left
X-00 nul   01 soh   02 stx   03 etx   04 eot   05 enq   06 ack   07 bel
X-08 bs    09 ht    0a nl    0b vt    0c np    0d cr    0e so    0f si 
X-10 dle   11 dc1   12 dc2   13 dc3   14 dc4   15 nak   16 syn   17 etb
X-18 can   19 em    1a sub   1b esc   1c fs    1d gs    1e rs    1f us 
X-20 sp    21  !    22  "    23  #    24  $    25  %    26  &    27  ' 
X-28  (    29  )    2a  *    2b  +    2c  ,    2d  -    2e  .    2f  / 
X-30  0    31  1    32  2    33  3    34  4    35  5    36  6    37  7 
X-38  8    39  9    3a  :    3b  ;    3c  <    3d  =    3e  >    3f  ? 
X-40  @    41  A    42  B    43  C    44  D    45  E    46  F    47  G 
X-48  H    49  I    4a  J    4b  K    4c  L    4d  M    4e  N    4f  O 
X-50  P    51  Q    52  R    53  S    54  T    55  U    56  V    57  W 
X-58  X    59  Y    5a  Z    5b  [    5c  \e\    5d  ]    5e  ^    5f  _ 
X-60  \`    61  a    62  b    63  c    64  d    65  e    66  f    67  g 
X-68  h    69  i    6a  j    6b  k    6c  l    6d  m    6e  n    6f  o 
X-70  p    71  q    72  r    73  s    74  t    75  u    76  v    77  w 
X-78  x    79  y    7a  z    7b  {    7c  |    7d  }    7e  ~    7f del
X+00 NUL   10 DLE   20 sp    30  0    40  @    50  P    60  \`    70  p    
X+01 SOH   11 DC1   21  !    31  1    41  A    51  Q    61  a    71  q    
X+02 STX   12 DC2   22  "    32  2    42  B    52  R    62  b    72  r    
X+03 ETX   13 DC3   23  #    33  3    43  C    53  S    63  c    73  s    
X+04 EOT   14 DC4   24  $    34  4    44  D    54  T    64  d    74  t    
X+05 ENQ   15 NAK   25  %    35  5    45  E    55  U    65  e    75  u    
X+06 ACK   16 SYN   26  &    36  6    46  F    56  V    66  f    76  v    
X+07 BEL   17 ETB   27  '    37  7    47  G    57  W    67  g    77  w 
X+08 BS    18 CAN   28  (    38  8    48  H    58  X    68  h    78  x    
X+09 HT    19 EM    29  )    39  9    49  I    59  Y    69  i    79  y    
X+0a NL    1a SUB   2a  *    3a  :    4a  J    5a  Z    6a  j    7a  z    
X+0b VT    1b ESC   2b  +    3b  ;    4b  K    5b  [    6b  k    7b  {    
X+0c NP    1c FS    2c  ,    3c  <    4c  L    5c  \e\    6c  l    7c  |    
X+0d CR    1d GS    2d  -    3d  =    4d  M    5d  ]    6d  m    7d  }    
X+0e SO    1e RS    2e  .    3e  >    4e  N    5e  ^    6e  n    7e  ~    
X+0f SI    1f US    2f  /    3f  ?    4f  O    5f  _    6f  o    7f DEL
X .Ed
X .Pp
X The
X .Nm decimal
X set:
X .Bd -literal -offset left
X-  0 nul    1 soh    2 stx    3 etx    4 eot    5 enq    6 ack    7 bel
X-  8 bs     9 ht    10 nl    11 vt    12 np    13 cr    14 so    15 si 
X- 16 dle   17 dc1   18 dc2   19 dc3   20 dc4   21 nak   22 syn   23 etb
X- 24 can   25 em    26 sub   27 esc   28 fs    29 gs    30 rs    31 us 
X- 32 sp    33  !    34  "    35  #    36  $    37  %    38  &    39  ' 
X- 40  (    41  )    42  *    43  +    44  ,    45  -    46  .    47  / 
X- 48  0    49  1    50  2    51  3    52  4    53  5    54  6    55  7 
X- 56  8    57  9    58  :    59  ;    60  <    61  =    62  >    63  ? 
X- 64  @    65  A    66  B    67  C    68  D    69  E    70  F    71  G 
X- 72  H    73  I    74  J    75  K    76  L    77  M    78  N    79  O 
X- 80  P    81  Q    82  R    83  S    84  T    85  U    86  V    87  W 
X- 88  X    89  Y    90  Z    91  [    92  \e\    93  ]    94  ^    95  _ 
X- 96  `    97  a    98  b    99  c   100  d   101  e   102  f   103  g 
X-104  h   105  i   106  j   107  k   108  l   109  m   110  n   111  o 
X-112  p   113  q   114  r   115  s   116  t   117  u   118  v   119  w 
X-120  x   121  y   122  z   123  {   124  |   125  }   126  ~   127 del
X+  0 NUL   16 DLE   32 sp    48  0    64  @    80  P    96  `   112  p   
X+  1 SOH   17 DC1   33  !    49  1    65  A    81  Q    97  a   113  q   
X+  2 STX   18 DC2   34  "    50  2    66  B    82  R    98  b   114  r   
X+  3 ETX   19 DC3   35  #    51  3    67  C    83  S    99  c   115  s   
X+  4 EOT   20 DC4   36  $    52  4    68  D    84  T   100  d   116  t   
X+  5 ENQ   21 NAK   37  %    53  5    69  E    85  U   101  e   117  u   
X+  6 ACK   22 SYN   38  &    54  6    70  F    86  V   102  f   118  v   
X+  7 BEL   23 ETB   39  '    55  7    71  G    87  W   103  g   119  w 
X+  8 BS    24 CAN   40  (    56  8    72  H    88  X   104  h   120  x   
X+  9 HT    25 EM    41  )    57  9    73  I    89  Y   105  i   121  y   
X+ 10 NL    26 SUB   42  *    58  :    74  J    90  Z   106  j   122  z   
X+ 11 VT    27 ESC   43  +    59  ;    75  K    91  [   107  k   123  {   
X+ 12 NP    28 FS    44  ,    60  <    76  L    92  \e\   108  l   124  |   
X+ 13 CR    29 GS    45  -    61  =    77  M    93  ]   109  m   125  }   
X+ 14 SO    30 RS    46  .    62  >    78  N    94  ^   110  n   126  ~   
X+ 15 SI    31 US    47  /    63  ?    79  O    95  _   111  o   127 DEL
X .Ed
X .Sh FILES
X .Bl -tag -width /usr/share/misc/ascii -compact
END-of-ascii.7.diff
exit
How-To-Repeat: 
just issue "man 7 ascii" :)
Comment 1 John Baldwin freebsd_committer freebsd_triage 2001-05-08 19:21:14 UTC 
On 08-May-01 Gerhard Sittig wrote:
> 
>>Description:
> 
> The tables' layout in the ascii(7) manpage are hard to read since
> indices are incremented "sideways" (looking like fmt(1) output).

That is a matter of opinion.  /usr/share/misc/ascii is laid out in the same
format.  Unless there is a significant favoring of one format over the other
the change is just gratuitous.

> There has been confusion about the missing capitalization of the
> special characters (0x01 to 0x1F).  All the literature refers to
> them in uppercase letters.  The manpage differs from this
> convention.

Not all literature does. :)  Also, this is Un*x after all, and Un*x has a great
affinity for lower case.  K&R calls '\0' "the null character".  Also, the tab
character is '\t' in C, not '\T'.

-- 

John Baldwin <jhb@FreeBSD.org> -- http://www.FreeBSD.org/~jhb/
PGP Key: http://www.baldwin.cx/~john/pgpkey.asc
"Power Users Use the Power to Serve!"  -  http://www.FreeBSD.org/
Comment 2 dd freebsd_committer freebsd_triage 2001-09-04 10:57:43 UTC 
State Changed
From-To: open->closed

The originator did not respond to jhb's comments about this, so we'll assume 
he's in agreement with them.
Comment 3 Gerhard Sittig 2001-09-17 20:05:41 UTC 
On Tue, Sep 04, 2001 at 02:58 -0700, dd@FreeBSD.org wrote:
> 
> State-Changed-From-To: open->closed
> State-Changed-By: dd
> State-Changed-When: Tue Sep 4 02:57:43 PDT 2001
> State-Changed-Why: 
> The originator did not respond to jhb's comments about this, so we'll assume
> he's in agreement with them.
> 
> http://www.FreeBSD.org/cgi/query-pr.cgi?pr=27209

For the record:  No, I don't agree to the "we don't need this"
argument.  If I did, there would have been no need for me to sit
down and provide the patch.  But responding to the rejection(?)
couldn't be done in any other form than repeating what I stated
initially:  Columns are definitely easier to receive than wide
lines.  I believed this to be obvious and a proven / established
opinion.  It seems it wasn't.  Or at least there has been no other
feedback but one public voice against my change (don't know about
the reasons but I guess the issue is just too small to argue about
it for too long).  And I was afraid that somebody would shout out
something along the lines of "bike shed!" should some discussion
start or even last for a little while. :)

To cut it short:  I don't force this change on anybody, but I
still invite interested FreeBSD admins in using it.  And I will
keep this one in my local repo for sure. :>


virtually yours   82D1 9B9C 01DC 4FB4 D7B4  61BE 3F49 4F77 72DE DA76
Gerhard Sittig   true | mail -s "get gpg key" Gerhard.Sittig@gmx.net
-- 
     If you don't understand or are scared by any of the above
             ask your parents or an adult to help you.