By default, Sphinx tries to pre-process text through SmartyPants,
which attempts to convert ASCII quotes and dashes to Unicode
characters. Unfortunately, this mangles technical text such as command
lines. For instance, this excerpt from notmuch-tag.rst:
**notmuch** **tag** **--batch** [--input=<*filename*>]
got turned into:
notmuch tag –batch [–input=<filename>]
That's an en-dash and an em-dash respectively.
Not only are these characters visually confusing and could easily be
mistaken for a single dash, copying and pasting such command lines
into a terminal is doomed to result in incomprehensible error
messages.
* doc/conf.py: Disable SmartyPants.
No need to repeat mostly the same information twice in conf.py. We
probably want to have a corresponding texinfo document for all the man
pages. Python list comprehension to the rescue. (The reverse is not
true; we have a texinfo document for notmuch-emacs we don't want as a
man page.)
There should be no user visible changes.
Although this manual is far from complete, it may be helpful for
someone. In particular building it as part of the standard build
process makes it easier to find problems when editing the
notmuch-emacs-manual.
Avoid:
$ make HAVE_SPHINX=1 sphinx-html
python ./doc/mkdocdeps.py ./doc doc/_build doc/docdeps.mk
sphinx-build -b html -d doc/_build/doctrees -q ./doc doc/_build/html
Making output directory...
WARNING: html_static_path entry '/home/wking/src/notmuch/notmuch/doc/_static' does not exist
because we have no static source in doc/_static.
This is the output from sphinx-quickstart, massaged a bit, along with
our existing man pages converted to rst.
A skeleton notmuch-emacs manual is also included. It is not suitable
for end user use yet.
