Man tag concept #1497

masatake · 2017-06-29T16:48:11Z

I wrote my understanding about "tag", "kind", "field", "extra" and "role", the core concept of ctags.

I was attracted them 2 or 3 years ago. Since then I have tried to understand the meaning of them evenryday.

@k-takata, can I ask you to review the changes as usual?

Of couse, I'm happy if other people give me feed-back, especially who wants "releasing".

coveralls · 2017-06-29T17:37:19Z

Coverage increased (+0.0005%) to 85.112% when pulling 20a66ac on masatake:man--tag-concept into 53e7958 on universal-ctags:master.

coveralls · 2017-07-01T13:58:25Z

Coverage increased (+0.01%) to 85.122% when pulling 8da96cd on masatake:man--tag-concept into 53e7958 on universal-ctags:master.

coveralls · 2017-07-01T20:29:01Z

Coverage increased (+0.01%) to 85.122% when pulling 14f3a08 on masatake:man--tag-concept into 53e7958 on universal-ctags:master.

coveralls · 2017-07-02T16:22:27Z

Coverage decreased (-0.008%) to 85.123% when pulling 4ccb0f3 on masatake:man--tag-concept into cd27b61 on universal-ctags:master.

k-takata · 2017-07-03T09:31:50Z

man/Makefile

@@ -51,21 +51,24 @@ pdf_pages  = $(addsuffix .pdf,$(man_pages))
 #
 # though rst2man doesn't accept it. docutils must be fixed.
 #
-all: $(man_pages) $(html_pages) # $(pdf_pages)
+all: $(man_pages) $(html_pages) $(pdf_pages)


This might be out of scope of this PR, but how about adding man, html and pdf make targets?
Currently, it is not easy to make only man pages, html or pdf.

And, do you think pdf pages should be always built?
I wonder if I should include pdf files in Windows zip packages.

(Out of scope comments are really welcome if you have time :-)

man/Makefile is for us, people who are writing the pages.
For users, targets for generating files are in Makefile.am of top level.
For Unix-like platform, I think providing .1 and .7 man pages is enough.
However, for Windows, I'm not sure. If man command is not avaiable, people may want alternatives.
Such platforms may have *.mak files. So we should add "pdf" or something other targets to the .mak files. Putting html files derived from ctags.1.rst.in is another issue.

About man/Makefile, change as you wants. There is not impact on our users.
About *.mak files for platforms other than Unix-like OS, change as you wants.
About Makefile.am, make a pull request or open an issue. I would like to work together.

Any way, adding more targets to man/Makfile is good idea. I will add them.

OK, then I think html files are enough for Windows package.

k-takata · 2017-07-03T09:44:08Z

man/ctags.1.rst.in

+Roles
+~~~~~~
+
+*Role* is newly introduced concept in Universal-ctags. Role is a


Is an "a" needed before "newly"? Not sure.

k-takata · 2017-07-03T09:44:47Z

man/ctags.1.rst.in

+   ``--alias-<LANG>=`` (done)
+
+
+TAG ENTRY


"ENTRY" or "ENTRIES"? Not sure.

k-takata · 2017-07-03T09:52:32Z

man/ctags.1.rst.in

+	Inquire the output of ``--list-extras`` option for the other minor
+	extras.
+
+	A name associated with an extra can be used as alternative to to a


to to -> to

k-takata · 2017-07-03T09:54:46Z

man/ctags.1.rst.in


 	As an example for the C language, in order to add prototypes and
 	external variable declarations to the default set of tag kinds,
 	but exclude macros, use "--c-kinds=+px-d"; to include only tags for
 	functions, use "--c-kinds=f".

+	A name associated with a kind can be used as alternative to to a


to to -> to

k-takata · 2017-07-03T10:03:35Z

man/ctags.1.rst.in

+	REFONLY
+		Whether the kind is specialized for reference tagging or not.
+		If the column is "yes", the kind is for reference tagging, and
+		it is never used for definition tagging. See also "TAG ENTRY".


If you change above, you also need to change this "ENTRY" to "ENTRIES".

k-takata · 2017-07-03T10:13:03Z

main/options.c

 #endif
 #ifdef HAVE_LIBXML
-	"xpath",
+	{"xpath", "linked with library for parsing xml input"},


Out of scope of this PR, but I want to know why this is "xpath" not "xml".

...Good point.

Originally, I wanted to add --xpath-<LANG>=... option like --regex-<LANG>= option; I think it is useful feature that people can create a parser with specifying xpaths.
However, I have not implemented it yet because I cannot find how the option parameters should be.
What I have done is some libxml2 base parser. In the future, when I implement --xpath-<LANG> option, the feature "xpath" is the signed that a ctags binary can accept --xpath option.

masatake · 2017-07-03T11:54:26Z

Updated. Thank you very much.

coveralls · 2017-07-03T11:57:44Z

Coverage decreased (-0.008%) to 85.123% when pulling a91c54f on masatake:man--tag-concept into cd27b61 on universal-ctags:master.

coveralls · 2017-07-04T05:31:08Z

Coverage decreased (-0.008%) to 85.123% when pulling b6e5cdb on masatake:man--tag-concept into cd27b61 on universal-ctags:master.

masatake · 2017-07-04T05:31:57Z

I added one small change.

coveralls · 2017-07-04T05:53:17Z

Coverage decreased (-0.008%) to 85.123% when pulling e290391 on masatake:man--tag-concept into cd27b61 on universal-ctags:master.

masatake · 2017-07-04T12:14:50Z

I also added description about --list-{kinds,extras,fields,roles}, --kinds=, --extras=, --fields=, and --roles.

masatake · 2017-07-04T12:15:34Z

I will write ctags-optlib.5 next.

masatake · 2017-07-04T15:48:39Z

I'm sorry disturbing the branch under your reviewing. It seems that I injected something wrong change in the branch.

coveralls · 2017-07-04T15:59:18Z

Coverage increased (+0.2%) to 85.339% when pulling 8eb82fb on masatake:man--tag-concept into 0645b2c on universal-ctags:master.

coveralls · 2017-07-05T02:15:03Z

Coverage increased (+0.2%) to 85.339% when pulling 730e4b4 on masatake:man--tag-concept into 0645b2c on universal-ctags:master.

coveralls · 2017-07-05T02:29:36Z

Coverage increased (+0.2%) to 85.339% when pulling b5678e3 on masatake:man--tag-concept into 0645b2c on universal-ctags:master.

coveralls · 2017-07-05T02:47:25Z

Coverage increased (+0.2%) to 85.339% when pulling 509f7da on masatake:man--tag-concept into 0645b2c on universal-ctags:master.

masatake · 2017-07-05T03:23:41Z

@KazuakiM, I have a question about the behavior of sed on MacOSX.

In my test harness for ctags, I used following code to report the result of testing:

cat "$f" | sed -e 's|.*|	\0|'

Here $f is a diff file generated by a test case. My intention is that adding a tab character as prefix for printing each line of $f.

This works well on my GNU/Linux:

[jet@localhost]~/var/ctags% cat FOO
abc
efg
[jet@localhost]~/var/ctags% f=FOO; cat $f | sed -e 's|.*|       \0|'
	abc
	efg

However, I cannot get the same expected result on MacOSX running on Travis-CI.
Do you have any idea for making the result on MacOSX as same as that on GNU/Linux?

KazuakiM · 2017-07-05T12:49:54Z

I tried the following case. Both tabs were set to prefix.

$ cat FOO
abc
efg

-- case :  \t
$ f=FOO; cat "$f" | sed -e 's|.*|\t\0|'
        abc
        efg

-- case : tab character
$ f=FOO; cat "$f" | sed -e 's|.*|        \0|'
        abc
        efg

masatake · 2017-07-05T19:08:06Z

@KazuakiM, thank you. Surprisingly, the command line including sed on MacOSX works well as same as hat on GNU/Linux...It seems that there is something special in MacOSX instance running at Travis-CI...

KazuakiM · 2017-07-05T21:57:58Z

@masatake
I'm sorry. I overlooked important things.
I installed gnu-sed at homebrew.
Results of running on sed of Mac are as follows.

$ f=FOO; cat "$f" | sed -e 's|.*|\t\0|'
t0
t0
mabuchikazuaki $ f=FOO; cat "$f" | sed -e 's|.*|        \0|'
        0
        0

KazuakiM · 2017-07-05T22:38:43Z

@masatake
And I set PATH

gnu_sed_prefix=`brew --prefix gnu-sed`
export PATH="$gnu_sed_prefix/libexec/gnubin:$PATH"

masatake · 2017-07-06T02:15:30Z

@KazuakiM, thank you.

Introducing gnu-sed is one of the solution but I would like to understand what happens to
avoid potential mistakes I will take in the future.

How about using & instead of \0?

$ f=FOO; cat "$f" | sed -e 's|.*|        &|'

I would like to try the above command line with the original(build-in?) sed of MacOSX.

masatake · 2017-07-06T04:38:18Z

@k-takata, I'm sorry but could you suspend your reviewing I asked?
This pull request includes code changes and manual-page changes.
If they are a few changes, I think it is o.k. However, now they are many.
So I will split this pull request into two: one for code and another for manual-page.
I already open #1504 as for code. After merging it, I will push --force the change for manual-page parts here.

masatake · 2017-07-06T04:56:58Z

@KazuakiM , I tried & as the replacement of \0 in 19b63ab.

& works well as I expected. Thank you for the cooperation.