Skip to content

Commit b0d414e

Browse files
committed
fixup! add ctags-lang-julia manpage
1 parent d61021e commit b0d414e

File tree

6 files changed

+252
-0
lines changed

6 files changed

+252
-0
lines changed

Makefile.am

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -220,6 +220,7 @@ man_MANS = \
220220
man/ctags-incompatibilities.7 \
221221
man/ctags-optlib.7 \
222222
\
223+
man/ctags-lang-julia.7 \
223224
man/ctags-lang-python.7 \
224225
man/ctags-lang-verilog.7 \
225226
man/ctags-lang-inko.7 \

configure.ac

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -759,6 +759,7 @@ AC_CONFIG_FILES([Makefile
759759
man/ctags-client-tools.7.rst
760760
man/ctags-incompatibilities.7.rst
761761
man/ctags-optlib.7.rst
762+
man/ctags-lang-julia.7.rst
762763
man/ctags-lang-python.7.rst
763764
man/ctags-lang-verilog.7.rst
764765
man/ctags-lang-inko.7.rst

docs/man-pages.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ Man pages
1010
ctags(1) <man/ctags.1.rst>
1111
ctags-client-tools(7) <man/ctags-client-tools.7.rst>
1212
ctags-incompatibilities(7) <man/ctags-incompatibilities.7.rst>
13+
ctags-lang-julia(7) <man/ctags-lang-julia.7.rst>
1314
ctags-lang-python(7) <man/ctags-lang-python.7.rst>
1415
ctags-lang-verilog(7) <man/ctags-lang-verilog.7.rst>
1516
ctags-lang-inko(7) <man/ctags-lang-inko.7.rst>

docs/man/ctags-lang-julia.7.rst

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
.. _ctags-lang-julia(7):
2+
3+
==============================================================
4+
ctags-lang-julia
5+
==============================================================
6+
-------------------------------------------------------------------
7+
Random notes about tagging Julia source code with Universal-ctags
8+
-------------------------------------------------------------------
9+
:Version: 5.9.0
10+
:Manual group: Universal-ctags
11+
:Manual section: 7
12+
13+
SYNOPSIS
14+
--------
15+
| **ctags** ... --languages=+Julia ...
16+
| **ctags** ... --language-force=Julia ...
17+
| **ctags** ... --map-Julia=+.jl ...
18+
19+
DESCRIPTION
20+
-----------
21+
This man page gathers random notes about tagging Julia source code.
22+
23+
TAGGING ``import`` AND ``using`` EXPRESSIONS
24+
--------------------------------------------
25+
26+
Summary
27+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
28+
29+
`using X`
30+
31+
==== ========== ================== ===================
32+
name kind role other noticeable fields
33+
==== ========== ================== ===================
34+
X module used N/A
35+
==== ========== ================== ===================
36+
37+
`using X: a, b`
38+
39+
==== ========== ================== ===================
40+
name kind role other noticeable fields
41+
==== ========== ================== ===================
42+
X module namespace N/A
43+
a, b unknown used scope:module:X
44+
==== ========== ================== ===================
45+
46+
`import X`
47+
48+
==== ========== ================== ===================
49+
name kind role other noticeable fields
50+
==== ========== ================== ===================
51+
X module imported N/A
52+
==== ========== ================== ===================
53+
54+
`import X.a, Y.b`
55+
56+
==== ========== ================== ===================
57+
name kind role other noticeable fields
58+
==== ========== ================== ===================
59+
X, Y module namespace N/A
60+
a unknown imported scope:module:X
61+
b unknown imported scope:module:Y
62+
==== ========== ================== ===================
63+
64+
`import X: a, b`
65+
66+
==== ========== ================== ===================
67+
name kind role other noticeable fields
68+
==== ========== ================== ===================
69+
X module namespace N/A
70+
a,b unknown imported scope:module:X
71+
==== ========== ================== ===================
72+
73+
Examples
74+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
75+
"input.jl"
76+
77+
.. code-block:: Julia
78+
79+
using X0
80+
81+
"output.tags"
82+
with "--options=NONE -o - --extras=+r --fields=+rzK input.jl"
83+
84+
.. code-block:: tags
85+
86+
X0 input.jl /^using X$/;" kind:module roles:used
87+
88+
``--extras=+r`` (or ``--extras=+{reference}``) option is needed for this tag,
89+
since it's a reference tag. This is because module ``X`` is not defined here.
90+
It is defined in another file. Enable ``roles:`` field with ``--fields=+r`` is
91+
for recording that the module is "used", i.e., loaded by ``using``.
92+
93+
"input.jl"
94+
95+
.. code-block:: Julia
96+
97+
import X1.a, X2.b, X3
98+
99+
"output.tags"
100+
with "--options=NONE -o - --extras=+r --fields=+rzKZ input.jl"
101+
102+
.. code-block:: tags
103+
104+
X1 julia-example.jl /^import X1.a, X2.b, X3$/;" kind:module roles:namespace
105+
X2 julia-example.jl /^import X1.a, X2.b, X3$/;" kind:module roles:namespace
106+
X3 julia-example.jl /^import X1.a, X2.b, X3$/;" kind:module roles:imported
107+
a julia-example.jl /^import X1.a, X2.b, X3$/;" kind:unknown scope:module:X1 roles:imported
108+
b julia-example.jl /^import X1.a, X2.b, X3$/;" kind:unknown scope:module:X2 roles:imported
109+
110+
Why ``X1`` and ``X2`` have role "namespace", while ``X3`` have role "imported"?
111+
It's because the symbol ``a`` in module ``X1``, and ``b`` in module ``X2`` are
112+
brought to the current scope, but ``X1`` and ``X2`` themselves are not. We use
113+
"namespace" role for such modules.
114+
115+
``X3`` is different. The symbol ``X3``, together with all exported symbols in
116+
``X3``, is brought to current scope. For such modules, we use "imported" or
117+
"used" role depending whether they are loaded by ``import`` or ``using``.
118+
119+
Also, notice that ``a`` and ``b`` have the "unknown" kind. This is because we
120+
cannot know whether it's a function, constant, or macro, etc.
121+
122+
SEE ALSO
123+
--------
124+
:ref:`ctags(1) <ctags(1)>`, :ref:`ctags-client-tools(7) <ctags-client-tools(7)>`

man/Makefile

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ IN_SOURCE_FILES = \
4747
ctags-incompatibilities.7.rst.in \
4848
ctags-client-tools.7.rst.in \
4949
\
50+
ctags-lang-julia.7.rst.in \
5051
ctags-lang-python.7.rst.in \
5152
ctags-lang-verilog.7.rst.in \
5253
ctags-lang-inko.7.rst.in \

man/ctags-lang-julia.7.rst.in

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
.. _ctags-lang-julia(7):
2+
3+
==============================================================
4+
ctags-lang-julia
5+
==============================================================
6+
-------------------------------------------------------------------
7+
Random notes about tagging Julia source code with Universal-ctags
8+
-------------------------------------------------------------------
9+
:Version: @VERSION@
10+
:Manual group: Universal-ctags
11+
:Manual section: 7
12+
13+
SYNOPSIS
14+
--------
15+
| **@CTAGS_NAME_EXECUTABLE@** ... --languages=+Julia ...
16+
| **@CTAGS_NAME_EXECUTABLE@** ... --language-force=Julia ...
17+
| **@CTAGS_NAME_EXECUTABLE@** ... --map-Julia=+.jl ...
18+
19+
DESCRIPTION
20+
-----------
21+
This man page gathers random notes about tagging Julia source code.
22+
23+
TAGGING ``import`` AND ``using`` EXPRESSIONS
24+
--------------------------------------------
25+
26+
Summary
27+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
28+
29+
`using X`
30+
31+
==== ========== ================== ===================
32+
name kind role other noticeable fields
33+
==== ========== ================== ===================
34+
X module used N/A
35+
==== ========== ================== ===================
36+
37+
`using X: a, b`
38+
39+
==== ========== ================== ===================
40+
name kind role other noticeable fields
41+
==== ========== ================== ===================
42+
X module namespace N/A
43+
a, b unknown used scope:module:X
44+
==== ========== ================== ===================
45+
46+
`import X`
47+
48+
==== ========== ================== ===================
49+
name kind role other noticeable fields
50+
==== ========== ================== ===================
51+
X module imported N/A
52+
==== ========== ================== ===================
53+
54+
`import X.a, Y.b`
55+
56+
==== ========== ================== ===================
57+
name kind role other noticeable fields
58+
==== ========== ================== ===================
59+
X, Y module namespace N/A
60+
a unknown imported scope:module:X
61+
b unknown imported scope:module:Y
62+
==== ========== ================== ===================
63+
64+
`import X: a, b`
65+
66+
==== ========== ================== ===================
67+
name kind role other noticeable fields
68+
==== ========== ================== ===================
69+
X module namespace N/A
70+
a,b unknown imported scope:module:X
71+
==== ========== ================== ===================
72+
73+
Examples
74+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
75+
"input.jl"
76+
77+
.. code-block:: Julia
78+
79+
using X0
80+
81+
"output.tags"
82+
with "--options=NONE -o - --extras=+r --fields=+rzK input.jl"
83+
84+
.. code-block:: tags
85+
86+
X0 input.jl /^using X$/;" kind:module roles:used
87+
88+
``--extras=+r`` (or ``--extras=+{reference}``) option is needed for this tag,
89+
since it's a reference tag. This is because module ``X`` is not defined here.
90+
It is defined in another file. Enable ``roles:`` field with ``--fields=+r`` is
91+
for recording that the module is "used", i.e., loaded by ``using``.
92+
93+
"input.jl"
94+
95+
.. code-block:: Julia
96+
97+
import X1.a, X2.b, X3
98+
99+
"output.tags"
100+
with "--options=NONE -o - --extras=+r --fields=+rzKZ input.jl"
101+
102+
.. code-block:: tags
103+
104+
X1 julia-example.jl /^import X1.a, X2.b, X3$/;" kind:module roles:namespace
105+
X2 julia-example.jl /^import X1.a, X2.b, X3$/;" kind:module roles:namespace
106+
X3 julia-example.jl /^import X1.a, X2.b, X3$/;" kind:module roles:imported
107+
a julia-example.jl /^import X1.a, X2.b, X3$/;" kind:unknown scope:module:X1 roles:imported
108+
b julia-example.jl /^import X1.a, X2.b, X3$/;" kind:unknown scope:module:X2 roles:imported
109+
110+
Why ``X1`` and ``X2`` have role "namespace", while ``X3`` have role "imported"?
111+
It's because the symbol ``a`` in module ``X1``, and ``b`` in module ``X2`` are
112+
brought to the current scope, but ``X1`` and ``X2`` themselves are not. We use
113+
"namespace" role for such modules.
114+
115+
``X3`` is different. The symbol ``X3``, together with all exported symbols in
116+
``X3``, is brought to current scope. For such modules, we use "imported" or
117+
"used" role depending whether they are loaded by ``import`` or ``using``.
118+
119+
Also, notice that ``a`` and ``b`` have the "unknown" kind. This is because we
120+
cannot know whether it's a function, constant, or macro, etc.
121+
122+
SEE ALSO
123+
--------
124+
ctags(1), ctags-client-tools(7)

0 commit comments

Comments
 (0)