csgrep.1: add example explaining what checker/evt/msg are

... and move the description of available modes into the man page only

Suggested-by: Petr Špaček

Author: kdudka

CMakeLists.txt

@@ -109,10 +109,16 @@ endif()
 
 # macro to generate a man page from the corresponding binary
 macro(create_manpage BINARY)
+    set(H2M_INCLUDE "${CMAKE_CURRENT_SOURCE_DIR}/${BINARY}.h2m")
+    if(EXISTS "${H2M_INCLUDE}")
+        set(H2M_ARGS --include ${H2M_INCLUDE})
+    else()
+        set(H2M_ARGS "")
+    endif()
     add_custom_command(TARGET ${BINARY} POST_BUILD
-        COMMAND ${HELP2MAN} --no-info --section 1
+        COMMAND ${HELP2MAN} --no-info --section 1 ${H2M_ARGS}
             ${CMAKE_CURRENT_BINARY_DIR}/${BINARY}
-            > ${BINARY}.1
+            > ${BINARY}.1 || rm -f ${BINARY}.1
         COMMENT "Generating ${BINARY} man page"
         VERBATIM)
     install(FILES ${CMAKE_CURRENT_BINARY_DIR}/${BINARY}.1

csgrep.cc

@@ -487,25 +487,6 @@ bool chainFilters(
 template <class TDesc, class TStream>
 void printUsage(TStream &str, const TDesc &desc) {
     desc.print(str);
-    str << "\n\n\
-DESCRIPTION OF AVAILABLE MODES\n\
-------------------------------\n\
-\n\
-dig_key_events - for each defect, print only the checker and key event\n\
-\n\
-evtstat - print overall checker/key_event statistics for the matched defects\n\
-\n\
-files - print only names of error files that contain the matched defects\n\
-\n\
-filestat - print statistics of matched defects per individual source files\n\
-\n\
-grep - print matched defects using the same format as expected on the input\n\
-\n\
-grouped - print matched defects, grouped by error files they originate from\n\
-\n\
-json - print matched defects in a JSON format\n\
-\n\
-stat - print overall statistics of the matched defects in given error files\n\n";
 }
 
 template <class TDecorator>
@@ -547,9 +528,9 @@ int main(int argc, char *argv[])
 
     try {
         desc.add_options()
-            ("checker",             po::value<string>(),        "defect matches if its checker matches the given regex")
+            ("checker",             po::value<string>(),        "defect matches if its checker matches the given regex (each defect has assigned exactly one checker)")
             ("path",                po::value<string>(),        "defect matches if the path of its key event matches the given regex")
-            ("event",               po::value<string>(),        "defect matches if its key event matches the given regex")
+            ("event",               po::value<string>(),        "defect matches if its key event matches the given regex (each defect has exactly one key event, which determines its location in the code)")
             ("error",               po::value<string>(),        "defect matches if the message of its key event matches the given regex")
             ("msg",                 po::value<string>(),        "defect matches if any of its messages matches the given regex")
             ("annot",               po::value<string>(),        "defect matches if its annotation matches the given regex")

csgrep.h2m

@@ -0,0 +1,44 @@
+[NAME]
+csgrep - filter the list of defects by the specified regex-based predicates
+
+[EXAMPLE - CHECKERS, EVENTS, MESSAGES]
+.nf
+Error: FORWARD_NULL (CWE-476):
+libhsm.c:1168: assign_zero: Assigning: key_handles = NULL.
+libhsm.c:1210: var_deref_op: Dereferencing null pointer key_handles.
+.fi
+
+In the above example, FORWARD_NULL is the
+.B checker
+, assign_zero and var_deref_op are
+.B events
+, where var_deref_op is the key event and
+"Dereferencing null pointer key_handles." is the
+.B message
+associated with the key event.
+
+[DESCRIPTION OF AVAILABLE MODES]
+
+.B dig_key_events
+- for each defect, print only the checker and key event
+
+.B evtstat
+- print overall checker/key_event statistics for the matched defects
+
+.B files
+- print only names of error files that contain the matched defects
+
+.B filestat
+- print statistics of matched defects per individual source files
+
+.B grep
+- print matched defects using the same format as expected on the input
+
+.B grouped
+- print matched defects, grouped by error files they originate from
+
+.B json
+- print matched defects in a JSON format
+
+.B stat
+- print overall statistics of the matched defects in given error files