.\" Copyright (c) 2003-2012
.\" Distributed Systems Software.  All rights reserved.
.\" See the file LICENSE for redistribution information.
.\" $Id: copyright-nr 2564 2012-03-02 00:17:08Z brachman $
'\" t
.\"     Title: dacstransform
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 08/23/2020
.\"    Manual: DACS Commands Manual
.\"    Source: DACS 1.4.40
.\"  Language: English
.\"
.TH "DACSTRANSFORM" "1" "08/23/2020" "DACS 1.4.40" "DACS Commands Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
dacstransform \- rule\-based document transformation
.SH "SYNOPSIS"
.HP \w'\fBdacstransform\fR\ 'u
\fBdacstransform\fR [\fI\m[blue]\fBdacsoptions\fR\m[]\&\s-2\u[1]\d\s+2\fR] [\fB\-admin\fR] [\fB\-ct\ \fR\fB\fIstr\fR\fR] [\fB\-docs\ \fR\fB\fIdir\fR\fR] [\fB\-f\fR] [\fB\-F\ \fR\fB\fIfield_sep\fR\fR] [\fB\-fd\ \fR\fB\fIdomain\fR\fR] [\fB\-fh\ \fR\fB\fIhostname\fR\fR] [\fB\-fj\ \fR\fB\fIjurname\fR\fR]
.br
[\fB\-fn\ \fR\fB\fIfedname\fR\fR] [\fB\-h\fR | \fB\-help\fR] [\fB\-i\ \fR\fB\fIident\fR\fR] [\fB\-il\ \fR\fB\fIident\fR\fR] [\fB\-ilg\ \fR\fB\fIident\fR\fR] [\fB\-ieuid\fR]
.br
[\fB\-ieuidg\fR] [\fB\-iuid\fR] [\fB\-insert\fR] [\fB\-iuidg\fR] [\fB\-lg\fR] [\fB\-name\ \fR\fB\fIstr\fR\fR] [\fB\-prefix\ \fR\fB\fIstr\fR\fR] [\fB\-roles\ \fR\fB\fIroles_vfs\fR\fR] [\fB\-rprefix\ \fR\fB\fIregex\fR\fR] [\fB\-rsuffix\ \fR\fB\fIregex\fR\fR] [\fB\-suffix\ \fR\fB\fIstr\fR\fR] [{\fB\-r\fR\ |\ \fB\-rules\fR}\ \fIrules_uri\fR]
.br
[\fB\-var\ \fR\fB\fIname=value\fR\fR] [\fB\-x\fR] [\fB\-\-\fR] {\fB\-\fR | \fIfile\fR}
.SH "DESCRIPTION"
.PP
This program is part of the
\fBDACS\fR
suite\&.
.PP
\fBdacstransform\fR
supplies the functionality of
\fBdacs_transform\fR
from the command\-line\&. Because the two programs are almost identical, please refer to
\m[blue]\fBdacs_transform(8)\fR\m[]\&\s-2\u[2]\d\s+2
for details\&.
.PP
If the program is executed through the system\*(Aqs "#!" mechanism (\m[blue]\fBexecve(2)\fR\m[]\&\s-2\u[3]\d\s+2), one or more command line arguments can be given:
.sp
.if n \{\
.RS 4
.\}
.nf
#!/usr/local/dacs/bin/dacstransform \-Dfoo=val \-ct \*(Aq\*(Aq
Hello, world

Bye
.fi
.if n \{\
.RE
.\}
.sp
Such programs always use the script file as input, therefore no expression or other file can be specified on the "#!" line\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
The program has some limitations, including missing configuration capabilities and features, that might be expected in a production version but which have not yet been implemented\&.
.sp .5v
.RE
.SH "OPTIONS"
.PP
The arguments are processed as they are examined (left\-to\-right) and their ordering can be significant\&. Command line arguments override
\fBDACS\fR
configuration (see below)\&.
.PP
Please refer to
\m[blue]\fBdacscheck(1)\fR\m[]\&\s-2\u[4]\d\s+2
for a description of the flags related to setting identities and
\fBDACS\fR
context\&. If no identity is specified, the program will use the values of the environment variables
\fBREMOTE_USER\fR
and
\fBDACS_ROLES\fR
if they are available and valid\&.
.PP
The following command line flags are recognized:
.PP
\fB\-ct \fR\fB\fIstr\fR\fR
.RS 4
Set the MIME Content\-Type to
\fIstr\fR\&. The default is not to emit this header\&.
.RE
.PP
\fB\-docs \fR\fB\fIdir\fR\fR
.RS 4
Set the directory containing the documents to
\fIdir\fR
\- the
\fIfile\fR
argument will be relative to
\fIdir\fR\&. If
\fIdir\fR
is the empty string, however, this mapping will not be performed\&. The mapping is also disabled if the
\fB\-f\fR
is given or if the standard input is read\&. This argument overrides any configuration of
transform_docs
or default behaviour\&.
.RE
.PP
\fB\-f\fR
.RS 4
Disable input file location mapping\&.
.RE
.PP
\fB\-h\fR
.br
\fB\-help\fR
.RS 4
Prints the usage blurb, which includes a listing of the program\*(Aqs defaults\&.
.RE
.PP
\fB\-insert \fR\fB\fIdir\fR\fR
.RS 4
If a relative path is given for the value of a
filename
attribute with the
insert,
insertv, or
expand
directive, prefix the relative path with the string
\fIdir\fR\&.
.RE
.PP
\fB\-name \fR\fB\fIstr\fR\fR
.RS 4
The name of the input document is
\fIstr\fR\&. This is used to associate a rule with the document; that is, it is matched against a rule\*(Aqs
service
or
delegate
element\&. By default, it is the name of the input file or the path component of the input URI\&. If the effective name does not begin with a slash character, one is prepended\&. The argument should probably be given if the standard input is being read\&.
.RE
.PP
\fB\-prefix \fR\fB\fIstr\fR\fR
.RS 4
A directive is introduced by
\fIstr\fR
appearing at the beginning of an input line\&. The default is "<\-\-DACS\ \&"\&.
.RE
.PP
\fB\-suffix \fR\fB\fIstr\fR\fR
.RS 4
A directive is terminated by
\fIstr\fR
appearing at the end of a directive line\&. The default is "\-\->"\&.
.RE
.PP
\fB\-r \fR\fB\fIrules_uri\fR\fR
.br
\fB\-rules \fR\fB\fIrules_uri\fR\fR
.RS 4
The location of the ruleset to be applied to the document, as a
\fBDACS\fR
VFS URI\&.
.RE
.PP
\fB\-rprefix \fR\fB\fIregex\fR\fR
.RS 4
A line whose beginning matches
\fIregex\fR
introduces a directive\&. This overrides the default and any
\fB\-prefix\fR
flag\&. IEEE Std 1003\&.2 ("POSIX\&.2") "extended" regular expressions are supported (\m[blue]\fBregex(3)\fR\m[]\&\s-2\u[5]\d\s+2)\&.
.RE
.PP
\fB\-rsuffix \fR\fB\fIregex\fR\fR
.RS 4
A directive is terminated by a string that matches
\fIregex\fR, followed immediately by the end of the line\&. This overrides the default and any
\fB\-suffix\fR
flag\&. IEEE Std 1003\&.2 ("POSIX\&.2") "extended" regular expressions are supported (\m[blue]\fBregex(3)\fR\m[]\&\s-2\u[5]\d\s+2)\&.
.RE
.PP
\fB\-var\fR \fIname=value\fR
.RS 4
Add a variable definition to the
\fIDACS\fR
namespace\&. The variable
\fI${DACS::\fR\fI\fIname\fR\fR\fI}\fR
will be assigned the string
\fIvalue\fR\&. The
\fIname\fR
must be syntactically valid\&. This flag is equivalent to the
\m[blue]\fBdacsoptions\fR\m[]\&\s-2\u[1]\d\s+2
flag
\fB\-D\fR\fIname=value\fR\&. This flag may be repeated\&. It is best to avoid the variable name
\fIstdin\fR, which has a special purpose\&. If
\fIname\fR
is defined more than once its value is indeterminate\&.
.sp
In a directive, an attribute value that is enclosed within backtick quotes is evaluated as an expression, which may include variable references\&. Variables from the
\fIEnv\fR
namespace and, if available, the
\fIConf\fR
are also instantiated\&. The current directive\*(Aqs attributes are accessible in the
\fIAttr\fR
namespace; these attribute values are
\fIunevaluated\fR
and quoted\&.
.RE
.PP
\fB\-x\fR
.RS 4
Run as a command, not a web service\&. This is often required when
\fBdacstransform\fR
is run as a CGI program\&.
.RE
.PP
\fB\-\-\fR
.RS 4
Flags end\&. An input source argument may follow\&.
.RE
.PP
After the flags, the input source can be specified\&. By default, or if
\fB\-\fR
is given, the standard input is read, otherwise
\fIfile\fR
is read\&.
.PP
Whitespace is not ignored at the beginning or end of an input line with respect to directive prefix and suffix matching\&.
.SS "Configuration"
.PP
Configuration variables can be set to change some of the program\*(Aqs defaults, but each one is overridden if a value is also given on the command line:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fItransform_docs\fR: This is the full pathname of the root directory in which original documents are kept\&. By default, the program will use a subdirectory
\fI${Conf::DACS_HOME}\fRdacs_transform/docs\&. (default:
/usr/local/dacs/dacs_transform/docs)
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBSecurity\fR
.ps -1
.br
Change the default with care\&. In the absence of an appropriate access control rule, setting the pathname to "/" or the empty string, would provide access to any file on the server that can be read by this web service\&.
.sp .5v
.RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fItransform_acls\fR: This is the VFS specification for the rules\&. By default, the program will use
\fI${Conf::DACS_HOME}\fRdacs_transform/acls\&. (default:
[transform\-acls]dacs\-fs:/usr/local/dacs/dacs_transform/acls)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fItransform_annotation\fR: This is the annotation to interpolate in redacted text instead of the default\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fItransform_prefix\fR: Instead of the default prefix string used to introduce a directive, the value of this variable is used\&. It must appear at the beginning of a line\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fItransform_suffix\fR: Instead of the default string used to end a directive, the value of this variable is used\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fItransform_rprefix\fR: A line whose beginning matches the specified regular expression introduces a directive\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fItransform_rsuffix\fR: The end of a directive is found by matching the specified regular expression\&.
.RE
.sp
.SH "DIAGNOSTICS"
.PP
The program exits
0
if everything was fine,
1
if an error occurred\&.
.SH "SEE ALSO"
.PP
\m[blue]\fBdacs_transform(8)\fR\m[]\&\s-2\u[2]\d\s+2,
\m[blue]\fBdacs\&.exprs(5)\fR\m[]\&\s-2\u[6]\d\s+2,
\m[blue]\fBdacs\&.acls(5)\fR\m[]\&\s-2\u[7]\d\s+2
.SH "AUTHOR"
.PP
Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[8]\d\s+2)
.SH "COPYING"
.PP
Copyright \(co 2003\-2018 Distributed Systems Software\&. See the
\m[blue]\fBLICENSE\fR\m[]\&\s-2\u[9]\d\s+2
file that accompanies the distribution for licensing information\&.
.SH "NOTES"
.IP " 1." 4
dacsoptions
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#dacsoptions
.RE
.IP " 2." 4
dacs_transform(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_transform.8.html
.RE
.IP " 3." 4
execve(2)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=execve&apropos=0&esektion=2&emanpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP " 4." 4
dacscheck(1)
.RS 4
\%http://dacs.dss.ca/man/dacscheck.1.html
.RE
.IP " 5." 4
regex(3)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=regex&apropos=0&esektion=3&emanpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP " 6." 4
dacs.exprs(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html
.RE
.IP " 7." 4
dacs.acls(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.acls.5.html
.RE
.IP " 8." 4
www.dss.ca
.RS 4
\%http://www.dss.ca
.RE
.IP " 9." 4
LICENSE
.RS 4
\%http://dacs.dss.ca/man/../misc/LICENSE
.RE