=head1 NAME
srcredact - a program for redaction of text files
=head1 SYNOPSIS
srcredact [I<OPTIONS>] B<-e> I<audience> [I<full_file>]
srcredact [I<OPTIONS>] B<-u> I<audience> I<full_file> [I<redacted_file>]
srcredact B<-l> [I<full_file>]
srcredact B<-h|-v>
=head1 DESCRIPTION
B<srcredact> is the program to extract ``redacted versions'' of the
master file (option B<-e>) or to incorporate the changes in the
redacted versions into the master file (``unredact'', option B<-u>).
The master file consists of I<chunks> intended for different
audiences. Each audience has a I<name>, e.g. C<classified>,
C<unclssified>, C<expert> etc. Chunks are started and stopped by
I<guard lines>. Each guard line has the format (for the default TeX
syntax)
%<*name1|name2|...>
or
%</name1|name2|...>
In the first cases the text following the guard is I<included> for the
audiences C<name1>, C<name2>, .... In the second case it is
I<excluded> for these audiences.
THere is a special audience C<ALL>: a wild card for all audiences.
Thus the idiom
%</ALL>
%<*classified>
means that the chunk is excluded for all audiences but C<classified>
Exactly one of the options B<-e> (extract) or B<-u> (unextract) must be
present. In the extract mode the non-option argument is the name of
the full file. If it is absent, or is C<->, standard input is used.
In the unextract mode the first non-option argument
=head1 OPTIONS
=over 4
=item B<-c> I<list of comment patterns>
Use the given pattern for comment lines to search for guards instead
of the default C<TeX> pattern. The recognized patterns are:
=over 4
=item B<c>
/*<guard>*/
=item B<cpp>
//<guard>
=item B<fortran>
C<guard>
=item B<shell>
#<guard>
=item B<TeX>
%<guard>
=back
The pattern names should be separated by commas, and the list may be
enclosed in quotes to prevent shell expansion, e.g
-c "TeX, c, shell"
=item B<-d>
Debug mode on.
=item B<-e> I<audience>
Extract the contents for the current audience into the file I<file>.
The cuurent audience is guessed from the I<file> name, if the latter
has the structure I<base>-I<audience>.I<extension>,
e.g. C<report-unclassified.tex>. The key B<-a> overrides this guess
and should be used if the file name does not follow this pattern. The
file name C<-> means the standard output.
=item B<-h>
Print help information and exit.
=item B<-l>
List all audiences set in the file (one per line) and exit.
=item B<-u> I<audience>
Take a edited file intended for the I<audience> (the second
non-option argument) and incorporate the changes in it into the full
file (the first non-option argument). If the second argument is
missing, standard input is used instead. As usual, C<-> also means
standard input. Note that only one of the two file arguments in this
case can be standard input.
=item B<-v>
Print version information and exit.
=item B<-w> I<on|off|1|0|true|false>
If C<on>, C<1> or C<true> (the deafult), implicitly wrap the full
document into the guards
%<*ALL>
...
%</ALL>
=back
=head1 RETURN VALUE
The program returns 0 if successful, 1 if conflicts were found in the
C<unextract> mode and 2 in case of problems.
=head1 CONFLICTS IN UNEXTRACT MODE
Like the standard L<diff3(1)> tool, the program may find conflicts
between the full version and the edited one in the B<-u> mode. Then
the resulting file brackets the conflicts in the usual manner, e.g.
<<<<<<< /tmp/BrjXo0hMOB/full
%</nobonds>
Forty-five tons best old dry government bonds, suitable for furnace, gold
7 per cents., 1864, preferred.
%<*nobonds>
||||||| /tmp/BrjXo0hMOB/extracted
Forty-five tons best old dry government bonds, suitable for furnace, gold
7 per cents., 1864, preferred.
=======
>>>>>>> /tmp/BrjXo0hMOB/new
Here C<full> is the full document, C<extracted> is the extracted file
for the given audience, C<new> is the edited file.
=head1 AUTHOR
Boris Veytsman,
[email protected]
This work was commissioned by Consumer Financial Protection Bureau,
United States Treasury.
=head1 LICENSE AND COPYRIGHT
Copyright (C) 2015 Boris Veytsman. Version 1.0
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or (at
your option) any later version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301, USA
