Merge lp:~kissiel/checkbox/job-unit-manpage-flags-update into lp:checkbox

[Maciej Kisielewski]

This MR adds information about 'preserve-locale', 'win32', and 'noreturn'
flags to job-units manpage.

[Sylvain Pineau (sylvain-pineau)]

For the record, I'd add a link to a bug (https://bugs.launchpad.net/plainbox/+bug/1403832) where the noreturn flag is required (just to help understanding why this type of flag exists in plainbox).

[Zygmunt Krynicki (zyga)]

This looks good but I'd like to tweak formatting a little:

http://paste.ubuntu.com/10142501/

(feel free to ignore the first, unrelated change that corrects a warning

[lp:~kissiel/checkbox/job-unit-manpage-flags-update]

3568. By Maciej Kisielewski on 2015-02-09

docs:plainbox-job-units: add info about flags to manpage

This patch adds information about 'preserve-locale', 'win32', and 'noreturn'
flags to job-units manpage.

Signed-off-by: Maciej Kisielewski <email address hidden>

[Maciej Kisielewski (kissiel)]

> This looks good but I'd like to tweak formatting a little:
>
> http://paste.ubuntu.com/10142501/
>
> (feel free to ignore the first, unrelated change that corrects a warning

Applied your patch. Repushed.

[Zygmunt Krynicki (zyga)]

+1

review: Approve

=== modified file 'plainbox/docs/manpages/plainbox-job-units.rst'
--- plainbox/docs/manpages/plainbox-job-units.rst	2015-01-29 12:35:39 +0000
+++ plainbox/docs/manpages/plainbox-job-units.rst	2015-02-09 14:15:00 +0000
@@ -145,6 +145,7 @@
         passes or fails. The question should be phrased in such a way
         that an answer of **Yes** means the test passed, and an answer of
         **No** means it failed.
+
 .. warning::
     since version 0.17 fields: purpose, steps and verification should be used
     instead of description.
@@ -218,6 +219,30 @@
     expected to run for, as a positive float value indicating
     the estimated job duration in seconds.
 
+``flags``:
+    (optional) This fields contains list of flags separated by spaces or
+    commas that might induce plainbox to run the job in particular way.
+    Currently, following flags are inspected by plainbox:
+
+    ``preserve-locale``:
+        This flag makes plainbox carry locale settings to the job's command. If
+        this flag is not set, plainbox will neuter locale settings.  Attach
+        this flag to all job definitions with commands that use translations .
+
+    ``win32``:
+        This flag makes plainbox run jobs' commands in windows-specific manner.
+        Attach this flag to jobs that are run on Windows OS.
+
+    ``noreturn``:
+        This flag makes plainbox suspend execution after job's command is run.
+        This prevents scenario where plainbox continued to operate (writing
+        session data to disk and so on), while other process kills it (leaving
+        plainbox session in unwanted/undefined state).
+        Attach this flag to jobs that cause killing of plainbox process during
+        their operation. E.g. run shutdown, reboot, etc.
+
+    Additional flags may be present in job definition; they are ignored.
+
 ===========================
 Extension of the job format
 ===========================