manual.md: Improved 'Get started' chapter. Add 'HTML Report' chapter

man/manual.md

@@ -38,17 +38,121 @@ When you have filled out the project settings and click on OK; the Cppcheck anal
 
 ### Command line
 
-A good first command to try is either...
+#### First test
 
-If you have a Visual studio solution / compile database (cmake/qbs/etc) / C++ Builder 6 project:
+Here is a simple code
 
-    cppcheck --enable=warning --project=<path of solution / project / compile database>
+    int main()
+    {
+        char a[10];
+        a[10] = 0;
+        return 0;
+    }
 
-Or:
+If you save that into file1.c and execute:
 
-    cppcheck --enable=warning <folder where your source code is>
+    cppcheck file1.c
+
+The output from cppcheck will then be:
+
+    Checking file1.c...
+    [file1.c:4]: (error) Array 'a[10]' index 10 out of bounds
+
+
+#### Checking all files in a folder
+
+Normally a program has many source files. And you want to check them all. Cppcheck can check all source files in a directory:
+
+    cppcheck path
+
+If "path" is a folder then cppcheck will recursively check all source files in this folder.
+
+    Checking path/file1.cpp...
+    1/2 files checked 50% done
+    Checking path/file2.cpp...
+    2/2 files checked 100% done
+
+#### Check files manually or use project file
+
+With Cppcheck you can check files manually, by specifying files/paths to check and settings. Or you can use a project file (cmake/visual studio/etc).
+
+We don't know which approach will give you the best results. It is recommended that you try both. It is possible that you will get different results so that to find most bugs you need to use both approaches.
+
+Later chapters will describe this in more detail.
+
+#### Excluding a file or folder from checking
+
+To exclude a file or folder, there are two options. The first option is to only provide the paths and files you want to check.
+
+    cppcheck src/a src/b
+
+All files under src/a and src/b are then checked.
+
+The second option is to use -i, with it you specify files/paths to ignore. With this command no files in src/c are checked:
+
+    cppcheck -isrc/c src
+
+This option does not currently work with the `--project` option and is only valid when supplying an input directory. To ignore multiple directories supply the -i multiple times. The following command ignores both the src/b and src/c directories.
+
+    cppcheck -isrc/b -isrc/c
+
+### Severities
+
+The possible severities for messages are:
+
+**error**
+
+used when bugs are found
+
+**warning**
+
+suggestions about defensive programming to prevent bugs
+
+**style**
+
+stylistic issues related to code cleanup (unused functions, redundant code, constness, and such)
+
+**performance**
+
+Suggestions for making the code faster. These suggestions are only based on common knowledge. It is not certain you'll get any measurable difference in speed by fixing these messages.
+
+**portability**
+
+portability warnings. 64-bit portability. code might work different on different compilers. etc.
+
+**information**
+
+Configuration problems. The recommendation is to only enable these during configuration.
+
+
+### Platform
+
+You should use a platform configuration that match your target.
+
+By default Cppcheck uses native platform configuration that works well if your code is compiled and executed locally.
+
+Cppcheck has builtin configurations for unix and windows targets. You can easily use these with the --platform command line flag.
+
+You can also create your own custom platform configuration in a xml file. Here is an example:
+
+    <?xml version="1"?>
+    <platform>
+      <char_bit>8</char_bit>
+      <default-sign>signed</default-sign>
+      <sizeof>
+        <short>2</short>
+        <int>4</int>
+        <long>4</long>
+        <long-long>8</long-long>
+        <float>4</float>
+        <double>8</double>
+        <long-double>12</long-double>
+        <pointer>4</pointer>
+        <size_t>4</size_t>
+        <wchar_t>2</wchar_t>
+      </sizeof>
+    </platform>
 
-You can extend and adjust the analysis in many ways later.
 
 ## Importing project
 
@@ -545,4 +649,31 @@ If you have a question about the .cfg file format it is recommended that you ask
 
 The command line cppcheck will try to load custom .cfg files from the working path - execute cppcheck from the path where the .cfg files are.
 
-The cppcheck GUI will try to load custom .cfg files from the project file path. The custom .cfg files should be shown in the `Edit Project File` dialog that you open from the `File` menu.
+The cppcheck GUI will try to load custom .cfg files from the project file path. The custom .cfg files should be shown in the Edit Project File dialog that you open from the `File` menu.
+
+## HTML Report
+
+You can convert the XML output from cppcheck into a HTML report. You'll need Python and the pygments module (http://pygments.org/) for this to work. In the Cppcheck source tree there is a folder htmlreport that contains a script that transforms a Cppcheck XML file into HTML output.
+
+This command generates the help screen:
+
+    htmlreport/cppcheck-htmlreport -h
+
+The output screen says:
+
+    Usage: cppcheck-htmlreport [options]
+
+    Options:
+       -h, --help      show this help message and exit
+       --file=FILE     The cppcheck xml output file to read defects from.
+                       Default is reading from stdin.
+       --report-dir=REPORT_DIR
+                       The directory where the html report content is written.
+       --source-dir=SOURCE_DIR
+                       Base directory where source code files can be found.
+
+An example usage:
+
+    ./cppcheck gui/test.cpp --xml 2> err.xml
+    htmlreport/cppcheck-htmlreport --file=err.xml --report-dir=test1 --source-dir=.
+