Update the docs: extending.rst and optlib.rst sections #1826

hadrielk · 2018-08-14T06:11:52Z

This is a first pass at updating the optlib.rst doc (and minor stuff for extending.rst).
There's still more to do, but I thought this is a big enough change to get some feedback on.
There are also a few open questions I had, which I added as comments in optlib.rst, marked .. Q:.
Feedback would be great. Even if it's: "this is crap".

coveralls · 2018-08-14T06:20:18Z

Coverage remained the same at 84.433% when pulling b40096f on hadrielk:hadriel/docs-optlib into a0206b0 on universal-ctags:master.

hadrielk · 2018-08-24T04:05:57Z

Any comments/issues with this PR? If not I'd like to merge it in. (I have more things to add to optlib.rst but don't want a conflict with this PR)

masatake · 2018-08-24T13:43:52Z

Could you wait till next week?

hadrielk · 2018-08-24T15:09:27Z

Could you wait till next week?

Sure, of course.

masatake · 2018-08-29T11:45:22Z

I will concentrate on this important PR.

masatake

Thank you very much for updating this document.
I have one request. I don't remove the sentence about the cork API.

I wonder why you put python and/or perl after .. code-block::. I don't want to use it just for highlighting regex patterns.

I'm thinking about extending rst parser to run another parser inside code blocks.
If we use .. code-block::ctags, the rst parser can schedule to run ctags optlib parser to the blocks.

Anyway, thank again.

masatake · 2018-09-02T17:54:27Z

docs/optlib.rst

 passed in command line.

 Following file is an example of option file.

-.. code-block::
+.. code-block:: python


Why python?

I don't remember for this particular code block, but I generated the HTML for each of them while trying various highlighters sphinx/pygment/whatever has built-in support for, and picked the ones that looked the best.

I remember now - when you build the docs into html, you get warnings if the code-block language highlighting fails. For this particular code block, perl failed but python worked while still looking ok.

masatake · 2018-09-02T17:57:17Z

docs/optlib.rst

@@ -81,98 +103,101 @@ Quoted from man page of Exuberant-ctags::
 				  use new lines to indicate separate command-line
 				  arguments.

-Let me explain the differences and their intentions.
+What follows explains the differences and their intentions...



I wonder ... is needed here. Just . is not enough?

Just a single dot . is enough - using three is less formal, and not necessary.

masatake · 2018-09-02T18:02:55Z

docs/optlib.rst

-e           extend
-i           icase
-=========== ===========
+.. code-block:: perl


Should we use perl here?
For highlighting the regex patterns?

It shows fairly nicely in the generated HTML.

masatake · 2018-09-02T18:08:19Z

docs/optlib.rst


-NOTE: Giving a scope long flag implies setting `useCork` of the parser
-to `TRUE`. See `cork API`.


Could keep the above sentence about cork ?
I think the sentence helps a developer understand u-ctags internal.

But an optlib developer (i.e., a person who creates optlib files) does not need to know anything about it, and will be confused why they should care. I mean it's just an internal implementation detail, like setting the parserDefinition.method flag METHOD_REGEX. No?

This is an example of something that confused me when reading the doc the first time: who's the target audience? Is it general users of ctags and authors of optlib files, or is it for C-code developers?

Though I have not written well as I expect, this document is for rather C-code developers.

I assume optlib developers (== general users) read ctags-optlib.7 man page.
I will write more about this topic in #1835.

masatake · 2018-09-02T18:13:18Z

docs/optlib.rst


+.. Q: this was fixed in https://github.com/universal-ctags/ctags/pull/331
+	so can we remove this section?
+


Yes, we can remove this section because I wrote this to man/ctags-incompatibilities.7.rst.in.
I marked .. IN MAN PAGE when I wrote the topic to our man pages.
In the case, we can remove it. I planed removing all the marked topic when releasing 6.0.
However, you can remove some of them now.

masatake · 2018-09-02T18:27:45Z

docs/optlib.rst

+	That name seems like an internal detail. Users of ctags never see that
+	name anywhere except in these docs, and it's weird. How about
+	"specified" option files, or "requested" or some such? (i.e., the file
+	is explicitly specified or requested when ctags is run)


I agree.

The idea behind the term "optlib" is written at the head of man/ctags-optlib.7.rst.in.

masatake · 2018-09-02T18:33:26Z

docs/optlib.rst

+
+.. Q: why even discuss the single-character version of the flags? Just
+	make everyone use the long form.
+


I don't have strong reason.
The single character version (letter version) like i may be still used by users.
It is still useful if a flag is still appears frequently in a .ctags file.

masatake · 2018-09-02T18:36:31Z

docs/optlib.rst

-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+......................................................................
+
+.. Q: what is the point of documenting this?



We should remove this section.

masatake · 2018-09-02T18:45:30Z

docs/optlib.rst

+	start position of the whole regex pattern). You do not need to add it for
+	the multi-table ``--_mtable-regex-<LANG>``.
+
+.. Q: isn't the above restriction really a bug? I think it is. I should fix it.


Yes, it looks a bug.
Can I ask you to open an issue with an example (or .b unit test).

masatake · 2018-09-02T18:48:24Z

docs/optlib.rst


+.. Q: this was previously titled "Byte oriented pattern matching...", presumably
+	because it "matched against the input at the current byte position, not line".
+	But that's also true for --mline-regex-<LANG>, as far as I can tell.


Yes. I agree.

hadrielk · 2018-09-02T22:10:30Z

I wonder why you put python and/or perl after .. code-block::. I don't want to use it just for highlighting regex patterns.

Yes it was mostly for highlighting the regex, but also it makes the # comments look like comments (makes them light gray), and generally looks better than nothing. (I even use perl syntax highlighting for .ctags files I edit, in my editor)
Oh, and it got rid of warning messages generated when you build the docs.

I'm thinking about extending rst parser to run another parser inside code blocks. If we use .. code-block::ctags, the rst parser can schedule to run ctags optlib parser to the blocks

Yes, a pygment or whatever parser for ctags optlib format in rst files would be really nice!

masatake · 2018-09-03T03:00:26Z

I will make a reply for #1835 first.

masatake · 2018-09-03T15:19:51Z

@hadrielk, could make a separated commit for changing the .. code-block: lines?
So we can know the intention of the change.

masatake · 2018-09-15T16:51:34Z

Though I made some comments, I will merge this; the change makes the document much better.

masatake · 2018-09-15T16:51:54Z

Thank you very much.

Update the docs: extending.rst and optlib.rst sections

b40096f

masatake self-requested a review August 14, 2018 06:16

hadrielk added the Documentation label Aug 17, 2018

This was referenced Aug 24, 2018

Add options/flags to help users develop multi-table regex parsers #1856

Closed

optlib: Add option/flags to help users develop multi-table regex parsers #1857

Merged

masatake requested changes Sep 2, 2018

View reviewed changes

masatake merged commit 6912b52 into universal-ctags:master Sep 15, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update the docs: extending.rst and optlib.rst sections #1826

Update the docs: extending.rst and optlib.rst sections #1826

hadrielk commented Aug 14, 2018

coveralls commented Aug 14, 2018

hadrielk commented Aug 24, 2018

masatake commented Aug 24, 2018

hadrielk commented Aug 24, 2018

masatake commented Aug 29, 2018

masatake left a comment

masatake Sep 2, 2018

hadrielk Sep 2, 2018

hadrielk Sep 2, 2018

masatake Sep 2, 2018

hadrielk Sep 2, 2018

masatake Sep 2, 2018

hadrielk Sep 2, 2018

masatake Sep 2, 2018

hadrielk Sep 2, 2018

masatake Sep 3, 2018

masatake Sep 2, 2018

masatake Sep 2, 2018

masatake Sep 2, 2018

masatake Sep 2, 2018

masatake Sep 2, 2018

masatake Sep 2, 2018

hadrielk commented Sep 2, 2018

masatake commented Sep 3, 2018

masatake commented Sep 3, 2018

masatake commented Sep 15, 2018

masatake commented Sep 15, 2018


		NOTE: Giving a scope long flag implies setting `useCork` of the parser
		to `TRUE`. See `cork API`.


		.. Q: this was fixed in https://github.com/universal-ctags/ctags/pull/331
		so can we remove this section?


		.. Q: why even discuss the single-character version of the flags? Just
		make everyone use the long form.

Update the docs: extending.rst and optlib.rst sections #1826

Update the docs: extending.rst and optlib.rst sections #1826

Conversation

hadrielk commented Aug 14, 2018

coveralls commented Aug 14, 2018

hadrielk commented Aug 24, 2018

masatake commented Aug 24, 2018

hadrielk commented Aug 24, 2018

masatake commented Aug 29, 2018

masatake left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hadrielk commented Sep 2, 2018

masatake commented Sep 3, 2018

masatake commented Sep 3, 2018

masatake commented Sep 15, 2018

masatake commented Sep 15, 2018