[v2,12/12] doc: use reST for manpages

Commit Message

Luc Van Oostenryck May 19, 2018, 12:52 p.m. UTC

MarkDown is really nice and easy to get something quickly but
for manpages, the rendering is not really nice and lack index entries.

reST has a special syntax for option lists but:
1) not all option syntax are recognized (for example when we use [xyz] to
  to show that xyz is optionnal).
2) when converted to HTML, a table is used for the list but:
  * options that are too long break the presentation
  * unrecognized options break the table
3) the options are also not put in the index

Solve this by using reST with '.. option::' directives.

Signed-off-by: Luc Van Oostenryck <[e-mail]>
---
 Documentation/Makefile        |  2 +-
 Documentation/dev-options.md  | 42 --------------------------------
 Documentation/dev-options.rst | 45 +++++++++++++++++++++++++++++++++++
 3 files changed, 46 insertions(+), 43 deletions(-)
 delete mode 100644 Documentation/dev-options.md
 create mode 100644 Documentation/dev-options.rst

Patch

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 64dc0f66b..2e8cbdfd7 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -20,7 +20,7 @@  help:
 $(targets): conf.py Makefile
 	@$(SPHINXBUILD) -M  $@  "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
 
-%.1: %.md man
+%.1: %.rst man
 	@mv build/man/$@ $@
 
 .PHONY: Makefile	# avoid circular deps with the catch-all rule
diff --git a/Documentation/dev-options.md b/Documentation/dev-options.md
deleted file mode 100644
index 8b1b30bcf..000000000
--- a/Documentation/dev-options.md
+++ /dev/null
@@ -1,42 +0,0 @@ 
-# sparse - extra options for developers
-
-## SYNOPSIS
-`tools` [`options`]... `file.c`
-
-## DESCRIPTION
-
-This file is a complement of sparse's man page meant to
-document options only useful for development on sparse itself.
-
-## DEVELOPER OPTIONS
-
--f<name-of-the-pass>[-disable|-enable|=last]
-
-  If `=last` is used, all passes after the specified one are disabled.
-  By default all passes are enabled.
-
-  The passes currently understood are:
-
-  * `mem2reg`
-  * `optim`
-
-### DEBUGGING
-
--fdump-ir[=pass[,pass...]]
-
-  Dump the IR at each of the given passes.
-
-  The passes currently understood are:
-
-  * `linearize`
-  * `mem2reg`
-  * `final`
-
-  The default pass is `linearize`.
-
--v<debug-flag>
-
-  Add or display some debug info. The flag can be one of:
-
-  * `dead`: annotate dead pseudos.
-  * `entry`: dump the IR after all optimization passes.
diff --git a/Documentation/dev-options.rst b/Documentation/dev-options.rst
new file mode 100644
index 000000000..1f213afee
--- /dev/null
+++ b/Documentation/dev-options.rst
@@ -0,0 +1,45 @@ 
+sparse - extra options for developers
+=====================================
+
+SYNOPSIS
+--------
+``tools`` [`options`]... `file.c``
+
+DESCRIPTION
+-----------
+
+This file is a complement of sparse's man page meant to
+document options only useful for development on sparse itself.
+
+OPTIONS
+-------
+
+.. option:: -fdump-ir=pass,[pass]
+
+  Dump the IR at each of the given passes.
+
+  The passes currently understood are:
+
+    * ``linearize``
+    * ``mem2reg``
+    * ``final``
+
+  The default pass is ``linearize``.
+
+.. option:: -f<name-of-the-pass>[-disable|-enable|=last]
+
+  If ``=last`` is used, all passes after the specified one are disabled.
+  By default all passes are enabled.
+
+  The passes currently understood are:
+
+    * ``mem2reg``
+    * ``optim``
+
+.. option:: -vdead
+
+  Add ``OP_DEATHNOTE`` annotations to dead pseudos.
+
+.. option:: -ventry
+
+  Dump the IR after all optimization passes.