.\" Copyright (c) 2003 The Anarcat
.\" 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: src/share/examples/mdoc/example.1,v 1.12.2.6 2001/08/17 13:08:35 ru Exp $
.\"
.\" Note: The date here should be updated whenever a non-trivial
.\" change is made to the manual page.
.Dd August 27, 2003
.Dt WHEREINTHEWORLD 8
.Os
.Sh NAME
.Nm whereintheworld
.Nd "print summary of make world logs"
.Sh SYNOPSIS
.Nm
.Op Pa file
.Sh DESCRIPTION
The
.Nm
command is a simple filter that reads the output of a make world and
outputs only the important status lines, skipping all the compilation
commands. The result is a terse summary of where the compilation is at
now.
.Pp
.Nm
can be run against an existing
.Pa file
or it can simply read from stdin. It will continue reading from the
pipe or the
.Pa file
until EOF at which point it will print out the few last lines of the
log.
.Sh IMPLEMENTATION NOTES
.Nm
expects the build log to be in a certain format. In particular, it
recognizes lines starting with repeating dashes as ''section
delimiters''. Lines starting with ''>>>'' will be considered as the
names of the sections. Lines starting with ''===>'' are considered to
be modules being build in the section, and will be printed on screen,
but always on the same line so that they don't make the screen scroll
endlessly.
.Pp
See the
.Sx EXAMPLES
section for output samples.
.Pp
.Nm
is written in Perl and therefore will need an installed 
.Xr perl 1
interpreter to run. It has been tested on 5.00503 and 5.6.1.
.Sh FILES
.Bl -tag -width ".Pa /usr/src/world.out" -compact
.It Pa /usr/src/world.out
.Nm
will first try to open this file if started without argument. If
missing, it will read stdin.
.El
.Sh EXAMPLES
The most simple incantation would be:
.Pp
.Dl "whereintheworld"
.Pp
A more typical usage of the
.Nm
command:
.Pp
.Dl "make world 2>&1 | tee /var/log/build.log | whereintheworld"
.Pp
If you lost this terminal for one reason or another, the display can
be restarted, with a little pipe magic:
.Pp
.Dl "(cat build.log && tail -f build.log ) | whereintheworld"
.Pp
The live output will look something like this:
.Bd -unfilled
--------------------------------------------------------------
>>> Rebuilding the temporary build tree
--------------------------------------------------------------
>>> stage 1: bootstrap tools
--------------------------------------------------------------
===> gnu/usr.bin/groff/font/devlatin1
.Ed
.Pp
with the last line changing as a new module is compiled.
.Sh DIAGNOSTICS
Should be self-explanatory.
.Sh COMPATIBILITY
The
.Nm
command has been written to parse make world logs for
.Fx
3.x, but it should work with about any version, provided the
.Fx
folks do not change the output format too much.
.Sh SEE ALSO
.Pa /usr/src/README ,
.Xr tee 1 ,
.Xr cat 1 ,
.Xr tail 1 .
.Pp
http://www.FreeBSD.org/handbook/makeworld.html
.Sh HISTORY
The
.Nm
manual page example first appeared in worldtools 1.2.
.Sh AUTHORS
This manual page was written by
.An The Anarcat Aq anarcat@anarcat.ath.cx .
The
.Nm
command was written by
.An Bill Fenner Aq fenner@freebsd.org
in January 2000 and was modified by
.An The Anarcat Aq anarcat@anarcat.ath.cx
to output modules without scrolling.
.Sh BUGS
The
.Nm
command is written in
.Xr perl 1
and therefore cannot be included in the
base
.Fx
system.