1
0
Fork 0
mirror of https://git.tukaani.org/xz.git synced 2024-04-04 12:36:23 +02:00

xzdiff, xzgrep, and xzmore: Rewrite the man pages.

The main reason is a kind of silly one:

xz-man.pot contains strings from all man pages in XZ Utils.
The man pages of xzdiff, xzgrep, and xzmore were under GPLv2
and the rest under 0BSD. Thus xz-man.pot contained strings
under two licences. po4a creates the translated man pages
from the combined 0BSD+GPLv2 xz-man.pot.

I haven't liked this mixing in xz-man.pot but the
Translation Project requires that all man pages must be
in the same .pot file. So a separate xz-man-gpl.pot
wasn't an option.

Since these man pages are short, rewriting them was quick enough.
Now xz-man.pot is entirely under 0BSD and marking the per-file
licenses is simpler.

As a bonus, some wording hopefully is now slightly better
although it's perhaps a matter of taste.

NOTE: In xzgrep.1, the EXIT STATUS section was written by me
in the commit d796b6d7fd so that's
why that section could be taken as is from the old xzgrep.1.
This commit is contained in:
Lasse Collin 2024-02-12 17:09:10 +02:00
parent 3e551b111b
commit e48287bf51
3 changed files with 174 additions and 117 deletions

View file

@ -1,66 +1,89 @@
.\" SPDX-License-Identifier: GPL-2.0-or-later .\" SPDX-License-Identifier: 0BSD
.\" .\"
.\" Original zdiff.1 for gzip: Jean-loup Gailly .\" Authors: Lasse Collin
.\" Jia Tan
.\" .\"
.\" Modifications for XZ Utils: Lasse Collin .\" (Note that this file is not based on gzip's zdiff.1.)
.\" Andrew Dudman
.\" .\"
.TH XZDIFF 1 "2021-06-04" "Tukaani" "XZ Utils" .TH XZDIFF 1 "2024-02-12" "Tukaani" "XZ Utils"
.SH NAME .SH NAME
xzcmp, xzdiff, lzcmp, lzdiff \- compare compressed files xzcmp, xzdiff, lzcmp, lzdiff \- compare compressed files
.
.SH SYNOPSIS .SH SYNOPSIS
.B xzcmp .B xzcmp
.RI [ cmp_options "] " file1 " [" file2 ] .RI [ option... ]
.I file1
.RI [ file2 ]
.br .br
.B xzdiff .B xzdiff
.RI [ diff_options "] " file1 " [" file2 ] \&...
.br .br
.B lzcmp .B lzcmp
.RI [ cmp_options "] " file1 " [" file2 ] \&...
.br .br
.B lzdiff .B lzdiff
.RI [ diff_options "] " file1 " [" file2 ] \&...
.
.SH DESCRIPTION .SH DESCRIPTION
.B xzcmp .B xzcmp
and and
.B xzdiff .B xzdiff
invoke compare uncompressed contents of two files.
Uncompressed data and options are passed to
.BR cmp (1) .BR cmp (1)
or or
.BR diff (1) .BR diff (1)
on files compressed with unless
.B \-\-help
or
.B \-\-version
is specified.
.PP
If both
.I file1
and
.I file2
are specified, they can be uncompressed files or files in formats that
.BR xz (1), .BR xz (1),
.BR lzma (1),
.BR gzip (1), .BR gzip (1),
.BR bzip2 (1), .BR bzip2 (1),
.BR lzop (1), .BR lzop (1),
or or
.BR zstd (1). .BR zstd (1)
All options specified are passed directly to can decompress.
.BR cmp (1) The required decompression commands are determined from
or the filename suffixes of
.BR diff (1).
If only one file is specified, then the files compared are
.I file1 .I file1
(which must have a suffix of a supported compression format) and and
.I file1 .IR file2 .
from which the compression format suffix has been stripped. A file with an unknown suffix is assumed to be either uncompressed
If two files are specified, or in a format that
then they are uncompressed if necessary and fed to .BR xz (1)
.BR cmp (1) can decompress.
or
.BR diff (1).
The exit status from
.BR cmp (1)
or
.BR diff (1)
is preserved unless a decompression error occurs; then exit status is 2.
.PP .PP
The names If only one filename is provided,
.I file1
must have a suffix of a supported compression format and the name for
.I file2
is assumed to be
.I file1
with the compression format suffix removed.
.PP
The commands
.B lzcmp .B lzcmp
and and
.B lzdiff .B lzdiff
are provided for backward compatibility with LZMA Utils. are provided for backward compatibility with LZMA Utils.
.
.SH EXIT STATUS
If a decompression error occurs, the exit status is
.BR 2 .
Otherwise the exit status of
.BR cmp (1)
or
.BR diff (1)
is used.
.
.SH "SEE ALSO" .SH "SEE ALSO"
.BR cmp (1), .BR cmp (1),
.BR diff (1), .BR diff (1),
@ -68,11 +91,4 @@ are provided for backward compatibility with LZMA Utils.
.BR gzip (1), .BR gzip (1),
.BR bzip2 (1), .BR bzip2 (1),
.BR lzop (1), .BR lzop (1),
.BR zstd (1), .BR zstd (1)
.BR zdiff (1)
.SH BUGS
Messages from the
.BR cmp (1)
or
.BR diff (1)
programs refer to temporary filenames instead of those specified.

View file

@ -1,18 +1,18 @@
.\" SPDX-License-Identifier: GPL-2.0-or-later .\" SPDX-License-Identifier: 0BSD
.\" .\"
.\" Original zgrep.1 for gzip: Jean-loup Gailly .\" Authors: Lasse Collin
.\" Charles Levert <charles@comm.polymtl.ca> .\" Jia Tan
.\" .\"
.\" Modifications for XZ Utils: Lasse Collin .\" (Note that this file is not based on gzip's zgrep.1.)
.\" .\"
.TH XZGREP 1 "2022-07-19" "Tukaani" "XZ Utils" .TH XZGREP 1 "2024-02-12" "Tukaani" "XZ Utils"
.SH NAME .SH NAME
xzgrep \- search compressed files for a regular expression xzgrep \- search possibly-compressed files for patterns
.
.SH SYNOPSIS .SH SYNOPSIS
.B xzgrep .B xzgrep
.RI [ grep_options ] .RI [ option... ]
.RB [ \-e ] .RI [ pattern_list ]
.I pattern
.RI [ file... ] .RI [ file... ]
.br .br
.B xzegrep .B xzegrep
@ -29,54 +29,83 @@ xzgrep \- search compressed files for a regular expression
.br .br
.B lzfgrep .B lzfgrep
\&... \&...
.
.SH DESCRIPTION .SH DESCRIPTION
.B xzgrep .B xzgrep
invokes invokes
.BR grep (1) .BR grep (1)
on on uncompressed contents of files.
The formats of the
.I files .I files
which may be either uncompressed or compressed with are determined from the filename suffixes.
Any
.I file
with a suffix supported by
.BR xz (1), .BR xz (1),
.BR lzma (1),
.BR gzip (1), .BR gzip (1),
.BR bzip2 (1), .BR bzip2 (1),
.BR lzop (1), .BR lzop (1),
or or
.BR zstd (1). .BR zstd (1)
All options specified are passed directly to will be decompressed;
.BR grep (1). all other files are assumed to be uncompressed.
.PP .PP
If no If no
.I files
are specified or
.I file .I file
is specified, then standard input is decompressed if necessary is
and fed to .B \-
.BR grep (1). then standard input is read.
When reading from standard input, When reading from standard input, only files supported by
.BR gzip (1), .BR xz (1)
.BR bzip2 (1), are decompressed.
.BR lzop (1), Other files are assumed to be in uncompressed form already.
and .PP
.BR zstd (1) Most
compressed files are not supported. .I options
of
.BR grep (1)
are supported.
However, the following options are not supported:
.IP "" 4
.BR \-r ,
.B \-\-recursive
.IP "" 4
.BR \-R ,
.B \-\-dereference\-recursive
.IP "" 4
.BR \-d ,
.BI \-\-directories= action
.IP "" 4
.BR \-Z ,
.B \-\-null
.IP "" 4
.BR \-z ,
.B \-\-null\-data
.IP "" 4
.BI \-\-include= glob
.IP "" 4
.BI \-\-exclude= glob
.IP "" 4
.BI \-\-exclude\-from= file
.IP "" 4
.BI \-\-exclude\-dir= glob
.PP .PP
If
.B xzgrep
is invoked as
.B xzegrep .B xzegrep
or is an alias for
.BR "xzgrep \-E" .
.B xzfgrep .B xzfgrep
then is an alias for
.B grep \-E .BR "xzgrep \-F" .
or .PP
.B grep \-F The commands
is used instead of
.BR grep (1).
The same applies to names
.BR lzgrep , .BR lzgrep ,
.BR lzegrep , .BR lzegrep ,
and and
.BR lzfgrep , .B lzfgrep
which are provided for backward compatibility with LZMA Utils. are provided for backward compatibility with LZMA Utils.
.
.SH EXIT STATUS .SH EXIT STATUS
.TP .TP
0 0
@ -90,18 +119,19 @@ No errors occurred.
>1 >1
One or more errors occurred. One or more errors occurred.
It is unknown if matches were found. It is unknown if matches were found.
.
.SH ENVIRONMENT .SH ENVIRONMENT
.TP .TP
.B GREP .B GREP
If the If
.B GREP .B GREP
environment variable is set, is set to a non-empty value,
.B xzgrep it is used instead of
uses it instead of .BR "grep" ,
.BR grep (1),
.BR "grep \-E" , .BR "grep \-E" ,
or or
.BR "grep \-F" . .BR "grep \-F" .
.
.SH "SEE ALSO" .SH "SEE ALSO"
.BR grep (1), .BR grep (1),
.BR xz (1), .BR xz (1),

View file

@ -1,52 +1,63 @@
.\" SPDX-License-Identifier: GPL-2.0-or-later .\" SPDX-License-Identifier: 0BSD
.\" .\"
.\" Original zdiff.1 for gzip: Jean-loup Gailly .\" Authors: Andrew Dudman
.\" Modifications for XZ Utils: Lasse Collin .\" Lasse Collin
.\" .\"
.TH XZMORE 1 "2013-06-30" "Tukaani" "XZ Utils" .\" (Note that this file is based on xzless.1 instead of gzip's zmore.1.)
.\"
.TH XZMORE 1 "2024-02-12" "Tukaani" "XZ Utils"
.SH NAME .SH NAME
xzmore, lzmore \- view xz or lzma compressed (text) files xzmore, lzmore \- view xz or lzma compressed (text) files
.
.SH SYNOPSIS .SH SYNOPSIS
.B xzmore .B xzmore
.RI [ file ...] .RI [ file ...]
.br .br
.B lzmore .B lzmore
.RI [ file ...] .RI [ file ...]
.
.SH DESCRIPTION .SH DESCRIPTION
.B xzmore .B xzmore
is a filter which allows examination of displays text from compressed files to a terminal using
.BR more (1).
Files supported by
.BR xz (1) .BR xz (1)
or are decompressed;
.BR lzma (1) other files are assumed to be in uncompressed form already.
compressed text files one screenful at a time If no
on a soft-copy terminal. .I files
are given,
.B xzmore
reads from standard input.
See the
.BR more (1)
manual for the keyboard commands.
.PP .PP
To use a pager other than the default Note that scrolling backwards might not be possible
.B more, depending on the implementation of
set environment variable .BR more (1).
.B PAGER This is because
to the name of the desired program. .B xzmore
The name uses a pipe to pass the decompressed data to
.BR more (1).
.BR xzless (1)
uses
.BR less (1)
which provides more advanced features.
.PP
The command
.B lzmore .B lzmore
is provided for backward compatibility with LZMA Utils. is provided for backward compatibility with LZMA Utils.
.
.SH ENVIRONMENT
.TP .TP
.BR e " or " q .B PAGER
When the prompt \-\-More\-\-(Next file: If
.IR file ) .B PAGER
is printed, this command causes is set,
.B xzmore it's value is used as the pager instead of
to exit.
.TP
.B s
When the prompt \-\-More\-\-(Next file:
.IR file )
is printed, this command causes
.B xzmore
to skip the next file and continue.
.PP
For list of keyboard commands supported while actually viewing the
content of a file, refer to manual of the pager you use, usually
.BR more (1). .BR more (1).
.
.SH "SEE ALSO" .SH "SEE ALSO"
.BR more (1), .BR more (1),
.BR xz (1), .BR xz (1),