summaryrefslogtreecommitdiff
path: root/support/srcredact/srcredact.pod
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/srcredact/srcredact.pod
Initial commit
Diffstat (limited to 'support/srcredact/srcredact.pod')
-rw-r--r--support/srcredact/srcredact.pod185
1 files changed, 185 insertions, 0 deletions
diff --git a/support/srcredact/srcredact.pod b/support/srcredact/srcredact.pod
new file mode 100644
index 0000000000..4f690848f0
--- /dev/null
+++ b/support/srcredact/srcredact.pod
@@ -0,0 +1,185 @@
+=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, borisv@lk.net
+
+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
+