From 85af85b57b37258ade7c5eb1f932e56658e9b575 Mon Sep 17 00:00:00 2001 From: Masatake YAMATO Date: Sat, 28 Sep 2019 00:53:19 +0900 Subject: [PATCH] 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 --- Makefile.am | 15 ++++++- docs/contributions.rst | 2 +- docs/index.rst | 1 - docs/output-format.rst | 3 ++ man/Makefile | 9 +++- man/ctags-incompatibilities.7.rst.in | 4 ++ man/ctags-optlib.7.rst.in | 4 +- man/ctags.1.rst.in | 2 + docs/format.rst => man/tags.5.rst | 65 +++++++++++++++------------- 9 files changed, 68 insertions(+), 37 deletions(-) rename docs/format.rst => man/tags.5.rst (93%) diff --git a/Makefile.am b/Makefile.am index a1bacc1c63..96c138e230 100644 --- a/Makefile.am +++ b/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 diff --git a/docs/contributions.rst b/docs/contributions.rst index 635a9bb724..498db587ed 100644 --- a/docs/contributions.rst +++ b/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. diff --git a/docs/index.rst b/docs/index.rst index 6489728397..6f758ed5e1 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/output-format.rst b/docs/output-format.rst index f5f439b5c8..df9e6c5e36 100644 --- a/docs/output-format.rst +++ b/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 diff --git a/man/Makefile b/man/Makefile index 2f854a3077..bf444f6ddd 100644 --- a/man/Makefile +++ b/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)) diff --git a/man/ctags-incompatibilities.7.rst.in b/man/ctags-incompatibilities.7.rst.in index fd186b5cc2..ffc6ab4b47 100644 --- a/man/ctags-incompatibilities.7.rst.in +++ b/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). diff --git a/man/ctags-optlib.7.rst.in b/man/ctags-optlib.7.rst.in index 93f286d9ed..2a5e116c7a 100644 --- a/man/ctags-optlib.7.rst.in +++ b/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-`` 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 ------ diff --git a/man/ctags.1.rst.in b/man/ctags.1.rst.in index 171a999bca..4c27bb7c20 100644 --- a/man/ctags.1.rst.in +++ b/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/ diff --git a/docs/format.rst b/man/tags.5.rst similarity index 93% rename from docs/format.rst rename to man/tags.5.rst index 2e62f0a0c5..bf81663d4f 100644 --- a/docs/format.rst +++ b/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 and Darren Hiebert +Proposal for extended Vi tags file format +----------------------------------------- +| Version: 0.06 DRAFT +| Date: 1998 Feb 8 +| Author: Bram Moolenaar and Darren Hiebert 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)