documentation: update project's man pages

rizsotto · rizsotto · commit ba4b173319d4 · 2021-09-04T11:42:55.000+10:00
diff --git a/source/bear/man/bear.1 b/source/bear/man/bear.1
@@ -1,17 +1,15 @@
 .\" Automatically generated by Pandoc 2.9.2.1
 .\"
-.TH "BEAR" "1" "May 10, 2019" "Bear User Manuals" ""
+.TH "BEAR" "1" "Sep 04, 2021" "Bear User Manuals" ""
 .hy
 .SH NAME
 .PP
-Bear - Build EAR
+Bear - a tool to generate compilation database for Clang tooling.
 .SH SYNOPSIS
 .PP
 bear [\f[I]options\f[R]] -- [\f[I]build command\f[R]]
 .SH DESCRIPTION
 .PP
-Bear is a tool to generate compilation database for clang tooling.
-.PP
 The JSON compilation database
 <http://clang.llvm.org/docs/JSONCompilationDatabase.html> is used in
 Clang project to provide information how a single compilation unit was
@@ -84,7 +82,29 @@ file name to \f[C]citnames\f[R].
 .SH EXIT STATUS
 .PP
 The exit status of the program is the exit status of the build command.
-Except when the program itself crashes, then it sets to non zero.
+Except when the program itself crashes, then it sets to non-zero.
+.SH TROUBLESHOOTING
+.PP
+The potential problems you can face with are: the build with and without
+Bear behaves differently or the output is empty.
+.PP
+The most common cause for empty outputs is that the build command did
+not execute any commands.
+The reason for that could be, because incremental builds not running the
+compilers if everything is up-to-date.
+Remember, Bear does not understand the build file (eg.: makefile), but
+intercepts the executed commands.
+.PP
+The other common cause for empty output is that the build has a
+\[lq]configure\[rq] step, which captures the compiler to build the
+project.
+In case of Bear is using the \f[I]wrapper\f[R] mode (read
+\f[C]intercept\f[R] man page), it needs to run the configure step with
+Bear too (and discard that output), before run the build with Bear.
+.PP
+There could be many reasons for any of these failures.
+It\[cq]s better to consult with the project wiki page for known
+problems, before open a bug report.
 .SH SEE ALSO
 .PP
 intercept(1), citnames(1)
diff --git a/source/bear/man/bear.1.md b/source/bear/man/bear.1.md
@@ -1,19 +1,17 @@
 % BEAR(1) Bear User Manuals
 % László Nagy
-% Dec 14, 2020
+% Sep 04, 2021
 
 # NAME
 
-Bear - Build EAR
+Bear - a tool to generate compilation database for Clang tooling.
 
 # SYNOPSIS
 
 bear [*options*] \-\- [*build command*]
 
 # DESCRIPTION
 
-Bear is a tool to generate compilation database for clang tooling.
-
 The JSON compilation database
 <http://clang.llvm.org/docs/JSONCompilationDatabase.html> is used in
 Clang project to provide information how a single compilation unit
@@ -79,13 +77,33 @@ version of Bear generates entries where:
 
 # CONFIG FILE
 
-Read `citnames` man page for the content of this file. `bear` is not reading the
-content of this file, but passing the file name to `citnames`.
+Read `citnames` man page for the content of this file. `bear` is not reading
+the content of this file, but passing the file name to `citnames`.
 
 # EXIT STATUS
 
 The exit status of the program is the exit status of the build command.
-Except when the program itself crashes, then it sets to non zero.
+Except when the program itself crashes, then it sets to non-zero.
+
+# TROUBLESHOOTING
+
+The potential problems you can face with are: the build with and without Bear
+behaves differently or the output is empty.
+
+The most common cause for empty outputs is that the build command did not
+execute any commands. The reason for that could be, because incremental builds
+not running the compilers if everything is up-to-date. Remember, Bear does not
+understand the build file (eg.: makefile), but intercepts the executed
+commands.
+
+The other common cause for empty output is that the build has a "configure"
+step, which captures the compiler to build the project. In case of Bear is
+using the _wrapper_ mode (read `intercept` man page), it needs to run the
+configure step with Bear too (and discard that output), before run the build
+with Bear.
+
+There could be many reasons for any of these failures. It's better to consult
+with the project wiki page for known problems, before open a bug report.
 
 # SEE ALSO
 
diff --git a/source/citnames/man/citnames.1 b/source/citnames/man/citnames.1
@@ -1,10 +1,10 @@
 .\" Automatically generated by Pandoc 2.9.2.1
 .\"
-.TH "CITNAMES" "1" "Jun 19, 2021" "Bear User Manuals" ""
+.TH "CITNAMES" "1" "Sep 04, 2021" "Bear User Manuals" ""
 .hy
 .SH NAME
 .PP
-citnames - Deduce command semantic
+citnames - deduce command semantic
 .SH SYNOPSIS
 .PP
 citnames [\f[I]options\f[R]] --input <file> --output <file>
@@ -65,15 +65,15 @@ The configuration file captures how the output should be formatted and
 which entries it shall contain.
 .SH EXIT STATUS
 .PP
-Citnames exit status is non zero in case of IO problems, otherwise
+Citnames exit status is non-zero in case of IO problems, otherwise
 it\[cq]s zero.
-The exit status is independent from how many command it recognized or
-was it recognized at all.
+The exit status is independent of how many command it recognized or was
+it recognized at all.
 .SH OBSERVABILITY
 .PP
 Any insight about the command recognition logic can be observed with
 \f[C]--verbose\f[R] flag on the standard error.
-Otherwise the command is silent.
+Otherwise, the command is silent.
 .SH INPUT FILE
 .PP
 It\[cq]s a JSON file, with the command execution history.
@@ -85,7 +85,7 @@ Read more about the syntax of the file in the \f[C]intercept\f[R] man
 page.
 .SH OUTPUT FILE
 .PP
-Currently the only output format is the JSON compilation database.
+Currently, the only output format is the JSON compilation database.
 Read more about the syntax of that in the \f[C]bear\f[R] man page.
 .SH CONFIG FILE
 .PP
diff --git a/source/citnames/man/citnames.1.md b/source/citnames/man/citnames.1.md
@@ -1,10 +1,10 @@
 % CITNAMES(1) Bear User Manuals
 % László Nagy
-% Jun 19, 2021
+% Sep 04, 2021
 
 # NAME
 
-citnames - Deduce command semantic
+citnames - deduce command semantic
 
 # SYNOPSIS
 
@@ -61,14 +61,14 @@ is currently the only output of the tool.)
 
 # EXIT STATUS
 
-Citnames exit status is non zero in case of IO problems, otherwise it's zero.
-The exit status is independent from how many command it recognized or was
+Citnames exit status is non-zero in case of IO problems, otherwise it's zero.
+The exit status is independent of how many command it recognized or was
 it recognized at all.
 
 # OBSERVABILITY
 
 Any insight about the command recognition logic can be observed with `--verbose`
-flag on the standard error. Otherwise the command is silent.
+flag on the standard error. Otherwise, the command is silent.
 
 # INPUT FILE
 
@@ -81,7 +81,7 @@ Read more about the syntax of the file in the `intercept` man page.
 
 # OUTPUT FILE
 
-Currently the only output format is the JSON compilation database.
+Currently, the only output format is the JSON compilation database.
 Read more about the syntax of that in the `bear` man page. 
 
 # CONFIG FILE
diff --git a/source/intercept/man/intercept.1 b/source/intercept/man/intercept.1
@@ -1,6 +1,6 @@
 .\" Automatically generated by Pandoc 2.9.2.1
 .\"
-.TH "INTERCEPT" "1" "Jul 11, 2021" "Bear User Manuals" ""
+.TH "INTERCEPT" "1" "Sep 04, 2021" "Bear User Manuals" ""
 .hy
 .SH NAME
 .PP
@@ -79,16 +79,16 @@ the interception behaves differently (eg.: the build crash with the
 The output is empty, and it failed to intercept the children process
 execution by the build command.
 .PP
-There could be many reasons for any of these failures.
-It\[cq]s better to consult with the project wiki page for known
-problems, before open a bug report.
-.PP
 The most common cause for empty outputs is that the build command did
 not execute any commands.
 The reason for that could be, because incremental builds not running the
-compilers if everything is up to date.
-Remember, \f[C]intercept\f[R] is not understanding the build file (eg.:
+compilers if everything is up-to-date.
+Remember, \f[C]intercept\f[R] does not understand the build file (eg.:
 makefile), but intercepts the executed commands.
+.PP
+There could be many reasons for any of these failures.
+It\[cq]s better to consult with the project wiki page for known
+problems, before open a bug report.
 .SH SEE ALSO
 .PP
 bear(1)
diff --git a/source/intercept/man/intercept.1.md b/source/intercept/man/intercept.1.md
@@ -1,6 +1,6 @@
 % INTERCEPT(1) Bear User Manuals
 % László Nagy
-% Jul 11, 2021
+% Sep 04, 2021
 
 # NAME
 
@@ -78,15 +78,15 @@ interception behaves differently (eg.: the build crash with the `intercept`
 tool, but succeed otherwise). The output is empty, and it failed to intercept
 the children process execution by the build command.
 
-There could be many reasons for any of these failures. It's better to consult
-with the project wiki page for known problems, before open a bug report.
-
 The most common cause for empty outputs is that the build command did not
 execute any commands. The reason for that could be, because incremental builds
-not running the compilers if everything is up to date. Remember, `intercept`
-is not understanding the build file (eg.: makefile), but intercepts the executed
+not running the compilers if everything is up-to-date. Remember, `intercept`
+does not understand the build file (eg.: makefile), but intercepts the executed
 commands.
 
+There could be many reasons for any of these failures. It's better to consult
+with the project wiki page for known problems, before open a bug report.
+
 # SEE ALSO
 
 bear(1)
