Reorganize "About", and make all TODO items more clear using todo extension.

diff --git a/docs/en/rst/_static/bugzilla.css b/docs/en/rst/_static/bugzilla.css
index 2826b19e7829d3c5cad1ada169fbd06dfdeb7383..c8f3529473cbab47b6b0c1f29e42d5769f749ceb 100644 (file)
--- a/docs/en/rst/_static/bugzilla.css
+++ b/docs/en/rst/_static/bugzilla.css
@@ -8,3 +8,8 @@ dt { font-weight: bold; }
 .group    { font-family: monospace; }
 .field    { font-weight: bold; }
 .command  { font-family: monospace; font-size: 130% }
+
+.admonition-todo {
+  background-color: lightpink;
+  border: 2px darkred solid;
+}

diff --git a/docs/en/rst/about.rst b/docs/en/rst/about.rst
index 720c5d4cc1694a3f0c7da4271ec8cf4018a676a2..4801e0f3a9aa30ac3bccaeed9321f559e6a71cf3 100644 (file)
--- a/docs/en/rst/about.rst
+++ b/docs/en/rst/about.rst
@@ -4,12 +4,124 @@
 About This Guide
 ================
 
-.. toctree::
-   :maxdepth: 2
-
-   about/introduction
-   about/evaluating
-   about/getting-help
-   about/document-conventions
-   about/license
-   about/credits
+This is the documentation for version |version| of Bugzilla, a bug-tracking
+system from Mozilla. Bugzilla is an enterprise-class piece of software
+that tracks millions of bugs and issues for thousands of organizations around
+the world.
+
+The most current version of this document can always be found on the
+`Bugzilla website <http://www.bugzilla.org/docs/>`_.
+
+.. _evaluating:
+
+Evaluating Bugzilla
+###################
+
+If you want to try out Bugzilla to see if it meets your needs, you can do so
+on `Landfill <https://landfill.bugzilla.org/bugzilla-4.4-branch/>`_, our test
+server. The `Bugzilla FAQ <https://wiki.mozilla.org/Bugzilla:FAQ>`_ may also
+be helpful, as it answers a number of questions people sometimes have about
+whether Bugzilla is for them.
+
+.. _getting-help:
+
+Getting More Help
+#################
+
+If this document does not answer your questions, we run a
+`Mozilla forum <https://www.mozilla.org/about/forums/#support-bugzilla>`_
+which can be accessed as a newsgroup, mailing list, or over the web as a
+Google Group. Please
+`search it <https://groups.google.com/forum/#!forum/mozilla.support.bugzilla>`_
+first, and then ask your question there.
+
+If you need a guaranteed response, commercial support is
+`available <http://www.bugzilla.org/support/consulting.html>`_ for Bugzilla
+from a number of people and organizations.
+
+.. _conventions:
+
+Document Conventions
+####################
+
+This document uses the following conventions:
+
+.. warning:: This is a warning - something you should be aware of.
+
+.. note:: This is just a note, for your information.
+
+A filename or a path to a filename is displayed like this:
+:file:`/path/to/filename.ext`
+
+A command to type in the shell is displayed like this:
+:command:`command --arguments`
+
+A sample of code is illustrated like this:
+
+::
+
+    First Line of Code
+    Second Line of Code
+    ...
+
+This documentation is maintained in
+`reStructured Text
+<http://docutils.sourceforge.net/docs/user/rst/quickstart.html>`_ format using
+the `Sphinx <http://www.sphinx-doc.org/>`_ documentation system. It has
+recently been rewritten, so undoubtedly has bugs. Please file any you find, in
+the `Bugzilla Documentation
+<https://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla;component=Documentation>`_
+component in Mozilla's installation of Bugzilla. If you also want to make a
+patch, that would be wonderful. Changes are best submitted as diffs, attached
+to a bug. There is a :ref:`Style Guide <style-guide>` to help you write any
+new text and markup.
+
+.. _license:
+
+License
+#######
+
+Bugzilla is `free <http://www.gnu.org/philosophy/free-sw.html>`_ and
+`open source <http://opensource.org/osd>`_ software, which means (among other
+things) that you can download it, install it and run it for any purpose
+whatsoever without the need for license or payment. Isn't that refreshing?
+
+Bugzilla's code is made available under the
+`Mozilla Public License 2.0 <http://www.mozilla.org/MPL/2.0/>`_ (MPL),
+specifically the variant which is Incompatible with Secondary Licenses.
+However, again, if you only want to install and run Bugzilla, you don't need
+to worry about that; it's only relevant if you redistribute the code or any
+changes you make. 
+
+Bugzilla's documentation is made available under the
+`Creative Commons CC-BY-SA International License 4.0
+<https://creativecommons.org/licenses/by-sa/4.0/>`_,
+or any later version.
+
+.. _credits:
+
+Credits
+#######
+
+The people listed below have made significant contributions to the
+creation of this documentation:
+
+Andrew Pearson,
+Ben FrantzDale,
+Dave Lawrence,
+Dave Miller,
+Dawn Endico,
+Eric Hanson,
+Gervase Markham,
+Jacob Steenhagen,
+Joe Robins,
+Kevin Brannen,
+Martin Wulffeld,
+Matthew P. Barnson,
+Ron Teitelbaum,
+Shane Travis,
+Spencer Smith,
+Tara Hernandez,
+Terry Weissman,
+Vlad Dascalu,
+Zach Lipton.

diff --git a/docs/en/rst/about/credits.rst b/docs/en/rst/about/credits.rst
deleted file mode 100644 (file)
index c395455..0000000
--- a/docs/en/rst/about/credits.rst
+++ /dev/null
@@ -1,27 +0,0 @@
-.. _credits:
-
-Credits
-#######
-
-The people listed below have made significant contributions to the
-creation of this documentation:
-
-Andrew Pearson,
-Ben FrantzDale,
-Dave Lawrence,
-Dave Miller,
-Dawn Endico,
-Eric Hanson,
-Gervase Markham,
-Jacob Steenhagen,
-Joe Robins,
-Kevin Brannen,
-Martin Wulffeld,
-Matthew P. Barnson,
-Ron Teitelbaum,
-Shane Travis,
-Spencer Smith,
-Tara Hernandez,
-Terry Weissman,
-Vlad Dascalu,
-Zach Lipton.

diff --git a/docs/en/rst/about/document-conventions.rst b/docs/en/rst/about/document-conventions.rst
deleted file mode 100644 (file)
index 507e704..0000000
--- a/docs/en/rst/about/document-conventions.rst
+++ /dev/null
@@ -1,36 +0,0 @@
-.. _conventions:
-
-Document Conventions
-####################
-
-This document uses the following conventions:
-
-.. warning:: This is a warning - something you should be aware of.
-
-.. note:: This is just a note, for your information.
-
-A filename or a path to a filename is displayed like this:
-:file:`/path/to/filename.ext`
-
-A command to type in the shell is displayed like this:
-:command:`command --arguments`
-
-A sample of code is illustrated like this:
-
-::
-
-    First Line of Code
-    Second Line of Code
-    ...
-
-This documentation is maintained in
-`reStructured Text
-<http://docutils.sourceforge.net/docs/user/rst/quickstart.html>`_ format using
-the `Sphinx <http://www.sphinx-doc.org/>`_ documentation system. It has
-recently been rewritten, so undoubtedly has bugs. Please file bugs on it in
-the `Bugzilla Documentation
-<https://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla;component=Documentation>`_
-component. If you want to make a patch, that would be wonderful. Changes are
-best submitted as diffs, attached to a bug. There is a
-:ref:`Style Guide <style-guide>` to help you write any new text and markup.
-

diff --git a/docs/en/rst/about/evaluating.rst b/docs/en/rst/about/evaluating.rst
deleted file mode 100644 (file)
index 8974351..0000000
--- a/docs/en/rst/about/evaluating.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-.. _evaluating:
-
-Evaluating Bugzilla
-###################
-
-If you want to evaluate Bugzilla, you can try it out on
-`Landfill <https://landfill.bugzilla.org/bugzilla-4.4-branch/>`_, our test
-server. The `Bugzilla FAQ <https://wiki.mozilla.org/Bugzilla:FAQ>`_ may also
-be helpful, as it answers a number of questions people sometimes have about
-whether Bugzilla can do what they need.
-

diff --git a/docs/en/rst/about/getting-help.rst b/docs/en/rst/about/getting-help.rst
deleted file mode 100644 (file)
index b126ffb..0000000
--- a/docs/en/rst/about/getting-help.rst
+++ /dev/null
@@ -1,16 +0,0 @@
-.. _getting-help:
-
-Getting More Help
-#################
-
-If this document does not answer your questions, we run a
-`Mozilla forum <https://www.mozilla.org/about/forums/#support-bugzilla>`_
-which can be accessed as a newsgroup, mailing list, or over the web as a
-Google Group. Please
-`search it <https://groups.google.com/forum/#!forum/mozilla.support.bugzilla>`_
-first, and then ask your question there.
-
-If you need a guaranteed response, commercial support is
-`available <http://www.bugzilla.org/support/consulting.html>`_ for Bugzilla
-from a number of people and organizations.
-

diff --git a/docs/en/rst/about/introduction.rst b/docs/en/rst/about/introduction.rst
deleted file mode 100644 (file)
index efdd4bd..0000000
--- a/docs/en/rst/about/introduction.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-.. _introduction:
-
-Introduction
-############
-
-This is the documentation for version |version| of Bugzilla, a bug-tracking
-system from Mozilla. Bugzilla is an enterprise-class piece of software
-that tracks millions of bugs and issues for thousands of organizations around
-the world.
-
-The most current version of this document can always be found on the
-`Bugzilla website <http://www.bugzilla.org/docs/>`_.

diff --git a/docs/en/rst/about/license.rst b/docs/en/rst/about/license.rst
deleted file mode 100644 (file)
index fae238e..0000000
--- a/docs/en/rst/about/license.rst
+++ /dev/null
@@ -1,22 +0,0 @@
-.. _license:
-
-License
-#######
-
-Bugzilla is `free <http://www.gnu.org/philosophy/free-sw.html>`_ and
-`open source <http://opensource.org/osd>`_ software, which means (among other
-things) that you can download it, install it and run it for any purpose
-whatsoever without the need for license or payment. Isn't that refreshing?
-
-Bugzilla's code is made available under the
-`Mozilla Public License 2.0 <http://www.mozilla.org/MPL/2.0/>`_ (MPL),
-specifically the variant which is Incompatible with Secondary Licenses.
-However, again, if you only want to install and run Bugzilla, you don't need
-to worry about that; it's only relevant if you redistribute the code or any
-changes you make. 
-
-Bugzilla's documentation is made available under the
-`Creative Commons CC-BY-SA International License 4.0
-<https://creativecommons.org/licenses/by-sa/4.0/>`_,
-or any later version.
-

diff --git a/docs/en/rst/administering/categorization.rst b/docs/en/rst/administering/categorization.rst
index f9ab5b2bdcd186cff906ebff89a8ab29cf5cfbc6..afd191c06f982c90aaf817a4d9105ad0787db899 100644 (file)
--- a/docs/en/rst/administering/categorization.rst
+++ b/docs/en/rst/administering/categorization.rst
@@ -90,7 +90,7 @@ To create a new product:
 
 #. Enter the details as outlined above.
 
-XXX This section is pointless; if it's not obvious, we should make it more obvious :-)
+.. todo:: This section is pointless; if it's not obvious, we should make it more obvious :-)
 
 .. _edit-products:
 

diff --git a/docs/en/rst/administering/flags.rst b/docs/en/rst/administering/flags.rst
index 49a8bfba7605db3c61611ab90157e160c630faef..4ad60864b15fb4e61bc5e1b29adf01e19d7ffe7e 100644 (file)
--- a/docs/en/rst/administering/flags.rst
+++ b/docs/en/rst/administering/flags.rst
@@ -365,7 +365,7 @@ the flag description.
 
 .. COMMENT: flags-admin
 
-.. COMMENT: XXX We should add a "Uses of Flags" section, here, with examples.
+.. todo:: We should add a "Uses of Flags" section, here, with examples.
 
 .. COMMENT: flags
 

diff --git a/docs/en/rst/administering/keywords.rst b/docs/en/rst/administering/keywords.rst
index 4127f262a88904c11847aa9096a4eaf8a87be1e5..57e4e8164fc580af51f2fa7e60466fa1fa2974a0 100644 (file)
--- a/docs/en/rst/administering/keywords.rst
+++ b/docs/en/rst/administering/keywords.rst
@@ -11,9 +11,11 @@ bugs much easier.
 
 Keywords are global, rather than per-product. If the administrator changes
 a keyword currently applied to any bugs, the keyword cache must be rebuilt
-using the :ref:`sanity-check` script. XXXDoes this mean changing the name of the keyword? Is it still true?
-Currently keywords cannot
-be marked obsolete to prevent future usage.
+using the :ref:`sanity-check` script.
+
+.. todo:: Does this mean changing the name of the keyword? Is it still true?
+
+Currently keywords cannot be marked obsolete to prevent future usage.
 
 Keywords can be created, edited or deleted by clicking the "Keywords"
 link in the admin page. There are two fields for each keyword - the keyword

diff --git a/docs/en/rst/administering/parameters.rst b/docs/en/rst/administering/parameters.rst
index d825b8fe923487a0549f91e270e816cf8219a544..b191760a18900004a9434ac9966ffc7e4ac96780 100644 (file)
--- a/docs/en/rst/administering/parameters.rst
+++ b/docs/en/rst/administering/parameters.rst
@@ -87,7 +87,7 @@ shutdownhtml
        log in, and your name/password will be accepted here (but nowhere
        else).
 
-       XXX Is this still true?
+       .. todo:: Is this still true?
 
 announcehtml
     Any text in this field will be displayed at the top of every HTML
@@ -227,7 +227,7 @@ attachment_base
 
     For added security, you can insert ``%bugid%`` into the URL, which will be replaced with the ID of the current bug that the attachment is on, when you access an attachment. This will limit attachments to accessing only other attachments on the same bug. Remember, though, that all those possible domain names (such as 1234.your.domain.com) must point to this same Bugzilla instance.
 
-    XXX So this requires wildcard DNS? We should explain a bit about what is needed here.
+    .. todo:: So this requires wildcard DNS? We should explain a bit about what is needed here.
 
 allow_attachment_deletion
     If this option is on, administrators will be able to delete the contents
@@ -237,12 +237,12 @@ allow_attachment_deletion
 maxattachmentsize
     The maximum size (in kilobytes) of attachments to be stored in the database. If a file larger than this size is attached to a bug, Bugzilla will look at the maxlocalattachment parameter to determine if the file can be stored locally on the web server. If the file size exceeds both limits, then the attachment is rejected. Settings both parameters to 0 will prevent attaching files to bugs.
 
-    XXX Talk about MySQL max_allowed_packet
+    .. todo:: Talk about MySQL max_allowed_packet
     
 maxlocalattachment
     The maximum size (in megabytes) of attachments to be stored locally on the web server. If set to a value lower than the :param:`maxattachmentsize` parameter, attachments will never be kept on the local filesystem.
 
-    XXX When should people use this feature?
+    .. todo:: When should people use this feature?
 
 .. _param-bug-change-policies:
 
@@ -392,7 +392,9 @@ For more information on Groups and Group Security, see
 makeproductgroups
     Determines whether or not to automatically create groups
     when new products are created. If this is on, the groups will be
-    used for querying bugs. XXX This is spectacularly unclear.
+    used for querying bugs.
+
+    .. todo:: This is spectacularly unclear.
 
 chartgroup
     The name of the group of users who can use the 'New Charts' feature. Administrators should ensure that the public categories and series definitions do not divulge confidential information before enabling this for an untrusted population. If left blank, no users will be able to use New Charts.
@@ -627,7 +629,9 @@ whinedays
     in the CONFIRMED state before notifying people they have
     untouched new bugs. If you do not plan to use this feature, simply
     do not set up the whining cron job described in the installation
-    instructions, or set this value to "0" (never whine). XXXlink
+    instructions, or set this value to "0" (never whine).
+
+    .. todo:: link
 
 globalwatchers
     This allows you to define specific users who will
@@ -647,7 +651,7 @@ features of the Patch Viewer. Bonsai is a tool that enables queries
 to a CVS tree. LXR is a tool that can cross reference and index source
 code.
 
-XXX Does anyone use this stuff any more?
+.. todo:: Does anyone use this stuff any more?
 
 cvsroot
     The CVS root that most users of your system will be using for 'cvs diff'. Used in Patch Viewer ('Diff' option on patches) to figure out where patches are rooted even if users did the 'cvs diff' from different places in the directory structure. (NOTE: if your CVS repository is remote and requires a password, you must either ensure the Bugzilla user has done a 'cvs login' or specify the password as part of the CVS root.) Leave this blank if you have no CVS repository.

diff --git a/docs/en/rst/conf.py b/docs/en/rst/conf.py
index a298f2ced923e6ffd590f617c3898f0773b10be5..6a0349b95eb91584a6c58a3765b5c72ab76e6076 100644 (file)
--- a/docs/en/rst/conf.py
+++ b/docs/en/rst/conf.py
@@ -370,3 +370,5 @@ pdf_use_numbered_links = True
 
 # Background images fitting mode
 pdf_fit_background_mode = 'scale'
+
+todo_include_todos = True

diff --git a/docs/en/rst/customizing/templates.rst b/docs/en/rst/customizing/templates.rst
index 77337b912b9b970404383eac89acc62f30baca48..433d339da92c7596b04b34f3a0cedd3eabf9b746 100644 (file)
--- a/docs/en/rst/customizing/templates.rst
+++ b/docs/en/rst/customizing/templates.rst
@@ -106,7 +106,9 @@ Template Toolkit to do this (or the 'uri' filter to encode special
 characters in URLs).  If you forget, you may open up your installation
 to cross-site scripting attacks.
 
-XXXMOVE Editing templates is a good way of doing a 'poor man's custom
+.. todo:: Move the below.
+
+Editing templates is a good way of doing a 'poor man's custom
 fields'.
 For example, if you don't use the :guilabel:`Status Whiteboard`, but want to
 have a free-form text entry box for :guilabel:`Build Identifier`,
@@ -198,7 +200,7 @@ customizing for your installation.
   your Bugzilla installation.
 
 :file:`global/variables.none.tmpl`:
-  XXX Need to describe the use of this file
+  .. todo:: Need to describe the use of this file
 
 :file:`list/table.html.tmpl`:
   This template controls the appearance of the bug lists created

diff --git a/docs/en/rst/customizing/writing-extensions.rst b/docs/en/rst/customizing/writing-extensions.rst
index c2796bb3faed9efe81e920df03370944a542e6d4..12bc1ca3b19f4902b2c953a4c0d2838154be1836 100644 (file)
--- a/docs/en/rst/customizing/writing-extensions.rst
+++ b/docs/en/rst/customizing/writing-extensions.rst
@@ -8,8 +8,8 @@ documentation <../html/api/Bugzilla/Extension.html>`_ for the core
 documentation on how to write an Extension. We also have some additional
 tips and tricks here.
 
-XXX These came from the wiki. Should they actually be integrated into the
-POD, or should some of the POD come here, or something else?
+.. todo:: These came from the wiki. Should they actually be integrated into the
+          POD, or should some of the POD come here, or something else?
 
 Checking Syntax
 ===============

diff --git a/docs/en/rst/installing/apache.rst b/docs/en/rst/installing/apache.rst
index d0351c429adeacff3d69f17e2a20c941677ddd1a..7834f84c25975e0f0ae2293d57a9cc9b5f105621 100644 (file)
--- a/docs/en/rst/installing/apache.rst
+++ b/docs/en/rst/installing/apache.rst
@@ -43,7 +43,7 @@ Apache with mod_cgi
 To configure your Apache web server to work with Bugzilla while using
 mod_cgi, do the following:
 
-XXX Shouldn't we be using sites-available/sites-enabled here?
+.. todo:: Shouldn't we be using sites-available/sites-enabled here?
 
 #. Edit the Apache configuration file (see above).
 
@@ -102,7 +102,7 @@ and mod_perl.
    .. warning:: You should also ensure that you have disabled ``KeepAlive``
       support in your Apache install when utilizing Bugzilla under mod_perl
 
-      XXX How? Why?
+      .. todo:: How? Why?
 
 On restarting Apache, Bugzilla should now be running within the
 mod_perl environment.

diff --git a/docs/en/rst/installing/email.rst b/docs/en/rst/installing/email.rst
index d25085785984fa0ca02b9bfbccbdf0f678a4f921..fd7458624b09f956be841e8d0042eef94af540d2 100644 (file)
--- a/docs/en/rst/installing/email.rst
+++ b/docs/en/rst/installing/email.rst
@@ -13,8 +13,8 @@ or run one yourself on the Bugzilla machine.
 Bugzilla's approach to email is configured in the :guilabel:`Email` section
 of the Parameters.
 
-XXX Bug: description of mail_delivery_method talks about Qmail, and is in
-other ways wrong.
+.. todo:: Bug: description of mail_delivery_method talks about Qmail, and is in
+          other ways wrong.
 
 .. _install-MTA:
 
@@ -58,7 +58,7 @@ Run Your Own Mail Server
 This section corresponds to choosing a :param:`mail_delivery_method` of
 :paramval:`Sendmail`.
 
-XXX Do we still need this? Why would anyone want to do this in 2014?
+.. todo:: Do we still need this? Why would anyone want to do this in 2014?
 
 Unless you know what you are doing, and can deal with the possible problems
 of spam, bounces and blacklists, it is probably unwise to set up your own

diff --git a/docs/en/rst/installing/iis.rst b/docs/en/rst/installing/iis.rst
index 26054260b2e34f13aea60d903da45d77d7631360..a2d616227df99ac32573f1526d511eb5cad5bcba 100644 (file)
--- a/docs/en/rst/installing/iis.rst
+++ b/docs/en/rst/installing/iis.rst
@@ -65,4 +65,4 @@ such as :file:`localconfig` and your
 :file:`data` directory are
 secured.
 
-XXX See also https://wiki.mozilla.org/Installing_under_IIS_7.5
+.. todo:: See also https://wiki.mozilla.org/Installing_under_IIS_7.5

diff --git a/docs/en/rst/installing/linux.rst b/docs/en/rst/installing/linux.rst
index 47907e405c79da4183b3af082b6ed82ac4e03d97..c8b33fd63a149e61233e4da8135fbd12bb9501aa 100644 (file)
--- a/docs/en/rst/installing/linux.rst
+++ b/docs/en/rst/installing/linux.rst
@@ -12,12 +12,12 @@ of additional configuration required.
 If you are installing your machine from scratch, :ref:`quick-start` may be
 the best instructions for you.
 
-XXX What's our current position on Debian/Ubuntu packages of Bugzilla? Are
-there any, and are they any good?
+.. todo:: What's our current position on Debian/Ubuntu packages of Bugzilla? Are
+          there any, and are they any good?
 
-XXX Which versions of RHEL have packages new enough for us to support them?
+.. todo:: Which versions of RHEL have packages new enough for us to support them?
 
-XXX What's the right order for all these steps?
+.. todo:: What's the right order for all the following steps?
 
 Install Packages
 ================
@@ -116,7 +116,7 @@ Bugzilla-only copy of the newer version.
 At this point, you need to :file:`su` to root. You should remain as root
 until the end of the install.
 
-XXX Is this true, if they are installing modules locally?
+.. todo:: Is this true, if they are installing modules locally?
 
 To check whether you have all the required modules and what is still missing,
 run:
@@ -141,7 +141,7 @@ Or, you can pass an individual module name:
    distribution you are using, but are often called
    :file:`<packagename>-devel`.
 
-   XXX Give examples for Debian/Ubuntu and RedHat?
+   .. todo:: Give examples for Debian/Ubuntu and RedHat?
 
 .. _config-webserver:
 
@@ -159,7 +159,7 @@ We have specific instructions for the following:
 You can run :command:`testserver.pl http://bugzilla-url/` from the command
 line to check if your web server is correctly configured.
 
-XXX Does this work before doing any localconfig stuff?
+.. todo:: Does this work before doing any localconfig stuff?
 
 .. _config-database:
 
@@ -246,7 +246,7 @@ you should see the Bugzilla front page.
 
 Next, do the :ref:`post-install-config`.
 
-XXXX How to we integrate the below (copied from the wiki)?
+.. todo:: How to we integrate the below (copied from the wiki)?
 
 Gentoo
 ======

diff --git a/docs/en/rst/installing/mysql.rst b/docs/en/rst/installing/mysql.rst
index b6e9d8eb16d51eb52f44de5e50f5ba0f9c505416..229676faf753dc9b252b6264387f4804efae9ce6 100644 (file)
--- a/docs/en/rst/installing/mysql.rst
+++ b/docs/en/rst/installing/mysql.rst
@@ -60,7 +60,7 @@ on Linux.
 By default, MySQL will only allow you to insert things
 into the database that are smaller than 1MB.
 
-XXX Is this still true? It's 16MB on Ubuntu 14.04...
+.. todo:: Is this still true? It's 16MB on Ubuntu 14.04...
 
 Bugzilla attachments
 may be larger than this. Also, Bugzilla combines all comments

diff --git a/docs/en/rst/installing/post-install-config.rst b/docs/en/rst/installing/post-install-config.rst
index d5a8a0094dea4b38175027eceba4df8bb8874b13..b94f12956a0d3b6c395ef405503a363cd2c84d19 100644 (file)
--- a/docs/en/rst/installing/post-install-config.rst
+++ b/docs/en/rst/installing/post-install-config.rst
@@ -43,7 +43,7 @@ section, and change or clear the :param:`createemailregexp` parameter.
 Optional
 ========
 
-XXXHACKME
+.. todo:: HACKME
 
 Bugzilla has a number of optional features. This section describes how
 to configure or enable them.

diff --git a/docs/en/rst/installing/quick-start.rst b/docs/en/rst/installing/quick-start.rst
index e433d52801f85f7002d0b1342aeac534a74c56cd..f58e53a97b44b63c216175c7a928ccdf2e72866e 100644 (file)
--- a/docs/en/rst/installing/quick-start.rst
+++ b/docs/en/rst/installing/quick-start.rst
@@ -70,8 +70,8 @@ home page. It requires a little familiarity with Linux and the command line.
    You will get a notification about having a detached HEAD. Don't worry,
    your head is still firmly on your shoulders.
 
-   XXX is this the right way to get the current bugzilla-stable code? Or
-   should we pull directly from a branch?
+   .. todo:: is this the right way to get the current bugzilla-stable code? Or
+             should we pull directly from a branch?
    
 5. Configure MySQL
 
@@ -88,11 +88,11 @@ home page. It requires a little familiarity with Linux and the command line.
 
    Save and exit.
 
-   XXX default value of maxattachmentsize is 1MB. Default value of max_allowed_packet
-   is 16MB. Should we just omit this step entirely, for simplicity? Do we need
-   ft_min_word_len changed?
+   .. todo:: default value of maxattachmentsize is 1MB. Default value of max_allowed_packet
+             is 16MB. Should we just omit this step entirely, for simplicity? Do we need
+             ft_min_word_len changed?
 
-   XXX docs for maxattachmentsize should mention max_allowed_packet. File bug.
+   .. todo:: docs for maxattachmentsize should mention max_allowed_packet. File bug.
 
    Restart MySQL:
    
@@ -144,8 +144,8 @@ home page. It requires a little familiarity with Linux and the command line.
    * Line 67: set ``$db_pass`` to the MySQL root user password you created
      when installing Ubuntu
 
-   XXX Given this is a quick setup on a dedicated box, is it OK to use the
-   MySQL root user?
+   .. todo:: Given this is a quick setup on a dedicated box, is it OK to use the
+             MySQL root user?
     
 10. Check Setup (again)
 
@@ -164,7 +164,7 @@ home page. It requires a little familiarity with Linux and the command line.
     All the tests should pass. (Note: currently, the first one will give a
     warning instead. You can ignore that. Bug 1040728.)
 
-    XXX Also, Chart::Base gives deprecation warnings :-|
+    .. todo:: Also, Chart::Base gives deprecation warnings :-|
    
 12. Access Via Web Browser
 
@@ -211,6 +211,6 @@ home page. It requires a little familiarity with Linux and the command line.
 
     Click :guilabel:`Save Changes` at the bottom of the page.
 
-    XXX There should be a "send test email" button on that page
+    .. todo:: There should be a "send test email" button on that page
 
     And you're all ready to go. :-)

diff --git a/docs/en/rst/installing/sqlite.rst b/docs/en/rst/installing/sqlite.rst
index 09e5db3c3df44d936266a64016c14a6779cbc3b1..390159ada8b5b159febb6da0347894050d5a571c 100644 (file)
--- a/docs/en/rst/installing/sqlite.rst
+++ b/docs/en/rst/installing/sqlite.rst
@@ -11,7 +11,7 @@ Once you have SQLite installed, no additional configuration is required to
 run Bugzilla. Simply set ``$db_driver`` to ``Sqlite`` (case-sensitive) in
 :file:`localconfig`, when you get to that point in the installation.
 
-XXX This doesn't work - gives a timezone-related error on my box.
+.. todo:: This doesn't work - gives a timezone-related error on my box.
 
 The database will be stored in :file:`data/db/$db_name`, where ``$db_name``
 is the database name defined in :file:`localconfig`.

diff --git a/docs/en/rst/integrating/tips.rst b/docs/en/rst/integrating/tips.rst
index d7b8c04f4c0afb689875e654cfcc51e0f959b2de..4c0961aa6a4b48539ca4ff34387ee67e2b59528d 100644 (file)
--- a/docs/en/rst/integrating/tips.rst
+++ b/docs/en/rst/integrating/tips.rst
@@ -3,4 +3,4 @@
 Integration Tips
 ################
 
-XXX Do we have any of these?
+.. todo:: Do we have any of these?

diff --git a/docs/en/rst/upgrading/upgrading-from-1.rst.inc b/docs/en/rst/upgrading/upgrading-from-1.rst.inc
index 37cb7f8b03d53570c5098884756690d1f4b674ed..0fc333e94fad48ab92d10e8e90ee879509b40bdb 100644 (file)
--- a/docs/en/rst/upgrading/upgrading-from-1.rst.inc
+++ b/docs/en/rst/upgrading/upgrading-from-1.rst.inc
@@ -1,5 +1,8 @@
+.. This file is included in multiple places, so can't have labels as they
+   appear as duplicates.
+   
 The procedure to switch to Git is as follows. The idea is to switch version
-control systems without changing the exact version of Bugzilla you are using,
+control systems without changing the version of Bugzilla you are using,
 to minimise the risk of conflict or problems. Any major upgrade can then
 happen as a separate step. 
 
@@ -7,7 +10,11 @@ Update Bugzilla To The Latest Point Release
 ===========================================
 
 It is recommended that you switch to Git while using the latest
-point release for your major version. 
+point release for your major version, so if you aren't running that, you may
+want to do a minor upgrade first.
+
+.. todo:: Is this actually necessary? It adds several extra steps. What are we
+          trying to avoid here?
 
 First, you need to find what version of Bugzilla you are using. It should be
 in the top right corner of the front page but, if not, open the file
@@ -43,8 +50,6 @@ Then run checksetup to upgrade your database:
 You should then test your Bugzilla carefully, or just use it for a day or two,
 to make sure it's all still working fine.
 
-.. _get-from-git:
-
 Download Code from Git
 ======================
 

diff --git a/docs/en/rst/upgrading/upgrading-from-2.rst.inc b/docs/en/rst/upgrading/upgrading-from-2.rst.inc
index ebe8c84f9c7a1b4c036888ae6453f944c511d881..e7213da0b9fbc9daf1ec4291d0f97ea78b0c6106 100644 (file)
--- a/docs/en/rst/upgrading/upgrading-from-2.rst.inc
+++ b/docs/en/rst/upgrading/upgrading-from-2.rst.inc
@@ -1,3 +1,6 @@
+.. This file is included in multiple places, so can't have labels as they
+   appear as duplicates.
+   
 Save Any Local Customizations
 =============================
 

diff --git a/docs/en/rst/upgrading/upgrading-from-bazaar.rst b/docs/en/rst/upgrading/upgrading-from-bazaar.rst
index 3957b91a332387d2424a68570f4387d4dbf5f545..c368db53c308bd8e047ae6ba54bed87c11623b7a 100644 (file)
--- a/docs/en/rst/upgrading/upgrading-from-bazaar.rst
+++ b/docs/en/rst/upgrading/upgrading-from-bazaar.rst
@@ -7,5 +7,5 @@ Upgrading from Bazaar
 .. |diffcommand|   replace:: :command:`bzr diff > patch.diff`
 .. |extstatusinfo| replace:: The command :command:`bzr status extensions/` should help you work out what you added, if anything.
 
-.. include:: upgrading-from-1.rst
-.. include:: upgrading-from-2.rst
+.. include:: upgrading-from-1.rst.inc
+.. include:: upgrading-from-2.rst.inc

diff --git a/docs/en/rst/upgrading/upgrading-from-cvs.rst b/docs/en/rst/upgrading/upgrading-from-cvs.rst
index 8e210e5f0065537a449fe95bf91ff8b85eed4860..03456966a67266244349b51e8ab09a3e2cf9fbc2 100644 (file)
--- a/docs/en/rst/upgrading/upgrading-from-cvs.rst
+++ b/docs/en/rst/upgrading/upgrading-from-cvs.rst
@@ -7,7 +7,7 @@ Upgrading from CVS
 .. |diffcommand|   replace:: :command:`cvs diff -puN > patch.diff`
 .. |extstatusinfo| replace:: The command :command:`cvs status extensions/` should help you work out what you added, if anything.
 
-.. include:: upgrading-from-1.rst
-.. include:: upgrading-from-2.rst
+.. include:: upgrading-from-1.rst.inc
+.. include:: upgrading-from-2.rst.inc
 
 

diff --git a/docs/en/rst/upgrading/upgrading-with-a-tarball.rst b/docs/en/rst/upgrading/upgrading-with-a-tarball.rst
index 1a9c5d97bf5940157e86d7f4b6f2171f6419fbc4..6910c648069c8a2d7b8b296f220ae4d3c7e36832 100644 (file)
--- a/docs/en/rst/upgrading/upgrading-with-a-tarball.rst
+++ b/docs/en/rst/upgrading/upgrading-with-a-tarball.rst
@@ -21,4 +21,4 @@ Bugzilla installation (which we will assume is in a directory called
                              work out by hand which extensions came with
                              Bugzilla and which you added.
 
-.. include:: upgrading-from-2.rst
+.. include:: upgrading-from-2.rst.inc

diff --git a/docs/en/rst/upgrading/upgrading-with-git.rst b/docs/en/rst/upgrading/upgrading-with-git.rst
index 8221beaa3f3d82e7b6901034a480ba210a0ae772..a7067eba2d1bc303f4cfdb546cfa660416b78b9a 100644 (file)
--- a/docs/en/rst/upgrading/upgrading-with-git.rst
+++ b/docs/en/rst/upgrading/upgrading-with-git.rst
@@ -23,8 +23,8 @@ steps to take:
    Upgraders" sections, if present. They may make you aware of additional
    considerations.
 
-   XXX We need to make these more accessible - they are currently rather hard
-   to find. We could collate them on a single page with no intervening cruft.
+.. todo:: We need to make these more accessible - they are currently rather hard
+          to find. We could collate them on a single page with no intervening cruft.
 
 #. Run the :ref:`sanity-check` on your installation. Attempt to fix all
    warnings that the page produces before you start, or it's
@@ -84,7 +84,7 @@ in which Bugzilla is installed.
 
 :command:`git pull`
 
-XXX What is the best way to pull latest stable?
+.. todo:: What is the best way to pull latest stable?
 
 .. _upgrade-database:
 

diff --git a/docs/en/rst/using/finding.rst b/docs/en/rst/using/finding.rst
index 578a4f04f644f60f88ee2c12d150f3b773e58822..e8e13148381534abe180a0526843093fc0281edb 100644 (file)
--- a/docs/en/rst/using/finding.rst
+++ b/docs/en/rst/using/finding.rst
@@ -97,7 +97,7 @@ There are three fields in each row of a boolean search.
 Multiple Charts
 ---------------
 
-XXX This needs rewriting for the new UI.
+.. todo:: This needs rewriting for the new UI.
 
 The terms within a single row of a boolean chart are all
 constraints on a single piece of data. If you are looking for
@@ -243,7 +243,7 @@ Remember Search As:
 Adding and Removing Tags on Bugs
 ================================
 
-XXX Looks like you can no longer do this from search results; is that right?
+.. todo:: Looks like you can no longer do this from search results; is that right?
 
 You can add and remove tags from individual bugs, which let you find and
 manage bugs more easily. Tags are per-user and so are only visible and editable