[Reportbug-commits] [SCM] Reportbug - reports bugs in the Debian distribution branch, master, updated. 4.9-64-g52467de

[Sandro Tosi]

The following commit has been merged in the master branch:
commit 06124717f9d533d83901d67bff1e6f40d15762c0
Author: Sandro Tosi <morph at debian.org>
Date:   Sat Mar 6 09:47:56 2010 +0100

    document how to add a pseudo-header

diff --git a/debian/changelog b/debian/changelog
index 3e5e0c1..13c6c94 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -20,8 +20,10 @@ reportbug (4.10.3) UNRELEASED; urgency=low
     - identify the pseudo-headers passed on the command-line and don't merge
       them in the mail headers, but add them to the bug "standard"
       pseudo-headers; thanks to Piotr Engelking for the report; Closes: #552167
+  * doc/README.Users
+    - document how to add a pseudo-header
 
- -- Sandro Tosi <morph at debian.org>  Wed, 03 Mar 2010 19:18:46 +0100
+ -- Sandro Tosi <morph at debian.org>  Sat, 06 Mar 2010 09:47:22 +0100
 
 reportbug (4.10.2) unstable; urgency=low
 
diff --git a/doc/README.Users b/doc/README.Users
index 6e376fe..af0fe06 100644
--- a/doc/README.Users
+++ b/doc/README.Users
@@ -76,4 +76,36 @@ or else Emacs won't listen for connections from emacsclient (and a new
 With this changes, using the `gnus` MUA, the mail is opened in the
 running `emacs`, or if there's none, a new instance is executed.
 
-Thanks to: Håkon Stordahl <hakon at stordahl.org>
\ No newline at end of file
+Thanks to: Håkon Stordahl <hakon at stordahl.org>
+
+How To Specify Pseudo-Headers
+=============================
+
+A pseudo-header is like a mail header (a pair of '<field>: value') but specified
+at the beginning of the mail body, instead of in the mail headers section.
+
+Some pseudo-headers, like 'Version' or 'Package' are added automatically by
+reportbug when preparing the report, but others can be specified by the
+reporter.
+
+This can be achieved in two ways:
+
+ - from the command-line, using "-P '<field>: value'" command-line option;
+ - directly when writing the report, appending the pseudo-header to the list at
+   the beginning of the email body.
+
+First of all, please note that reportbug tries to recognize if a given header is
+a pseudo-header, and so it should be left in the pseudo-header list, or else
+it's a mail header, and so it should be moved into mail headers section. This is
+done because it's easier to add a mail header to the pseudo-header list (because
+it's in the mail body, so you don't have to edit the mail headers) and let
+reportbug move it (or leave it) to the correct location (for example,
+'X-Debbugs-Cc' if added to the pseudo-header is then moved to mail headers
+section to be processed by debbugs engine).
+
+That said, please note that this two ways have now a different semantics: any
+pseudo-header passed on the command-line is preserved as a pseudo-header, and
+not moved to the mail headers part of the email, while adding a header into the
+mail body still trigger the reportbug recognition code that will move the header
+to mail headers part if not a "common" pseudo-header (like 'Usertags',
+'Severity', or 'Package' and so on).

-- 
Reportbug - reports bugs in the Debian distribution