[doc] Use sentence-case for headings

The use of title-case feels dated and is harder to get right consistently.

Rewrite all headings to plain sentence-case.

CONTRIBUTING.md

@@ -1,6 +1,6 @@
-# Instructions for Developers #
+# Instructions for developers #
 
-## Submitting Patches ##
+## Submitting patches ##
 
 We welcome patches and rely on your contributions to make IWYU smarter.
 
@@ -10,7 +10,7 @@ Use GitHub's [pull request system](https://github.com/include-what-you-use/inclu
 
 It's usually a good idea to run ideas by the [IWYU mailing list](http://groups.google.com/group/include-what-you-use) to get general agreement on directions before you start hacking.
 
-## Running the Tests ##
+## Running the tests ##
 
 If fixing a bug in IWYU, please add a test to the test suite!  You can create a file called `whatever.cc` (_not_ .cpp), and, if necessary, `whatever.h`, and `whatever-<extension>.h`.  You may be able to get away without adding any `.h` files, and just including `direct.h` -- see, for instance, `tests/remove_fwd_decl_when_including.cc`.
 
@@ -42,7 +42,7 @@ It's possible to run include-what-you-use in `gdb`, to debug that way. Another u
 
     env IWYU_VERBOSE=7 make -k CXX=/path/to/llvm/Debug+Asserts/bin/include-what-you-use 2>&1 > /tmp/iwyu.verbose
 
-## A Quick Tour of the Codebase ##
+## A quick tour of the codebase ##
 
 The codebase is strewn with TODOs of known problems, and also language constructs that aren't adequately tested yet.  So there's plenty to do!  Here's a brief guide through the codebase:
 

README.md

@@ -4,7 +4,7 @@
 
 For more in-depth documentation, see [docs](docs).
 
-## Instructions for Users ##
+## Instructions for users ##
 
 "Include what you use" means this: for every symbol (type, function, variable, or macro) that you use in `foo.cc` (or `foo.cpp`), either `foo.cc` or `foo.h` should include a .h file that exports the declaration of that symbol. (Similarly, for `foo_test.cc`, either `foo_test.cc` or `foo.h` should do the including.)  Obviously symbols defined in `foo.cc` itself are excluded from this requirement.
 
@@ -16,7 +16,7 @@ This is alpha quality software -- at best (as of July 2018).  It was originally
 
 While we work to get IWYU quality up, we will be stinting new features, and will prioritize reported bugs along with the many existing, known bugs.  The best chance of getting a problem fixed is to submit a patch that fixes it (along with a test case that verifies the fix)!
 
-### How to Build ###
+### How to build ###
 
 Include-what-you-use makes heavy use of Clang internals, and will occasionally break when Clang is updated. Usually such discrepancies are detected by build bot and fixed promptly.
 
@@ -91,7 +91,7 @@ To set up an environment for building:
 
 Instructions for building Clang are available at <https://clang.llvm.org/get_started.html>.
 
-### How to Install ###
+### How to install ###
 
 If you're building IWYU out-of-tree or installing pre-built binaries, you need to make sure it can find Clang built-in headers (`stdarg.h` and friends.)
 
@@ -105,7 +105,7 @@ So for IWYU to function correctly, you need to copy the Clang `include` director
 
 This weirdness is tracked in [issue 100](https://github.com/include-what-you-use/include-what-you-use/issues/100), hopefully we can make this more transparent over time.
 
-### How to Run ###
+### How to run ###
 
 The original design was built for Make, but a number of alternative run modes have come up over the years.
 
@@ -183,7 +183,7 @@ If you don't like the way `fix_includes.py` munges your `#include` lines, you ca
 * `-b`: Put blank lines between system and Google includes
 * `--nocomments`: Don't add the 'why' comments next to includes
 
-### How to Correct IWYU Mistakes ###
+### How to correct IWYU mistakes ###
 
 * If `fix_includes.py` has removed an `#include` you actually need, add it back in with the comment '`// IWYU pragma: keep`' at the end of the `#include` line.  Note that the comment is case-sensitive.
 * If `fix_includes.py` has added an `#include` you don't need, just take it out.  We hope to come up with a more permanent way of fixing later.

docs/IWYUMappings.md

@@ -1,4 +1,4 @@
-# IWYU Mappings #
+# IWYU mappings #
 
 One of the difficult problems for IWYU is distinguishing between which header contains a symbol definition and which header is the actual documented header to include for that symbol.
 
@@ -12,11 +12,11 @@ However, many mappings are toolchain- and version-dependent. Symbol homes and `#
 
 Any mappings outside of the default set can therefore be specified as external *mapping files*.
 
-## Default Mappings ##
+## Default mappings ##
 
 IWYU's default mappings are hard-coded in `iwyu_include_picker.cc`, and are very GCC-centric. There are both symbol- and include mappings for GNU libstdc++ and libc.
 
-## Mapping Files ##
+## Mapping files ##
 
 The mapping files conventionally use the `.imp` file extension, for "Iwyu MaPping" (terrible, I know). They use a [JSON](http://json.org/) meta-format with the following general form:
 
@@ -42,7 +42,7 @@ IWYU uses LLVM's YAML/JSON parser to interpret the mapping files, and it has som
 
 If the YAML parser is ever made more rigorous, it might be wise not to lean on non-standard behavior, so apart from comment style, try to keep mapping files in line with the JSON spec.
 
-### Include Mappings ###
+### Include mappings ###
 
 The `include` directive specifies a mapping between two include names (relative path, including quotes or angle brackets.)
 
@@ -67,7 +67,7 @@ Include mappings support a special wildcard syntax for the first entry:
 
 The `@` prefix is a signal that the remaining content is a regex, and can be used to re-map a whole subdirectory of private headers to a public facade header.
 
-### Symbol Mappings ###
+### Symbol mappings ###
 
 The `symbol` directive maps from a qualified symbol name to its authoritative header.
 
@@ -86,7 +86,7 @@ The symbol visibility is largely redundant -- it must always be `private`. It is
 
 Unlike `include`, `symbol` directives do not support the `@`-prefixed regex syntax in the first entry. Track the [following bug](https://github.com/include-what-you-use/include-what-you-use/issues/233) for updates.
 
-### Mapping Refs ###
+### Mapping refs ###
 
 The last kind of directive, `ref`, is used to pull in another mapping file, much like the C preprocessor's `#include` directive. Data for this directive is a single string: the filename to include.
 
@@ -97,7 +97,7 @@ For example;
 
 The rationale for the `ref` directive was to make it easier to compose project-specific mappings from a set of library-oriented mapping files. For example, IWYU might ship with mapping files for [Boost](http://www.boost.org), the SCL, various C standard libraries, the Windows API, the [Poco Library](http://pocoproject.org), etc. Depending on what your specific project uses, you could easily create an aggregate mapping file with refs to the relevant mappings.
 
-### Specifying Mapping Files ###
+### Specifying mapping files ###
 
 Mapping files are specified on the command-line using the `--mapping_file` switch:
 

docs/IWYUStyle.md

@@ -1,4 +1,4 @@
-# IWYU Coding Style #
+# IWYU coding style #
 
 IWYU is developed by a small number of loosely knit maintainers, and we rely on
 external contributions to stand a chance to improve the tool.

docs/WhatIsAUse.md

@@ -1,4 +1,4 @@
-# What Is a Use? #
+# What is a use? #
 
 (*Disclaimer:* the information here is accurate as of 12 May 2011, when it was written.  Specifics of IWYU's policy, and even philosophy, may have changed since then.  We'll try to remember to update this file as that happens, but may occasionally forget.  The further we are from May 2011, the more you should take the below with a grain of salt.)
 
@@ -21,7 +21,7 @@ Does `bar.cc` "use" `std::ostream`, such that it should `#include <ostream>`?  Y
 
 But IWYU doesn't (at least, modulo bugs).  This is because of its attempt to analyze "author intent".
 
-## Author Intent ##
+## Author intent ##
 
 If code has `typedef Foo MyTypedef`, and you write `MyTypedef var;`, you are using `MyTypedef`, but are you also using `Foo`?  The answer depends on the _intent_ of the person who wrote the typedef.
 
@@ -46,7 +46,7 @@ Another case where author intent turns up is in function return types.  Consider
 
 If you write `GetSingletonObject()->methodOnFoo()`, are you "using" `Foo::methodOnFoo`, such that you should `#include "foo.h"`?  Or are you supposed to be able to operate on the results of `GetSingletonObject` without needing to include the definition of the returned type?  The answer is: it depends on the author intent.  Sometimes the author is willing to provide the definition of the return type, sometimes it is not.
 
-### Re-Exporting ###
+### Re-exporting ###
 
 When the author of a file is providing a definition of a symbol from somewhere else, we say that the file is "re-exporting" that symbol.  In the first `OutputEmitter` example, we say that `foo.h` is re-exporting `ostream`.  As a result, people who `#include "foo.h"` get a definition of `ostream` along for free, even if they don't directly `#include <ostream>` themselves.  Another way of thinking about it is: if file A re-exports symbol B, we can pretend that A defines B, even if it doesn't.
 
@@ -95,7 +95,7 @@ If IWYU says you intend to re-export the underlying type, then nobody who uses y
 
 IWYU supports this in its analysis.  If you are using `Typedef1` in your code and `#include "foo.h"` anyway, IWYU will suggest you remove it, since you are getting the definition of `Foo` via the typedef.
 
-### Automatic re-export: Function return values ###
+### Automatic re-export: function return values ###
 
 The same rule applies with the return value in a function declaration:
 
@@ -136,7 +136,7 @@ Here is an example of the rule in action:
 
 In this case, IWYU will say that `baz.cc` does not need to `#include "foo.h"`, since `bar.h` re-exports it.
 
-### Automatic re-export: Conversion constructors ###
+### Automatic re-export: conversion constructors ###
 
 Consider the following code:
 

docs/WhyIWYU.md

@@ -1,20 +1,20 @@
-# Why Include What You Use? #
+# Why include what you use? #
 
 Are there any concrete benefits to a strict include-what-you-use policy? We like to think so.
 
-## Faster Compiles ##
+## Faster compiles ##
 
 Every .h file you bring in when compiling a source file lengthens the time to compile, as the bytes have to be read, preprocessed, and parsed.  If you're not actually using a .h file, you remove that cost.  With template code, where entire instantiations have to be in .h files, this can be hundreds of thousands of bytes of code.  In one case at Google, running include-what-you-use over a .cc file improved its compile time by 30%.
 
 Here, the main benefit of include-what-you-use comes from the flip side: "don't include what you don't use."
 
-## Fewer Recompiles ##
+## Fewer recompiles ##
 
 Many build tools, such as `make`, provide a mechanism for automatically figuring out what .h files a .cc file depends on.  These mechanisms typically look at `#include` lines.  When unnecessary `#includes` are listed, the build system is more likely to recompile in cases where it's not necessary.
 
 Again, the main advantage here is from "don't include what you don't use."
 
-## Allow Refactoring ##
+## Allow refactoring ##
 
 Suppose you refactor `foo.h` so it no longer uses vectors.  You'd like to remove `#include <vector>` from `foo.h`, to reduce compile time -- template class files such as `vector` can include a lot of code.  But can you?  In theory yes, but in practice maybe not: some other file may be #including you and using vectors, and depending (probably unknowingly) on your `#include <vector>` to compile.  Your refactor could break code far away from you.
 
@@ -30,13 +30,13 @@ The 'commented' `#include` lines can also make it simpler to match function call
 
 (The downside, of course, is the comments can get out of date as the code changes, so unless you run IWYU often, you still have to take the comments with a grain of salt.  Nothing is free. :-) )
 
-## Dependency Cutting ##
+## Dependency cutting ##
 
 Again, this makes the most sense for large code-bases.  Suppose your binaries are larger than you would expect, and upon closer examination use symbols that seem totally irrelevant.  Where do they come from?  Why are they there?  With include-what-you-use, you can easily determine this by seeing who includes the files that define these symbols: those includers, and those alone, are responsible for the use.
 
 Once you know where a symbol is used in your binary, you can see how practical it is to remove that use, perhaps by breaking up the relevant .h files into two parts, and fixing up all callers.  Again it's IWYU to the rescue: with include-what-you-use, figuring out the callers that need fixing is easy.
 
-## Why Forward-Declare? ##
+## Why forward-declare? ##
 
 Include-what-you-use tries very hard to figure out when a forward-declare can be used instead of an `#include` (IWYU would be about 90% less code if it didn't bother with trying to forward-declare).
 

docs/WhyIWYUIsDifficult.md

@@ -1,10 +1,10 @@
-# Why Include What You Use Is Difficult #
+# Why include-what-you-use is difficult #
 
 This section is informational, for folks who are wondering why include-what-you-use requires so much code and yet still has so many errors.
 
 Include-what-you-use has the most problems with templates and macros. If your code doesn't use either, IWYU will probably do great. And, you're probably not actually programming in C++...
 
-## Use Versus Forward Declare ##
+## Use versus forward declare ##
 
 Include-what-you-use has to be able to tell when a symbol is being used in a way that you can forward-declare it. Otherwise, if you wrote
 
@@ -29,7 +29,7 @@ But that's not enough: when instantiating the templates, we need to keep track o
 
 In this case, the caller of `MyFunc` is not using the full type of `MyClass`, because the template parameter is only used as a pointer. On the other hand, the file that defines `MyFunc` is using the full type information for `MyClass`. The end result is that the caller can forward-declare `MyClass`, but the file defining `MyFunc` has to `#include "myclass.h"`.
 
-## Handling Template Arguments ##
+## Handling template arguments ##
 
 Even figuring out what types are 'used' with a template can be difficult. Consider the following two declarations:
 
@@ -52,7 +52,7 @@ Even normal template arguments can be confusing. Consider this templated functio
 
 and you call `MyFunc(FunctionReturningAFunctionPointer())`. What types are being used where, in this case?
 
-## Who is Responsible for Dependent Template Types? ##
+## Who is responsible for dependent template types? ##
 
 If you say `vector<MyClass> v;`, it's clear that you, and not `vector.h` are responsible for the use of `MyClass`, even though all the functions that use `MyClass` are defined in `vector.h`. (OK, technically, these functions are not "defined" in a particular location, they're instantiated from template methods written in `vector.h`, but for us it works out the same.)
 
@@ -76,7 +76,7 @@ In C++, `strchr` is a templatized function (different impls for `char*` and `con
 
 As you can imagine, distinguishing all these cases is extremely difficult. To get it exactly right would require re-implementing C++'s (byzantine) lookup rules, which we have not yet tackled.
 
-## Template Template Types ##
+## Template template types ##
 
 Let's say you have a function
 
@@ -107,7 +107,7 @@ Not only is the template argument `hash_map` instead of `MyMap`, it includes all
 
 It's no surprise macros cause a huge problem for include-what-you-use. Basically, all the problems of templates also apply to macros, but worse: with templates you can analyze the uninstantiated template, but with macros, you can't analyze the uninstantiated macro -- it likely doesn't even parse cleanly in isolation. As a result, we have very few tools to distinguish when the author of a macro is responsible for a symbol used in a macro, and when the caller of the macro is responsible.
 
-## Includes with Side Effects ##
+## Includes with side effects ##
 
 While not a major problem, this indicates the myriad "gotchas" that exist around include-what-you-use: removing an `#include` and replacing it with a forward-declare may be dangerous even if no symbols are fully used from the `#include`.  Consider the following code:
 
@@ -129,7 +129,7 @@ Another case is a header file like this:
 
 We might think we can remove an `#include` of `foo.h` and replace it by `#include "module_writer.h"`, but that is likely to break the build if `module_writer.h` requires `MODULE_NAME` be defined.  Since my file doesn't participate in this dependency at all, it won't even notice it.  IWYU needs to keep track of dependencies between files it's not even trying to analyze!
 
-## Private Includes ##
+## Private includes ##
 
 Suppose you write `vector<int> v;`. You are using vector, and thus have to `#include <vector>`. Even this seemingly easy case is difficult, because vector isn't actually defined in `<vector>`; it's defined in `<bits/stl_vector.h>`. The C++ standard library has hundreds of private files that users are not supposed to `#include` directly. Third party libraries have hundreds more.  There's no general way to distinguish private from public headers; we have to manually construct the proper mapping.
 
@@ -137,7 +137,7 @@ In the future, we hope to provide a way for users to annotate if a file is publi
 
 The mappings themselves can be ambiguous. For instance, `NULL` is provided by many files, including `stddef.h`, `stdlib.h`, and more. If you use `NULL`, what header file should IWYU suggest? We have rules to try to minimize the number of `#includes` you have to add; it can get rather involved.
 
-## Unparsed Code ##
+## Unparsed code ##
 
 Conditional `#includes` are a problem for IWYU when the condition is false:
 
@@ -156,7 +156,7 @@ Conditional `#includes` are a problem for IWYU when the condition is false:
 
 If you're running IWYU without that preprocessor definition set, it has no way of telling if `verbose_logger.h` is a necessary `#include` or not.
 
-## Placing New Includes and Forward-Declares ##
+## Placing new includes and forward-declares ##
 
 Figuring out where to insert new `#includes` and forward-declares is a complex problem of its own (one that is the responsibility of `fix_includes.py`). In general, we want to put new `#includes` with existing `#includes`. But the existing `#includes` may be broken up into sections, either because of conditional `#includes` (with `#ifdefs`), or macros (such as `#define __GNU_SOURCE`), or for other reasons. Some forward-declares may need to come early in the file, and some may prefer to come later (after we're in an appropriate namespace, for instance).