/
relit.1
121 lines (121 loc) · 6.75 KB
/
relit.1
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
.\" Harold Thimbleby
.TH relit 1 "26 April 2016"
.hw relit
.SH NAME
relit \- Reverse literate programming tool
.SH SYNOPSIS
.B relit
[\fB-a\fR]
[\fB-f\fR]
[\fB-g\fR]
[\fB-n\fR]
[\fB-s\fR]
[\fB-t\fIarg\fR]
[\fB-u\fR]
[\fB-v\fR]
[\fB-x\fR]
[\fIdefinitions...\fR]
[\fB--\fR]
.IR sourcefilenames...
.SH DESCRIPTION
.B relit
is a 'reverse literate programming' tool. Relit is designed to process LaTeX and TeX files (or potentially troff, etc) and flexibly extract and assemble complete source code and other files. Reverse literate programming encourages putting the entire compilable source code in publishable documents (such as peer reviewed publications), in any suitable order, and perhaps with unit tests and other support (e.g., makefiles) in the same file but hidden from the reader.
.SH OPTIONS
Flags are processed left-to-right, but files can be in any order.
.TP
-a
List all name and file definitions (overrides -n).
.TP
-d
Run for diagnostics only and do not generate or update any files; -d may be used with other options (e.g., -v).
.TP
-f
Force all generated files to be updated (giving you choices on how you use makefiles).
.TP
-g
List all files generated to standard output (overrides -u).
.TP
-n
List all names and files (more concise output than -a).
.TP
-s
List subscript information.
.TP
-t\fIarg\fR
List all commands and tags, line by line. Fields are separated by the -t argument string, or ':' if none is provided explicitly. Intended to be post-processed by a Unix filter, e.g., grep '^generate:.*\.c::1:' will list first lines of all C files (more precisely, files ending in .c) generated with no tags.
.TP
-u
List only changed files to standard output. Note if you use -f and -u together, you get a list of all files generated, whether they are changed or not.
.TP
-v
Verbose mode (show \fBrelit\fR commands as they are processed).
.TP
\fIname\fR=\fIvalue\fR
Define a name. If there are spaces in the \fIvalue\fR it must be enclosed in quote marks.
.TP
--
Treat all subsequent parameters as file names, following the same convention as \fBrm\fR (1). This allows file names like -- etc (should you need them!).
.SH DESCRIPTION
The
.B relit
tool generally processes TeX or LaTeX files. Commands are written either as comments (as text following the % character, so they are completely ignored by LaTeX) or they can be written as ordinary LaTeX commands, which LaTeX (or TeX) can then also process for any further purposes in the usual way. In normal use, \\relit can be defined to disappear, but if the author wishes it can be defined like \\marginpar, so that the author can easily keep track of where relit commands are used. The advantage of the % notation is that it requires no new LaTeX definitions to start using it immediately.
.LP
Definitions and uses of names can be in any order. Names do not need to be defined before they are used. Name definitions are global and do not need to be in the files where they are used.
.LP
% define \fIname\fR \fIre\fR, \fIre\fR [, \fItag\fR]
\fBor\fR
\\relit[\fItag\fR]{define \fIname\fR \fIre\fR, \fIre\fR}
.IP
Define
.I name
to be the following lines that match between the two regular expressions inclusive. The name can be optionally tagged. (In the LaTeX form, if a tag is specified, the square brackets are required.) If the tag is omitted, it is taken from the last %set-tag command; if no tag is required, then 'none' can be used.
.LP
% generate \fIname\fR \fIre\fR, \fIre\fR [, \fItag\fR]
\fBor\fR
\\relit[\fItag\fR]{generate \fIname\fR \fIre\fR, \fIre\fR}
.IP
Generate a file called
.I name
to be the following lines that match between the two regular expressions inclusive. If the file already exists, it is only updated if its contents are changed (but see -f flag above).
.LP
Within the text matched for %define and %generate, names of the form <\fIname\fR> are expanded by their definitions.
.LP
There is only one name space, so a file name can be used as an ordinary name (i.e., in the form <\fIfilename\fR> in the body of a %define or %generate) as well. This allows generated files to be built up from both defines and from other files.
.LP
Both %define and %generate commands can be used in normal text or hidden (e.g., after the \\end{document}) or in files that are only processed by \fBrelit\fR. Note that it would be unusual to use variable names (e.g., <n>) except in hidden parts of a document (or files that are not typeset), since names are only expanded when files are generated \(em the original text is never changed by \fBrelit\fR.
.LP
With both %define and %generate, names can have # subscripts. For each distinct name, a # is replaced by a subscript counter. So %generate f#.txt ..., %generate f#.txt will actually generate files called f1.txt and f2.txt, etc. (Note that f# and #f are different names, generating f1, f2, f3... and 1f, 2f, 3f... respectively.)
.LP
% set-tag \fIvalue\fR
\fBor\fR
\\relit{set-tag \fIvalue\fR}
.IP
Define a default tag for any subsequent %defines or %generates without an explicit tag. A tag value can
include <\fInames\fR>, so by using <\fIname\fR> as a tag, the name, and hence the tag, can be set in the command line. Default tags can be changed (or cleared if set to 'none') using %set-tag repeatedly as required.
.PP
Where \fIre\fR can have the form:
.TP
\&.
Match the current line (i.e., if the first \fIre\fR, the immediately next line after the % command, and if the second \fIre\fR, the line the first \fIre\fR matches). Hence the pair .,. means the next line. However, in the case of the \\relit command form, the first . includes all text from the closing } to the end of line: hence .+1,. would mean the next line.
.TP
/ \fIregular expression\fR /
Match the regular expression, starting the search on the line the meaning of '.' (see above). See \fBre_format\fR (7).
.LP
REs can be followed by +\fInumber\fR or -\fInumber\fR, to adjust the line match.
.SH EXAMPLE
.nf
%generate t.c /demo/, /define/-1
<demo>
%define demo ., /Hello/, Boo!
Hello world
.fi
.PP
will create a file t.c containing "Hello world" and a file t.c-tagged.txt (which would not be created if there were no tags) containing "Boo!Hello world".
.PP
Typically, a %generate command, placed after LaTeX's \\end{document}, will be used to create a makefile to keep track of how to make, compile and unit test the source code files. Typically, tags will be \\seen{} and \\unseen{}, appropriately defined.
.SH BUGS
Regular expressions cannot contain '/' (or '}' in the \\relit form)
.PP
The fixed strings, and % and \\relit in particular, cannot be changed (it might be nice to be able to process files using other conventions, such as makefiles or C programs, too). If \\relit is used after a %, it is not ignored. It is easy enough to fix everything in the C source for \fBrelit\fR, as it is simply based on regular expressions.
.SH AUTHOR
Harold Thimbleby, harold@thimbleby.net, 2016 on.