Update documentation for new exit codes

Some creative writing in both README and manpage.

README.md

@@ -108,19 +108,23 @@ This weirdness is tracked in [issue 100](https://github.com/include-what-you-use
 
 The original design was built for Make, but a number of alternative run modes have come up over the years.
 
-#### Plugging into Make ####
+#### Running on single source file ####
 
-The easiest way to run IWYU over your codebase is to run
+The simplest way to use IWYU is to run it against a single source file:
 
-      make -k CXX=/path/to/llvm/Debug+Asserts/bin/include-what-you-use
+      include-what-you-use $CXXFLAGS myfile.cc
 
-or
+where `$CXXFLAGS` are the flags you would normally pass to the compiler.
 
-      make -k CXX=/path/to/llvm/Release/bin/include-what-you-use
+#### Plugging into existing build system ####
 
-(include-what-you-use always exits with an error code, so the build system knows it didn't build a .o file.  Hence the need for `-k`.)
+Typically there is already a build system containing the relevant compiler flags for all source files. Replace your compiler with `include-what-you-use` to generate a large batch of IWYU advice. Depending on your build system/build tools, this can take many forms, but for a simple GNU Make system it might look like this:
 
-Include-what-you-use only analyzes .cc (or .cpp) files built by `make`, along with their corresponding .h files.  If your project has a .h file with no corresponding .cc file, IWYU will ignore it unless you use the `--check_also` switch to add it for analysis together with a .cc file.
+      make -k CXX=include-what-you-use CXXFLAGS="-Xiwyu --error_always"
+
+(The additional `-Xiwyu --error_always` switch makes `include-what-you-use` always exit with an error code, so the build system knows it didn't build a .o file.  Hence the need for `-k`.)
+
+In this mode `include-what-you-use` only analyzes the .cc (or .cpp) files known to your build system, along with their corresponding .h files.  If your project has a .h file with no corresponding .cc file, IWYU will ignore it unless you use the `--check_also` switch to add it for analysis together with a .cc file. It is possible to run IWYU against individual header files, provided the compiler flags are carefully constructed to match all includers.
 
 #### Using with CMake ####
 
@@ -170,7 +174,7 @@ See `iwyu_tool.py --help` for more options.
 
 We also include a tool that automatically fixes up your source files based on the IWYU recommendations.  This is also alpha-quality software!  Here's how to use it (requires python):
 
-      make -k CXX=/path/to/llvm/Debug+Asserts/bin/include-what-you-use 2> /tmp/iwyu.out
+      make -k CXX=include-what-you-use CXXFLAGS="-Xiwyu --error_always" 2> /tmp/iwyu.out
       python fix_includes.py < /tmp/iwyu.out
 
 If you don't like the way `fix_includes.py` munges your `#include` lines, you can control its behavior via flags. `fix_includes.py --help` will give a full list, but these are some common ones:

include-what-you-use.1

@@ -4,7 +4,7 @@
 .\" This file is distributed under the University of Illinois Open Source
 .\" License. See LICENSE.TXT for details.
 .\"
-.TH INCLUDE-WHAT-YOU-USE 1 "2019-11-02" include-what-you-use "User Commands"
+.TH INCLUDE-WHAT-YOU-USE 1 "2022-02-21" include-what-you-use "User Commands"
 .SH NAME
 include-what-you-use \- analyze includes in C and C++ source files.
 .SH SYNOPSIS
@@ -47,6 +47,18 @@ This flag may be specified multiple times to specify multiple glob patterns.
 .B \-\-cxx17ns
 Suggest the more concise syntax for nested namespaces introduced in C++17.
 .TP
+.BI \-\-error [=N]
+Exit with error code
+.IR N
+(defaults to 1 if omitted) if there are \(lqinclude-what-you-use\(rq
+violations.
+.TP
+.BI \-\-error_always [=N]
+Exit with error code
+.IR N
+(defaults to 1 if omitted) whether there are \(lqinclude-what-you-use\(rq
+violations or not (for use with \fBmake(1)\fR).
+.TP
 .BI \-\-keep= glob
 Always keep the includes matched by
 .IR glob .
@@ -113,10 +125,16 @@ is already visible in the file's transitive includes.
 Set verbosity. At the highest level, this will dump the AST of the source file
 and explain all decisions.
 .SH EXIT STATUS
+By default
 .B include-what-you-use
-always returns with a nonzero status code to make usage with
-.BR make (1)
-feasible.
+exits with zero exit code unless there's a critical error, but
+.B \-\-error
+or
+.B \-\-error_always
+can be used to customize the exit code depending on invoker expectations.
+See
+.IR EXAMPLE\fR.
+
 .SH MAPPING FILES
 Sometimes headers are not meant to be included directly,
 and sometimes headers are guaranteed to include other headers.
@@ -240,18 +258,22 @@ issue tracker
 .UE
 on GitHub.
 .SH EXAMPLE
-The easiest way to run
+It is possible to put
 .B include-what-you-use
-over your codebase is to run
+in place of your compiler to process all source files known to your build system
 .PP
 .RS
 .EX
-make \-k CC=include-what-you-use CXX=include-what-you-use
+make \-k CC=include-what-you-use CFLAGS="-Xiwyu --error_always"
+.EE
+
+.EX
+make \-k CXX=include-what-you-use CXXFLAGS="-Xiwyu --error_always"
 .EE
 .RE
 .PP
-The program always exits with an error code, so the build system knows that it
-didn't build an object file. Hence the need for
+With \fB-Xiwyu --error_always\fR the program always exits with an error code, so
+the build system knows that it didn't build an object file. Hence the need for
 .BR -k .
 It only analyzes source files built by
 .BR make (1)