about summary refs log tree commit diff
path: root/www/text.causal.agency/015-reusing-tags.7
blob: 19546496e210488f7d26d86c95d164d61fa33951 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
.Dd January 17, 2021
.Dt REUSING-TAGS 7
.Os "Causal Agency"
.
.Sh NAME
.Nm reusing tags
.Nd beyond ctags
.
.Sh DESCRIPTION
I've tried to start writing this post a couple times now
and I keep getting bogged down in explanations,
so I'm just going to tell you
about some cool things I did
and hope they make sense.
.
.Pp
When I wrote my first syntax highlighter,
I decided that function definitions
should have anchor links,
because line number anchor links
are entirely useless
if you expect the file to change at all.
Since the syntax highlighter
was somewhat deliberately just a big pile of regex,
I hacked in more regex to try
to identify function and type definitions.
It wasn't elegant and it didn't always work well.
It did work though,
and I found the links very useful.
.
.Pp
Recently I was thinking about
the lexer generator
.Xr lex 1
and decided to
rewrite the syntax highlighter
using it.
Really syntax highlighting
is no different than lexical analysis.
I ran into a problem though,
trying to preserve my anchor link function,
because really that should involve
some amount of parsing.
Trying to port my regex hacks to
.Xr lex 1
made the lexers way more complicated
and less reliable,
so I gave up on it for a while.
.
.Pp
And then,
probably in the shower,
I realized I was approaching it
completely from the wrong direction.
There's already a tool that does what I want,
and I already use it:
.Xr ctags 1 .
All I need to do is use its output
to insert anchor links
into my syntax highlighter output.
In an afternoon I wrote
.Xr htagml 1 ,
which loads tag definitions for its input file,
then scans through the input for where they match.
It can either HTML-escape
the input as it goes,
or use already formatted HTML
being piped into it from a syntax highlighter.
.
.Pp
The result is three simple tools
working together to accomplish
what a more complex tool
couldn't reliably achieve.
I'm very pleased with it,
and I've updated my site and cgit
to use the new
.Xr lex 1 Ns -based
highlighter,
.Xr ctags 1
and
.Xr htagml 1 .
I'm currently missing a lexer for
.Xr sh 1 ,
but I plan to write it eventually.
I also want to write a tool
to generate tags for
.Xr make 1 ,
.Xr mdoc 7
and perhaps
.Xr sh 1 .
The cool thing about generating more kinds of tags
is that they'll not only improve
the HTML output,
they'll also be usable in my editor.
.
.Pp
Speaking of generating different kinds of tags,
I also wrote some scripts not too long ago
for reading IETF RFCs offline.
The plain text files are available to
.Xr rsync 1 ,
but they're hard to navigate on their own.
By scanning the files for headings
and generating tags,
it allows jumping to sections using
.Ic :ta
or
.Ic ^]
in
.Xr vi 1 .
For
.Xr nvim 1
I also added an
.Ic :RFC
command to open an RFC by number
and set up
.Ic ^]
to work optimally for them.
.
.Pp
I'm still using
.Xr vi 1
for most of my editing,
by the way.
And of course
.Xr ctags 1
was made to work with it!
Simple old tools
are really doing it for me lately.
.
.Sh SEE ALSO
.Bl -item -compact
.It
.Lk https://causal.agency/bin/htagml.html htagml
.It
.Lk https://causal.agency/bin/hilex.html hilex
.It
.Lk https://git.causal.agency/src/tree/doc/rfc rfctags
.El
.
.Sh AUTHORS
.An june Aq Mt june@causal.agency
.
.Sh ADDENDUM
.Xr catgirl 1 ,
.Xr pounce 1 ,
.Xr litterbox 1
and
.Xr scooper 1
all have new releases,
if you're using any of them.
Also, this space is now
available over gopher,
if that's your sort of thing.