Documentation update/additions.

Remove implemented TODO item.
Add entry for rst2man.py tool.

git-svn-id: https://svn.code.sf.net/p/docutils/code/trunk@8874 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

2 files changed, 79 insertions, 34 deletions

diff --git a/docutils/docs/dev/todo.txt b/docutils/docs/dev/todo.txt
index 133c58b7e..b93daed7b 100644
--- a/docutils/docs/dev/todo.txt
+++ b/docutils/docs/dev/todo.txt
@@ -68,6 +68,39 @@ Many of these are now handled by Sphinx_
 
 .. _Sphinx: http://sphinx.pocoo.org/
 
+Repository
+==========
+
+Move to a Git repository.
+
+* This is a long standing `feature request`__
+  (with pointers to Sphinx issues and discussion).
+
+  __ https://sourceforge.net/p/docutils/feature-requests/58/
+
+* From a `post by David Goodger`__
+
+    An absolute requirement, for me, is that such a change be complete.
+    We can't lose any data or have to refer to the old system as an
+    "archive". So all the SVN history, all branches, and the full sandbox
+    need to be converted at the same time.
+
+  __ https://sourceforge.net/p/docutils/mailman/message/31878077/
+
+Convert with reposurgeon_?
+
+  If you are doing a full import rather than gatewaying, reposurgeon is
+  probably what you want. It has been tested against a lot of large, old,
+  nasty repositories and is thus known to be robust in the presence of
+  repository malformations (a property regularly checked by a test suite
+  that is a rogue's gallery of Subversion botches).
+
+  -- `Git Wiki`__
+
+.. _reposurgeon: http://www.catb.org/esr/reposurgeon/
+__ https://git.wiki.kernel.org/index.php/
+   Interfaces,_frontends,_and_tools#Subversion
+
 General
 =======
 
@@ -2269,22 +2302,6 @@ Unimplemented Transforms
 HTML Writer
 ===========
 
-* Make it easier to find out fragment names (#foo-bar) of ``_`inline
-  targets```.  Currently you have to either look at the source or
-  guess the fragment.
-
-  For example, we could add support for self-referencing targets
-  (i.e. inline targets would [unobtrusively] link to themselves, so
-  that you can just click them and then copy the address).  Or we
-  could add support for titles that display the fragment name (as in
-  <http://subversion.tigris.org/mailing-list-guidelines.html>; just
-  hover the paragraphs).
-
-  Either way it should be optional and deactivated by default.
-
-  This would be useful for documents like Docutils' bug list or to-do
-  list.
-
 * Make the _`list compacting` logic more generic: For example, allow
   for literal blocks or line blocks inside of compact list items.
 
diff --git a/docutils/docs/user/tools.txt b/docutils/docs/user/tools.txt
index 649fa314c..c71b2db9d 100644
--- a/docutils/docs/user/tools.txt
+++ b/docutils/docs/user/tools.txt
@@ -46,6 +46,9 @@ Getting Help
 
 First, try the "``--help``" option each front-end tool has.
 
+Command line options and their corresponding configuration file entries
+are detailed in `Docutils Configuration`_.
+
 Users who have questions or need assistance with Docutils or
 reStructuredText should post a message to the Docutils-users_ mailing
 list.
@@ -65,12 +68,21 @@ docutils-cli.py
 
 :Readers: Standalone, PEP
 :Parser: reStructuredText, Markdown (reCommonMark)
-:Writers: html_, html4css1_, html5_, pep_html_, s5_html_, 
-          latex__, xelatex_, xml_, odt_, Pseudo-XML_
+:Writers: html_, html4css1_, html5_, latex__, manpage_,
+          odt_, pep_html_, pseudo-xml_, s5_html_, xelatex_, xml_,
+
+The ``docutils-cli.py`` front allows combining reader, parser, and
+writer components.
+
+For example, to process a Markdown_ file "``test.md``" into
+Pseudo-XML_ ::
+
+    docutils_.py --parser=markdown --writer=pseudoxml test.md test.txt
 
 __ `Generating LaTeX with Docutils`_
 .. _Generating LaTeX with Docutils: latex.html
-
+.. _manpage: manpage.html
+.. _Markdown: https://www.markdownguide.org/
 
 HTML-Generating Tools
 =====================
@@ -111,6 +123,8 @@ ensures that the correct settings are in place (a ``docutils.conf``
 automatically).  Command-line options may be used to override config
 file settings or replace them altogether.
 
+.. _configuration file: configuration files
+
 
 rst2html.py
 -----------
@@ -371,22 +385,20 @@ For details see `Generating LaTeX with Docutils`_.
 .. _LuaTeX: https://en.wikipedia.org/wiki/LuaTeX
 
 
-XML-Generating Tools
-====================
+Man-Page-Generating Tools
+=========================
 
-rst2xml.py
+rst2man.py
 ----------
 
 :Reader: Standalone
 :Parser: reStructuredText
-:Writer: _`XML` (Docutils native)
+:Writer: manpage_
 
-The ``rst2xml.py`` front end produces Docutils-native XML output.
-This can be transformed with standard XML tools such as XSLT
-processors into arbitrary final forms. An example is the xml2rst_ processor
-in the Docutils sandbox.
+The ``rst2man.py`` front end reads standalone reStructuredText source
+files and produces troff_ sources for Unix man pages.
 
-.. _xml2rst: ../../../sandbox/xml2rst
+.. _troff: https://troff.org/
 
 
 ODF/OpenOffice-Generating Tools
@@ -411,6 +423,7 @@ etc from `Odt Writer for Docutils`_.
 .. _Odt Writer for Docutils:
 .. _odt: odt.html
 
+
 reStructuredText-Generating Tools
 =================================
 
@@ -421,6 +434,24 @@ To generate reStructuredText documents with Docutils, you can use
 the XML (Docutils native) writer and the xml2rst_ processor.
 
 
+XML-Generating Tools
+====================
+
+rst2xml.py
+----------
+
+:Reader: Standalone
+:Parser: reStructuredText
+:Writer: _`XML` (Docutils native)
+
+The ``rst2xml.py`` front end produces Docutils-native XML output.
+This can be transformed with standard XML tools such as XSLT
+processors into arbitrary final forms. An example is the xml2rst_ processor
+in the Docutils sandbox.
+
+.. _xml2rst: ../../../sandbox/xml2rst
+
+
 Testing/Debugging Tools
 =======================
 
@@ -458,7 +489,6 @@ document.  Various forms output are possible:
 - Raw native XML (with or without a stylesheet reference)
 
 
-
 ---------------
  Customization
 ---------------
@@ -470,10 +500,8 @@ Command-line options are intended for one-off customization.
 They take priority over configuration file settings.
 
 Use the "--help" option on each of the front ends to list the
-command-line options it supports.  
-
+command-line options it supports.
 
-.. _configuration file:
 
 Configuration Files
 ===================
@@ -482,9 +510,9 @@ Configuration files are used for persistent customization; they can be
 set once and take effect every time you use a front-end tool.
 
 Command-line options and their corresponding configuration file entry
-names are listed in the `Docutils Configuration Files`_ document.
+names are listed in the `Docutils Configuration`_ document.
 
-.. _Docutils Configuration Files: config.html
+.. _Docutils Configuration: config.html
 
 
 ..