Rules for writing man pages
---------------------------------------------------------------------

* put two single quotes around an option name like ``--help``.

* put two single quotes with colon around field name like ``field:``.

* put double quotes aground an example of command line, option usage like
  "--langdef=MyLang", referring a section, and a file path.

* use two asterisks for newly introduced conceptual **word** and reserved
  words. The reserved words are

  * "default" in --langmap

* use one asterisk for option parameter like *LANG* in --kind-<LANG> option.

* To represent a backslash, surround it with double backquote. i.e. ``\``.
  Escaping a backslash with another backslash doesn't work well depending
  on the tools. When converting rst to man, two backslashes are converted
  into one, however when converting to html, four backslashes are converted
  into one.

* the files in ../docs/man/ need to be updated after writing man pages.
  Execute the following command to update them:

	make QUICK=1 update-docs


Tips for writing man pages
---------------------------------------------------------------------

* about hyperlinks

  + `phrase reference`_ style is valid only in the same page.
    When this is used on rst2man, it is shown with underline.

  + rst2html (and sphinx) converts this to a hyperlink.
    :ref:`title <tag>` style can jump across files, but this can
    be used only on sphinx and cause error on old docutils
    (rst2man).


Testing and verification
---------------------------------------------------------------------
* pick reserved words

  - "default"
  - "all"
  - "NONE"
  - '-'

* verify whether + and - can be used as part of language names:

  --langmap
	languages like C++ and/or Objective-C can be specified.

  --languages
	languages like C++ and/or Objective-C can be specified.

* TODO

  - strcasecmp must be used when comparing the name of languages.