docs(man): write about the conditions when escaping rules are applied…

… to input fields Co-authored-by: AmaiKinono <amaikinono@gmail.com> Signed-off-by: Masatake YAMATO <yamato@redhat.com>
universal-ctags · Dec 31, 2022 · f72f908 · f72f908
1 parent 4758655
commit f72f908
Show file tree

Hide file tree

Showing 6 changed files with 68 additions and 2 deletions.
diff --git a/docs/man/ctags-client-tools.7.rst b/docs/man/ctags-client-tools.7.rst
@@ -236,6 +236,18 @@ for using notable ones.
 	``--output-format`` option is for choosing the output mode within
 	the tags output format. See :ref:`ctags(1) <ctags(1)>` about the option.
 
+	In "e-ctags" mode, for not violating the tags file format
+	described in :ref:`tags(5) <tags(5)>`, Universal Ctags skips emitting tag entries
+	including illegal characters like <Tab>.
+
+	In input fields ({tagfile} in :ref:`tags(5) <tags(5)>`), we have one more
+	condition for applying the escaping rules: ``\`` characters
+	are not used as filename separators. UNIX-like systems use ``/``
+	for the purpose. On MS Windows, Universal Ctags converts ``\``
+	in filenames to ``/`` by default. So, generally this condition is
+	satisfied. The condition is not satisfied only when you specify
+	``--use-slash-as-filename-separator=no`` on MS Windows.
+
 ``TAG_OUTPUT_VERSION`` (new in Universal Ctags 6.0)
 	Indicates the language-common interface version of the output::
 

diff --git a/docs/man/readtags.1.rst b/docs/man/readtags.1.rst
@@ -92,6 +92,13 @@ human-readable, but when utilizing readtags output in a script or a client
 tool, ``-E`` option should be used. See :ref:`ctags-client-tools(7) <ctags-client-tools(7)>` for more
 discussion on this.
 
+About printing input fields ({tagfile} in :ref:`tags(5) <tags(5)>`) with ``-E`` option: readtags
+always prints the input field literally (as it is in the tags file), and when
+ctags writes the tags file, the escaping rules are applied only when
+``TAG_OUTPUT_MODE`` pseudo tag has "u-ctags" and ``TAG_OUTPUT_FILESEP`` has
+"slash" as values for their input fields, as explained in
+:ref:`ctags-client-tools(7) <ctags-client-tools(7)>`.
+
 Filtering, Sorting, and Formatting
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Further filtering, sorting, and formatting on the tags listed by actions

diff --git a/docs/man/tags.5.rst b/docs/man/tags.5.rst
@@ -294,7 +294,8 @@ A tagfield has a name, a colon, and a value: "name:value".
     not handled in the above "value" rules.
 
   EXCEPTION: Universal Ctags allows all these escape sequences in {tagname}
-  also.
+  and {tagfile} also. However, about {tagfile}, a condition must be
+  satisfied. See "`Exceptions in Universal Ctags`_" about the condition.
 
   - The leading space (0x20) and ``!`` (0x21) in {tagname} are converted
     to ``\x`` prefixed hexadecimal number (``\x20`` and ``\x21``) if the
@@ -448,6 +449,11 @@ command can be used::
 
 (replace ^I with a real <Tab>).
 
+COMMENT: Universal Ctags running on MS Windows converts the ``\`` separator
+to ``/`` by defualt, and allows the escape sequences even in {tagfile}
+if a condition is satisfied. See "`Exceptions in Universal Ctags`_" about
+the condition.
+
 TAG FILE INFORMATION:
 
 Pseudo-tag lines can be used to encode information into the tag file regarding
@@ -515,6 +521,14 @@ Exceptions
    exceptions. See {tagname} of Proposal section for more detail about the
    conversion.
 
+#. {tagfile} in tags file generated by Universal Ctags may contain
+   spaces and several escape sequences if ``\`` characters are not used as
+   filename separators. UNIX-like systems use ``/`` for the
+   purpose. On MS Windows, Universal Ctags converts ``\`` in filenames
+   to ``/`` by default. So, generally this condition is satisfied.
+   Universal Ctags emits several psuedo tags telling whether the condition
+   is satisfied or not. See :ref:`ctags-client-tools(7) <ctags-client-tools(7)>` about these psuedo tags.
+
 #. "name" part of {tagfield} in a tag generated by Universal Ctags may
    contain numeric characters, but the first character of the "name"
    must be alphabetic.

diff --git a/man/ctags-client-tools.7.rst.in b/man/ctags-client-tools.7.rst.in
@@ -236,6 +236,18 @@ for using notable ones.
 	``--output-format`` option is for choosing the output mode within
 	the tags output format. See ctags(1) about the option.
 
+	In "e-ctags" mode, for not violating the tags file format
+	described in tags(5), Universal Ctags skips emitting tag entries
+	including illegal characters like <Tab>.
+
+	In input fields ({tagfile} in tags(5)), we have one more
+	condition for applying the escaping rules: ``\`` characters
+	are not used as filename separators. UNIX-like systems use ``/``
+	for the purpose. On MS Windows, Universal Ctags converts ``\``
+	in filenames to ``/`` by default. So, generally this condition is
+	satisfied. The condition is not satisfied only when you specify
+	``--use-slash-as-filename-separator=no`` on MS Windows.
+
 ``TAG_OUTPUT_VERSION`` (new in Universal Ctags 6.0)
 	Indicates the language-common interface version of the output::
 

diff --git a/man/readtags.1.rst.in b/man/readtags.1.rst.in
@@ -92,6 +92,13 @@ human-readable, but when utilizing readtags output in a script or a client
 tool, ``-E`` option should be used. See ctags-client-tools(7) for more
 discussion on this.
 
+About printing input fields ({tagfile} in tags(5)) with ``-E`` option: readtags
+always prints the input field literally (as it is in the tags file), and when
+ctags writes the tags file, the escaping rules are applied only when
+``TAG_OUTPUT_MODE`` pseudo tag has "u-ctags" and ``TAG_OUTPUT_FILESEP`` has
+"slash" as values for their input fields, as explained in
+ctags-client-tools(7).
+
 Filtering, Sorting, and Formatting
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Further filtering, sorting, and formatting on the tags listed by actions

diff --git a/man/tags.5.rst.in b/man/tags.5.rst.in
@@ -294,7 +294,8 @@ A tagfield has a name, a colon, and a value: "name:value".
     not handled in the above "value" rules.
 
   EXCEPTION: Universal Ctags allows all these escape sequences in {tagname}
-  also.
+  and {tagfile} also. However, about {tagfile}, a condition must be
+  satisfied. See "`Exceptions in Universal Ctags`_" about the condition.
 
   - The leading space (0x20) and ``!`` (0x21) in {tagname} are converted
     to ``\x`` prefixed hexadecimal number (``\x20`` and ``\x21``) if the
@@ -448,6 +449,11 @@ command can be used::
 
 (replace ^I with a real <Tab>).
 
+COMMENT: Universal Ctags running on MS Windows converts the ``\`` separator
+to ``/`` by defualt, and allows the escape sequences even in {tagfile}
+if a condition is satisfied. See "`Exceptions in Universal Ctags`_" about
+the condition.
+
 TAG FILE INFORMATION:
 
 Pseudo-tag lines can be used to encode information into the tag file regarding
@@ -515,6 +521,14 @@ Exceptions
    exceptions. See {tagname} of Proposal section for more detail about the
    conversion.
 
+#. {tagfile} in tags file generated by Universal Ctags may contain
+   spaces and several escape sequences if ``\`` characters are not used as
+   filename separators. UNIX-like systems use ``/`` for the
+   purpose. On MS Windows, Universal Ctags converts ``\`` in filenames
+   to ``/`` by default. So, generally this condition is satisfied.
+   Universal Ctags emits several psuedo tags telling whether the condition
+   is satisfied or not. See ctags-client-tools(7) about these psuedo tags.
+
 #. "name" part of {tagfield} in a tag generated by Universal Ctags may
    contain numeric characters, but the first character of the "name"
    must be alphabetic.