Branch: refs/heads/master Author: Jiří Techet techet@gmail.com Committer: Jiří Techet techet@gmail.com Date: Mon, 16 Oct 2023 23:09:13 UTC Commit: 3f6f10c627ab33cdc04dfbee6c889768b784ec99 https://github.com/geany/geany/commit/3f6f10c627ab33cdc04dfbee6c889768b784ec...
Log Message: ----------- Update geany.txt with ctags usage for generating tag files
Co-authored-by: Colomban Wendling lists.ban@herbesfolles.org
Modified Paths: -------------- doc/geany.txt
Modified: doc/geany.txt 87 lines changed, 61 insertions(+), 26 deletions(-) =================================================================== @@ -1685,25 +1685,32 @@ Global tags file format
Global tags files can have three different formats:
-* Tagmanager format -* Pipe-separated format * CTags format +* Pipe-separated format +* Tagmanager format
-For the tagmanager or pipe-separated format, the first line of global tag files -should be a comment, introduced by ``#`` followed by a space and a string like -``format=tagmanager`` or ``format=pipe``, respectively; these are -case-sensitive. This helps Geany to read the file properly. If this -line is missing, Geany tries to auto-detect the used format but this -might fail. Tag files using the CTags format should be left unmodified in the +Tag files using the CTags format should be left unmodified in the form generated by the ctags command-line tool.
+For the pipe-separated or tagmanager format, the first line of global tag files +should be a comment, introduced by ``#`` followed by a space and +``format=pipe`` or ``format=tagmanager``, respectively; these are +case-sensitive. This helps Geany to read the file properly. If this +line is missing, Geany tries to auto-detect the format used but this +might fail. + + +CTags format +************ +This is the recommended tags file format, generated by the ctags command-line +tool from the universal-ctags project (https://github.com/universal-ctags/ctags). +This format is compatible with the format historically used by Vi. + +The format is described at https://ctags.sourceforge.net/FORMAT, but +for the full list of existing extensions please refer to universal-ctags. +However, note that Geany may actually only honor a subset of the +existing extensions.
-The Tagmanager format is a bit more complex and is used for files -created by the ``geany -g`` command. There is one symbol per line. -Different symbol attributes like the return value or the argument list -are separated with different characters indicating the type of the -following argument. This is the more complete and recommended tags file -format.
Pipe-separated format ********************* @@ -1726,19 +1733,47 @@ You can easily write your own global tags files using this format. Just save them in your tags directory, as described earlier in the section `Global tags files`_.
-CTags format -************ -This is the format that ctags generates, and that is used by Vim. -This format is compatible with the format historically used by Vi.
-The format is described at https://ctags.sourceforge.net/FORMAT, but -for the full list of existing extensions please refer to ctags. -However, note that Geany may actually only honor a subset of the -existing extensions. +Tagmanager format +***************** +The Tagmanager format is a bit more complex and is used for files +created by the ``geany -g`` command. There is one symbol per line. +Different symbol attributes like the return value or the argument list +are separated with different characters indicating the type of the +following argument. +
Generating a global tags file `````````````````````````````
+Generating tags files using ctags +********************************* +This is currently the recommended way of generating tags files. Unlike the +methods below which use the Geany binary for their generation, this method +should produce tags files which are compatible across Geany releases, starting +from Geany 2.0. + +Geany supports loading tag files generated using the ``ctags`` command-line +tool from the universal-ctags project (https://github.com/universal-ctags/ctags). +Even though Geany should work with any ctags file, it is recommended to use +certain fields to give Geany some additional information. The recommended fields +are ``EfiklsZSt``, so to generate symbols for all sources in the my_project +directory one can use:: + + ctags -n --fields=EfiklsZSt -R -o my_project.c.tags my_project + +Additional options may be given to the ``ctags`` tool, for instance, to restrict +the generated tags file to some languages only, use certain tag kinds, etc. + +Note that when the ``l`` field (specifying the programming language) is enabled, +the language of all symbols is set based on the value of this field instead of +the language specified in the extension of the tags file. You however still +have to name the file according to the same rules regardless of whether the +``l`` field is used or not. + + +Generating tags files using Geany +********************************* You can generate your own global tags files by parsing a list of source files. The command is::
@@ -1760,8 +1795,8 @@ Example for the wxD library for the D programming language:: geany -g wxd.d.tags /home/username/wxd/wx/*.d
-Generating C/C++ tags files -*************************** +Generating C/C++ tags files using Geany +*************************************** You may need to first setup the `C ignore.tags`_ file.
For C/C++ tags files gcc is required by default, so that header files @@ -1779,8 +1814,8 @@ You can adapt this command to use CFLAGS and header files appropriate for whichever libraries you want.
-Generating tags files on Windows -******************************** +Generating tags files on Windows using Geany +******************************************** This works basically the same as on other platforms::
"c:\program files\geany\bin\geany" -g c:\mytags.php.tags c:\code\somefile.php
-------------- This E-Mail was brought to you by github_commit_mail.py (Source: https://github.com/geany/infrastructure).