Documentation: getting started / tutorial

[pragmaware]

Some users have been asking me for simple usage instructions for ctags and I couldn't find them. It would be nice to have a "getting started" guide that shows how to run ctags on a tree of sources, to turn on/off languages, kinds and fields and maybe how to hook everything up with an editor. It should be pretty short and condensed with eventual pointers to more information for deeper understanding.

One would expect to find it either on the first page of the site or on the github page.

An user pointed me to http://ctags.sourceforge.net/faq.html#15 as example. But I think it could be quite a lot nicer, maybe with some markup and a few ready-to-copy-and-paste examples.

[masatake]

How about providing ctags-example(1) man page?

[masatake]

I'm working on improving readtags. After finishing, I will work on this topic.

[masatake]

I wrote a short introduction for my class ago.
http://people.redhat.com/yamato/talks/reading/slides/1/12ctags-usage.pdf (In Japanese)
I can start from here.

[pragmaware]

A man page is not very visible. Better a markup that can be placed on github and maybe processed into html to be placed on the site.

[masatake]

Do you know our man pages are visible as part the web site?
https://docs.ctags.io/en/latest/man-pages.html
Currently, the man pages are appeared at the end of menus in the web site.
But we can arrange the order.

[pBlasiak]

sorry but your man pages are maybe good for advanced users
for standard users, like me, it is a worthless help that is hard to understand
much better would be detailed information that are already provided in your man pages
and example tutorial just like here
http://ctags.sourceforge.net/faq.html#15

[masatake]

Could you tell me more what you expect the ideal ... ctags-intro(1) document.

I think normal users should not only ctags -R about ctags itself.
About the operations on vim or something other editors, I think we should not provide much.

BTW, I'm happy if you use '.' in your comments. Without periods, it is very hard for me to parse your comment.

[pBlasiak]

I think enough would be just copy and paste on your website what is here
http://ctags.sourceforge.net/faq.html#15

However I do not know if it is possible. If not, similar guides-tutorial
should be provided. Unless in universal ctags simple ctags -R is sufficient and
one does not have to care if it is many local tag files or on big tag file.

[masatake]

...it seems that I'm not a good person to write such document. I myself use only ctags -R --kinds-all='*' --fields='*' --fields-all='*' --extras='*' --extras-all='*' and readtags -Q. What I do is making tags file as much informative as possible. I don't use vim much. So I cannot write about "the best way to make tags file for your vim".

https://vi.stackexchange.com/questions/22346/is-it-possible-to-create-a-snippet-to-expand-struct-members-to-fill In the comment, one writes about readtags. It is really nice comment.

Anyway, I have to add ctags-faq(7) man page.

[mr-mocap]

I ended up learning a LOT about ctags over the decades. Believe me, I understand the frustration in figuring out how to effectively use ctags. I eventually created my own bash script wrapper around it that generates tags files for various libs in the system. This was the breakthrough for me... NOT having one massive tags file like everyone seems to want to do.
I eventually put the code in to the repository vim-ctags-modules. It uses exuberant ctags, but could be adapted to any ctags variant.
I hope this helps, even if only a little.
Basically what I'm saying is: let me know if or how I can help.

[masatake]

@mr-mocap, impressive.

I'm thinking about introduceing -r|--semantic-recursion and --path-=[+|-]... option.

Consider foo.c

#include <stdio.h>
int main (void) { printf ("hello, world\n"); }

You will run ctags with following command line:

$ u-ctags --add-C=+/usr/include -r foo.c

In the first pass, the C parser of ctags detects stdio.h is included.
ctags searches the stdio.h from /usr/include. It will finds /usr/include/stdio.h and enqueue the header
file to the input list used in ctags internally.
Then, the the C parser detects stddef.h is included from /usr/include/stdio.h.
ctags searches the stddef.h from /usr/include....

This idea is applicable to "import" of Python.
See #2428

I'm also thinking about psuedo tag named "!_TAG_INCLUDE_TAG".
This is for including/referencing pre existing tag files from a tag file.

You may have an interest in #2427