Merge lp:~ian-clatworthy/bzr/user-ref-topics into lp:bzr

[Ian Clatworthy]

[Ian Clatworthy (ian-clatworthy)]

This branch formats the User Reference as a set of topics. Improving the formatting of the User Reference in this way was recently discussed and agreed to on the bzr-doc mailing list. The formatting and cross-linking of numerous topics has also been improved.

As a side effect of this change, each help topic is now available as http://doc.bazaar.canonical.com/test/en/user-reference/xxx-help.html. The old "conflicts" help topic has been renamed to "conflict-types" so that the conflicts command and it don't map to exactly the same URL.

[Martin Pool (mbp)]

The change of 'conflicts' name is good but should be in NEWS; perhaps the reformatting should be too.

Thanks

review: Needs Fixing

[lp:~ian-clatworthy/bzr/user-ref-topics]

4935. By Ian Clatworthy on 2010-01-04

Add NEWS items as requested by poolie's review.

[Ian Clatworthy (ian-clatworthy)]

> The change of 'conflicts' name is good but should be in NEWS; perhaps the
> reformatting should be too.

Done.

=== modified file 'NEWS'
--- NEWS	2010-01-04 05:40:01 +0000
+++ NEWS	2010-01-04 08:49:20 +0000
@@ -79,7 +79,14 @@
 
 * There is a System Administrator's Guide in ``doc/en/admin-guide``,
   including discussions of installation, relevant plugins, security and 
-  backup.
+  backup. (Neil Martinsen-Burrell)
+
+* The ``conflicts`` help topic has been renamed to ``conflict-types``.
+  (Ian Clatworthy)
+
+* The User Reference is now presented as a series of topics.
+  Many of the included topics have link and format tweaks applied.
+  (Ian Clatworthy)
 
 API Changes
 ***********

=== modified file 'bzrlib/bugtracker.py'
--- bzrlib/bugtracker.py	2009-06-10 03:31:01 +0000
+++ bzrlib/bugtracker.py	2010-01-04 08:49:20 +0000
@@ -39,12 +39,12 @@
 
 _bugs_help = \
 """When making a commit, metadata about bugs fixed by that change can be
-recorded by using the --fixes option. For each bug marked as fixed, an
+recorded by using the ``--fixes`` option. For each bug marked as fixed, an
 entry is included in the 'bugs' revision property stating '<url> <status>'.
 (The only ``status`` value currently supported is ``fixed.``)
 
-The --fixes option allows you to specify a bug tracker and a bug identifier
-rather than a full URL. This looks like
+The ``--fixes`` option allows you to specify a bug tracker and a bug identifier
+rather than a full URL. This looks like::
 
     bzr commit --fixes <tracker>:<id>
 
@@ -56,10 +56,13 @@
 use this feature, you just need to know the tracker identifier to use.
 These are the bugtrackers that are built in:
 
-     URL                          | Abbreviation | Example
-     https://bugs.launchpad.net/  | lp           | lp:12345
-     http://bugs.debian.org/      | deb          | deb:12345
-     http://bugzilla.gnome.org/   | gnome        | gnome:12345
+  ============================ ============ ============
+  URL                          Abbreviation Example
+  ============================ ============ ============
+  https://bugs.launchpad.net/  lp           lp:12345
+  http://bugs.debian.org/      deb          deb:12345
+  http://bugzilla.gnome.org/   gnome        gnome:12345
+  ============================ ============ ============
 
 For the bug trackers not listed above configuration is required.
 Support for generating the URLs for any project using Bugzilla or Trac
@@ -82,11 +85,11 @@
 
 Use ``bzr commit --fixes lp:2`` to record that this commit fixes bug 2.
 
-bugzilla_<tracker_abbreviation>_url
------------------------------------
+bugzilla_<tracker>_url
+----------------------
 
 If present, the location of the Bugzilla bug tracker referred to by
-<tracker_abbreviation>. This option can then be used together with ``bzr commit
+<tracker>. This option can then be used together with ``bzr commit
 --fixes`` to mark bugs in that tracker as being fixed by that commit. For
 example::
 
@@ -95,11 +98,11 @@
 would allow ``bzr commit --fixes squid:1234`` to mark Squid's bug 1234 as
 fixed.
 
-trac_<tracker_abbrevation>_url
-------------------------------
+trac_<tracker>_url
+------------------
 
 If present, the location of the Trac instance referred to by
-<tracker_abbreviation>. This option can then be used together with ``bzr commit
+<tracker>. This option can then be used together with ``bzr commit
 --fixes`` to mark bugs in that tracker as being fixed by that commit. For
 example::
 
@@ -108,11 +111,11 @@
 would allow ``bzr commit --fixes twisted:1234`` to mark Twisted's bug 1234 as
 fixed.
 
-bugtracker_<tracker_abbrevation>_url
-------------------------------------
+bugtracker_<tracker>_url
+------------------------
 
 If present, the location of a generic bug tracker instance referred to by
-<tracker_abbreviation>. The location must contain an ``{id}`` placeholder,
+<tracker>. The location must contain an ``{id}`` placeholder,
 which will be replaced by a specific bug ID. This option can then be used
 together with ``bzr commit --fixes`` to mark bugs in that tracker as being
 fixed by that commit. For example::

=== modified file 'bzrlib/bzrdir.py'
--- bzrlib/bzrdir.py	2009-12-02 17:56:06 +0000
+++ bzrlib/bzrdir.py	2010-01-04 08:49:20 +0000
@@ -3513,7 +3513,7 @@
                 experimental_pairs.append((key, help))
             else:
                 output += wrapped(key, help, info)
-        output += "\nSee ``bzr help formats`` for more about storage formats."
+        output += "\nSee :doc:`formats-help` for more about storage formats."
         other_output = ""
         if len(experimental_pairs) > 0:
             other_output += "Experimental formats are shown below.\n\n"
@@ -3532,7 +3532,7 @@
             other_output += \
                 "\nNo deprecated formats are available.\n\n"
         other_output += \
-            "\nSee ``bzr help formats`` for more about storage formats."
+                "\nSee :doc:`formats-help` for more about storage formats."
 
         if topic == 'other-formats':
             return other_output

=== modified file 'bzrlib/commands.py'
--- bzrlib/commands.py	2009-12-09 05:47:32 +0000
+++ bzrlib/commands.py	2010-01-04 08:49:20 +0000
@@ -511,8 +511,9 @@
                         # so don't create a real link
                         see_also_links.append(item)
                     else:
-                        # Use a reST link for this entry
-                        see_also_links.append("`%s`_" % (item,))
+                        # Use a Sphinx link for this entry
+                        link_text = ":doc:`%s <%s-help>`" % (item, item)
+                        see_also_links.append(link_text)
                 see_also = see_also_links
             result += ':See also: '
             result += ', '.join(see_also) + '\n'

=== modified file 'bzrlib/conflicts.py'
--- bzrlib/conflicts.py	2009-11-23 03:15:33 +0000
+++ bzrlib/conflicts.py	2010-01-04 08:49:20 +0000
@@ -58,7 +58,7 @@
             Option('text',
                    help='List paths of files with text conflicts.'),
         ]
-    _see_also = ['resolve']
+    _see_also = ['resolve', 'conflict-types']
 
     def run(self, text=False):
         from bzrlib.workingtree import WorkingTree

=== modified file 'bzrlib/doc_generate/autodoc_rstx.py'
--- bzrlib/doc_generate/autodoc_rstx.py	2009-09-09 14:35:26 +0000
+++ bzrlib/doc_generate/autodoc_rstx.py	2010-01-04 08:49:20 +0000
@@ -14,7 +14,7 @@
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 
-"""Generate ReStructuredText source for the User Reference Manual.
+"""Generate reStructuredText source for the User Reference Manual.
 Loosely based on the manpage generator autodoc_man.py.
 
 Written by the Bazaar community.
@@ -36,7 +36,7 @@
 # ought to be prefixed with their section name as well so
 # there's zero risk of clashing with a standard sphinx
 # topic (like search.html).
-FILE_PER_TOPIC = False
+FILE_PER_TOPIC = True
 
 
 def get_filename(options):
@@ -74,8 +74,7 @@
         output_dir=topic_dir))
     result.append(_get_section(registry, SECT_LIST, "Lists",
         output_dir=topic_dir))
-    result.append(_get_commands_section(registry))
-    #result.append(_get_section(registry, SECT_PLUGIN, "Standard Plug-ins"))
+    result.append(_get_commands_section(registry, output_dir=topic_dir))
     return "\n".join(result)
 
 
@@ -86,8 +85,9 @@
     If output_dir is not None, topics are dumped into text files there
     during processing, as well as being included in the return result.
     """
-    topics = sorted(registry.get_topics_for_section(section))
     lines = [title, hdg_level1 * len(title), ""]
+    if FILE_PER_TOPIC:
+        lines.extend([".. toctree::", "   :maxdepth: 1", ""])
 
     # docutils treats section heading as implicit link target.
     # But in some cases topic and heading are different, e.g.:
@@ -102,56 +102,68 @@
     # .. _topic: `heading`_
     links_glue = []
 
+    topics = sorted(registry.get_topics_for_section(section))
     for topic in topics:
         help = registry.get_detail(topic)
-        heading,text = help.split("\n", 1)
-        lines.append(heading)
+        heading, text = help.split("\n", 1)
         if not text.startswith(hdg_level2):
-            lines.append(hdg_level2 * len(heading))
-        lines.append(text)
-        lines.append('')
+            underline = hdg_level2 * len(heading)
+            help = "%s\n%s\n\n%s\n\n" % (heading, underline, text)
+        else:
+            help = "%s\n%s\n\n" % (heading, text)
+        if FILE_PER_TOPIC:
+            topic_id = _dump_text(output_dir, topic, help)
+            lines.append("   %s" % topic_id)
+        else:
+            lines.append(help)
+
         # check that topic match heading
         if topic != heading.lower():
             links_glue.append((topic, heading))
-        # dump the text if requested
-        if output_dir is not None:
-            out_file = bzrlib.osutils.pathjoin(output_dir, topic + ".txt")
-            _dump_text(out_file, help)
 
     # provide links glue for topics that don't match headings
-    lines.extend([".. _%s: `%s`_" % i for i in links_glue])
-    lines.append('')
+    #lines.append('')
+    #lines.extend([".. _%s: `%s`_" % i for i in links_glue])
+    #lines.append('')
 
     return "\n" + "\n".join(lines) + "\n"
 
 
-def _dump_text(filename, text):
-    """Dump text to filename."""
-    if not FILE_PER_TOPIC:
-        return
-    f =  open(filename, "w")
-    f.writelines(text)
-    f.close()
-
-
 def _get_commands_section(registry, title="Commands", hdg_level1="#",
-                          hdg_level2="="):
+        hdg_level2="=", output_dir=None):
     """Build the commands reference section of the manual."""
     lines = [title, hdg_level1 * len(title), ""]
+    if FILE_PER_TOPIC:
+        lines.extend([".. toctree::", "   :maxdepth: 1", ""])
+
     cmds = sorted(bzrlib.commands.builtin_command_names())
     for cmd_name in cmds:
         cmd_object = bzrlib.commands.get_cmd_object(cmd_name)
         if cmd_object.hidden:
             continue
         heading = cmd_name
+        underline = hdg_level2 * len(heading)
         text = cmd_object.get_help_text(plain=False, see_also_as_links=True)
-        lines.append(heading)
-        lines.append(hdg_level2 * len(heading))
-        lines.append(text)
-        lines.append('')
+        help = "%s\n%s\n\n%s\n\n" % (heading, underline, text)
+        if FILE_PER_TOPIC:
+            topic_id = _dump_text(output_dir, cmd_name, help)
+            lines.append("   %s" % topic_id)
+        else:
+            lines.append(help)
+
     return "\n" + "\n".join(lines) + "\n"
 
 
+def _dump_text(output_dir, topic, text):
+    """Dump text for a topic to a file."""
+    topic_id = "%s-%s" % (topic, "help")
+    filename = bzrlib.osutils.pathjoin(output_dir, topic_id + ".txt")
+    f =  open(filename, "w")
+    f.writelines(text)
+    f.close()
+    return topic_id
+
+
 ##
 # TEMPLATES
 
@@ -194,8 +206,8 @@
 
 The following web sites provide further information on Bazaar:
 
-:Home page:                     http://www.bazaar-vcs.org/
-:Official docs:                 http://doc.bazaar-vcs.org/
+:Home page:                     http://bazaar.canonical.com/
+:Official docs:                 http://doc.bazaar.canonical.com/
 :Launchpad:                     https://launchpad.net/bzr/
 """
 

=== modified file 'bzrlib/help_topics/__init__.py'
--- bzrlib/help_topics/__init__.py	2009-12-07 18:50:45 +0000
+++ bzrlib/help_topics/__init__.py	2010-01-04 08:49:20 +0000
@@ -306,7 +306,7 @@
 """Global Options
 
 These options may be used with any command, and may appear in front of any
-command.  (e.g. "bzr --profile help").
+command.  (e.g. ``bzr --profile help``).
 
 --version      Print the version number. Must be supplied before the command.
 --no-aliases   Do not process command aliases when running this command.
@@ -325,9 +325,11 @@
                will be a pickle.
 --coverage     Generate line coverage report in the specified directory.
 
-See doc/developers/profiling.txt for more information on profiling.
+See http://doc.bazaar.canonical.com/developers/profiling.html for more
+information on profiling.
+
 A number of debug flags are also available to assist troubleshooting and
-development.  See `bzr help debug-flags`.
+development.  See :doc:`debug-flags-help`.
 """
 
 _standard_options = \
@@ -647,7 +649,7 @@
 differences.
 """
 
-_branches_out_of_sync = """Branches out of sync
+_branches_out_of_sync = """Branches Out of Sync
 
 When reconfiguring a checkout, tree or branch into a lightweight checkout,
 a local branch must be destroyed.  (For checkouts, this is the local branch
@@ -682,18 +684,20 @@
 project owner to upgrade.
 
 
-Note: Some of the older formats have two variants:
-a plain one and a rich-root one. The latter include an additional
-field about the root of the tree. There is no performance cost
-for using a rich-root format but you cannot easily merge changes
-from a rich-root format into a plain format. As a consequence,
-moving a project to a rich-root format takes some co-ordination
-in that all contributors need to upgrade their repositories
-around the same time. 2a and all future formats will be
-implicitly rich-root.
-
-See ``bzr help current-formats`` for the complete list of
-currently supported formats. See ``bzr help other-formats`` for
+.. note::
+
+   Some of the older formats have two variants:
+   a plain one and a rich-root one. The latter include an additional
+   field about the root of the tree. There is no performance cost
+   for using a rich-root format but you cannot easily merge changes
+   from a rich-root format into a plain format. As a consequence,
+   moving a project to a rich-root format takes some co-ordination
+   in that all contributors need to upgrade their repositories
+   around the same time. 2a and all future formats will be
+   implicitly rich-root.
+
+See :doc:`current-formats-help` for the complete list of
+currently supported formats. See :doc:`other-formats-help` for
 descriptions of any available experimental and deprecated formats.
 """
 
@@ -742,14 +746,12 @@
                         'Information on configuring authentication')
 topic_registry.register('configuration', _load_from_file,
                         'Details on the configuration settings available')
-topic_registry.register('conflicts', _load_from_file,
+topic_registry.register('conflict-types', _load_from_file,
                         'Types of conflicts and what to do about them')
 topic_registry.register('debug-flags', _load_from_file,
                         'Options to show or record debug information')
 topic_registry.register('log-formats', _load_from_file,
                         'Details on the logging formats available')
-topic_registry.register('diverged-branches', _load_from_file,
-                        'How to fix diverged branches')
 
 
 # Register concept topics.
@@ -763,6 +765,9 @@
 topic_registry.register('content-filters', _load_from_file,
                         'Conversion of content into/from working trees',
                         SECT_CONCEPT)
+topic_registry.register('diverged-branches', _load_from_file,
+                        'How to fix diverged branches',
+                        SECT_CONCEPT)
 topic_registry.register('eol', _load_from_file,
                         'Information on end-of-line handling',
                         SECT_CONCEPT)

=== modified file 'bzrlib/help_topics/en/authentication.txt'
--- bzrlib/help_topics/en/authentication.txt	2008-05-09 16:40:21 +0000
+++ bzrlib/help_topics/en/authentication.txt	2010-01-04 08:49:20 +0000
@@ -110,10 +110,8 @@
 File format
 -----------
 
-The general rules for `configuration files`_ apply except for the variable
-policies.
-
-.. _configuration files: #configuration-settings
+The general rules for :doc:`configuration files <configuration-help>`
+apply except for the variable policies.
 
 Each section describes an authentication definition.
 

=== modified file 'bzrlib/help_topics/en/configuration.txt'
--- bzrlib/help_topics/en/configuration.txt	2009-12-15 20:32:34 +0000
+++ bzrlib/help_topics/en/configuration.txt	2010-01-04 08:49:20 +0000
@@ -272,7 +272,7 @@
 variable policies which don't apply.
 
 For more information on the possible uses of the authentication configuration
-file see `Authentication Settings`_.
+file see :doc:`authentication-help`.
 
 
 Common variable options

=== renamed file 'bzrlib/help_topics/en/conflicts.txt' => 'bzrlib/help_topics/en/conflict-types.txt'
--- bzrlib/help_topics/en/conflicts.txt	2009-11-25 16:42:55 +0000
+++ bzrlib/help_topics/en/conflict-types.txt	2010-01-04 08:49:20 +0000
@@ -1,5 +1,5 @@
-Conflicts Types
-===============
+Conflict Types
+==============
 
 Some operations, like merge, revert and pull, modify the contents of your
 working tree.  These modifications are programmatically generated, and so they

=== modified file 'bzrlib/help_topics/en/content-filters.txt'
--- bzrlib/help_topics/en/content-filters.txt	2009-02-25 06:41:51 +0000
+++ bzrlib/help_topics/en/content-filters.txt	2010-01-04 08:49:20 +0000
@@ -65,8 +65,8 @@
 Note: ``bzr commit`` does not implicitly apply write converters after
 comitting files. If this makes sense for a given plugin providing
 a content filter, the plugin can usually achieve this effect by using a
-``start_commit`` or ``post_commit`` hook say. See ``bzr help hooks`` and
-`Using hooks`_ in the Bazaar User Guide for more information on hooks.
+``start_commit`` or ``post_commit`` hook say. See :doc:`hooks-help`
+for more information on hooks.
 
 
 Refreshing your working tree

=== modified file 'bzrlib/help_topics/en/log-formats.txt'
--- bzrlib/help_topics/en/log-formats.txt	2009-02-09 08:19:18 +0000
+++ bzrlib/help_topics/en/log-formats.txt	2010-01-04 08:49:20 +0000
@@ -1,4 +1,4 @@
-Log formats
+Log Formats
 ===========
 
 A log format controls how information about each revision is displayed.

=== modified file 'bzrlib/help_topics/en/rules.txt'
--- bzrlib/help_topics/en/rules.txt	2009-04-26 03:04:30 +0000
+++ bzrlib/help_topics/en/rules.txt	2010-01-04 08:49:20 +0000
@@ -16,8 +16,9 @@
 
 Preferences like these are useful for commands and plugins wishing to
 provide custom behaviour for selected files.  For more information on 
-end of line conversion see ``bzr help eol``.  Keyword support is provided
-by the bzr-keywords plugin (http://launchpad.net/bzr-keywords).
+end of line conversion see :doc:`eol-help`.
+Keyword support is provided by the `keywords plugin
+<http://doc.bazaar.canonical.com/plugins/en/keywords-plugin.html>`_.
 
 Files
 -----
@@ -31,7 +32,9 @@
 Patterns are ordered and searching stops as soon as one matches.
 As a consequence, more explicit patterns should be placed towards
 the top of the file. Rule patterns use exactly the same conventions
-as ignore patterns. See ``bzr help patterns`` for details.
-
-Note: Patterns containing square brackets or spaces should be
-surrounded in quotes to ensure they are correctly parsed.
+as ignore patterns. See :doc:`patterns-help` for details.
+
+.. note::
+
+   Patterns containing square brackets or spaces should be
+   surrounded in quotes to ensure they are correctly parsed.

=== modified file 'bzrlib/hooks.py'
--- bzrlib/hooks.py	2009-09-01 12:29:54 +0000
+++ bzrlib/hooks.py	2010-01-04 08:49:20 +0000
@@ -277,7 +277,7 @@
 
 See `Using hooks`_ in the User Guide for examples.
 
-.. _Using hooks: ../user-guide/index.html#using-hooks
+.. _Using hooks: ../user-guide/hooks.html
 
 The class that contains each hook is given before the hooks it supplies. For
 instance, BranchHooks as the class is the hooks class for

=== modified file 'doc/en/user-guide/hooks.txt'
--- doc/en/user-guide/hooks.txt	2008-10-29 06:10:45 +0000
+++ doc/en/user-guide/hooks.txt	2010-01-04 08:49:20 +0000
@@ -8,18 +8,18 @@
 perform actions before or after certain Bazaar operations.  The operations
 include ``commit``, ``push``, ``pull``, and ``uncommit``.
 For a complete list of hooks and their parameters, see `Hooks
-<../user-reference/bzr_man.html#hooks>`_ in the User Reference.
+<../user-reference/hooks-help.html>`_ in the User Reference.
 
 Most hooks are run on the client, but a few are run on the server.  (Also
-see the `bzr-push-and-update`_ plugin that handles one special case of
+see the `push-and-update plugin`_ that handles one special case of
 server-side operations.)
 
-.. _bzr-push-and-update: https://launchpad.net/bzr-push-and-update/
+.. _push-and-update plugin: http://doc.bazaar.canonical.com/plugins/en/push-and-update-plugin.html
 
 Using hooks
 -----------
 
-To use a hook, you should `write a plugin <#writing-a-plugin>`_.  Instead of
+To use a hook, you should `write a plugin`_.  Instead of
 creating a new command, this plugin will define and install the hook.  Here's
 an example::
 
@@ -33,6 +33,8 @@
     branch.Branch.hooks.install_named_hook('post_push', post_push_hook,
                                      'My post_push hook')
 
+.. _write a plugin: http://doc.bazaar.canonical.com/plugins/en/plugin-development.html
+
 To use this example, create a file named ``push_hook.py``, and stick it in
 ``plugins`` subdirectory of your configuration directory.  (If you have never
 installed any plugins, you may need to create the ``plugins`` directory).