[latexila] Documentation: differences between Latexmk and Rubber

[SÃbastien Wilmet <swilmet src gnome org>]

commit ee88d5b246beaebc6f46745bfb3006132188abd2
Author: SÃbastien Wilmet <swilmet src gnome org>
Date:   Thu Jul 7 18:04:14 2011 +0200

    Documentation: differences between Latexmk and Rubber

 TODO                    |    1 -
 help/C/build_tools.page |   43 +++++++++++++++++++++++++++++++------------
 2 files changed, 31 insertions(+), 13 deletions(-)
---
diff --git a/TODO b/TODO
index 994e2d3..b1f5fc7 100644
--- a/TODO
+++ b/TODO
@@ -13,7 +13,6 @@ LaTeXila 2.2
 	  => Insert environments as soon as we find the \begin, and then update the item (or delete it)
 
 - Write some documentation:
-	- the difference between Latexmk and Rubber
 	- open the Mallard doc from the program
 	- manage translations
 
diff --git a/help/C/build_tools.page b/help/C/build_tools.page
index 14eaf10..1580370 100644
--- a/help/C/build_tools.page
+++ b/help/C/build_tools.page
@@ -13,8 +13,7 @@
   format.</p>
 </synopsis>
 
-<!-- TODO mini toc -->
-<!-- <link type="section" /> -->
+<!-- <links type="section" /> -->
 
 <section id="overview">
   <title>Overview</title>
@@ -68,12 +67,12 @@
 
   <p>Compiling a LaTeX document can involve to execute several low-level commands, in a
   certain order and a certain number of times. Here is an example:</p>
-  <code>
+  <screen>
 $ latex document.tex
 $ bibtex document.aux
 $ latex document.tex
 $ dvips -t a4 document.dvi
-$ ps2pdf document.ps</code>
+$ ps2pdf document.ps</screen>
 
   <p>Using a higher-level tool such as Latexmk or Rubber simplify a lot all this process,
   since only one command is required. Indeed, these tools can detect how many times the
@@ -82,13 +81,33 @@ $ ps2pdf document.ps</code>
   Latexmk.</p>
 </section>
 
-<!--
 <section id="latexmk-rubber">
-<title>Differences Between Latexmk and Rubber</title>
-
-<p></p>
+  <title>Differences Between Latexmk and Rubber</title>
+  <p><link href="http://www.phys.psu.edu/~collins/software/latexmk-jcc/";>Latexmk</link>
+  and <link href="https://launchpad.net/rubber/";>Rubber</link> have the same purpose:
+  simplify the compilation process of a LaTeX document. Latexmk is written in Perl, while
+  Rubber is written in Python.</p>
+
+  <p>The output of Latexmk contains more information: which commands are executed, how
+  many times, their output, and the reasons why Latexmk executes (or doesn't execute)
+  these commands. The output of Rubber, on the other hand, doesn't contain a lot of
+  information. When an error occurs, it can be more difficult to diagnose.</p>
+
+  <p>Also, Rubber filter the output of the <cmd>latex</cmd> or <cmd>pdflatex</cmd>
+  command. As a consequence, when Rubber prints an error, it's more difficult to know
+  which type of error it is. If you use Latexmk, errors are categorized into three types:
+  critical errors, simple warnings and bad-boxes (for example when a word exceed the
+  margin). With Rubber, there is no distinction between critical errors and simple
+  warnings. See <link xref="#post-processors" /> for more information.</p>
+
+  <p>Latexmk is more flexible. Each low-level command can be customized, for example for
+  adding a parameter, or use a completely other tool. This can be done both from the
+  command line and in configuration files (see the <cmd>-e</cmd> and <cmd>-r</cmd>
+  options). Rubber is also configurable, but less than Latexmk.</p>
+
+  <p>Last, but not least: Rubber seems to have more bugs and is less actively maintained
+  than Latexmk.</p>
 </section>
--->
 
 <section id="execute">
   <title>Execute a Build Tool</title>
@@ -167,7 +186,7 @@ $ ps2pdf document.ps</code>
     <item>
       <title>latex</title>
       <p>Filter the output of the <cmd>latex</cmd> or <cmd>pdflatex</cmd> commands.
-      There can be three types of errors: critical errors, warnings, or badboxes. There
+      There can be three types of errors: critical errors, warnings, or bad-boxes. There
       are also some other useful information: the size of the document, the number of
       pages, and the number of errors.</p>
     </item>
@@ -179,7 +198,7 @@ $ ps2pdf document.ps</code>
       <p>In the <link xref="#general_configuration" />, there is an option for always
       showing all information of this post processor. If this option is disabled (which
       is the case by default), only the output of the last <cmd>latex</cmd> or
-      <cmd>pdflatex</cmd> command is displayed, if no error occured in another command.
+      <cmd>pdflatex</cmd> command is displayed, if no error occurred in another command.
       This allows to reduce the output showed in the bottom panel. But even if there are
       no errors, it can be useful to see exactly which commands are executed, with their
       output.</p>
@@ -187,7 +206,7 @@ $ ps2pdf document.ps</code>
     <item>
       <title>rubber</title>
       <p>This is the post-processor used for the <cmd>rubber</cmd> command. The errors are
-      categorised into two types: badboxes, and the others. So, unlike the <em>latex</em>
+      categorized into two types: bad-boxes, and the others. So, unlike the <em>latex</em>
       post processor, there is no distinction between critical errors and simple
       warnings.</p>
     </item>