Merge lp:~jelmer/bzr/bzr.1-generate-environment-section into lp:bzr

[Jelmer Vernooij]

Generate environment variables section in bzr(1) from standard list of environment variables.

Generate list of environment variables under ENVIRONMENT section in the manpage from the same list that is used to generate the 'bzr help env-topics' topic.

Now with ordering preserved.

[Martin Packman (gz)]

I'd be tempted to use a list of 2-tuples to preserve order rather than a dict and sorting it, which would split up BZR_EMAIL and EMAIL, for instance. Should probably also think about opening these to translation, though not in this branch.

[Jelmer Vernooij (jelmer)]

Hmm, fair enough. I guess if we're doing tuples we might as well include something to filter out the lines not relevant on the current platform.

[Vincent Ladeuil (vila)]

I have a vague feeling that env vars related to config options should be documented there (and also discouraged since they can't be used on windows but that's quite out of scope for this proposal).

That being said, this is a significant step in the right direction so please proceed to the launchpad (fixing the conflicts and while you're there if you could think of at least one test to start rolling the ball, please do ;) and land.

review: Approve

[Martin Packman (gz)]

I like the idea of making it a 3-tuple with set([None, 'posix', 'nt']) for defining bit and displaying only if `t[2] in (None, os.name)` or similar.

Some mini tests for the layout function?

+ ret.append("=" * max_key_len + " " + "=" * desc_len + "\n")
...
+ ret += "=" * max_key_len + " " + "=" * desc_len + "\n"

One of these lines is not like the other. So, which adds one string of 80 characters, and which adds 80 strings of one character? :)

[Jelmer Vernooij (jelmer)]

sent to pqm by email

=== modified file 'bzrlib/doc_generate/autodoc_man.py'
--- bzrlib/doc_generate/autodoc_man.py	2012-03-14 18:11:34 +0000
+++ bzrlib/doc_generate/autodoc_man.py	2012-03-15 16:14:18 +0000
@@ -56,6 +56,7 @@
     outfile.write(man_escape(man_head % params))
     outfile.write(man_escape(getcommand_list(params)))
     outfile.write(man_escape(getcommand_help(params)))
+    outfile.write("".join(environment_variables()))
     outfile.write(man_escape(man_foot % params))
 
 
@@ -171,6 +172,16 @@
     return help
 
 
+def environment_variables():
+    yield ".SH \"ENVIRONMENT\"\n"
+
+    from bzrlib.help_topics import known_env_variables
+    for k, desc in known_env_variables:
+        yield ".TP\n"
+        yield ".I \"%s\"\n" % k
+        yield man_escape(desc) + "\n"
+
+
 man_preamble = """\
 .\\\"Man page for Bazaar (%(bzrcmd)s)
 .\\\"
@@ -215,30 +226,6 @@
 """
 
 man_foot = """\
-.SH "ENVIRONMENT"
-.TP
-.I "BZRPATH"
-Path where
-.B "%(bzrcmd)s"
-is to look for shell plugin external commands.
-.TP
-.I "BZR_EMAIL"
-E-Mail address of the user. Overrides default user config.
-.TP
-.I "EMAIL"
-E-Mail address of the user. Overrides default user config.
-.TP
-.I "BZR_EDITOR"
-Editor for editing commit messages
-.TP
-.I "EDITOR"
-Editor for editing commit messages
-.TP
-.I "BZR_PLUGIN_PATH"
-Paths where bzr should look for plugins
-.TP
-.I "BZR_HOME"
-Home directory for bzr
 .SH "FILES"
 .TP
 .I "~/.bazaar/bazaar.conf"
 
=== modified file 'bzrlib/help_topics/__init__.py'
--- bzrlib/help_topics/__init__.py	2012-02-23 19:45:15 +0000
+++ bzrlib/help_topics/__init__.py	2012-03-15 16:14:18 +0000
@@ -595,38 +595,42 @@
 """
 
 
-_env_variables = \
-"""Environment Variables
-
-=================== ===========================================================
-BZRPATH             Path where bzr is to look for shell plugin external
-                    commands.
-BZR_EMAIL           E-Mail address of the user. Overrides EMAIL.
-EMAIL               E-Mail address of the user.
-BZR_EDITOR          Editor for editing commit messages. Overrides EDITOR.
-EDITOR              Editor for editing commit messages.
-BZR_PLUGIN_PATH     Paths where bzr should look for plugins.
-BZR_DISABLE_PLUGINS Plugins that bzr should not load.
-BZR_PLUGINS_AT      Plugins to load from a directory not in BZR_PLUGIN_PATH.
-BZR_HOME            Directory holding .bazaar config dir. Overrides HOME.
-BZR_HOME (Win32)    Directory holding bazaar config dir. Overrides APPDATA and
-                    HOME.
-BZR_REMOTE_PATH     Full name of remote 'bzr' command (for bzr+ssh:// URLs).
-BZR_SSH             Path to SSH client, or one of paramiko, openssh, sshcorp,
-                    plink or lsh.
-BZR_LOG             Location of .bzr.log (use '/dev/null' to suppress log).
-BZR_LOG (Win32)     Location of .bzr.log (use 'NUL' to suppress log).
-BZR_COLUMNS         Override implicit terminal width.
-BZR_CONCURRENCY     Number of processes that can be run concurrently (selftest)
-BZR_PROGRESS_BAR    Override the progress display. Values are 'none' or 'text'.
-BZR_PDB             Control whether to launch a debugger on error.
-BZR_SIGQUIT_PDB     Control whether SIGQUIT behaves normally or invokes a
-                    breakin debugger.
-BZR_TEXTUI_INPUT    Force console input mode for prompts to line-based (instead
-                    of char-based).
-=================== ===========================================================
-"""
-
+known_env_variables = [
+    ("BZRPATH", "Path where bzr is to look for shell plugin external commands."),
+    ("BZR_EMAIL", "E-Mail address of the user. Overrides EMAIL."),
+    ("EMAIL", "E-Mail address of the user."),
+    ("BZR_EDITOR", "Editor for editing commit messages. Overrides EDITOR."),
+    ("EDITOR", "Editor for editing commit messages."),
+    ("BZR_PLUGIN_PATH", "Paths where bzr should look for plugins."),
+    ("BZR_DISABLE_PLUGINS", "Plugins that bzr should not load."),
+    ("BZR_PLUGINS_AT", "Plugins to load from a directory not in BZR_PLUGIN_PATH."),
+    ("BZR_HOME", "Directory holding .bazaar config dir. Overrides HOME."),
+    ("BZR_HOME (Win32)", "Directory holding bazaar config dir. Overrides APPDATA and HOME."),
+    ("BZR_REMOTE_PATH", "Full name of remote 'bzr' command (for bzr+ssh:// URLs)."),
+    ("BZR_SSH", "Path to SSH client, or one of paramiko, openssh, sshcorp, plink or lsh."),
+    ("BZR_LOG", "Location of .bzr.log (use '/dev/null' to suppress log)."),
+    ("BZR_LOG (Win32)", "Location of .bzr.log (use 'NUL' to suppress log)."),
+    ("BZR_COLUMNS", "Override implicit terminal width."),
+    ("BZR_CONCURRENCY", "Number of processes that can be run concurrently (selftest)"),
+    ("BZR_PROGRESS_BAR", "Override the progress display. Values are 'none' or 'text'."),
+    ("BZR_PDB", "Control whether to launch a debugger on error."),
+    ("BZR_SIGQUIT_PDB", "Control whether SIGQUIT behaves normally or invokes a breakin debugger."),
+    ("BZR_TEXTUI_INPUT", "Force console input mode for prompts to line-based (instead of char-based)."),
+    ]
+
+def _env_variables(topic):
+    import textwrap
+    ret = ["Environment Variables\n\n"]
+    max_key_len = max([len(k[0]) for k in known_env_variables])
+    desc_len = (80 - max_key_len - 2)
+    ret.append("=" * max_key_len + " " + "=" * desc_len + "\n")
+    for k, desc in known_env_variables:
+        ret.append(k + (max_key_len + 1 - len(k)) * " ")
+        ret.append("\n".join(textwrap.wrap(
+            desc, width=desc_len, subsequent_indent=" " * (max_key_len + 1))))
+        ret.append("\n")
+    ret += "=" * max_key_len + " " + "=" * desc_len + "\n"
+    return "".join(ret)
 
 _files = \
 r"""Files
 
=== modified file 'doc/en/release-notes/bzr-2.6.txt'
--- doc/en/release-notes/bzr-2.6.txt	2012-03-15 15:09:48 +0000
+++ doc/en/release-notes/bzr-2.6.txt	2012-03-15 16:14:18 +0000
@@ -119,6 +119,7 @@
 
 .. Improved or updated documentation.
 
+<<<<<<< TREE
 * Document "bzr lp-propose", "bzr register-branch" and
   the other Launchpad plugin commands in bzr(1).
   (Jelmer Vernooij, #843801, #163995)
@@ -127,6 +128,11 @@
   accidentally be interpreted as a roff macro in bzr(1).
   (Jelmer Vernooij, #711079)
 
+=======
+* Generate ``ENVIRONMENT`` section in bzr(1) from known environment variable
+  list rather than hardcoding. (Jelmer Vernooij, #197618)
+
+>>>>>>> MERGE-SOURCE
 * Properly format apostrophes in manual page. (Jelmer Vernooij, #234771)
 
 API Changes