chiark - git - mdw - misc/blob - space.1

   1 .\" -*-nroff-*-
   2 .ie t .ds o \(bu
   3 .el .ds o *
   4 .de hP
   5 .IP
   6 \fB\h'-\w'\\$1'u-1m'\\$1\h'1m'\fP\c
   7 ..
   8 .TH space 1 "27 January 2007" "Straylight/Edgeware"
   9 .SH NAME
  10 space \- check and fix whitespace in files
  11 .SH SYNOPSIS
  12 .B space
  13 .RB [ \-clmtuv ]
  14 .RB [ \-i \c
  15 .RI [ backup ]]
  16 .RI [ file ...]
  17 .SH DESCRIPTION
  18 The (low-budget)
  19 .B space
  20 program identifies and fixes problematic use of whitespace in text
  21 files.  In particular, it will notice and (if you want) fix
  22 .hP \*o
  23 .I trailing whitespace
  24 \(en tabs and spaces just before a newline;
  25 .hP \*o
  26 .I spaces before tabs
  27 \(en which are obviously pointless;
  28 .hP \*o
  29 .I end-of-file in mid-line
  30 \(en which confuses a number of programs,
  31 .BR diff (1)
  32 not least;
  33 .hP \*o
  34 .I trailing blank lines
  35 \(en which some editors, notably Emacs, introduce by default;
  36 .hP \*o
  37 .I groups of spaces which could be replaced by tabs
  38 \(en replacing them with the appropriate tab characters; or
  39 .hP \*o
  40 .I all tab characters
  41 \(en replacing them with appropriate numbers of spaces.
  42 .PP
  43 The program is capable of fixing files in place (leaving backups if you
  44 ask for them).
  45 .PP
  46 The following command-line options are recognized.
  47 .TP
  48 .B \-h
  49 Give a short help message describing the options available.
  50 .TP
  51 .B \-c
  52 Just check files, exiting zero if they're all OK, or 1 if there are
  53 whitespace problems with any of them; exit 32 if there are actual
  54 errors.  You may want the
  55 .B \-v
  56 option with this; without it,
  57 .B space
  58 is silent.
  59 .TP
  60 .B \-l
  61 Check the file for trailing blank lines, i.e., lines containing only
  62 horizontal whitespace.  With
  63 .BR \-v ,
  64 report if the file has trailing blank lines; without
  65 .BR \-c ,
  66 remove these trailing blank lines from the output.
  67 .TP
  68 .BR \-i [ \fIbackup ]
  69 Modify all the
  70 .IR file s
  71 in place.  During processing, the fixed copy of the file is written to
  72 some new name not currently in use.  If the processing was successful,
  73 the old
  74 .I file
  75 is renamed to
  76 .I file "" backup
  77 and the new file is renamed to
  78 .IR file .
  79 If something very complicated goes wrong at just the right moment, it's
  80 possible that you'll be left with just
  81 .I filebackup
  82 but that's not very likely.  The new file is created with the same
  83 permissions as the old file, but no attempt is made to give it the same
  84 owner or anything like that.
  85 .TP
  86 .B \-m
  87 Worry about tabs in the middle of lines as well as tabs forming the
  88 initial indentation.  Normally, identify (and fix) tabs preceded by
  89 spaces in the middle of lines; with
  90 .BR \-t ,
  91 fix all groups of whitespace which could be turned into tabs.
  92 .TP
  93 .B \-t
  94 Turn runs of horizontal whitespace into tabs where possible.
  95 With
  96 .BR \-c ,
  97 only complain about runs of space which could be turned into tabs but
  98 don't actually do anything.  By default, only runs of whitespace at the
  99 starts of lines are affected.  With
 100 .BR \-m ,
 101 however, all runs of whitespace are considered to be fair game.  The
 102 rules for internal whitespace are as follows.  A run at the start of a
 103 line, or which contains a tab is always fair game; a run of two or more
 104 spaces is fair game
 105 .I unless
 106 it follows a
 107 .RB ` . '
 108 or
 109 .RB ` : '
 110 character, either immediately or separated only by
 111 .RB ` """" '
 112 or
 113 .RB ` ' '
 114 characters, in which case three spaces are required.  This is because
 115 some typists (including the author) put two spaces after a full stop,
 116 and don't want them randomly turning into tabs for no good reason.
 117 .TP
 118 .B \-u
 119 Turn tabs into appropriate numbers of spaces.  With
 120 .BR \-c ,
 121 only complain about finding tabs, but don't actually do anything.  All
 122 tabs are considered fair game here and the
 123 .B \-m
 124 option is ignored.
 125 .PP
 126 Tab stops are assumed to occur every eight columns, as is usual.
 127 .SH BUGS
 128 There's no way yet of controlling where the tab stops are.
 129 .PP
 130 This space program doesn't even attempt moon landings.  The space man
 131 page doesn't have wiggly antennae.
 132 .PP
 133 The jokes in the man page are somewhat lame.
 134 .SH AUTHOR
 135 Mark Wooding, <mdw@distorted.org.uk>