-
Notifications
You must be signed in to change notification settings - Fork 3
/
hardv.1.s
293 lines (221 loc) · 6.76 KB
/
hardv.1.s
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
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
.ta T 8
.TH hardv 1
.SH NAME
hardv - flashcards quiz
.SH SYNOPSIS
.nf
\fBhardv\fR [\fIoptions\fR] \fIfile\fR...
\fBhardv\fR \fB--help\fR|\fB--version\fR
.fi
.SH DESCRIPTION
\fBhardv\fR filters flashcards in \fIfile\fRs scheduled to be tested
earlier than or within today (see the \fB-e\fR option).
\fBhardv\fR runs a quiz with these flashcards,
and updates their schedules.
The format of \fIfile\fR is demonstrated below.
The key and value of a field is separated by a tab character.
Subsequent lines in the value are indented by a tab character.
See the \fIINPUT FORMAT\fR section for detail.
.RS
.nf
Q hex(128) = ?
A 0x80
%%
Q hex(32768) = ?
A 0x8000
%%
Q the most famous C program from K&R, second edition
A #include <stdio.h>
main()
{
printf("hello world\\n");
}
.fi
.RE
\fBhardv\fR may insert other fields after running,
to record metadata.
.SH STANDARD QUIZ PROCEDURE
If the card doesn't contain the \fBMOD\fR field,
the standard quiz procedure is used.
\fBhardv\fR prints the content of the \fBQ\fR field.
The user tries to recall the corresponding \fBA\fR field
and asks \fBhardv\fR to print it.
There are three actions for a card the user can execute.
.TP
1. \fBy\fR
The user is able to recall the content;
The next quiz time for this card will be scheduled at the double further
time.
Formally speaking, the new value of the \fBNEXT\fR field will be set to:
\fISTART_TIME\fR + 2*(\fINEXT\fR - \fIPREV\fR)
If \fINEXT\fR - \fIPREV\fR is less than 24 hours,
it will be reset to 24 hours.
.TP
2. \fBn\fR
The user is not able to recall the content;
The next quiz time for this card will be scheduled at 24 hours later
after the start time of the current quiz.
.TP
3. \fBs\fR
Skip the card;
Nothing will be updated.
.SH CUSTOMIZED QUIZ PROCEDURE
If the card contains the \fBMOD\fR field,
the customized quiz procedure is used.
The value of the \fBMOD\fR field is executed by \fB/bin/sh -c\fR,
with several environment variables set:
.TP
\fBHARDV_F_\fIkey\fR
The original content (not normalized) of the \fIkey\fR field.
.TP
\fBHARDV_Q\fR
the normalized content of the \fBQ\fR field
.TP
\fBHARDV_A\fR
the normalized content of the \fBA\fR field
.TP
\fBHARDV_PREV\fR
the \fBPREV\fR field in the form of the seconds since the Epoch
.TP
\fBHARDV_NEXT\fR
the \fBNEXT\fR field in the form of the seconds since the Epoch
.TP
\fBHARDV_NOW\fR
the quiz starting time in the form of the seconds since the Epoch
.TP
\fBHARDV_FIRST\fR
If the card is the first quizzed card in the current quiz,
it is set to \fB1\fR.
Otherwise, it's set to the empty string.
.RE
The normalized content is the content without
leading newlines, trailing newlines, and indent tabs.
The original content of each field is stored in \fBHARDV_F_\fIkey\fR.
For example,
the original content of the \fBQ\fR field
can be accessed by \fBHARDV_F_Q\fR.
If the mod script exits with status \fB0\fR, the effect is equivalent to
take the \fBy\fR action in the standard quiz procedure.
If the mod script exits with status \fB1\fR, the effect is equivalent to
take the \fBn\fR action in the standard quiz procedure.
Otherwise, the effect is equivalent to
take the \fBs\fR action in the standard quiz procedure.
.SH INPUT FORMAT
A card is a key-value structure contains at least two fields \fBQ\fR
and \fBA\fR.
The \fBQ\fR field represents the front side of a physical card.
It's usually a question or a clue.
The \fBA\fR field represents the back side of a physical card.
It's usually the answer or information regarding the \fBQ\fR field.
The key and the value are separated by a tab character or a newline
character.
Every line in the value which is not on the same line with the key
must start with a tab character, except for blank lines.
For blank lines in the value, the leading tab character is optional.
Cards are separated by a line starting with the percent sign (\fB%\fR).
\fB%%\fR on a line by it self is recommended.
Empty cards are ignored.
Thus separators can be used as comments,
demonstrated by the following.
.RS
.nf
%% This is a card set for hardv(1)
%% Created at Feb 1, 1997
Q hex(256) = ?
A 0x100
%%
Q hex(128) = ?
A 0x80
%% Arithmetic cards begin
Q 1 + 1 = ?
A 2
%%
Q 8 - 5 = ?
A 3
%% Arithmetic cards end
.fi
.RE
After a card is quizzed with \fBhardv\fR, two fields \fBPREV\fR and
\fBNEXT\fR are updated (or inserted if they didn't exist) to indicate
the previous quiz time and the next scheduled quiz time,
demonstrated by the following.
.RS
.nf
NEXT 2001-08-21 15:31:06 -0500
PREV 2001-08-23 15:31:06 -0500
Q 1 + 1 = ?
A 2
.fi
.RE
You could modify the \fBPREV\fR and \fBNEXT\fR fields to manually tune
the quiz time.
If the card doesn't contain the \fBPREV\fR field,
it will be reset to the start time of the current quiz.
If the card doesn't contain the \fBNEXT\fR field,
it will be reset to the start time of the current quiz.
Both \fBPREV\fR and \fBNEXT\fR are required to be later than
\fB1970-01-01 00:00:00 +0000\fR.
A card is allowed to contain other fields not mentioned above, as long
as the key consists of alphabets, digits and underlines.
However, field keys consisting of only uppercase alphabets are reserved
for the system.
They are allowed but not recommended, for specific meanings could be
assigned to them in further versions.
.SH OPTIONS
.TP
\fB-e
Quiz a card only if the start time of the quiz is not earlier
than the exact scheduled quiz time of the card;
If this option is not specified, any card whose scheduled quiz time
is earlier than or within today will be quizzed.
.TP
\fB-r
Quiz cards in a random order.
.TP
\fB-n \fIn\fR
Quiz at most \fIn\fR cards.
.TP
\fB--help
Print the brief help message.
This option shall appear alone.
.TP
\fB--version
Print the version and building arguments.
This option shall appear alone.
.SH ENVIRONMENT
.TP
\fBHARDV_NOW\fR
If this environment variable is set,
\fBhardv\fR uses it as the quiz starting time,
instead of the current system time.
The format of this variable is the same as of
the \fBPREV\fR and \fBNEXT\fR fields.
.SH LIMITATION
Calling \fBhardv --version\fR prints several building arguments
which determine the limitation of data.
.TP
\fBNLINE\fR
The number of lines in an input file can't exceed \fBNLINE\fR.
.TP
\fBLINESZ
A line in input files must be less than \fBLINESZ\fR bytes.
.TP
\fBNCARD\fR
The number of cards in an input file can't exceed \fBNCARD\fR.
This limitation is only enabled while the \fB-d\fR option is specified.
.TP
\fBNFIELD\fR
The number of fields in a card can't exceed \fBNFIELD\fR.
.TP
\fBKEYSZ\fR
The field key must be less than \fBKEYSZ\fR bytes.
.TP
\fBVALSZ\fR
The field value must be less than \fBVALSZ\fR bytes.
.TP
\fBPATHSZ\fR
The path of \fIfile\fR must be less than \fBPATHSZ\fR bytes.
.SH FURTHER DOCUMENTATION
See <https://github.com/dongyx/hardv>.
.SH AUTHORS
HardV was created by DONG Yuxuan <https://www.dyx.name> in 2022.