path: root/rxhv.1.s

.ta T 8
.TH rxhv 1

.SH NAME

rxhv - flashcards quiz

.SH SYNOPSIS

.nf
\fBrxhv\fR [\fIoptions\fR] \fIfile\fR... 
\fBrxhv\fR \fB--help\fR|\fB--version\fR
.fi

.SH DESCRIPTION

\fBrxhv\fR filters flashcards in \fIfile\fRs scheduled to be tested
earlier than or within today (see the \fB-e\fR option).
\fBrxhv\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

\fBrxhv\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. 

\fBrxhv\fR prints the content of the \fBQ\fR field.
The user tries to recall the corresponding \fBA\fR field
and asks \fBrxhv\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 rxhv(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 \fBrxhv\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,
\fBrxhv\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 \fBrxhv --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://git.runxiyu.org/runxiyu/current/rxhv.git>.

.SH AUTHORS

HardV was created by DONG Yuxuan <https://www.dyx.name> in 2022.
Runxi Yu <https://runxiyu.org> forked it into rxhv in 2024.