From 93fc3f322b2974744b010104d329036a16e8c43d Mon Sep 17 00:00:00 2001
From: Andrew Gvozdev
Date: Wed, 2 Jun 2010 17:51:10 +0000
Subject: bug 289168: "Tuning Error Parsers" chapter in the doc.

---
 .../reference/cdt_u_console_view.htm               |   2 +-
 .../reference/cdt_u_newproj_parser_error.htm       |   2 +-
 .../cdt_u_prop_build_settings_errparser.htm        |   2 +-
 .../tasks/cdt_o_build_task.htm                     |   2 +-
 doc/org.eclipse.cdt.doc.user/tasks/cdt_o_tasks.htm |   2 +-
 .../tasks/cdt_t_proj_error_parser.htm              | 101 +++++++++++++--------
 doc/org.eclipse.cdt.doc.user/topics_Tasks.xml      |   2 +-
 7 files changed, 67 insertions(+), 46 deletions(-)

diff --git a/doc/org.eclipse.cdt.doc.user/reference/cdt_u_console_view.htm b/doc/org.eclipse.cdt.doc.user/reference/cdt_u_console_view.htm
index 2e5df1358a6..3c188cc7138 100644
--- a/doc/org.eclipse.cdt.doc.user/reference/cdt_u_console_view.htm
+++ b/doc/org.eclipse.cdt.doc.user/reference/cdt_u_console_view.htm
@@ -142,7 +142,7 @@ you see one or more of the following options in a context menu depending on the
 
 <p><img src="../images/ngref.gif" ALT="Related references" width="143" height="21">
 <br><a href="../reference/cdt_o_views.htm">C/C++ Views and Editors</a>
-<br><a href="../tasks/cdt_t_proj_error_parser.htm">Filtering errors</a>
+<br><a href="../tasks/cdt_t_proj_error_parser.htm">Tuning Error Parsers</a>
 </p>
 <hr >
 <p>
diff --git a/doc/org.eclipse.cdt.doc.user/reference/cdt_u_newproj_parser_error.htm b/doc/org.eclipse.cdt.doc.user/reference/cdt_u_newproj_parser_error.htm
index c6c1c1fa213..bdb4c96789b 100644
--- a/doc/org.eclipse.cdt.doc.user/reference/cdt_u_newproj_parser_error.htm
+++ b/doc/org.eclipse.cdt.doc.user/reference/cdt_u_newproj_parser_error.htm
@@ -58,7 +58,7 @@
 <a href="../concepts/cdt_c_build_over.htm">Build overview</a></p>
 <p><img border="0" src="../images/ngtasks.gif" ALT="Related tasks" width="143" height="21">
 <br>
-<a href="../tasks/cdt_t_proj_error_parser.htm">Filtering errors</a></p>
+<a href="../tasks/cdt_t_proj_error_parser.htm">Tuning Error Parsers</a></p>
 <p><img border="0" src="../images/ngref.gif" ALT="Related reference" width="143" height="21"> <br>
   <a href="cdt_o_proj_prop_pages.htm">New CDT Project Wizard</a></p>
 <hr>
diff --git a/doc/org.eclipse.cdt.doc.user/reference/cdt_u_prop_build_settings_errparser.htm b/doc/org.eclipse.cdt.doc.user/reference/cdt_u_prop_build_settings_errparser.htm
index 52c5599df83..f7d6f0a66ac 100644
--- a/doc/org.eclipse.cdt.doc.user/reference/cdt_u_prop_build_settings_errparser.htm
+++ b/doc/org.eclipse.cdt.doc.user/reference/cdt_u_prop_build_settings_errparser.htm
@@ -64,7 +64,7 @@ build output log.</p>
 <p><img border="0" src="../images/ngtasks.gif" alt="Related tasks"
  width="143" height="21">
 <br>
-<a href="../tasks/cdt_t_proj_error_parser.htm">Filtering errors</a></p>
+<a href="../tasks/cdt_t_proj_error_parser.htm">Tuning Error Parsers</a></p>
 
 <p style="margin-top: 0pt; margin-bottom: 0pt;"><img border="0"
  src="../images/ngref.gif" alt="Related reference" width="143"
diff --git a/doc/org.eclipse.cdt.doc.user/tasks/cdt_o_build_task.htm b/doc/org.eclipse.cdt.doc.user/tasks/cdt_o_build_task.htm
index 9c0d23eba08..c385141587d 100644
--- a/doc/org.eclipse.cdt.doc.user/tasks/cdt_o_build_task.htm
+++ b/doc/org.eclipse.cdt.doc.user/tasks/cdt_o_build_task.htm
@@ -14,7 +14,7 @@
 	<img src="../images/trans.gif" border="0" width="25" height="1" alt=""><a style="text-decoration:none" href="cdt_t_proj_rename.htm">Renaming a project</a><br>
 	<img src="../images/trans.gif" border="0" width="25" height="1" alt=""><a style="text-decoration:none" href="cdt_t_proj_build_set.htm">Defining Project Build settings</a><br>
 	<img src="../images/trans.gif" border="0" width="25" height="1" alt=""><a style="text-decoration:none" href="cdt_t_add_build_var.htm">Adding and Editing Build Variables</a><br>
-	<img src="../images/trans.gif" border="0" width="25" height="1" alt=""><a style="text-decoration:none" href="cdt_t_proj_error_parser.htm">Filtering errors</a><br>
+	<img src="../images/trans.gif" border="0" width="25" height="1" alt=""><a style="text-decoration:none" href="cdt_t_proj_error_parser.htm">Tuning Error Parsers</a><br>
 	<img src="../images/trans.gif" border="0" width="25" height="1" alt=""><a style="text-decoration:none" href="cdt_t_proj_parser.htm">Selecting a binary parser</a><br>
 	<img src="../images/trans.gif" border="0" width="25" height="1" alt=""><a style="text-decoration:none" href="cdt_t_proj_paths.htm">Adding include paths and symbols</a><br>
 	<img src="../images/trans.gif" border="0" width="25" height="1" alt=""><a style="text-decoration:none" href="cdt_t_proj_platf.htm">Selecting a project type</a><br>
diff --git a/doc/org.eclipse.cdt.doc.user/tasks/cdt_o_tasks.htm b/doc/org.eclipse.cdt.doc.user/tasks/cdt_o_tasks.htm
index 50912cf8203..0cd5f40ae51 100644
--- a/doc/org.eclipse.cdt.doc.user/tasks/cdt_o_tasks.htm
+++ b/doc/org.eclipse.cdt.doc.user/tasks/cdt_o_tasks.htm
@@ -39,7 +39,7 @@
 	<img src="../images/trans.gif" border="0" width="50" height="1" alt=""><a style="text-decoration:none" href="cdt_t_proj_rename.htm">Renaming a project</a><br>
 	<img src="../images/trans.gif" border="0" width="50" height="1" alt=""><a style="text-decoration:none" href="../reference/cdt_u_prop_general_pns_ref.htm">Selecting referenced projects</a><br>
 	<img src="../images/trans.gif" border="0" width="50" height="1" alt=""><a style="text-decoration:none" href="cdt_t_proj_build_set.htm">Defining Project Build settings</a><br>
-	<img src="../images/trans.gif" border="0" width="50" height="1" alt=""><a style="text-decoration:none" href="cdt_t_proj_error_parser.htm">Filtering errors</a><br>
+	<img src="../images/trans.gif" border="0" width="50" height="1" alt=""><a style="text-decoration:none" href="cdt_t_proj_error_parser.htm">Tuning Error Parsers</a><br>
 	<img src="../images/trans.gif" border="0" width="50" height="1" alt=""><a style="text-decoration:none" href="cdt_t_proj_parser.htm">Selecting a binary parser</a><br>
 	<img src="../images/trans.gif" border="0" width="50" height="1" alt=""><a style="text-decoration:none" href="cdt_t_proj_paths.htm">Adding Include paths and symbols</a><br>
 	<img src="../images/trans.gif" border="0" width="50" height="1" alt=""><a style="text-decoration:none" href="cdt_t_proj_platf.htm">Selecting a deployment platform</a><br>
diff --git a/doc/org.eclipse.cdt.doc.user/tasks/cdt_t_proj_error_parser.htm b/doc/org.eclipse.cdt.doc.user/tasks/cdt_t_proj_error_parser.htm
index afd2b7abf90..510bf7fc4a8 100644
--- a/doc/org.eclipse.cdt.doc.user/tasks/cdt_t_proj_error_parser.htm
+++ b/doc/org.eclipse.cdt.doc.user/tasks/cdt_t_proj_error_parser.htm
@@ -6,59 +6,80 @@
 <meta name="GENERATOR" content="Microsoft FrontPage 5.0">
 <meta name="ProgId" content="FrontPage.Editor.Document">
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
-<title>Filtering errors</title>
+<title>Tuning Error Parsers</title>
 <link rel="stylesheet" type="text/css" href="../help.css">
 </head>
 
 <body>
 
-<h1>Filtering errors</h1>
+<h1>Tuning Error Parsers</h1>
 
-<p>The Error Parsers page of the Properties window lists a set of filters that detect error patterns in 
-the build output log.</p>
+<p>Error Parsers scan build output line by line looking for errors and warnings
+  (also for certain informational messages). They generate <strong>Problem Markers</strong>
+  which visually indicate those problems to a user. The problems are highlighted on the Console,
+  populate the Problems view and shown in the editor. Problem markers are organized
+  into Error <img src="../images/icon_error.gif" alt="Error">,
+  Warning <img src="../images/icon_warning.gif" alt="Warning">
+  and Info<img src="../images/icon_info.gif" alt="Info">categories.
+</p>
 
-<p>If an error or warning is detected, an icon appears on the file in the Tasks 
-view. If the file is not found, the icon appears on the project.</p>
+<p>There are several predefined Error Parsers where each one can handle output of a specific tool.
+Normally a toolchain defines a set of Error Parsers to deal with output of each tool. It is possible
+to redefine that set on a per-project basis in project properties:
+</p>
+<p>
+  <ol>
+    <li>In the C/C++ Projects view, right-click the project, and select <strong>Properties</strong>.</li>
+    <li>Expand <strong>C/C++ Build</strong>.</li>
+    <li>Select <strong>Settings</strong>.</li>
+    <li>Click the <strong>Error Parsers</strong> tab.</li>
+    <li>In the <strong>Error parsers</strong> list, select error parsers.</li>
+    <li>Click <strong>OK</strong>.</li>
+  </ol>
+</p>
+<p>Note that the order of error parsers is significant. Normally an error parser will <i>consume</i>
+the line where it spotted an error/warning and the others down the line won't get a chance to parse it.
+</p>
 
-<p>You can define the properties on a per project basis in the New CDT Project 
-wizard, in the C/C++ Projects view, or in the Navigator view. You can also define 
-project properties in the Preferences window for future make projects.</p>
+<p>CDT provides one special kind of error parser, <strong>CDT pushd/popd CWD Locator</strong>.
+This parser does not create problem markers but it is looking for output of <strong>pushd</strong>
+and <strong>popd</strong> commands which are commonly used in makefiles to print the Current Working Directory (CWD).
+CDT can use this information to associate the file names appearing in the output relative to the CWD.
+Note that that kind of parser needs to be the first to be able to provide the CWD to the other parsers.
+</p>
 
-<p>To select error parsers:</p>
+<p>Most of the error parsers are configurable via regular expression patterns and a user can:
+</p>
+<p>
+<ul>
+  <li>Adjust a pattern to detect a problem more accurately,</li>
+  <li>Disable useless or proliferating problems (Note that it can have positive effect on performance of the console),</li>
+  <li>Create own error parser for a custom tool.</li>
+</ul>
+</p>
 
-<ol>
-  <li>Do one of the following:</li>
-  <ul>
- 	</ol>
-  	  <li>To set properties for makefile projects, do the following:
-		<ol>
-		<li>Select <strong>Window &gt; Preferences </strong>. 
-		<li>Expand <strong>C/C++</strong>.
-		<li>Expand <strong>New CDT project wizard</strong>.
-		<li>Click <strong>Makefile Project</strong>.</li>
-		</ol>
-	  <li>For a typical make project, do the following:
-		<ol>
-			<li>In the C/C++ Projects view, right-click the project, and select <strong>Properties</strong>.  
-			<li>Expand <strong>C/C++ Build</strong>.</li>
-	  <li>Select <strong>Settings</strong>.  
-	</ol>
-</li>
-  </ul>
-  <li>Click the <strong>Error Parsers</strong> tab.</li>
-  <li>In the <strong>Error parsers</strong> list, select error parsers.</li>
-  <li>Click <strong>OK</strong>.</li>
-</ol>
-  <p><img border="0" src="../images/ngconcepts.gif" ALT="Related concepts" width="143" height="21">
-<br>
-  <a href="../concepts/cdt_c_projects.htm">CDT Projects</a><br>
-  <a href="../concepts/cdt_c_proj_file_views.htm">Project file views</a></p>
+<p>To customize Error parsers do following:
+</p>
+<p>
+  <ol>
+    <li>Select <strong>Window &gt; Preferences </strong>. </li>
+    <li>Expand <strong>C/C++</strong>.</li>
+    <li>Select <strong>Error Parsers</strong> tab.</li>
+    <li>Select error parser or <strong>Add</strong> a new one.</li>
+    <li>Follow <a href="../reference/cdt_u_pref_build.htm">Build preferences</a> to define your custom patterns</li>
+  </ol>
+</p>
 
+<p><img border="0" src="../images/ngconcepts.gif" ALT="Related concepts" width="143" height="21">
+<br><a href="../concepts/cdt_c_projects.htm">CDT Projects</a>
+<br><a href="../concepts/cdt_c_proj_file_views.htm">Project file views</a>
+</p>
 
-<p><img border="0" src="../images/ngref.gif" ALT="Related reference" width="143" height="21">
-<br>
-<a href="../reference/cdt_u_newproj_parser_error.htm">Error Parsers, C/C++ Properties window</a></p>
 
+<p><img border="0" src="../images/ngref.gif" ALT="Related reference" width="143" height="21">
+<br><a href="../reference/cdt_u_newproj_parser_error.htm">Error Parsers, C/C++ Properties window</a>
+<br><a href="../reference/cdt_u_pref_build.htm">Build preferences</a>
+</p>
 
 <img src="../images/ng00_04a.gif" ALT="QNX Copyright Statement" >
 
diff --git a/doc/org.eclipse.cdt.doc.user/topics_Tasks.xml b/doc/org.eclipse.cdt.doc.user/topics_Tasks.xml
index b293d389f32..5ebe2782b86 100644
--- a/doc/org.eclipse.cdt.doc.user/topics_Tasks.xml
+++ b/doc/org.eclipse.cdt.doc.user/topics_Tasks.xml
@@ -32,7 +32,7 @@
 			<topic label="Defining Project Build settings" href="tasks/cdt_t_proj_build_set.htm"/>
    <topic href="tasks/cdt_t_add_build_var.htm" label="Adding and Editing Build Variables">
    </topic>
-			<topic label="Filtering Errors" href="tasks/cdt_t_proj_error_parser.htm"/>
+			<topic label="Tuning Error Parsers" href="tasks/cdt_t_proj_error_parser.htm"/>
 			<topic label="Selecting a binary parser" href="tasks/cdt_t_proj_parser.htm"/>
 			<topic label="Adding Include paths and symbols" href="tasks/cdt_t_proj_paths.htm"/>
 			<topic label="Selecting a project type" href="tasks/cdt_t_proj_platf.htm"/>
-- 
cgit v1.2.3