[geany/geany] 230337: Update HACKING with up-to-date information about ctags parser addition

[Jiří Techet]

Branch:      refs/heads/master
Author:      Jiří Techet <techet at gmail.com>
Committer:   Jiří Techet <techet at gmail.com>
Date:        Sun, 10 Apr 2022 12:34:15 UTC
Commit:      230337d54e2bc245d59b4c58ede4fa1352719aa1
             https://github.com/geany/geany/commit/230337d54e2bc245d59b4c58ede4fa1352719aa1

Log Message:
-----------
Update HACKING with up-to-date information about ctags parser addition

Previously "tagmanager" was a synonym for ctags+tagmanager but these
are separate now and tagmanager is more or less par of core Geany now
and not a separate library so update/remove things related to tagmanager.

Anjuta and exuberant ctags parsers aren't compatible with current
universal-ctags parsers (or the current tag manager) so they can be
removed from the description too.

The rest is just updates related to the move of stuff from symbols.c
to tm_parsers.c.


Modified Paths:
--------------
    HACKING

Modified: HACKING
41 lines changed, 19 insertions(+), 22 deletions(-)
===================================================================
@@ -500,13 +500,13 @@ other changes should be passed on to the maintainers at
 http://scintilla.org. We normally update to a new Scintilla release
 shortly after one is made. See also scintilla/README.
 
-Tagmanager was originally taken from Anjuta 1.2.2, and parts of it
-(notably c.c) have been merged from later versions of Anjuta and
-CTags. The independent Tagmanager library itself ceased development
-before Geany was started. It's source code parsing is mostly taken from
-Exuberant CTags (see http://ctags.sf.net). If appropriate it's good to
-pass language parser changes back to the CTags project.
-
+We use an unmodified subset of universal-ctags sources
+(https://github.com/universal-ctags/ctags) to parse open documents. We
+also use the great majority of unmodified universal-ctags parsers except
+a few outliers that are maintained by us (those whose file names start
+with geany_). We normally update to the latest version of
+universal-ctags shortly after making a Geany release and keep this
+version during the rest of the development cycle.
 
 Notes
 =====
@@ -650,18 +650,13 @@ indentation after ':' is done from on_new_line_added().
 If the Scintilla lexer supports user type keyword highlighting (e.g.
 SCLEX_CPP), update document_update_tags() in document.c.
 
-Adding a TagManager parser
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+Adding a CTags parser
+^^^^^^^^^^^^^^^^^^^^^
 This assumes the filetype for Geany already exists.
 
 First write or find a CTags compatible parser, foo.c. Check this fork:
 https://github.com/universal-ctags/ctags
 
-There may be some unmerged language patches for CTags at:
-http://sf.net/projects/ctags - see the tracker.
-
-(You can also try the Anjuta project's anjuta-tags codebase.)
-
 Method
 ``````
 * Add foo.c to SRCS in Makefile.am.
@@ -673,20 +668,22 @@ In src/tagmanager/tm_parser.c:
 Add a map_FOO TMParserMapEntry mapping each kind's letter from foo.c's
 FooKinds to the appropriate TMTagType, and add the corresponding
 MAP_ENTRY(FOO) to parser_map.
-(You may want to make the symbols.c change before doing this).
 
 In src/tagmanager/tm_parser.c:
-Update tm_parser_scope_separator() and tm_parser_has_full_scope() to
-handle the new parser if applicable, by adding a TM_PARSER_FOO case entry.
+Add a group_FOO TMParserMapGroup defining root nodes of the symbol tree,
+used icons and TMTagType values grouped under the specified root.
+Multiple TMTagType values can be combined under a single root using |
+(bitwise OR).
+
+In src/tagmanager/tm_parser.c:
+Update various functions at the end of tm_parser.c to adjust Geany
+behavior to the behavior of the added parser. In particular, update
+tm_parser_scope_separator() and tm_parser_has_full_scope() so
+scope-related functionality works correctly.
 
 In filetypes.c, init_builtin_filetypes():
 Set the 2nd argument of the FT_INIT() macro for this filetype to FOO.
 
-In symbols.c:
-Unless your parser uses C-like tag type kinds, update
-add_top_level_items() for foo, calling tag_list_add_groups(). See
-get_tag_type_iter() for which tv_iters fields to use.
-
 Tests
 `````
 The tag parser tests checks if the proper tags are emitted



--------------
This E-Mail was brought to you by github_commit_mail.py (Source: https://github.com/geany/infrastructure).