regenerate lsync.8, it was broken

openpkg/lsync.8

@@ -0,0 +1,432 @@
+.rn '' }`
+''' $RCSfile$$Revision$$Date$
+'''
+''' $Log$
+'''
+.de Sh
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp
+.if t .sp .5v
+.if n .sp
+..
+.de Ip
+.br
+.ie \\n(.$>=3 .ne \\$3
+.el .ne 3
+.IP "\\$1" \\$2
+..
+.de Vb
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve
+.ft R
+
+.fi
+..
+'''
+'''
+'''     Set up \*(-- to give an unbreakable dash;
+'''     string Tr holds user defined translation string.
+'''     Bell System Logo is used as a dummy character.
+'''
+.tr \(*W-|\(bv\*(Tr
+.ie n \{\
+.ds -- \(*W-
+.ds PI pi
+.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+.ds L" ""
+.ds R" ""
+'''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
+'''   \*(L" and \*(R", except that they are used on ".xx" lines,
+'''   such as .IP and .SH, which do another additional levels of
+'''   double-quote interpretation
+.ds M" """
+.ds S" """
+.ds N" """""
+.ds T" """""
+.ds L' '
+.ds R' '
+.ds M' '
+.ds S' '
+.ds N' '
+.ds T' '
+'br\}
+.el\{\
+.ds -- \(em\|
+.tr \*(Tr
+.ds L" ``
+.ds R" ''
+.ds M" ``
+.ds S" ''
+.ds N" ``
+.ds T" ''
+.ds L' `
+.ds R' '
+.ds M' `
+.ds S' '
+.ds N' `
+.ds T' '
+.ds PI \(*p
+'br\}
+.\"	If the F register is turned on, we'll generate
+.\"	index entries out stderr for the following things:
+.\"		TH	Title 
+.\"		SH	Header
+.\"		Sh	Subsection 
+.\"		Ip	Item
+.\"		X<>	Xref  (embedded
+.\"	Of course, you have to process the output yourself
+.\"	in some meaninful fashion.
+.if \nF \{
+.de IX
+.tm Index:\\$1\t\\n%\t"\\$2"
+..
+.nr % 0
+.rr F
+.\}
+.TH LSYNC 1 "perl 5.005, patch 03" "18/Sep/2001" "User Contributed Perl Documentation"
+.UC
+.if n .hy 0
+.if n .na
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.de CQ          \" put $1 in typewriter font
+.ft CW
+'if n "\c
+'if t \\&\\$1\c
+'if n \\&\\$1\c
+'if n \&"
+\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
+'.ft R
+..
+.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
+.	\" AM - accent mark definitions
+.bd B 3
+.	\" fudge factors for nroff and troff
+.if n \{\
+.	ds #H 0
+.	ds #V .8m
+.	ds #F .3m
+.	ds #[ \f1
+.	ds #] \fP
+.\}
+.if t \{\
+.	ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.	ds #V .6m
+.	ds #F 0
+.	ds #[ \&
+.	ds #] \&
+.\}
+.	\" simple accents for nroff and troff
+.if n \{\
+.	ds ' \&
+.	ds ` \&
+.	ds ^ \&
+.	ds , \&
+.	ds ~ ~
+.	ds ? ?
+.	ds ! !
+.	ds /
+.	ds q
+.\}
+.if t \{\
+.	ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.	ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.	ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.	ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.	ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.	ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
+.	ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
+.	ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.	ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
+.\}
+.	\" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
+.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
+.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
+.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.ds oe o\h'-(\w'o'u*4/10)'e
+.ds Oe O\h'-(\w'O'u*4/10)'E
+.	\" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.	\" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+.	ds : e
+.	ds 8 ss
+.	ds v \h'-1'\o'\(aa\(ga'
+.	ds _ \h'-1'^
+.	ds . \h'-1'.
+.	ds 3 3
+.	ds o a
+.	ds d- d\h'-1'\(ga
+.	ds D- D\h'-1'\(hy
+.	ds th \o'bp'
+.	ds Th \o'LP'
+.	ds ae ae
+.	ds Ae AE
+.	ds oe oe
+.	ds Oe OE
+.\}
+.rm #[ #] #H #V #F C
+.SH "NAME"
+\fBlsync\fR \- Access Layer Synchronization Tool
+.SH "SYNOPSIS"
+\fBlsync\fR
+[\fB--version\fR|\fB\-v\fR]
+[\fB--help\fR|\fB\-h\fR]
+[\fB--init\fR|\fB\-i\fR]
+[\fB--nop\fR|\fB\-n\fR]
+[\fB--quiet\fR|\fB\-q\fR]
+[\fB--trace\fR|\fB\-t\fR]
+[\fB--local\fR|\fB\-l\fR]
+[\fB--uninstall\fR|\fB\-u\fR]
+[\fB--root=\fR\fIroot\fR]
+[\fB--pkgdir=\fR\fIpkgdir\fR]
+[\fB--subdirs=\fR\fIsubdir\fR[,\fIsubdir\fR,...]]
+.SH "DESCRIPTION"
+This program activates software packages which were locally
+installed in a sub-directory of a package hierarchy (located under
+\fIroot\fR/\fIpkgdir\fR/) by managing symbolic links in an access layer
+(located under \fIroot\fR/) corresponding to package installation
+files (found in \fIroot\fR/\fIpkgdir\fR/pkgname/subdir/) which need to be
+collected in global directories (located under \fIroot\fR/subdir/). 
+.PP
+The purpose of this is that individual packages can be installed and
+deinstalled seperately without interfering with other packages while
+all packages as a whole still can be treated like a single package
+(installed into the access layer).
+.PP
+The
+actual creation of symbolic links is as following ("foo\*(R" indicating an
+arbitrary file; \*(L"bar\*(R" indicating an arbitrary package name):
+.Ip "\fIroot\fR\fB/bin/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/bin/\fRfoo" 4
+This activates the user executeable
+\fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/bin\fR/foo as \fIroot\fR\fB/bin/\fRfoo. It can
+be found by the shell by placing \fIroot\fR\fB/bin\fR into the environment
+variable \f(CWPATH\fR (\fB\s-1PATH\s0=\*(R"..:\fR\fIroot\fR\fB/bin:..\*(R"\fR).
+.Ip "\fIroot\fR\fB/sbin/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/sbin/\fRfoo" 4
+This activates the system executeable
+\fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/sbin\fR/foo as \fIroot\fR\fB/sbin/\fRfoo. It can
+be found by the shell by placing \fIroot\fR\fB/sbin\fR into the environment
+variable \f(CWPATH\fR (\fB\s-1PATH\s0=\*(R"..:\fR\fIroot\fR\fB/sbin:..\*(R"\fR).
+.Ip "\fIroot\fR\fB/man/man\fR\fIN\fR\fB/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/man/man\fR\fIN\fR\fB/\fRfoo" 4
+This activates the Unix manual page
+\fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/man/man\fR\fIN\fR\fB/\fRfoo as
+\fIroot\fR\fB/man/man\fR\fIN\fR\fB/\fRfoo. It can be found by the \fIman\fR\|(1) tool
+by placing \fIroot\fR\fB/man\fR into the environment variable \f(CWMANPATH\fR
+(\fB\s-1MANPATH\s0=\*(R"..:\fR\fIroot\fR\fB/man:..\*(R"\fR). Keep in mind that \fIlsync\fR\|(1)
+activates any files found in the \fBman/man\fIN\fR\fR sub-directory of the
+package, but the \fIman\fR\|(1) tool usually requires the filename scheme
+foo\fB.\fR\fIN\fR before it can find the file.
+.Ip "\fIroot\fR\fB/info/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/info/\fRfoo" 4
+This activates the \s-1GNU\s0 info page \fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/info/\fRfoo
+as \fIroot\fR\fB/info/\fRfoo. It can be found by the \fIinfo\fR\|(1) and \fIpinfo\fR\|(1)
+tools by placing \fIroot\fR\fB/info\fR into the environment variable
+\f(CWINFOPATH\fR (\fB\s-1INFOPATH\s0=\*(R"..:\fR\fIroot\fR\fB/info:..\*(R"\fR). Keep in mind that
+\fIlsync\fR\|(1) activates any files found in the \fBinfo/\fR sub-directory of the
+package, but the \fIinfo\fR\|(1) and \fIpinfo\fR\|(1) tools usually require the filename
+scheme foo\fB.info\fR before it can find the file.
+.Ip "\fIroot\fR\fB/include/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/include/\fRfoo" 4
+This activates the C header \fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/include\fR/foo
+as \fIroot\fR\fB/include/\fRfoo. It can be found by the C/\*(C+ compilers
+by adding \fIroot\fR\fB/include\fR to their include search path (\fBcc ..
+\-I\fR\fIroot\fR\fB/include\fR \fB...\fR). Keep in mind that \fIlsync\fR\|(1) activates any
+files found in the \fBinclude/\fR sub-directory of the package, but the
+C/\*(C+ compiler usually by convention use the filename scheme foo\fB.h\fR.
+.Ip "\fIroot\fR\fB/lib/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/lib/\fRfoo" 4
+This activates the C library \fIroot\fR\fB/\fR\fIpkgdir\fR\fB/\fRbar\fB/lib\fR/foo
+as \fIroot\fR\fB/lib/\fRfoo. It can be found by the C/\*(C+ compilers (and
+the linker they use) by adding \fIroot\fR\fB/lib\fR to their library search
+path (\fBcc .. \-L\fR\fIroot\fR\fB/lib\fR \fB...\fR). It can be found by the Unix
+Dynamic Loader by adding \fIroot\fR\fB/lib\fR to the environment variable
+\f(CWLD_LIBRARY_PATH\fR (\fB\s-1LD_LIBRARY_PATH\s0=\*(R"..:\fR\fIroot\fR\fB/lib:..\*(R"\fR).
+Keep in mind that \fIlsync\fR\|(1) activates any files found in the \fBlib/\fR
+sub-directory of the package, but the C/\*(C+ compiler usually require the
+filename scheme \fBlib\fRfoo\fB.a\fR and the Unix Dynamic Loader the filename
+scheme \fBlib\fRfoo\fB.so\fR before they actually can use the file.
+.PP
+It is obvious that more sub-directories in a package installation
+might exist -- for instance \fBshare/\fR, \fBvar/\fR, \fBlibexec/\fR, etc. But
+\fIlsync\fR\|(1) intentionally does not link files in those directories into
+corresponding directories of the access layer, because those files do
+not require that they are located in a global area in order to be used.
+So \fIlsync\fR\|(1) only creates the access layer for files where a common area
+is required for (easy) use.
+.SH "SPECIAL FEATURES"
+There are two special features supported by \fIlsync\fR\|(1):
+.Ip "\fBRun-Command Files\fR" 4
+\fIlsync\fR\|(1) on startup implicitly reads command line options from
+\&\f(CW.lsyncrc\fR files. They are searched in all parent directories and in
+the callers home directory. Their contents is prepended to the list of
+given command line options.
+.Ip "\fBMultiple Package Versions\fR" 4
+\fIlsync\fR\|(1) skips all directories under \fIroot\fR/\fIpkgdir\fR/ which contain
+the pattern \*(L"\-[0-9]\*(R" in their directory name. On the other hand,
+\fIlsync\fR\|(1) follows also symbolic links under \fIroot\fR/\fIpkgdir\fR/.
+This can be used for installing multiple versions of a package and
+switching between them. For instance, if version 1.0 of package
+\*(L"foo\*(R" is installed into directory \fIroot\fR/\fIpkgdir\fR/foo-1.0,
+version 1.1 into \fIroot\fR/\fIpkgdir\fR/foo-1.1 and version 1.2 into
+\fIroot\fR/\fIpkgdir\fR/foo-1.2, \fIlsync\fR\|(1) does skip all three. To enable
+version 1.1 one just creates a symbolic link \fIroot\fR/\fIpkgdir\fR/foo
+pointing to foo-1.1. Then \fIlsync\fR\|(1) picks up the files in
+\fIroot\fR/\fIpkgdir\fR/foo-1.1. If you want to temporarily upgrade to
+foo-1.2, all you have to do is to change the symlink pointing from
+foo-1.1 to foo-1.2.
+.Ip "\fBTemporarily Deactivated Package\fR" 4
+One can deactivate a package \*(L"foo\*(R" by going to \fIroot\fR/\fIpkgdir\fR/foo/
+and running \*(L"lsync --local --uninstall\*(R", of course. Alternatively
+one can set the sticky bit on the directory \fIroot\fR/\fIpkgdir\fR/foo.
+Then \fIlsync\fR\|(1) also skips the package. Alternatively, assume
+package \*(L"foo\*(R" as a whole should not be deactivated, but its
+\fIroot\fR/\fIpkgdir\fR/foo/lib directory (usually because this directory
+unfortunately contains non-library files), one just sets the sticky bit
+on \fIroot\fR/\fIpkgdir\fR/foo/lib.
+.SH "OPTIONS"
+.Ip "\fB--version\fR, \fB\-v\fR" 4
+Display program version information only.
+.Ip "\fB--help\fR, \fB\-h\fR" 4
+Display program usage information only.
+.Ip "\fB--init\fR, \fB\-i\fR" 4
+Create an initial access layer hierarchy under \fIroot\fR.
+.Ip "\fB--nop\fR, \fB\-n\fR" 4
+No Operation -- causes \fIlsync\fR\|(1) to not perform any filesystem
+operations. In conjunction with \fB--trace\fR you can at least see what
+would be executed.
+.Ip "\fB--quiet\fR, \fB\-q\fR" 4
+Forces \fIlsync\fR\|(1) to perform the operations quietly, i.e., without any
+verbose messages.
+.Ip "\fB--trace\fR, \fB\-t\fR" 4
+Forces \fIlsync\fR\|(1) to show what filesystem operations are performed.
+.Ip "\fB--local\fR, \fB\-l\fR" 4
+This restricts the operations to a local package area. This option can
+only be used if you are physically staying below a package sub-directory
+under \fIroot\fR/\fIpkgdir\fR/. For instance, when you are staying in
+\fIroot\fR/\fIpkgdir\fR/bar or \fIroot\fR/\fIpkgdir\fR/bar/bin and use \fB--local\fR,
+all operations are restricted to the package \*(L"bar\*(R".
+.Ip "\fB--uninstall\fR, \fB\-u\fR" 4
+This performs only package uninstallation operations, i.e., only
+symbolic links are removed. This can be used to completely empty the
+access layer. Additionally it is very useful in combination with
+\fB--local\fR in order to uninstall a particular package without having to
+remove its files.
+.Ip "\fB--root=\fR\fIroot\fR" 4
+Sets the root directory where the access layer and package subdirectory
+is located. The default can be determined by running \f(CWlsync --help\fR
+(see section \*(L"Current configuration").
+.Ip "\fB--pkgdir=\fR\fIpkgdir\fR" 4
+Sets the sub-directory under the root directory where packages are
+located. The default can be determined by running \f(CWlsync --help\fR (see
+section \*(L"Current configuration").
+.Ip "\fB--subdirs=\fR\fIsubdirs\fR[,\fIsubdir\fR,...]" 4
+Sets one or more sub-directories of the access layer on which \fIlsync\fR\|(1)
+should act. The default can be determined by running \f(CWlsync --help\fR
+(see section \*(L"Current configuration").
+.SH "RESULTS"
+This program uses the following return codes on exit: 0 (operation
+successful), 1 (system error), 2 (command line error) and 3 (other user
+error).
+.SH "HISTORY"
+The idea of filesystem access layers consisting of symbolic links
+pointing to actual package installation areas is a rather old one. It
+dates back to the early days of Unix and was implemented many times over
+the last decades. One of many implementation was \fBGenOPT\fR, written by
+Ralf S. Engelschall for sd&m GmbH & Co KG, Munich in 1992. The name
+indicates the programs purpose: to generate symbolic links in an access
+layer which was located under \f(CW/opt\fR. \fBGenOPT\fR was very flexible, but
+hence also very complex. Because of lack of documentation it was never
+released and so only used at sd&m and on all machines which were under
+control of Ralf S. Engelschall.
+.PP
+For Cable & Wireless Deutschland GmbH, Munich, the old \fBGenOPT\fR
+principle was again needed to manage the \f(CW/cw/local\fR area on their
+servers. For this in November 2000 the functionality of \fBGenOPT\fR was
+revised, heavily stripped down and finally implemented from scratch. The
+result is the current \fBLSync\fR.
+.SH "AUTHOR"
+.PP
+.Vb 3
+\& Ralf S. Engelschall
+\& rse@engelschall.com
+\& www.engelschall.com
+.Ve
+
+.rn }` ''
+.IX Title "LSYNC 1"
+.IX Name "B<lsync> - Access Layer Synchronization Tool"
+
+.IX Header "NAME"
+
+.IX Header "SYNOPSIS"
+
+.IX Header "DESCRIPTION"
+
+.IX Item "\fIroot\fR\fB/bin/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/bin/\fRfoo"
+
+.IX Item "\fIroot\fR\fB/sbin/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/sbin/\fRfoo"
+
+.IX Item "\fIroot\fR\fB/man/man\fR\fIN\fR\fB/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/man/man\fR\fIN\fR\fB/\fRfoo"
+
+.IX Item "\fIroot\fR\fB/info/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/info/\fRfoo"
+
+.IX Item "\fIroot\fR\fB/include/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/include/\fRfoo"
+
+.IX Item "\fIroot\fR\fB/lib/\fRfoo \-> \fB../\fR\fIpkgdir\fR\fB/\fRbar\fB/lib/\fRfoo"
+
+.IX Header "SPECIAL FEATURES"
+
+.IX Item "\fBRun-Command Files\fR"
+
+.IX Item "\fBMultiple Package Versions\fR"
+
+.IX Item "\fBTemporarily Deactivated Package\fR"
+
+.IX Header "OPTIONS"
+
+.IX Item "\fB--version\fR, \fB\-v\fR"
+
+.IX Item "\fB--help\fR, \fB\-h\fR"
+
+.IX Item "\fB--init\fR, \fB\-i\fR"
+
+.IX Item "\fB--nop\fR, \fB\-n\fR"
+
+.IX Item "\fB--quiet\fR, \fB\-q\fR"
+
+.IX Item "\fB--trace\fR, \fB\-t\fR"
+
+.IX Item "\fB--local\fR, \fB\-l\fR"
+
+.IX Item "\fB--uninstall\fR, \fB\-u\fR"
+
+.IX Item "\fB--root=\fR\fIroot\fR"
+
+.IX Item "\fB--pkgdir=\fR\fIpkgdir\fR"
+
+.IX Item "\fB--subdirs=\fR\fIsubdirs\fR[,\fIsubdir\fR,...]"
+
+.IX Header "RESULTS"
+
+.IX Header "HISTORY"
+
+.IX Header "AUTHOR"
+