Skip to content

Commit 109d1ac

Browse files
masatakemasatake
authored
Merge pull request #2209 from masatake/format-5-man-page
convert docs/format.rst to tags(5) man page
2 parents 421f394 + 85af85b commit 109d1ac

File tree

9 files changed

+71
-40
lines changed

9 files changed

+71
-40
lines changed

‎Makefile.am‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ EXTRA_DIST = README.md autogen.sh \
1212
win32/ctags_vs2013.sln \
1313
win32/ctags_vs2013.vcxproj win32/ctags_vs2013.vcxproj.filters \
1414
win32/gen-repoinfo.bat \
15+
man/tags.5.rst \
1516
$(PEG_INPUT) $(OPTLIB2C_INPUT)
1617

1718
bin_PROGRAMS = ctags
@@ -179,15 +180,25 @@ include $(top_srcdir)/makefiles/testing.mak
179180
include $(top_srcdir)/makefiles/help.mak
180181

181182
if HAVE_RST2MAN
182-
man_MANS = man/ctags.1 man/ctags-incompatibilities.7 man/ctags-optlib.7
183+
man_MANS = \
184+
man/ctags.1 \
185+
\
186+
man/tags.5 \
187+
\
188+
man/ctags-incompatibilities.7 \
189+
man/ctags-optlib.7 \
190+
\
191+
$(NULL)
183192
rst2man_verbose = $(rst2man_verbose_@AM_V@)
184193
rst2man_verbose_ = $(rst2man_verbose_@AM_DEFAULT_V@)
185194
rst2man_verbose_0 = @echo RST2MAN " $@";
186-
SUFFIXES += .1.rst .1 .7.rst .7
195+
SUFFIXES += .1.rst .1 .5.rst .5 .7.rst .7
187196
# See man/Makefile
188197
RST2MAN_OPTIONS=--syntax-highlight=none
189198
.1.rst.1:
190199
$(rst2man_verbose)$(RST2MAN) $(RST2MAN_OPTIONS) $< $@
200+
.5.rst.5:
201+
$(rst2man_verbose)$(RST2MAN) $(RST2MAN_OPTIONS) $< $@
191202
.7.rst.7:
192203
$(rst2man_verbose)$(RST2MAN) $(RST2MAN_OPTIONS) $< $@
193204
endif

‎docs/contributions.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,7 @@ e.g. ::
8282

8383
make units LANGUAGES=TTCN VG=1 is passed.
8484
make fuzz LANGUAGES=TTCN VG=1 is passed.
85-
make chop LANGUAGES=TTCN VG=1 is passed.
85+
make chop LANGUAGES=TTCN VG=1 is passed.
8686

8787

8888
C language
@@ -197,7 +197,7 @@ Add a test case to Tmain when modifying the core.
197197

198198
Add a test case to Tinst when modifying the install target in the
199199
Makefile.
200-
200+
201201
Compatibility
202202
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
203203

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

212212
TBW.
213213

@@ -296,7 +296,7 @@ Here is an example.
296296
* This module contains functions for generating tags for property list defined
297297
* in http://www.apple.com/DTDs/PropertyList-1.0.dtd.
298298
*/
299-
299+
300300
Testing your parser
301301
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
302302

‎docs/index.rst‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,5 @@ This is a draft document. Proofreading and pull-requests are welcome!
4545
extending.rst
4646
tips.rst
4747
other-projects.rst
48-
format.rst
4948
development-process.rst
5049
developers.rst

‎docs/output-format.rst‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,9 @@ This section deals with individual output-format topics.
1313

1414
``--output-format=`` can be used for choosing an output format.
1515

16+
About the output format specified with ``e-ctags`` and ``u-ctags``,
17+
see tags(5) man page.
18+
1619
.. toctree::
1720
:maxdepth: 2
1821

‎man/Makefile‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,14 +39,19 @@ CONFIGURE_FLAGS =
3939

4040
.SUFFIXES: .rst .html .pdf .in
4141

42-
SOURCE_FILES = \
42+
IN_SOURCE_FILES = \
4343
ctags.1.rst.in \
4444
ctags-optlib.7.rst.in \
4545
ctags-incompatibilities.7.rst.in \
4646
\
4747
$(NULL)
4848

49-
rst_files = $(basename $(SOURCE_FILES))
49+
SOURCE_FILES = \
50+
tags.5.rst \
51+
\
52+
$(NULL)
53+
54+
rst_files = $(basename $(IN_SOURCE_FILES)) $(SOURCE_FILES)
5055
man_pages = $(basename $(rst_files))
5156
html_pages = $(addsuffix .html,$(man_pages))
5257
pdf_pages = $(addsuffix .pdf,$(man_pages))

‎man/ctags-incompatibilities.7.rst.in‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -185,3 +185,7 @@ to follow the above rule.
185185
* Ruby's "F" (singletonMethod) is changed to "S".
186186

187187
* SQL's "F" (field) is changed to "E".
188+
189+
SEE ALSO
190+
--------
191+
ctags(1) and tags(5).

‎man/ctags-optlib.7.rst.in‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -238,7 +238,7 @@ OPTION ITEMS
238238
message will be reported unless ``{placeholder}`` regex flag is
239239
specified. An optional kind specifier for tags matching regexp may
240240
follow *replacement*, which will determine what kind of tag is
241-
reported in the "kind" extension field (see ctags-tags(5)).
241+
reported in the "kind" extension field (see tags(5)).
242242

243243
*kind-spec* has two forms: letter only form and full form. The
244244
letter form assumes using ``--regex-<LANG>`` option with
@@ -421,7 +421,7 @@ The official Universal-ctags web site at:
421421

422422
https://ctags.io/
423423

424-
ctags(1), regex(5,7), egrep(1)
424+
ctags(1), tags(5), regex(5,7), egrep(1)
425425

426426
AUTHOR
427427
------

‎man/ctags.1.rst.in‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1795,6 +1795,8 @@ SEE ALSO
17951795
See ctags-optlib(7) for defining (or extending) a parser
17961796
in a configuration file.
17971797

1798+
See tags(5) for the format of tag files.
1799+
17981800
The official Universal-ctags web site at:
17991801

18001802
https://ctags.io/

‎docs/format.rst‎ renamed to ‎man/tags.5.rst‎

Lines changed: 36 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,35 @@
1-
===================================================================
2-
Proposal for extended Vi tags file format
3-
===================================================================
4-
5-
.. note::
6-
7-
The contents of next section is a copy of FORMAT file in exuberant
8-
ctags source code in its subversion repository at sourceforge.net.
9-
10-
We have made some modifications:
11-
12-
* Exceptions introduced in Universal-ctags are explained with
13-
"EXCEPTION" marker.
1+
.. _tags(5):
2+
3+
==============================================================
4+
tags
5+
==============================================================
6+
--------------------------------------------------------------
7+
Vi tags file format extended in ctags projects
8+
--------------------------------------------------------------
9+
:Version: 2+
10+
:Manual group: Universal-ctags
11+
:Manual section: 5
12+
13+
DESCRIPTION
14+
-----------
1415

15-
* `Exceptions in Universal-ctags`_ subsction summarizes the exceptions.
16+
The contents of next section is a copy of FORMAT file in exuberant
17+
ctags source code in its subversion repository at sourceforge.net.
1618

17-
.. contents:: `Table of contents`
18-
:depth: 3
19-
:local:
19+
Exceptions introduced in Universal-ctags are explained inline with
20+
"EXCEPTION" marker.
2021

2122
----
2223

23-
:Version: 0.06 DRAFT
24-
:Date: 1998 Feb 8
25-
:Author: Bram Moolenaar <Bram at vim.org> and Darren Hiebert <dhiebert at users.sourceforge.net>
24+
Proposal for extended Vi tags file format
25+
-----------------------------------------
2626

27+
| Version: 0.06 DRAFT
28+
| Date: 1998 Feb 8
29+
| Author: Bram Moolenaar <Bram at vim.org> and Darren Hiebert <dhiebert at users.sourceforge.net>
2730
2831
Introduction
29-
---------------------------------------------------------------------
32+
~~~~~~~~~~~~
3033

3134
The file format for the "tags" file, as used by Vi and many of its
3235
descendants, has limited capabilities.
@@ -48,7 +51,7 @@ This additional functionality is desired:
4851

4952

5053
From proposal to standard
51-
-------------------------------------------------------------------------
54+
~~~~~~~~~~~~~~~~~~~~~~~~~
5255

5356
To make this proposal into a standard for tags files, it needs to be supported
5457
by most people working on versions of Vi, ctags, etc.. Currently this
@@ -88,7 +91,7 @@ FTE
8891

8992

9093
Backwards compatibility
91-
---------------------------------------------------------------------------
94+
~~~~~~~~~~~~~~~~~~~~~~~
9295

9396
A tags file that is generated in the new format should still be usable by Vi.
9497
This makes it possible to distribute tags files that are usable by all
@@ -148,7 +151,7 @@ from this.
148151

149152

150153
Security
151-
------------------------------------------------------------------
154+
~~~~~~~~
152155

153156
Vi allows the use of any Ex command in a tags file. This has the potential of
154157
a trojan horse security leak.
@@ -194,7 +197,7 @@ position the cursor in a certain column.
194197

195198

196199
Goals
197-
--------
200+
~~~~~
198201

199202
Now the usage of the comment text has to be defined. The following is aimed
200203
at:
@@ -217,7 +220,7 @@ at:
217220
* It should be possible to treat a tags file like any normal text file.
218221

219222
Proposal
220-
-----------
223+
~~~~~~~~
221224

222225
Use a comment after the {tagaddress} field. The format would be::
223226

@@ -470,14 +473,14 @@ file, and provided solely for documentation purposes::
470473
!_TAG_PROGRAM_VERSION {version-id} /optional comment/
471474

472475
Exceptions in Universal-ctags
473-
--------------------------------
476+
--------------------------------------------
474477

475478
Universal-ctags supports this proposal with some
476479
exceptions.
477480

478481

479482
Exceptions
480-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
483+
~~~~~~~~~~~
481484

482485
#. {tagname} in tags file generated by Universal-ctags may contain
483486
spaces and several escape sequences. Parsers for documents like Tex and
@@ -494,7 +497,7 @@ Exceptions
494497
.. _compat-output:
495498

496499
Compatible output and weakness
497-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
500+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
498501

499502
.. NOT REVIEWED YET
500503

@@ -505,3 +508,7 @@ format as Exuberant-ctags. However, ``--output-format=e-ctags`` throws
505508
away a tag entry which name includes a space or a tab
506509
character. ``TAG_OUTPUT_MODE`` pseudo tag tells which format is
507510
used when ctags generating tags file.
511+
512+
SEE ALSO
513+
--------
514+
ctags(1), ctags-incompatibilities(7)

0 commit comments

Comments
 (0)