dist-3.0at70/bin/manilist.man

   1 ''' $Id: manilist.man,v 3.0.1.3 1995/05/12 11:57:31 ram Exp $
   2 '''
   3 '''  Copyright (c) 1991-1993, Raphael Manfredi
   4 '''
   5 '''  You may redistribute only under the terms of the Artistic Licence,
   6 '''  as specified in the README file that comes with the distribution.
   7 '''  You may reuse parts of this distribution only within the terms of
   8 '''  that same Artistic Licence; a copy of which may be found at the root
   9 '''  of the source tree for dist 3.0.
  10 '''
  11 ''' $Log: manilist.man,v $
  12 ''' Revision 3.0.1.3  1995/05/12  11:57:31  ram
  13 ''' patch54: updated my e-mail address
  14 '''
  15 ''' Revision 3.0.1.2  1994/01/24  13:52:55  ram
  16 ''' patch16: typo fix
  17 '''
  18 ''' Revision 3.0.1.1  1993/08/24  12:11:02  ram
  19 ''' patch3: typo fix
  20 '''
  21 ''' Revision 3.0  1993/08/18  12:04:04  ram
  22 ''' Baseline for dist 3.0 netwide release.
  23 '''
  24 '''
  25 .TH MANILIST 1 ram
  26 .SH NAME
  27 manilist \- report status of files in a source directory
  28 .SH SYNOPSIS
  29 .B manilist
  30 [
  31 .B \-abcdhnptV
  32 ] [
  33 .B \-i
  34 .I extension
  35 ] [
  36 .B \-f
  37 .I manifest
  38 ] [
  39 .B \-p
  40 .I format
  41 ] [
  42 .B \-s
  43 .I string
  44 ] [
  45 .B \-w
  46 .I which
  47 ] [
  48 .B \-x
  49 .I extension
  50 ] [
  51 .B \-C
  52 .I separator
  53 ] [
  54 .B \-I
  55 .I included
  56 ] [
  57 .B \-L
  58 .I colsize
  59 ] [
  60 .B \-X
  61 .I excluded
  62 ] [
  63 .I files or directories
  64 ]
  65 .SH DESCRIPTION
  66 .I Manilist
  67 scans a source directory and produces a report on the status of each file:
  68 whether it is up-to-date or not with respect to
  69 .I patchlevel.h ,
  70 if it is missing from MANIFEST.new, and some other useful information which
  71 may be dynamically configured. It can be use to maintain a MANIFEST.new file,
  72 produce a detailed listing and status of a group of directories, etc... The
  73 rich set of options concur to make \fImanilist\fR a perfect low-level tool.
  74 .PP
  75 Under its simplest invocation form at the top level directory of a package,
  76 with no arguments, \fImanilist\fR will scan the MANIFEST.new and produce
  77 a report on the status of each file listed there. Each line starts with a
  78 single character flag which indicates the state of the file, followed by the
  79 name of the file.
  80 .PP
  81 What happens in fact is more complex than that. \fIManilist\fR scans the
  82 MANIFEST.new file and then loops over all the files listed there. Internally,
  83 \fImanilist\fR maintains an inclusion and an exclusion list, both specifying
  84 extensions for files. For instance, the inclusion list could be ('.c', '.h')
  85 and the exclusion ('.o', ',v') so that C sources are included and object
  86 or RCS files excluded. By default, all files but those excluded are used.
  87 Some other selections may be applied at this stage, as will be explained later
  88 on. For those files which pass this selection process, a report is issued
  89 according to a report \fIformat\fR, which by default is "\fIA:%c %n\fR".
  90 The letter \fIA\fR (or anything before the initial ':' character is the
  91 file selection specification we've been talking about. The remaining is the
  92 formatting, a string which is printed as-is, modulo some escape sequences.
  93 It so happens that \fI%c\fR is the character flag and \fI%n\fR is the name
  94 of the current file.
  95 .PP
  96 Generally speaking, \fImanilist\fR should be regarded as a tool which emits
  97 configurable reports on a set of files, selectively picking them among a list
  98 or by directly scanning the directories to see what's out there...
  99 .PP
 100 By specifying a set of directories or files as arguments on the command line,
 101 you restrict the scanning area, limiting to reports concerning those files
 102 or directories. If you do not specify any, manilist restricts its report to
 103 the current directory and its subdirectories, unless the \fB\-t\fR option is
 104 given.
 105 .SH OPTIONS
 106 .I Manilist
 107 recognizes the following options:
 108 .TP 15
 109 .B \-a
 110 Make a report for \fIall\fR the files, regardless of what is specified by
 111 the \fIincluded\fR and \fIexcluded\fR suffix lists.
 112 .TP
 113 .B \-b
 114 Assume current directory is the base (root) of the package tree. When this
 115 option is not specified, \fImanilist\fR will look for a \fI.package\fR file
 116 to indicate the root directory of the package (also called the top) and
 117 complain if it does not find it.
 118 .TP
 119 .B \-c
 120 Check files against those listed in MANIFEST.new (or whatever file specified
 121 via the \fB\-f\fR option) and report discrepancies via the \fI%c\fR macro.
 122 .TP
 123 .B \-d
 124 Dump included and excluded suffix lists on stderr, extensions being space
 125 separated. A good way to know the default lists is to run: \fImanilist
 126 \-f /dev/null \-bd.
 127 .TP
 128 .B \-f\fI manifest
 129 Specify an alternate manifest file, the default being to use MANIFEST.new.
 130 .TP
 131 .B \-h
 132 Print the usage help message and exit.
 133 .TP
 134 .B \-i\fI extensions
 135 Add new extensions to the included suffix list. The \fIextensions\fR argument
 136 must list the suffixes separated by spaces, as in \fB\-i\fI '.ph .pl'\fR to add
 137 both \fI.ph\fR and \fI.pl\fR to the existing suffixes. Note that the argument
 138 needs to be quoted to protect spaces against shell interpretation.
 139 .TP
 140 .B \-n
 141 Do not use any manifest file. Rather scan the directories and act as with all
 142 the files there were already listed in a manifest.
 143 .TP
 144 .B \-p\fI format
 145 Set the new printing format, which has the form \fIselection\fR:\fIstring\fR,
 146 with \fIselection\fR being a list of single letters specifying which files
 147 from the manifest are to be used for reports, and \fIstring\fR being a
 148 message to print as report, with some macro substitutions. It is also possible
 149 to have column formatting by specifying a '|' inside the string to delimit
 150 the different columns you wish to see. See also \fB\-C\fR and \fB\-L\fR for
 151 more formatting parameters.
 152 .TP
 153 .B \-s\fI string
 154 Specify the \fIstring\fR part of the printing format (see \fB\-p\fR for a
 155 general description of the \fIformat\fR). Available macros are listed further
 156 down the manual page.
 157 .TP
 158 .B \-t
 159 Start from the top directory (the root directory of the distribution) regardless
 160 of the current directory. There must be a \fI.package\fR file to indicate
 161 what the top directory is.
 162 .TP
 163 .B \-w\fI selection
 164 Specifiy the \fIselection\fR part of the printing format. Available selections
 165 will be discussed later.
 166 .TP
 167 .B \-x\fI extensions
 168 Add new extensions to the excluded suffix list. The \fIextensions\fR argument
 169 must list the suffixes separated by spaces, as in \fB\-x\fI '.s .p'\fR to add
 170 both \fI.s\fR and \fI.p\fR to the existing list. Note that the argument
 171 needs to be quoted to protect spaces against shell interpretation.
 172 .TP
 173 .B \-C\fI separator
 174 Give the column separator, which is to be used in place of the '|' character
 175 in the report format string. By default, it is a single space.
 176 .TP
 177 .B \-I\fI included
 178 Specify a new list of suffixes to be included in the reports. This overrides
 179 the original default list (whereas \fB\-i\fR is used to \fIadd\fR suffixes to
 180 the list). Suffixes must be space separated.
 181 .TP
 182 .B \-L\fI colsize
 183 When using column formatting (the '|' character being used to denote columns),
 184 this option may be used to specify the maximum column width, separating each
 185 width by a single ','. Leaving a width unspecified does not impose any limit
 186 on its width. For instance, if the format string is \fI%n|%d|%t\fR, one could
 187 limit the middle column (descriptions from MANIFEST.new) to 40 characters and
 188 the name column (first one) to 15 characters, leaving the last one with no
 189 imposed limits, by using \fB\-L\fI 15,40,\fR.
 190 .TP
 191 .B \-V
 192 Print version number and exit.
 193 .TP
 194 .B \-X\fI excluded
 195 Specify a new list of suffixes to be excluded in the reports. This overrides
 196 the original default list (whereas \fB\-x\fR is used to \fIadd\fR suffixes to
 197 the list). Suffixes must be space separated.
 198 .SH USING FORMATS
 199 The flexibility of \fImanilist\fR is brought by its use of a dynamic formatting
 200 string for providing its reports. It is possible to specify a format via the
 201 \fB\-p\fR option or just parts of it: the text string via \fB\-s\fR and the
 202 file selection with \fB\-w\fR.
 203 .SS "File Selection"
 204 .PP
 205 The leading part of the formatting string tells \fImanilist\fR which files you
 206 wish to see in the final report. Available selectors are:
 207 .sp
 208 .PD 0
 209 .TP 5
 210 .B A
 211 All the files but the excluded ones (i.e. those files whose suffix is listed
 212 in the exclusion list). This is the default action.
 213 .TP
 214 .B a
 215 All the files included and/or excluded (shortcut for \fIix\fR). Note that files
 216 which are neither included nor excluded will not appear in the report.
 217 .TP
 218 .B d
 219 Report only for directories.
 220 .TP
 221 .B f
 222 Report only for files.
 223 .TP
 224 .B i
 225 Only included files are listed.
 226 .TP
 227 .B m
 228 Only those files or directories found in the manifest are listed.
 229 .TP
 230 .B n
 231 Only those files or directories \fInot\fR found in the manifest are listed.
 232 .TP
 233 .B x
 234 Only excluded files are listed.
 235 .PD
 236 .PP
 237 When you specify more than one letter, the resulting report depends on the
 238 nature of the selection. For \fId\fR, \fIf\fR, \fIm\fR and \fIn\fR, a logical
 239 union is performed. This means specifying \fIfd\fR or \fImn\fR is the same
 240 as not specifying anything, but it's less efficient since \fImanilist\fR is
 241 forced to perform the checks it would otherwise bypass. The \fIi\fR and \fIx\fR
 242 selectors are special: by default, all the files not excluded are reported.
 243 Specifying \fIx\fR also asks for excluded files. Specifying \fIi\fR restricts
 244 the report to the included files. Using both at the same time (\fIix\fR) will
 245 force a report for files which are included or excluded.
 246 .SS "Macro Substitution"
 247 .PP
 248 The string part of the report format can make use of the following macros:
 249 .sp
 250 .PD 0
 251 .TP 5
 252 %c
 253 A character coding the status of the file.
 254 .TP
 255 %d
 256 Description from the manifest file, if any.
 257 .TP
 258 %n
 259 Name of the file (its path from the top directory).
 260 .TP
 261 %s
 262 Size of the file, in bytes.
 263 .TP
 264 %t
 265 Time stamp of the last modification.
 266 .PD
 267 .SS "File Status"
 268 .PP
 269 The \fI%c\fR macro, giving a single character coding the file status, can
 270 expand into one of the following.
 271 .PD 0
 272 .TP 5
 273 \&.
 274 The file is up to date (not newer than \fIpatchlevel.h\fR).
 275 .TP
 276 -
 277 The file is present in the manifest but is missing.
 278 .TP
 279 >
 280 The file has been modified since last patch (newer than \fIpatchlevel.h\fR).
 281 .TP
 282 +
 283 The file exists but is not listed in the manifest.
 284 .TP
 285 o
 286 The file exists but is not listed in the manifest and is older than
 287 \fIpatchlevel.h\fR
 288 .TP
 289 x
 290 The file is listed in the manifest and exists, but has been excluded. Naturally,
 291 this will appear in the report only if the \fIx\fR selector is given in the
 292 report format.
 293 .TP
 294 ?
 295 The file is listed in the manifest, does not exist, and was excluded.
 296 .PD
 297 .SH EXAMPLES
 298 The command
 299 .in +5
 300 .nf
 301 .sp
 302 \fImanilist -ct -p 'ni:%n'\fR
 303 .sp
 304 .fi
 305 .in -5
 306 will list all the source files from your distribution which are not listed
 307 in your MANIFEST.new file. Note that this includes only "source" files, that
 308 is to say files whose extension is listed in the inclusion list.
 309 If you do not wish this restriction, replace the formatting string with
 310 \fIn:%n\fR (only the excluded files will not appear).
 311 .PP
 312 To build an initial MANIFEST file, use:
 313 .in +5
 314 .nf
 315 .sp
 316 \fImanilist -n -p 'Af:%n' > MANIFEST\fR
 317 .sp
 318 .fi
 319 .in -5
 320 from the top directory. You will eventually want to fill in descriptions for
 321 each file listed in the manifest.
 322 .SH FILES
 323 .PD 0
 324 .TP 20
 325 MANIFEST.new
 326 Default manifest file, listing files and giving a small description for each
 327 of them.
 328 .PD
 329 .SH AUTHOR
 330 Raphael Manfredi <ram@hptnos02.grenoble.hp.com>
 331 .SH "SEE ALSO"
 332 manifake(1), makedist(1), pat(1).