changeset 36:7be480bacd59

syntax and style changes in manpage.
author ng0@n0.is
date Wed, 15 May 2019 15:57:59 +0000
parents 92e240b49e01
children d0f4b0c3f807
files cvsps.1
diffstat 1 files changed, 151 insertions(+), 87 deletions(-) [+]
line wrap: on
line diff
--- a/cvsps.1	Fri May 03 15:33:35 2019 +0000
+++ b/cvsps.1	Wed May 15 15:57:59 2019 +0000
@@ -3,50 +3,59 @@
 .Os
 .Sh NAME
 .Nm cvsps
-.Nd
-create patchset information from CVS
+.Nd create patchset information from CVS
 .Sh SYNOPSIS
 .Nm
 .Op Fl ghuvtqxAV
-.Op Fl s Ar patchset
 .Op Fl a Ar author
-.Op Fl f Ar file
+.Op Fl b branch
+.Op Fl -bkcvs
+.Op Fl -cvs-direct
 .Op Fl d Ar date1 Fl Ar date2
-.Op Fl l Ar text [\-l <text>]
-.Op Fl b branch
-.Op Fl r Ar tag
+.Op Fl -debuglvl Ar bitmask
+.Op Fl -diff-opts Ar option\ string
+.Op Fl f Ar file
+.Op Fl l Ar text [ Fl l Ar <text>]
+.Op Fl -norc
+.Op Fl -no-rlog
 .Op Fl p Ar directory
-.Op Fl \-norc
-.Op Fl \-summary\-first
-.Op Fl \-test\-log Ar filename
-.Op Fl \-bkcvs
-.Op Fl \-no\-rlog
-.Op Fl \-diff\-opts Ar option\ string
-.Op Fl \-cvs\-direct
-.Op Fl \-debuglvl Ar bitmask
+.Op Fl r Ar tag
+.Op Fl -root Ar cvsroot
+.Op Fl s Ar patchset
+.Op Fl -summary-first
+.Op Fl -test-log Ar filename
+.Op Fl Z Ar compression
 .Op Fl z Ar fuzz
-.Op Fl Z Ar compression
-.Op Fl \-root Ar cvsroot
 .Ao Ar repository Ac
 .Sh DESCRIPTION
 CVSps is a program for generating 'patchset' information from a CVS repository.
-A patchset in this case is defined as a set of changes made to a collection of files, and all committed at the same time (using a single 'cvs commit' command).
-This information is valuable to seeing the big picture of the evolution of a cvs project.
-While cvs tracks revision information, it is often difficult to see what changes were committed 'atomically' to the repository.
-.Sh OPTIONS
-.Bl -tag -width Ds
+.Pp
+A patchset in this case is defined as a set of changes made to a collection of
+files, and all committed at the same time (using a single 'cvs commit' command).
+.Pp
+This information is valuable to seeing the big picture of the evolution of
+a CVS project.
+While CVS tracks revision information, it is often difficult to see what
+changes were committed 'atomically' to the repository.
+.Pp
+Its options are as follows:
+.Bl -tag -width indent
 .It Fl h
 Display usage summary.
 .It Fl x
-Ignore (and rebuild) ~/.cvsps/cvsps.cache file.
+Ignore (and rebuild)
+.Pa ~/.cvsps/cvsps.cache
+file.
 .It Fl u
-Update ~/.cvsps/cvsps.cache file.
+Update
+.Pa ~/.cvsps/cvsps.cache
+file.
 .It Fl z Ar fuzz
 Set the timestamp fuzz factor for identifying patch sets.
 .It Fl g
 Generate diffs of the selected patch sets.
-.It Fl s Ar patchset[\-[<patchset>]][,<patchset>...]
-generate a diff for a given patchsets and patchset ranges
+.It Fl s Ar patchset[-[<patchset>]][,<patchset>...]
+Generate a diff for a given patchsets and patchset ranges.
 .It Fl a Ar author
 Restrict output to patchsets created by author.
 .It Fl f Ar file
@@ -72,32 +81,41 @@
 Show very verbose parsing messages.
 .It Fl t
 Show some brief memory usage statistics.
-.It Fl \-norc
-When invoking cvs, ignore the .cvsrc file.
-.It Fl \-summary\-first
-When multiple patchset diffs are being generated, put the patchset summary for all patchsets at the beginning of the output.
-.It Fl \-test\-log Ar captured cvs log file
-For testing changes, you can capture cvs log output, then test against this captured file instead of hammering some poor CVS server.
-.It Fl \-bkcvs
+.It Fl -norc
+When invoking CVS, ignore the .cvsrc file.
+.It Fl -summary-first
+When multiple patchset diffs are being generated, put the patchset summary
+for all patchsets at the beginning of the output.
+.It Fl -test-log Ar captured cvs log file
+For testing changes, you can capture CVS log output, then test against
+this captured file instead of hammering some poor CVS server.
+.It Fl -bkcvs
 (see note below) for use in parsing the BK->CVS tree log formats only.
 This enables some hacks which are not generally applicable.
-.It Fl \-no\-rlog
+.It Fl -no-rlog
 Disable the use of rlog internally.
-Note: rlog is required for stable PatchSet numbering.
+Note:
+.Xr rlog 1
+is required for stable PatchSet numbering.
 Use with care.
-.It Fl \-diff\-opts Ar option string
-Send a custom set of options to diff, for example to increase the number of context lines, or change the diff format.
-.It Fl \-cvs\-direct \-no\-cvs\-direct
+.It Fl -diff-opts Ar option string
+Send a custom set of options to diff, for example to increase the
+number of context lines, or change the diff format.
+.It Fl -cvs-direct | -no-cvs-direct
 Enable or disable built-in cvs client code.
-This enables the 'pipelining' of multiple requests over a single client, reducing the overhead of handshaking and authentication to one per PatchSet instead of one per file.
-.It Fl \-debuglvl Ar bitmask
+This enables the 'pipelining' of multiple requests over a single client,
+reducing the overhead of handshaking and authentication to one per PatchSet
+instead of one per file.
+.It Fl -debuglvl Ar bitmask
 enable various debug output channels.
 .It Fl Z Ar compression
-A value 1\-9 which specifies amount of compression.
+A value 1-9 which specifies amount of compression.
 A value of 0 disables compression.
-.It Fl \-root Ar cvsroot
+.It Fl -root Ar cvsroot
 Override the setting of CVSROOT (overrides working dir. and environment).
-For --cvs-direct only.
+For
+.Fl -cvs-direct
+only.
 .It Fl q
 Be quiet about warnings.
 .It Fl A
@@ -105,66 +123,110 @@
 .It Fl V
 Show version and exit.
 .It Ao Ar repository Ac
-Operate on the specified repository (overrides working dir.)
+Operate on the specified repository (overrides working dir).
 .El
-.Sh "NOTE ON TAG HANDLING"
-Tags are fundamentally 'file at a time' in cvs, but like everything else, it would be nice to imagine that they are 'repository at a time.'
+.Ss "NOTE ON TAG HANDLING"
+Tags are fundamentally 'file at a time' in cvs, but like everything else,
+it would be nice to imagine that they are 'repository at a time.'
 The approach cvsps takes is that a tag is assigned to a patchset.
-The meaning of this is that after this patchset, every revision of every file is after
-the tag (and conversely, before this patchset, at least one file is still before the tag).
-However, there are two kinds of inconsistent (or 'funky') tags that can be created, even when following best practices for cvs.
+The meaning of this is that after this patchset, every revision of every file
+is after
+the tag (and conversely, before this patchset, at least one file is still
+before the tag).
+However, there are two kinds of inconsistent (or 'funky') tags that can
+be created, even when following best practices for cvs.
 .Pp
 The first is what is called a FUNKY tag.
-A funky tag is one where there are patchsets which are chronologically (and thus by patchset id) earlier than the tag, but are tagwise after.
-These tags will be marked as '**FUNKY**' in the Tag: section of the cvsps output.
+A funky tag is one where there are patchsets which are chronologically (and
+thus by patchset id) earlier than the tag, but are tagwise after.
+These tags will be marked as '**FUNKY**' in the Tag: section of the cvsps
+output.
 When a funky tag is specified as one of the
 .Fl r
-arguments, there are some number of patchsets which need to be considered out of sequence.
-In this case, the patchsets themselves will be labeled FUNKY and will be processed correctly.
+arguments, there are some number of patchsets which need to be considered
+out of sequence.
+In this case, the patchsets themselves will be labeled FUNKY and will be
+processed correctly.
 .Pp
 The second is called an INVALID tag.
-An invalid tag is a tag where there are patchsets which are chronologically (and thus by patchset id) earlier than the tag, but which have members which are tagwise both before, and after the tag, in the same patchset.
+An invalid tag is a tag where there are patchsets which are chronologically (and
+thus by patchset id) earlier than the tag, but which have members which are
+tagwise both before, and after the tag, in the same patchset.
 If an INVALID tag is specified as one of the
 .Fl r
-arguments, cvsps will flag each member of the affected patchsets as before or after the tag and the patchset summary will indicate which members are which, and diffs will be generated accordingly.
-.Sh "NOTE ON CVS VERSIONS"
+arguments, cvsps will flag each member of the affected patchsets as before or
+after the tag and the patchset summary will indicate which members are which,
+and diffs will be generated accordingly.
+.Ss "NOTE ON CVS VERSIONS"
 Among the different cvs subcommands used by cvsps is the 'rlog' command.
-The rlog command is used to get revision history of a module, and it disregards the current working directory.
-The important difference between 'rlog' and 'log' (from cvsps perspective) is the 'rlog' will include log data for files not in the current working directory.
-The impact of this is mainly when there are directories which at one time had files, but are now empty, and have been pruned from the working directory with the
+The rlog command is used to get revision history of a module, and it disregards
+the current working directory.
+The important difference between 'rlog' and 'log' (from cvsps perspective) is
+the 'rlog' will include log data for files not in the current working directory.
+The impact of this is mainly when there are directories which at one time had
+files, but are now empty, and have been pruned from the working directory
+with the
 .Fl P
 option.
-If 'rlog' is not used, these files logs will not be parsed, and the PatchSet numbering will be unstable.
+If 'rlog' is not used, these files logs will not be parsed, and
+the PatchSet numbering will be unstable.
 .Pp
-The main problem with 'rlog' is that, until cvs version 1.11.1, 'rlog' was an alias for the 'log' command.
+The main problem with 'rlog' is that, until cvs version 1.11.1, 'rlog' was
+an alias for the 'log' command.
 This means, for old versions of cvs, 'rlog' has different semantics and usage.
-cvsps will attempt to work around this problem by detecting capable versions of cvs.
+cvsps will attempt to work around this problem by detecting capable versions
+of cvs.
 If an old version is detected, 'log' will be used instead of 'rlog', and YMMV.
-.Sh "NOTE ON GENERATED DIFFS"
-Another important note is that cvsps will attempt, whenever possible, to use the r\-commands (rlog, rdiff  and co) instead of the local commands (log, diff, and update).
+.Ss NOTE ON GENERATED DIFFS
+Another important note is that cvsps will attempt, whenever possible, to use
+the r-commands (rlog, rdiff  and co) instead of the local commands (log, diff,
+and update).
 This is to allow cvsps to function without a completely checked out tree.
-Because these r\-commands are used, the generated diffs will include the module directory in them, and it is recommended to apply them in the working directory with the \-p1 option to the patch command.
-However, if the \-\-diff\-opts option is specified (to change, for example, the lines of context), then rdiff cannot be used, because it doesn't support arbitrary options.
-In this case, the patches will be generated without the module directory in the path, and \-p0 will be required when applying the patch.
-When diffs are generated in cvs\-direct mode (see below), however, they will always be \-p1 style patches.
-.Sh "NOTE ON BKCVS"
-The \-\-bkcvs option is a special operating mode that should only be used when parsing the log files from the BK -> CVS exported linux kernel trees.
-cvsps uses special semantics for recreating the BK ChangeSet metadata that has been embedded in the log files for those trees.
+Because these r-commands are used, the generated diffs will include the module
+directory in them, and it is recommended to apply them in the working directory
+with the
+.Fl p1
+option to the patch command.
+However, if the
+.Fl -diff-opts
+option is specified (to change, for example, the lines of context), then rdiff
+cannot be used, because it doesn't support arbitrary options.
+In this case, the patches will be generated without the module directory in
+the path, and
+.Fl p0
+will be required when applying the patch.
+When diffs are generated in cvs-direct mode (see below), however, they will
+always be
+.Fl p1
+style patches.
+.Ss "NOTE ON BKCVS"
 The
-.Fl \-bkcvs
-option should only be specified when the cache file is being created or updated (i.e. initial run of cvsps, or when
+.Fl -bkcvs
+option is a special operating mode that should only be used when parsing the
+log files from the BK -> CVS exported linux kernel trees.
+cvsps uses special semantics for recreating the BK (BK: BitKeeper) ChangeSet
+metadata that has been embedded in the log files for those trees.
+The
+.Fl -bkcvs
+option should only be specified when the cache file is being created or updated
+(i.e. initial run of cvsps, or when
 .Fl u
 and
 .Fl x
 options are used).
-.Sh "NOTE ON CVS\-DIRECT"
-As of version 2.0b6 cvsps has a partial implementation of the cvs client code built in.
-This reduces the RTT and/or handshaking overhead from one per patchset member to one per patchset.
-This dramatically increases the speed of generating diffs over a slow link, and improves the consistency of operation.
+.Ss NOTE ON CVS-DIRECT
+As of version 2.0b6 cvsps has a partial implementation of the cvs client code
+built in.
+This reduces the RTT and/or handshaking overhead from one per patchset member
+to one per patchset.
+This dramatically increases the speed of generating diffs over a slow link, and
+improves the consistency of operation.
 Currently the
-.Fl \-cvs\-direct
-option turns on the use of this code, but it very well may be default by the time 2.0 comes out.
-The built-in cvs code attempts to be compatible with cvs, but may have problems, which should be reported.
+.Fl -cvs-direct
+option turns on the use of this code, but it very well may be default by the
+time 2.0 comes out.
+The built-in cvs code attempts to be compatible with cvs, but may have
+problems, which should be reported.
 It honors the
 .Ev CVS_RSH
 and
@@ -172,15 +234,18 @@
 environment variables, but does not parse the
 .Pa ~/.cvsrc
 file.
-.Sh "NOTE ON CVSPS RC FILE"
+.Ss "NOTE ON CVSPS RC FILE"
 CVSps parses an rc file at startup.
 This file should be located in
 .Pa ~/.cvsps/cvspsrc .
-The file should contain arguments, in the exact syntax as the command line, one per line.
-If an argument takes a parameter, the parameter should be on the same line as the argument.
-.Sh "NOTE ON DATE FORMATS"
-All dates are reported in localtime.  This can be overridden (as usual) using the TZ
-environment variable.  Dates as arguments must be in the format 'yyyy/mm/dd hh:mm:ss'; for example,
+The file should contain arguments, in the exact syntax
+as the command line, one per line.
+If an argument takes a parameter, the parameter should be on the same line
+as the argument.
+.Ss "NOTE ON DATE FORMATS"
+All dates are reported in localtime. This can be overridden (as usual) using
+the TZ environment variable.
+Dates as arguments must be in the format 'yyyy/mm/dd hh:mm:ss'; for example,
 .IP "" 4
 $ cvsps -d '2004/05/01 00:00:00' -d '2004/07/07 12:00:00'
 .Sh "SEE ALSO"
@@ -200,4 +265,3 @@
 Report bugs to "David Mansfield <cvsps@dm.cobite.com>"
 .Sh BUGS
 No known bugs.
-