--- /dev/null
+.\" Copied from from Pod::Man template\r
+.\" Wed, 23 Mar 2005 11:51:08 +0100\r
+.\"\r
+.\" Standard preamble:\r
+.\" ======================================================================\r
+.de Sh \" Subsection heading\r
+.br\r
+.if t .Sp\r
+.ne 5\r
+.PP\r
+\fB\\$1\fR\r
+.PP\r
+..\r
+.de Sp \" Vertical space (when we can't use .PP)\r
+.if t .sp .5v\r
+.if n .sp\r
+..\r
+.de Ip \" List item\r
+.br\r
+.ie \\n(.$>=3 .ne \\$3\r
+.el .ne 3\r
+.IP "\\$1" \\$2\r
+..\r
+.de Vb \" Begin verbatim text\r
+.ft CW\r
+.nf\r
+.ne \\$1\r
+..\r
+.de Ve \" End verbatim text\r
+.ft R
+
+.fi
+..\r
+.\"\r
+.\" For nroff, turn off justification. Always turn off hyphenation; it\r
+.\" makes way too many mistakes in technical documents.\r
+.hy 0\r
+.if n .na\r
+.\"
+.IX Title "cp-update 1"
+.TH cp-update 1 "March 2005" CARNet "CARNet Packaging Tools"
+.SH NAME\r
+cp-update \- versatile line-based file updating tool\r
+.\"
+.SH SYNOPSIS\r
+.B cp-update\r
+[\fIoptions\fR] \fIpackage\fR \fIfile\fR < \fIstdin-content\fR
+.\"
+.SH DESCRIPTION
+This tool is usually used in postinst scripts of CARNet "\-cn" packages\r
+to modify configuration files of other pre-installed packages. It eases\r
+task of manipulating portions of configuration files by tagging blocks\r
+of content with recognizable begin and end marks. Configuration block\r
+marked that way can later be easily updated or removed.\r
+.PP\r
+When making modifications to filesystem, \fBcp-update\fR tries to do it\r
+as atomically as possible, thus shortening the window when the system,\r
+or some particular package, can be left in an unusable state.\r
+.PP\r
+Default mode of execution is to add the block read from standard input\r
+to the configuration file, enclosed by begin and end marks, or replace\r
+existing block identified by \fIpackage\fR \- usually the package name.\r
+.PP\r
+The blocks added to configuration file using default options look like:\r
+.Sp\r
+.Vb 5\r
+\& # Begin update by CARNet package test1 -- DO NOT DELETE THIS LINE!\r
+\& Block inserted by test1,\r
+\& using default options.\r
+\& This is the third line.\r
+\& # End update by CARNet package test1 -- DO NOT DELETE THIS LINE!\r
+.Ve
+.\"
+.SH OPTIONS
+Options provide a way to specify different operation mode, placement,\r
+block marking and file handling.\r
+.SS General options\r
+.Sp\r
+.TP
+\fB\-r\fR | \fB\-\-remove\fR\r
+Remove entry \fIpackage\fR from \fIfile\fR. Default is to add lines \r
+from stdin.\r
+.TP\r
+\fB\-m\fR | \fB\-\-allow\-multiple\fR\r
+Allow multiple blocks of the same type. By default, old blocks are \r
+replaced with the new one.\r
+.TP\r
+\fB\-h\fR | \fB\-\-help\fR\r
+Print usage reference and exit.\r
+.TP\r
+ \fB\-\-version\fR
+Print title, version, copyright message, and exit.\r
+.SS Placement control\r
+.TP\r
+\fB\-t\fR | \fB\-\-insert\-on\-top\fR\r
+Insert on top of the file. The default is to add it at the bottom.\r
+.TP\r
+\fB\-i\fR | \fB\-\-insert\-after\fR \fIpattern\fR\r
+Insert after the first line that matches given pattern.\r
+.TP\r
+\fB\-f\fR | \fB\-\-insert\-before\fR \fIpattern\fR\r
+Insert before the first line that matches given pattern.\r
+.TP\r
+\fB\-R\fR | \fB\-\-regexp\-match\fR | \fB\-\-regexp\fR\r
+Use regexp mode for line matching.\r
+.SS Manipulating block marks\r
+.TP\r
+\fB\-c\fR | \fB\-\-comment\fR \fIstring\fR\r
+Use alternative comment char/string. The default is shell-style #-sign\r
+(bangless she or an octothorpe :\-).\r
+.TP\r
+ \fB\-\-comment\-end\fR \fIstring\fR\r
+Use this marker for comment ending. The default is none. \r
+Examples: '\-\->', '*/'.\r
+.TP\r
+\fB\-b\fR | \fB\-\-begin\-mark\fR \fIstring\fR\r
+Block starting mark (ie. 'service ftp').\r
+.TP\r
+\fB\-e\fR | \fB\-\-end\-mark\fR \fIstring\fR\r
+Block ending mark (ie. '}').\r
+.PP\r
+Note that accidental use of these arguments can have\r
+harmful effects -- it could be the cause for script to \r
+delete content from the beginning mark to the end of the\r
+file if no end mark is found. There are measures in place\r
+to prevent that, but you should be warned nevertheless.\r
+Otheriwise, matching is non-greedy and stops at the first\r
+end mark found.\r
+.PP\r
+You can use \fB%P\fR to insert the \fIpackage\fR argument,\r
+and \fB%%\fR to insert a literal % sign into the mark.\r
+.SS File handling\r
+.TP\r
+\fB\-p\fR | \fB\-\-in\-place\fR\r
+Try to preserve original inode. Useful when removing blocks\r
+from the file so no disk space allocation needs to be done.\r
+In that case it is safer than normal mode which creates file\r
+anew and replaces the old by renaming it to target name.\r
+.TP\r
+\fB\-n\fR | \fB\-\-no\-close\fR\r
+Do not close and reopen file when editing it in place.\r
+Slightly optimized version of the above.\r
+.\"
+.SH "EXIT STATUS"
+Upon successful execution of given operation, program returns
+exit status of 0 which evaluates to true in shell\-scripting
+environment. In case of failure error code 1 is returned.
+.\"
+.SH COMMENTS
+If the File::Copy module is available on system it will be used\r
+to create backup copy of the file being updated before the target\r
+file gets replaced with the new one, thus increasing reliability.\r
+.\"
+.SH EXAMPLES
+A few examples illustrating basic use-cases follow.
+.PP\r
+Simple addition of a new block at the end of the file:
+.RS\r
+.Sp
+.Vb 1\r
+\& cp-update aide-cn /etc/aide/aide.conf < aide-cn.ins\r
+.Ve
+.RE
+Replacing or inserting a block at some specific place (Gentoo uses\r
+XML config-file so this is also an opportunity to show how to put\r
+the inserted block between customized markers):\r
+.RS
+.Sp
+.Vb 4\r
+\& cp-update --regexp --insert-before '</Controls>' \\\r
+\& --comment '<!--' --comment-end ' -->' \\\r
+\& gentoo-cn /etc/gentoorc < gentoo-cn.ins
+.Ve\r
+.RE\r
+Removing block added with the upper command (here again we mus use\r
+the same markers as we did when the block was inserted):\r
+.RS
+.Sp
+.Vb 4\r
+\& cp-update -r --regexp --insert-before '</Controls>' \\\r
+\& --comment '<!--' --comment-end ' -->' \\\r
+\& gentoo-cn /etc/gentoorc
+.Ve\r
+.RE\r
+.\"
+.SH ENVIRONMENT
+No special environment variables are used.
+.\"
+.SH FILES
+No special files are used for cp-update operation control.
+.\"
+.SH BUGS
+Should be none.
+.\"
+.SH AUTHORS
+Recent version of cp-update is a complete rewrite of the previous one,\r
+done by Damir Dzeko. Previous version was written by Hrvoje Niksic and\r
+maintaned by Zeljko Boros, Zoran Dzelajlija and Nikola Pavkovic.
+.\"
+.SH NOTES\r
+This man page documents cp-update version 2.0 and is modified occasionally.
+For precise insight in its operation don't hesitate to look at the source.\r
+.\"
+.SH "REPORTING BUGS"
+If you find any, we encourage you to send them to CARNet packaging group\r
+at SRCE <paketi@srce.hr>.
+.PP
+When sending bug reports, please try to run program in diagnostic mode
+and try to send us quality feedback so we could easily locate and
+correct the problem.\r
+.\"
+.SH "SEE ALSO"\r
+.BR carnet-tools(8),\r
+.BR dpkg-divert(8).
+.\" End
projects / carnet-tools-cn.git / commitdiff