From f72f908edbaf93ad057f5ea78fc17735060056a3 Mon Sep 17 00:00:00 2001 From: Masatake YAMATO Date: Sun, 18 Dec 2022 14:23:37 +0900 Subject: [PATCH] docs(man): write about the conditions when escaping rules are applied to input fields Co-authored-by: AmaiKinono Signed-off-by: Masatake YAMATO --- docs/man/ctags-client-tools.7.rst | 12 ++++++++++++ docs/man/readtags.1.rst | 7 +++++++ docs/man/tags.5.rst | 16 +++++++++++++++- man/ctags-client-tools.7.rst.in | 12 ++++++++++++ man/readtags.1.rst.in | 7 +++++++ man/tags.5.rst.in | 16 +++++++++++++++- 6 files changed, 68 insertions(+), 2 deletions(-) diff --git a/docs/man/ctags-client-tools.7.rst b/docs/man/ctags-client-tools.7.rst index f6e4b9bcd5..3700aa8322 100644 --- 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) ` about the option. + In "e-ctags" mode, for not violating the tags file format + described in :ref:`tags(5) `, Universal Ctags skips emitting tag entries + including illegal characters like . + + In input fields ({tagfile} in :ref:`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 index c80f17b868..9f7f1e9f9f 100644 --- 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) ` for more discussion on this. +About printing input fields ({tagfile} in :ref:`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) `. + 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 index 0b4b0fbcb5..27b57f7905 100644 --- 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 ). +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) ` 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 index e874113700..1285fd8d1e 100644 --- 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 . + + 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 index 5ea49350f2..65b8981157 100644 --- 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 index a26eee6cb7..e8c3f553a8 100644 --- 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 ). +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.