Skip to content

Documentation: getting started / tutorial #2464

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
pragmaware opened this issue Mar 9, 2020 · 12 comments
Open

Documentation: getting started / tutorial #2464

pragmaware opened this issue Mar 9, 2020 · 12 comments

Comments

@pragmaware
Copy link
Contributor

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
Copy link
Member

masatake commented Mar 9, 2020

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

@masatake masatake self-assigned this Mar 9, 2020
@masatake
Copy link
Member

masatake commented Mar 9, 2020

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

@masatake
Copy link
Member

masatake commented Mar 9, 2020

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
Copy link
Contributor Author

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 masatake removed their assignment Mar 10, 2020
@masatake
Copy link
Member

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
Copy link

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
Copy link
Member

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
Copy link

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
Copy link
Member

...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.

@masatake masatake added this to the M1 for 6.0 milestone Mar 22, 2020
@mr-mocap
Copy link

mr-mocap commented Jul 1, 2020

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
Copy link
Member

masatake commented Jul 2, 2020

@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

hirooih added a commit that referenced this issue Feb 10, 2021
Thank you for your review and approval.  Let me merge this.

I think now we can close #2312 and #2464.
@hirooih
Copy link
Contributor

hirooih commented Feb 12, 2021

I added ctags-faq(7) on #2855.
https://docs.ctags.io/en/latest/man/ctags-faq.7.html

It includes the contents of http://ctags.sourceforge.net/faq.html#15.

Feel free to add more contents to the FAQ.

@masatake masatake removed this from the M1 for 6.0 milestone Dec 2, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

5 participants