docs(web,man): convert docs/format.rst to tags(5) man page

Fixing many typoes are suggested by @k-takata.

Signed-off-by: Masatake YAMATO <[email protected]>

Makefile.am

@@ -12,6 +12,7 @@ EXTRA_DIST   = README.md autogen.sh \
 	       win32/ctags_vs2013.sln \
 	       win32/ctags_vs2013.vcxproj win32/ctags_vs2013.vcxproj.filters \
 	       win32/gen-repoinfo.bat \
+	       man/tags.5.rst \
 		$(PEG_INPUT) $(OPTLIB2C_INPUT)
 
 bin_PROGRAMS = ctags
@@ -179,15 +180,25 @@ include $(top_srcdir)/makefiles/testing.mak
 include $(top_srcdir)/makefiles/help.mak
 
 if HAVE_RST2MAN
-man_MANS = man/ctags.1 man/ctags-incompatibilities.7 man/ctags-optlib.7
+man_MANS = \
+	man/ctags.1 \
+	\
+	man/tags.5 \
+	\
+	man/ctags-incompatibilities.7 \
+	man/ctags-optlib.7 \
+	\
+	$(NULL)
 rst2man_verbose = $(rst2man_verbose_@AM_V@)
 rst2man_verbose_ = $(rst2man_verbose_@AM_DEFAULT_V@)
 rst2man_verbose_0 = @echo RST2MAN "  $@";
-SUFFIXES += .1.rst .1 .7.rst .7
+SUFFIXES += .1.rst .1 .5.rst .5 .7.rst .7
 # See man/Makefile
 RST2MAN_OPTIONS=--syntax-highlight=none
 .1.rst.1:
 	$(rst2man_verbose)$(RST2MAN) $(RST2MAN_OPTIONS) $< $@
+.5.rst.5:
+	$(rst2man_verbose)$(RST2MAN) $(RST2MAN_OPTIONS) $< $@
 .7.rst.7:
 	$(rst2man_verbose)$(RST2MAN) $(RST2MAN_OPTIONS) $< $@
 endif

docs/contributions.rst

@@ -207,7 +207,7 @@ following two areas.
 Tag file compatibility with Exuberant-ctags
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 We will not accept a patch that breaks the tags file format described
-in "Proposal for extended Vi tags file format" a.k.a. FORMAT file.
+in tags(5) man page.
 
 TBW.
 

docs/index.rst

@@ -45,6 +45,5 @@ This is a draft document. Proofreading and pull-requests are welcome!
 	extending.rst
 	tips.rst
 	other-projects.rst
-	format.rst
 	development-process.rst
 	developers.rst

docs/output-format.rst

@@ -13,6 +13,9 @@ This section deals with individual output-format topics.
 
 ``--output-format=`` can be used for choosing an output format.
 
+About the output format specified with ``e-ctags`` and ``u-ctags``,
+see tags(5) man page.
+
 .. toctree::
 	:maxdepth: 2
 

man/Makefile

@@ -39,14 +39,19 @@ CONFIGURE_FLAGS =
 
 .SUFFIXES: .rst .html .pdf .in
 
-SOURCE_FILES = \
+IN_SOURCE_FILES = \
 	ctags.1.rst.in \
 	ctags-optlib.7.rst.in \
 	ctags-incompatibilities.7.rst.in \
 	\
 	$(NULL)
 
-rst_files  = $(basename $(SOURCE_FILES))
+SOURCE_FILES = \
+	tags.5.rst \
+	\
+	$(NULL)
+
+rst_files  = $(basename $(IN_SOURCE_FILES)) $(SOURCE_FILES)
 man_pages  = $(basename $(rst_files))
 html_pages = $(addsuffix .html,$(man_pages))
 pdf_pages  = $(addsuffix .pdf,$(man_pages))

man/ctags-incompatibilities.7.rst.in

@@ -185,3 +185,7 @@ to follow the above rule.
 * Ruby's "F" (singletonMethod) is changed to "S".
 
 * SQL's "F" (field) is changed to "E".
+
+SEE ALSO
+--------
+ctags(1) and tags(5).

man/ctags-optlib.7.rst.in

@@ -238,7 +238,7 @@ OPTION ITEMS
 	message will be reported unless ``{placeholder}`` regex flag is
 	specified. An optional kind specifier for tags matching regexp may
 	follow *replacement*, which will determine what kind of tag is
-	reported in the "kind" extension field (see ctags-tags(5)).
+	reported in the "kind" extension field (see tags(5)).
 
 	*kind-spec* has two forms: letter only form and full form.  The
 	letter form assumes using ``--regex-<LANG>`` option with
@@ -421,7 +421,7 @@ The official Universal-ctags web site at:
 
 https://ctags.io/
 
-ctags(1), regex(5,7), egrep(1)
+ctags(1), tags(5), regex(5,7), egrep(1)
 
 AUTHOR
 ------

man/ctags.1.rst.in

@@ -1795,6 +1795,8 @@ SEE ALSO
 See ctags-optlib(7) for defining (or extending) a parser
 in a configuration file.
 
+See tags(5) for the format of tag files.
+
 The official Universal-ctags web site at:
 
 https://ctags.io/

docs/format.rst → man/tags.5.rst

@@ -1,32 +1,35 @@
-===================================================================
-Proposal for extended Vi tags file format
-===================================================================
-
-.. note::
-
-    The contents of next section is a copy of FORMAT file in exuberant
-    ctags source code in its subversion repository at sourceforge.net.
-
-	We have made some modifications:
-
-	* Exceptions introduced in Universal-ctags are explained with
-	  "EXCEPTION" marker.
+.. _tags(5):
+
+==============================================================
+tags
+==============================================================
+--------------------------------------------------------------
+Vi tags file format extended in ctags projects
+--------------------------------------------------------------
+:Version: 2+
+:Manual group: Universal-ctags
+:Manual section: 5
+
+DESCRIPTION
+-----------
 
-    * `Exceptions in Universal-ctags`_ subsction summarizes the exceptions.
+The contents of next section is a copy of FORMAT file in exuberant
+ctags source code in its subversion repository at sourceforge.net.
 
-.. contents:: `Table of contents`
-	:depth: 3
-	:local:
+Exceptions introduced in Universal-ctags are explained inline with
+"EXCEPTION" marker.
 
 ----
 
-:Version: 0.06 DRAFT
-:Date: 1998 Feb 8
-:Author: Bram Moolenaar <Bram at vim.org> and Darren Hiebert <dhiebert at users.sourceforge.net>
+Proposal for extended Vi tags file format
+-----------------------------------------
 
+| Version: 0.06 DRAFT
+| Date: 1998 Feb 8
+| Author: Bram Moolenaar <Bram at vim.org> and Darren Hiebert <dhiebert at users.sourceforge.net>
 
 Introduction
----------------------------------------------------------------------
+~~~~~~~~~~~~
 
 The file format for the "tags" file, as used by Vi and many of its
 descendants, has limited capabilities.
@@ -48,7 +51,7 @@ This additional functionality is desired:
 
 
 From proposal to standard
--------------------------------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To make this proposal into a standard for tags files, it needs to be supported
 by most people working on versions of Vi, ctags, etc..  Currently this
@@ -88,7 +91,7 @@ FTE
 
 
 Backwards compatibility
----------------------------------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~
 
 A tags file that is generated in the new format should still be usable by Vi.
 This makes it possible to distribute tags files that are usable by all
@@ -148,7 +151,7 @@ from this.
 
 
 Security
-------------------------------------------------------------------
+~~~~~~~~
 
 Vi allows the use of any Ex command in a tags file.  This has the potential of
 a trojan horse security leak.
@@ -194,7 +197,7 @@ position the cursor in a certain column.
 
 
 Goals
---------
+~~~~~
 
 Now the usage of the comment text has to be defined.  The following is aimed
 at:
@@ -217,7 +220,7 @@ at:
    * It should be possible to treat a tags file like any normal text file.
 
 Proposal
------------
+~~~~~~~~
 
 Use a comment after the {tagaddress} field.  The format would be::
 
@@ -470,14 +473,14 @@ file, and provided solely for documentation purposes::
     !_TAG_PROGRAM_VERSION	{version-id}	/optional comment/
 
 Exceptions in Universal-ctags
---------------------------------
+--------------------------------------------
 
 Universal-ctags supports this proposal with some
 exceptions.
 
 
 Exceptions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~
 
 #. {tagname} in tags file generated by Universal-ctags may contain
    spaces and several escape sequences. Parsers for documents like Tex and
@@ -494,7 +497,7 @@ Exceptions
 .. _compat-output:
 
 Compatible output and weakness
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. NOT REVIEWED YET
 
@@ -505,3 +508,7 @@ format as Exuberant-ctags. However, ``--output-format=e-ctags`` throws
 away a tag entry which name includes a space or a tab
 character. ``TAG_OUTPUT_MODE`` pseudo tag tells which format is
 used when ctags generating tags file.
+
+SEE ALSO
+--------
+ctags(1), ctags-incompatibilities(7)