Fix #15136 (gui: rewrite the online help)

gui/help/commandline.html

@@ -0,0 +1,63 @@
+<html>
+<head>
+<title>Command line options</title>
+<link rel="stylesheet" type="text/css" href="style.css">
+</head>
+<body>
+
+<h1>Command line options</h1>
+
+<p>The GUI can be started from a terminal or a shortcut with options:</p>
+
+<pre>cppcheck-gui [OPTIONS] [files or paths]</pre>
+
+<table class="options" border="1" cellspacing="0" cellpadding="4" width="100%">
+<tr><th>Option</th><th>Description</th></tr>
+<tr><td><code>-p &lt;file&gt;</code></td><td>Open the project file and analyze
+    it. If the project has a build dir with earlier results, these are shown
+    instead; click <i>Reanalyze all files</i> to analyze again.</td></tr>
+<tr><td><code>-l &lt;file&gt;</code></td><td>Open a results file in XML
+    format.</td></tr>
+<tr><td><code>-d &lt;directory&gt;</code></td><td>Used with <code>-l</code>:
+    the folder that was analyzed to create the results file. Relative paths in
+    the results file are relative to this folder. It is needed to show the
+    source code of the warnings.</td></tr>
+<tr><td><code>-h</code>, <code>--help</code></td><td>Show a short description
+    of the options.</td></tr>
+<tr><td><code>-v</code>, <code>--version</code></td><td>Show the version of
+    the GUI.</td></tr>
+<tr><td><code>--data-dir=&lt;directory&gt;</code></td><td>Meant for
+    installation scripts. Stores the folder where Cppcheck's data files
+    (translations, library configurations, platforms, addons) are installed.
+    The GUI is not started when this option is used.</td></tr>
+<tr><td><i>files or paths</i></td><td>Analyze these files and folders without
+    a project. If one of the arguments is a project file
+    (<code>*.cppcheck</code>), it is opened as with <code>-p</code>. If one of
+    them is an XML file, it is opened as a results file.</td></tr>
+</table>
+
+<h2>Examples</h2>
+
+<p>Open a project:</p>
+<pre>cppcheck-gui -p myproject.cppcheck</pre>
+<p>or simply:</p>
+<pre>cppcheck-gui myproject.cppcheck</pre>
+
+<p>Look at the results of a CI job. The job ran Cppcheck in the folder
+<code>/home/me/src/myproject</code> and saved the results:</p>
+<pre>cppcheck-gui -l results.xml -d /home/me/src/myproject</pre>
+
+<p>Analyze a folder without a project:</p>
+<pre>cppcheck-gui src/</pre>
+
+<h2>Starting without options</h2>
+
+<p>When the GUI is started without options, it opens the project that was open
+when it was closed last time, and shows the results of the last analysis if
+the project has a build dir.</p>
+
+<p class="nav">Previous: <a href="preferences.html">Preferences</a> |
+Next: <a href="troubleshooting.html">Troubleshooting</a></p>
+
+</body>
+</html>

gui/help/index.html

@@ -1,21 +1,103 @@
 <html>
 <head>
 <title>Cppcheck GUI</title>
+<link rel="stylesheet" type="text/css" href="style.css">
 </head>
 <body>
 
 <h1>Cppcheck GUI</h1>
 
-<p>With the Cppcheck GUI you can analyze your code.</p>
+<p>Cppcheck is a static analysis tool for C and C++ code. It looks for bugs
+such as undefined behavior, memory leaks, buffer overruns, null pointer
+dereferences and uninitialized variables, and it points out code that is
+suspicious, slow or hard to maintain. Cppcheck tries hard to avoid false
+positives: when it reports something there is usually a reason to look at
+it.</p>
+
+<p>The Cppcheck GUI is a graphical front end for Cppcheck. With the GUI you
+can:</p>
+<ul>
+<li>create and edit project files that describe what code to analyze and how
+    to analyze it,</li>
+<li>import Visual Studio solutions and projects, compile databases
+    (<code>compile_commands.json</code>) and Borland C++ Builder 6 projects,</li>
+<li>run the analysis in several threads and watch the results come in,</li>
+<li>browse the warnings, read the source code next to them and follow the
+    path that leads to each bug,</li>
+<li>filter, hide, suppress and tag warnings,</li>
+<li>open the code in your favorite editor,</li>
+<li>save results as XML, text or CSV and print them,</li>
+<li>try out small pieces of code in the scratchpad,</li>
+<li>write configuration files for your own libraries.</li>
+</ul>
+
+<p class="figure"><img src="images/main-window.png"></p>
 
 <h2>Contents</h2>
 
-<p>If you want to get started, look at the <a href="walkthrough.html">walk through</a>.</p>
+<table class="options" border="1" cellspacing="0" cellpadding="4" width="100%">
+<tr><th>Page</th><th>What you will find there</th></tr>
+<tr><td><a href="walkthrough.html">Getting started</a></td>
+    <td>A step by step walk through: create a project, run the analysis and
+        look at the first results. Start here if you are new to Cppcheck.</td></tr>
+<tr><td><a href="mainwindow.html">The main window</a></td>
+    <td>All menus, toolbars and panels of the main window.</td></tr>
+<tr><td><a href="standalone-analysis.html">Analyzing without a project</a></td>
+    <td>Quick analysis of files and folders, and the settings in the
+        <i>Analyze</i> menu.</td></tr>
+<tr><td><a href="projectfiledialog.html">Project files</a></td>
+    <td>Every option in the project file dialog explained in detail.</td></tr>
+<tr><td><a href="investigating-warnings.html">Investigating warnings</a></td>
+    <td>How to read the results list, the warning details and the code
+        view, and how to decide if a warning is a real bug.</td></tr>
+<tr><td><a href="severities.html">Severities and report types</a></td>
+    <td>What error, warning, style, performance, portability and information
+        mean, and how the compliance report types classify warnings.</td></tr>
+<tr><td><a href="suppressions.html">Hiding and suppressing warnings</a></td>
+    <td>Temporary hiding, permanent suppressions in the project file, and
+        inline suppressions in the code.</td></tr>
+<tr><td><a href="tagging.html">Tagging warnings</a></td>
+    <td>Categorize warnings with your own tags.</td></tr>
+<tr><td><a href="reports.html">Results files, printing and statistics</a></td>
+    <td>Save and open results, print reports and view statistics.</td></tr>
+<tr><td><a href="tools.html">Scratchpad, library editor and other tools</a></td>
+    <td>Tools for trying out code and for describing your own libraries.</td></tr>
+<tr><td><a href="preferences.html">Preferences</a></td>
+    <td>Every option in the preferences dialog.</td></tr>
+<tr><td><a href="commandline.html">Command line options</a></td>
+    <td>How to start the GUI with a project or a results file.</td></tr>
+<tr><td><a href="troubleshooting.html">Troubleshooting</a></td>
+    <td>Answers to common questions and problems.</td></tr>
+</table>
+
+<h2>Projects or quick analysis?</h2>
+
+<p>There are two ways to use the GUI:</p>
+<ul>
+<li><b>With a project file</b> (recommended). A project file
+    (<code>*.cppcheck</code>) stores where your code is, the include paths,
+    the preprocessor defines, the libraries you use, suppressions, tags and
+    much more. The analysis is more accurate when Cppcheck knows these
+    things, and you only configure them once. See
+    <a href="walkthrough.html">Getting started</a> and
+    <a href="projectfiledialog.html">Project files</a>.</li>
+<li><b>Without a project file</b>. Use <i>Analyze &gt; Files...</i> or
+    <i>Analyze &gt; Directory...</i> to analyze some code quickly. See
+    <a href="standalone-analysis.html">Analyzing without a project</a>.</li>
+</ul>
 
-<h2>Example</h2>
+<h2>More information</h2>
 
-<blockquote><img src="images/index-mainwindow.png"></blockquote>
+<p>The Cppcheck manual describes the analysis itself in more detail, including
+the command line tool, the configuration file format and addons. You can find
+it at <a href="https://cppcheck.sourceforge.io/manual.pdf">https://cppcheck.sourceforge.io/manual.pdf</a>.</p>
+
+<p>The Cppcheck home page is
+<a href="https://cppcheck.sourceforge.io/">https://cppcheck.sourceforge.io/</a>.
+There you can download new versions, read about the checks and report
+problems.</p>
+
+<p class="nav">Next: <a href="walkthrough.html">Getting started</a></p>
 
 </body>
 </html>
-

gui/help/investigating-warnings.html

@@ -1,22 +1,183 @@
 <html>
 <head>
 <title>Investigating warnings</title>
+<link rel="stylesheet" type="text/css" href="style.css">
 </head>
 <body>
 
 <h1>Investigating warnings</h1>
 
-<p>When you have run the analysis it is time to look at the results.</p>
+<p>When the analysis is done (or while it is still running) it is time to look
+at the results. This page explains how to read a warning, how to decide if it
+is a real bug, and what you can do with it.</p>
 
-<p>If you click on a warning then the corresponding code will be shown in the
-&quot;Warning details&quot; at the bottom.</p>
+<h2>Reading a warning</h2>
 
-<p>You can right click warnings to get options. The difference of
-&quot;hiding&quot; a warning and &quot;suppressing&quot; a warning is that
-the suppression is permanent and hiding the warning is only temporary. When
-suppressing warning(s), that is saved in the project file.
+<p class="figure"><img src="images/main-window.png"></p>
 
+<p>Click a warning in the results list. The lower part of the window then
+shows:</p>
+<ul>
+<li>the <b>id</b> of the warning, for example <code>arrayIndexOutOfBounds</code>.
+    The id identifies the kind of problem. Search for it in the Cppcheck
+    documentation or on the internet to learn more about it,</li>
+<li>the <b>CWE</b> number, if there is one. CWE (Common Weakness Enumeration)
+    is a standard list of software weaknesses. Look it up at
+    <a href="https://cwe.mitre.org/">cwe.mitre.org</a> for a general
+    description of the problem,</li>
+<li>the full <b>message</b>. It can be longer than the summary in the list,</li>
+<li>the <b>source code</b> with the line of the warning highlighted.</li>
+</ul>
+
+<p>In the example above Cppcheck says that <code>buf[16]</code> is accessed at
+index 16. The array has 16 elements, so the valid indexes are 0 to 15. The loop
+condition <code>i &lt;= BUFFER_SIZE</code> should be
+<code>i &lt; BUFFER_SIZE</code>.</p>
+
+<h3>Notes: the path to the bug</h3>
+
+<p>Many warnings have notes. Click the arrow in front of the warning to see
+them. Notes show the steps that lead to the problem, in order, for
+example:</p>
+<pre>Assuming that condition 'i&lt;=16' is not redundant   (line 9)
+Array index out of bounds                         (line 10)</pre>
+
+<p>Click a note to show its line in the code view. For a bug that depends on
+values, the notes usually tell you where the value comes from, which
+conditions Cppcheck assumes, and where the bad value is used. Follow the notes
+to understand the warning.</p>
+
+<p>A note like <i>Assuming that condition 'x' is not redundant</i> means that
+Cppcheck uses the condition in your code as a hint about possible values. For
+example, if the code checks <code>if (p == NULL)</code> after it has already
+used <code>p</code>, then either the check is not needed or the code can use a
+null pointer. Cppcheck warns because one of them must be wrong.</p>
+
+<h2>Is it a real bug?</h2>
+
+<p>Cppcheck tries to avoid false warnings, but no static analysis tool is
+perfect. To decide if a warning is right:</p>
+<ol>
+<li>Read the message and the notes, and look at the code they point to.</li>
+<li>Think about the values Cppcheck mentions. Can they really happen? Look at
+    the callers of the function if needed.</li>
+<li>Check if Cppcheck may be missing information. Warnings in code that uses
+    macros or types that Cppcheck could not see, because an include path is
+    missing, can be wrong. Look for <i>missingInclude</i> information
+    messages and fix the include paths in the project.</li>
+<li>Check if a library configuration is missing. If your code calls a
+    function that never returns (like a fatal error handler) and Cppcheck
+    does not know that, it may warn about code after the call. Select the
+    library in the project or write a configuration for your own functions.
+    See <a href="projectfiledialog.html#libraries">Libraries</a>.</li>
+</ol>
+
+<p>Even if a warning is not a bug today, it can point to code that is hard to
+understand or easy to break. Many developers prefer to change the code so that
+the warning goes away, instead of suppressing it.</p>
+
+<p>If you are sure Cppcheck is wrong, suppress the warning (see
+<a href="suppressions.html">Hiding and suppressing warnings</a>). It is also
+very helpful if you report the false warning, with a small code example, at
+<a href="https://trac.cppcheck.net/">https://trac.cppcheck.net/</a> or in the
+Cppcheck forum.</p>
+
+<h3>Inconclusive warnings</h3>
+
+<p>Sometimes Cppcheck finds something suspicious but can not be sure that it
+is a bug. These <i>inconclusive</i> warnings are not shown by default. Enable
+<i>Check for inconclusive errors also</i> in the
+<a href="preferences.html">preferences</a> to see them. An extra
+<i>Inconclusive</i> column then marks them. Expect more false warnings among
+them.</p>
+
+<h2>Where to start</h2>
+
+<p>The first analysis of a large project can give many warnings. Some
+tips:</p>
+<ul>
+<li>Start with <b>errors</b>, then <b>warnings</b>. Use the
+    <a href="severities.html">severity</a> buttons in the toolbar to hide the
+    other severities.</li>
+<li>Look at the <b>information</b> messages early. They are not bugs, but they
+    tell you about problems in the configuration, such as headers that can
+    not be found. Fixing them makes the other results better.</li>
+<li>Sort by the <i>Id</i> column to handle one kind of warning at a time. If
+    one kind of warning is wrong everywhere, it may be a configuration
+    problem.</li>
+<li>Use the quick filter to find warnings about a function, a variable or a
+    file.</li>
+<li>With a build dir, sort by <i>Since date</i> to see the newest warnings
+    first. New warnings are the easiest to fix, because the code is fresh in
+    your mind.</li>
+<li>Use <a href="tagging.html">tags</a> to remember what you have looked
+    at.</li>
+</ul>
+
+<h2>Opening the code in an editor</h2>
+
+<p>Double-click a warning, or select it and press Enter, to open the file in
+your default editor at the line of the warning. You can also right-click a
+warning and choose an editor at the top of the context menu.</p>
+
+<p>Editors are configured in the <a href="preferences.html#applications">
+preferences</a> on the <i>Applications</i> tab. On some systems the GUI finds
+installed editors automatically.</p>
+
+<p>If the file is not found, for example because the results were loaded from
+an XML file created on another computer, the GUI asks you to select the
+folder where the file is.</p>
+
+<a name="contextmenu"></a>
+<h2>The context menu</h2>
+
+<p>Right-click one or more selected warnings to get the context menu. Select
+several warnings with Ctrl+click or Shift+click.</p>
+
+<p class="figure"><img src="images/context-menu.png"></p>
+
+<table class="options" border="1" cellspacing="0" cellpadding="4" width="100%">
+<tr><th>Command</th><th>Description</th></tr>
+<tr><td>(editors)</td><td>Open the file of the warning in this editor.</td></tr>
+<tr><td>Recheck N file(s)</td><td>Analyze the selected files again. Select
+    file items (the top level items in the list) to enable this. Useful after
+    you have fixed something in a file. Not available while an analysis is
+    running or for results loaded from an XML file.</td></tr>
+<tr><td>Copy</td><td>Copy the selected warnings, notes or file names to the
+    clipboard as text, in the format
+    <code>file:line:column:severity: summary [id]</code>, followed by one line
+    for each note. Paste it in a bug report or a chat.</td></tr>
+<tr><td>Hide N result(s)</td><td>Hide the selected warnings until the next
+    analysis. See <a href="suppressions.html#hide">Hiding warnings</a>.</td></tr>
+<tr><td>Hide all with id</td><td>Hide all warnings with the same id as the
+    selected warning, until the next analysis.</td></tr>
+<tr><td>Suppress selected id(s)</td><td>Suppress all warnings with the ids of
+    the selected warnings, in all files. The suppression is saved in the
+    project file, so the warnings are not reported again. See
+    <a href="suppressions.html">Hiding and suppressing warnings</a>.</td></tr>
+<tr><td>Open containing folder</td><td>Open the folder of the file in your
+    file manager.</td></tr>
+<tr><td>Tag</td><td>Give the selected warnings a tag. Only shown if the
+    project has tags. See <a href="tagging.html">Tagging warnings</a>.</td></tr>
+</table>
+
+<h2>Analyzing again</h2>
+
+<p>After you have changed the code:</p>
+<ul>
+<li>Right-click a file in the results list and choose <i>Recheck</i> to
+    analyze just that file again.</li>
+<li>Use <i>Reanalyze all files</i> in the toolbar to analyze everything again.
+    With a build dir only changed files are analyzed again, so this is
+    fast.</li>
+<li>Use <i>Analyze &gt; Reanalyze modified files</i> (Ctrl+R) to analyze only
+    the files that changed since the last analysis. See
+    <a href="mainwindow.html">The main window</a> for when this is
+    available.</li>
+</ul>
+
+<p class="nav">Previous: <a href="projectfiledialog.html">Project files</a> |
+Next: <a href="severities.html">Severities and report types</a></p>
 
 </body>
 </html>
-