1# Universal Ctags Documentation # 2 3Go to https://docs.ctags.io to read formatted version of this documentation. 4 5## reStructuredText (Docutils and Sphinx) ## 6 7* [Docutils](https://docutils.sourceforge.io/docs/index.html) is used to format 8`man/*.rst.in` for man pages. Only reStructuredText syntaxes described 9[here](https://docutils.sourceforge.io/rst.html) can be used for the man pages. 10 11* [Sphinx Python Documentation Generator](https://www.sphinx-doc.org/en/master/index.html) is used to format `docs/*.rst`. 12See [here](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html) for more details of reStructuredText extended by Sphinx. 13 14## Rules for writing documents ## 15 16See also [Writing Documents](https://docs.ctags.io/en/latest/contributions.html#writing-documents). 17 18### reStructuredText Markup Rules 19 20* put two grave accents around a single-word option, an option usage like 21 `--langdef=MyLang`, a file path, and so on, as "``` ``--foo`` ```". For a 22 single character, add single quotes around it as "``` '``-``' ```". 23 24* put two grave accents and double quotes around a multi-word option and an 25 example of a command line, as " ``` "``-f file_name``" ``` " or " ``` 26 "``ctags --help``" ``` ". 27 28* put double quotes around referring a section, e.g. " `` See "Writing 29 Documents". `` ". 30 31* use one asterisk (emphasis) for a newly-introduced conceptual *word* as 32 "`*word*`". 33 34* use one asterisk and "`<>`" as "`*<LANG>*`" for an option parameter like 35 `<LANG>` in `--kind-<LANG>` option. 36 37* To represent a backslash, surround it with double backquote. i.e. "``` ``\`` ```". 38 Escaping a backslash with another backslash doesn't work well depending 39 on the tools. When converting rst to man, two backslashes are converted 40 into one, however when converting to html, four backslashes are converted 41 into one. 42 43### Hyperlinks 44 45* "`` `title`_ ``" and "`` `string <title>`_ ``" styles are valid only in the same page. 46 When this is used on `rst2man`, it is shown with underline. 47 48* "`` :ref:`label` ``" and "`` :ref:`string <label>` ``" style can jump across files. 49 `rst2html` (and sphinx) converts this to a hyperlink. 50 But this cause error on `rst2man` which is used to format man pages. 51 Don't use this style in man pages. 52 53* The titles of man pages (e.g. "``ctags(1)``", "``ctags-optlib(7)``", etc.) in 54 ``man/*.[1-9].rst.in`` are replaced to hyperlinks as "`` :ref:`ctags(1)` ``" 55 by "``make update-docs``". 56 57### Markers ### 58 59- "`NOT REVIEWED YET`" means the section or block is not reviewed yet. 60- "`IN MAN PAGE`" means the topic is also explained in the man page of ctags. 61- "`.. TODO: ...`": TODO comments for documents. 62- "`.. TODO(code): ...`": TODO comments for programming codes. 63- "`.. TESTCASE: ...`": A test case for the feature documented is at .... 64 65## Generating man pages ### 66 67The files in `docs/man/` directory are generated from the man pages in `man/` 68directory. **Do not edit the files in `docs/man/` directory directly.** 69 70Execute `make` in the top directory to update them. Or 71 72```sh 73make -C man 74``` 75 76will build the man pages only. 77 78During this process, hyperlinks to man pages are added as described above, and 79delete unnecessary section markups from `docs/man/*.rst`. See `man/Makefile.am` 80for more details. 81 82To generate the man pages `rst2man` command is needed. 83`rst2man` is part of the `python-docutils` package on Ubuntu. 84