Debian Codegraph @

texmf-dist/doc/man/man1/srcredact.1

raw
1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
6 .if t .sp .5v
7 .if n .sp
8 ..
9 .de Vb \" Begin verbatim text
10 .ft CW
11 .nf
12 .ne \\$1
13 ..
14 .de Ve \" End verbatim text
15 .ft R
16 .fi
17 ..
18 .\" Set up some character translations and predefined strings. \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
21 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
24 .tr \(*W-
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26 .ie n \{\
27 . ds -- \(*W-
28 . ds PI pi
29 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31 . ds L" ""
32 . ds R" ""
33 . ds C` ""
34 . ds C' ""
35 'br\}
36 .el\{\
37 . ds -- \|\(em\|
38 . ds PI \(*p
39 . ds L" ``
40 . ds R" ''
41 'br\}
42 .\"
43 .\" Escape single quotes in literal strings from groff's Unicode transform.
44 .ie \n(.g .ds Aq \(aq
45 .el .ds Aq '
46 .\"
47 .\" If the F register is turned on, we'll generate index entries on stderr for
48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
49 .\" entries marked with X<> in POD. Of course, you'll have to process the
50 .\" output yourself in some meaningful fashion.
51 .ie \nF \{\
52 . de IX
53 . tm Index:\\$1\t\\n%\t"\\$2"
54 ..
55 . nr % 0
56 . rr F
57 .\}
58 .el \{\
59 . de IX
60 ..
61 .\}
62 .\"
63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64 .\" Fear. Run. Save yourself. No user-serviceable parts.
65 . \" fudge factors for nroff and troff
66 .if n \{\
67 . ds #H 0
68 . ds #V .8m
69 . ds #F .3m
70 . ds #[ \f1
71 . ds #] \fP
72 .\}
73 .if t \{\
74 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75 . ds #V .6m
76 . ds #F 0
77 . ds #[ \&
78 . ds #] \&
79 .\}
80 . \" simple accents for nroff and troff
81 .if n \{\
82 . ds ' \&
83 . ds ` \&
84 . ds ^ \&
85 . ds , \&
86 . ds ~ ~
87 . ds /
88 .\}
89 .if t \{\
90 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
96 .\}
97 . \" troff and (daisy-wheel) nroff accents
98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105 .ds ae a\h'-(\w'a'u*4/10)'e
106 .ds Ae A\h'-(\w'A'u*4/10)'E
107 . \" corrections for vroff
108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
110 . \" for low resolution devices (crt and lpr)
111 .if \n(.H>23 .if \n(.V>19 \
112 \{\
113 . ds : e
114 . ds 8 ss
115 . ds o a
116 . ds d- d\h'-1'\(ga
117 . ds D- D\h'-1'\(hy
118 . ds th \o'bp'
119 . ds Th \o'LP'
120 . ds ae ae
121 . ds Ae AE
122 .\}
123 .rm #[ #] #H #V #F C
124 .\" ========================================================================
125 .\"
126 .IX Title "SRCREDACT 1"
127 .TH SRCREDACT 1 "2015-10-24" "1.0" "Text tools"
128 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
129 .\" way too many mistakes in technical documents.
130 .if n .ad l
131 .nh
132 .SH "NAME"
133 srcredact \- a program for redaction of text files
134 .SH "SYNOPSIS"
135 .IX Header "SYNOPSIS"
136 srcredact [\fI\s-1OPTIONS\s0\fR] \fB\-e\fR \fIaudience\fR [\fIfull_file\fR]
137 .PP
138 srcredact [\fI\s-1OPTIONS\s0\fR] \fB\-u\fR \fIaudience\fR \fIfull_file\fR [\fIredacted_file\fR]
139 .PP
140 srcredact \fB\-l\fR [\fIfull_file\fR]
141 .PP
142 srcredact \fB\-h|\-v\fR
143 .SH "DESCRIPTION"
144 .IX Header "DESCRIPTION"
145 \&\fBsrcredact\fR is the program to extract ``redacted versions'' of the
146 master file (option \fB\-e\fR) or to incorporate the changes in the
147 redacted versions into the master file (``unredact'', option \fB\-u\fR).
148 .PP
149 The master file consists of \fIchunks\fR intended for different
150 audiences. Each audience has a \fIname\fR, e.g. \f(CW\*(C`classified\*(C'\fR,
151 \&\f(CW\*(C`unclssified\*(C'\fR, \f(CW\*(C`expert\*(C'\fR etc. Chunks are started and stopped by
152 \&\fIguard lines\fR. Each guard line has the format (for the default TeX
153 syntax)
154 .PP
155 .Vb 1
156 \& %<*name1|name2|...>
157 .Ve
158 .PP
159 or
160 .PP
161 .Vb 1
162 \& %</name1|name2|...>
163 .Ve
164 .PP
165 In the first cases the text following the guard is \fIincluded\fR for the
166 audiences \f(CW\*(C`name1\*(C'\fR, \f(CW\*(C`name2\*(C'\fR, .... In the second case it is
167 \&\fIexcluded\fR for these audiences.
168 .PP
169 THere is a special audience \f(CW\*(C`ALL\*(C'\fR: a wild card for all audiences.
170 Thus the idiom
171 .PP
172 .Vb 2
173 \& %</ALL>
174 \& %<*classified>
175 .Ve
176 .PP
177 means that the chunk is excluded for all audiences but \f(CW\*(C`classified\*(C'\fR
178 .PP
179 Exactly one of the options \fB\-e\fR (extract) or \fB\-u\fR (unextract) must be
180 present. In the extract mode the non-option argument is the name of
181 the full file. If it is absent, or is \f(CW\*(C`\-\*(C'\fR, standard input is used.
182 In the unextract mode the first non-option argument
183 .SH "OPTIONS"
184 .IX Header "OPTIONS"
185 .IP "\fB\-c\fR \fIlist of comment patterns\fR" 4
186 .IX Item "-c list of comment patterns"
187 Use the given pattern for comment lines to search for guards instead
188 of the default \f(CW\*(C`TeX\*(C'\fR pattern. The recognized patterns are:
189 .RS 4
190 .IP "\fBc\fR" 4
191 .IX Item "c"
192 .Vb 1
193 \& /*<guard>*/
194 .Ve
195 .IP "\fBcpp\fR" 4
196 .IX Item "cpp"
197 .Vb 1
198 \& //<guard>
199 .Ve
200 .IP "\fBfortran\fR" 4
201 .IX Item "fortran"
202 .Vb 1
203 \& C<guard>
204 .Ve
205 .IP "\fBshell\fR" 4
206 .IX Item "shell"
207 .Vb 1
208 \& #<guard>
209 .Ve
210 .IP "\fBTeX\fR" 4
211 .IX Item "TeX"
212 .Vb 1
213 \& %<guard>
214 .Ve
215 .RE
216 .RS 4
217 .Sp
218 The pattern names should be separated by commas, and the list may be
219 enclosed in quotes to prevent shell expansion, e.g
220 .Sp
221 .Vb 1
222 \& \-c "TeX, c, shell"
223 .Ve
224 .RE
225 .IP "\fB\-d\fR" 4
226 .IX Item "-d"
227 Debug mode on.
228 .IP "\fB\-e\fR \fIaudience\fR" 4
229 .IX Item "-e audience"
230 Extract the contents for the current audience into the file \fIfile\fR.
231 The cuurent audience is guessed from the \fIfile\fR name, if the latter
232 has the structure \fIbase\fR\-\fIaudience\fR.\fIextension\fR,
233 e.g. \f(CW\*(C`report\-unclassified.tex\*(C'\fR. The key \fB\-a\fR overrides this guess
234 and should be used if the file name does not follow this pattern. The
235 file name \f(CW\*(C`\-\*(C'\fR means the standard output.
236 .IP "\fB\-h\fR" 4
237 .IX Item "-h"
238 Print help information and exit.
239 .IP "\fB\-l\fR" 4
240 .IX Item "-l"
241 List all audiences set in the file (one per line) and exit.
242 .IP "\fB\-u\fR \fIaudience\fR" 4
243 .IX Item "-u audience"
244 Take a edited file intended for the \fIaudience\fR (the second
245 non-option argument) and incorporate the changes in it into the full
246 file (the first non-option argument). If the second argument is
247 missing, standard input is used instead. As usual, \f(CW\*(C`\-\*(C'\fR also means
248 standard input. Note that only one of the two file arguments in this
249 case can be standard input.
250 .IP "\fB\-v\fR" 4
251 .IX Item "-v"
252 Print version information and exit.
253 .IP "\fB\-w\fR \fIon|off|1|0|true|false\fR" 4
254 .IX Item "-w on|off|1|0|true|false"
255 If \f(CW\*(C`on\*(C'\fR, \f(CW1\fR or \f(CW\*(C`true\*(C'\fR (the deafult), implicitly wrap the full
256 document into the guards
257 .Sp
258 .Vb 3
259 \& %<*ALL>
260 \& ...
261 \& %</ALL>
262 .Ve
263 .SH "RETURN VALUE"
264 .IX Header "RETURN VALUE"
265 The program returns 0 if successful, 1 if conflicts were found in the
266 \&\f(CW\*(C`unextract\*(C'\fR mode and 2 in case of problems.
267 .SH "CONFLICTS IN UNEXTRACT MODE"
268 .IX Header "CONFLICTS IN UNEXTRACT MODE"
269 Like the standard \fIdiff3\fR\|(1) tool, the program may find conflicts
270 between the full version and the edited one in the \fB\-u\fR mode. Then
271 the resulting file brackets the conflicts in the usual manner, e.g.
272 .PP
273 .Vb 10
274 \& <<<<<<< /tmp/BrjXo0hMOB/full
275 \& %</nobonds>
276 \& Forty\-five tons best old dry government bonds, suitable for furnace, gold
277 \& 7 per cents., 1864, preferred.
278 \& %<*nobonds>
279 \& ||||||| /tmp/BrjXo0hMOB/extracted
280 \& Forty\-five tons best old dry government bonds, suitable for furnace, gold
281 \& 7 per cents., 1864, preferred.
282 \& =======
283 \& >>>>>>> /tmp/BrjXo0hMOB/new
284 .Ve
285 .PP
286 Here \f(CW\*(C`full\*(C'\fR is the full document, \f(CW\*(C`extracted\*(C'\fR is the extracted file
287 for the given audience, \f(CW\*(C`new\*(C'\fR is the edited file.
288 .SH "AUTHOR"
289 .IX Header "AUTHOR"
290 Boris Veytsman, [email protected]
291 .PP
292 This work was commissioned by Consumer Financial Protection Bureau,
293 United States Treasury.
294 .SH "LICENSE AND COPYRIGHT"
295 .IX Header "LICENSE AND COPYRIGHT"
296 Copyright (C) 2015 Boris Veytsman. Version 1.0
297 .PP
298 This program is free software; you can redistribute it and/or modify
299 it under the terms of the \s-1GNU\s0 General Public License as published by
300 the Free Software Foundation; either version 2 of the License, or (at
301 your option) any later version.
302 .PP
303 This program is distributed in the hope that it will be useful, but
304 \&\s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of
305 \&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0. See the \s-1GNU\s0
306 General Public License for more details.
307 .PP
308 You should have received a copy of the \s-1GNU\s0 General Public License
309 along with this program; if not, write to the Free Software
310 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, \s-1MA\s0
311 02110\-1301, \s-1USA\s0