.\" Copyright (c) 2007 Giorgos Keramidas <keramida@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd July 9, 2008
.Dt CHECKUPDATE 1
.Os
.Sh NAME
.Nm checkupdate
.Nd "check a translation of the FreeBSD doc/ tree for source updates"
.Sh SYNOPSIS
.Nm
.Op Fl acenpPqtv
.Op Fl R Ar workspace
.Sh DESCRIPTION
The
.Nm
utility checks a translation of the FreeBSD
.Pa "doc/"
tree for source updates, i.e.\& changes in their original English source
files which may be interesting to merge.
.Pp
The list of files to check can be specified in the command-line of the
.Nm
utility, or it can be fed to the script through its standard input
stream.
.Pp
The number of checks performed, and the format of the script output are
controlled by command-line options.
.Pp
The options are as follows:
.Bl -tag -width ".Fl f Ar flist"
.It Fl a
Enable all file checks for each input file.
.It Fl c
Generate compact report primarily suitable for commit logs.  It will
only contain revision difference information and names of the affected
files.  This will automatically disable
.Dq patch preview
mode.
.It Fl e
Report everything.
File revision information is displayed for all the files of our input
list, and not just the files that actually need to be updated.
.It Fl n
Disable all file checks.
.It Fl p
Run in
.Dq patch preview
mode.
Whenever a difference is found in the revisions of the original
translated file and the current English revision, show a patch of the
untranslated changes.
.It Fl P
Do not be so
.Dq picky
and show all the information even if files do not contain tags.  It is
disabled by default and it is not recommended to use.
.It Fl q
Run in
.Dq quiet
mode.
No status messages are printed in the standard error stream of the
script, and if there are no updates to show its standard output shows
nothing at all.
This mode is useful for
.Xr crontab 5
entries, where it's ok to run without any output at all, to avoid
spurious email messages from
.Xr cron 8 .
.It Fl R Ar workspace
Switch to another
.Ar workspace
path before checking file translation updates.
The
.Nm
script assumes that it runs in the toplevel directory of the
.Fx
.Pa doc/
tree.
If this is not true, then the
.Fl R
option should be used to point to the toplevel directory of the
.Pa doc/
tree.
.It Fl t
Run in
.Dq tuple mode .
This option implies
.Fl e
too.
When the script runs in tuple mode it prints Python tuples with the file
information it collects for all the files, instead of parsing and
presenting the information in human readable format.
This may be a bit useful for post-processing the output of the script to
generate output in different ways.
.It Fl v
Bump verbosity level.
The
.Nm
script runs in
.Dq quiet mode
by default.
The
.Fl v
option increases the verbosity level, and it can be used multiple times
for extra verbosity.
.El
.Sh EXIT STATUS
.Ex -std
.Sh SEE ALSO
.Xr python 1 ,
.Xr crontab 5 ,
.Xr cron 8
.Sh HISTORY
The
.Nm
utility first appeared in
.Fx 7.0 .
.Sh AUTHORS
This manual page was written by
.An Giorgos Keramidas Aq keramida@FreeBSD.org .
.Sh BUGS
The actual code for this utility is vaporware.