add uniconv man page

diff --git a/man/man1/Makefile.am b/man/man1/Makefile.am
index 03f3ca8dc4776e8a36b75cd38081670ac2fc68d4..72b02d17479397d1437d5a7a59e4dca8e707ec4e 100644 (file)
--- a/man/man1/Makefile.am
+++ b/man/man1/Makefile.am
@@ -9,10 +9,11 @@ SUFFIXES= .tmpl .
            -e s@:BINDIR:@${bindir}@ \
            -e s@:ETCDIR:@${pkgconfdir}@ \
            -e s@:LIBDIR:@${libdir}@ \
+           -e s@:DEFAULT_CNID_SCHEME:@${DEFAULT_CNID_SCHEME}@ \
            <$< >$@
 
-GENERATED_MANS = apple_cp.1 apple_mv.1 apple_rm.1
-TEMPLATE_FILES = apple_cp.1.tmpl apple_mv.1.tmpl apple_rm.1.tmpl
+GENERATED_MANS = apple_cp.1 apple_mv.1 apple_rm.1 uniconv.1
+TEMPLATE_FILES = apple_cp.1.tmpl apple_mv.1.tmpl apple_rm.1.tmpl uniconv.1.tmpl
 NONGENERATED_MANS      =       achfile.1  \
                                acleandir.1 \
                                aecho.1 \

diff --git a/man/man1/uniconv.1.tmpl b/man/man1/uniconv.1.tmpl
new file mode 100644 (file)
index 0000000..b7f0103
--- /dev/null
+++ b/man/man1/uniconv.1.tmpl
@@ -0,0 +1,122 @@
+.TH uniconv 1  24\ Jun\ 2004 "Netatalk 2.0-beta2" 
+.SH NAME
+uniconv \- convert Netatalk volume encoding
+.SH SYNOPSIS
+\fBuniconv\fR [\-ndv] \-c \fBcnidbackend\fR \-f \fBfromcode\fR \-t \fBtocode\fR [\-m \fBmaccode\fR] \fBvolumepath\fR 
+.SH DESCRIPTION
+uniconv converts the volume encoding of
+\fIvolumepath\fR from the \fIfromcode\fR
+to the \fItocode\fR encoding.
+.SH OPTIONS
+.TP 
+\-c
+CNID backend used on this volume, usually cdb or dbd. Should
+match the backend selected with afpd for this volume. If not
+specified, the default CNID backend `:DEFAULT_CNID_SCHEME:' is
+used
+.TP 
+\-d
+don't CAP encode leading dots (:2e), equivalent to
+\fBusedots\fR in \fBAppleVolumes.default\fR(5)
+.TP 
+\-f
+encoding to convert from, use ASCII for CAP encoded volumes
+.TP 
+\-h
+display help
+.TP 
+\-m
+Macintosh client codepage, required for CAP encoded volumes.
+Defaults to `MAC_ROMAN'
+.TP 
+\-n
+`dry run', don't do any real changes
+.TP 
+\-t
+volume encoding to convert to, e.g. UTF8
+.TP 
+\-v
+verbose output, use twice for maximum logging.
+.TP 
+\-V
+print version and exit
+.PP
+.SH WARNING
+Setting the wrong options might render your data unusable!!! Make
+sure you know what you are doing. Always backup your data first.
+.PP
+It is \fB*strongly*\fR recommended to do
+a `dry run' first and to check the output for conversion errors.
+.PP
+\fBafpd\fR(8)
+should \fInot\fR be running while you change the volume
+encoding. Remember to change \fBvolcodepage\fR in
+\fBAppleVolumes.default\fR(5)
+to the new codepage, before restarting afpd.
+.PP
+\fBUSE AT YOUR OWN RISK!!!\fR
+.SH SELECTABLE\ CHARSETS
+Netatalk provides internal support for UTF\-8 (pre\- and decomposed)
+and CAP. If you want to use other charsets, they must be provided by
+\fBiconv\fR(1)
+.PP
+uniconv also knows iso\-8859.adapted, an old style
+1.x NLS widely used. This is only intended for upgrading old volumes,
+\fBafpd\fR(8)
+cannot handle iso\-8859.adapted anymore.
+.SH CNID\ BACKGROUND
+The CNID backends maintains name to ID mappings. If you change a
+filename outside afpd(8) (shell, samba), the CNID db, i.e. the DIDNAME
+index, gets inconsistent. Netatalk tries to recover from such
+inconsistencies as gracefully as possible. The mechanisms to resolve such
+inconsistencies may fail sometimes, though, as this is not an easy task to
+accomplish. I.e. if several names in the path to the file or directory
+have changed, things may go wrong.
+.PP
+If you change a lot of filenames at once, chances are higher that
+the afpds fallback mechanisms fail, i.e. files will be assigned new IDs,
+even though the file hasn't changed. uniconv
+therefore updates the CNID entry for each file/directory directly after it
+changes the name to avoid inconsistencies. The two supported backends for
+volumes, dbd and cdb, use the same CNID db format. Therefore, you
+\fIcould\fR use uniconv with cdb and
+afpd with dbd later.
+.PP
+\fBWarning\fR: There must not be two
+processes opening the CNID database using different backends at once! If a
+volume is still opened with dbd (cnid_metad/cnid_dbd) and you start
+uniconv with cdb, the result will be a corrupted CNID
+database, as the two backends use different locking schemes. You might run
+into additional problems, e.g. if dbd is compiled with transactions, cdb
+will not update the transaction logs.
+.PP
+In general, it is recommended to use the same backend for
+uniconv you are using with
+\fBafpd\fR(8).
+.SH EXAMPLES
+convert 1.x CAP encoded volume to UTF\-8, clients used MacRoman
+codepage, cnidscheme is dbd:
+.PP
+.nf
+example%\fB uniconv \-c dbd \-f ASCII \-t UTF8 \-m MAC_ROMAN /path/to/share\fR
+.fi
+.PP
+convert iso8859\-1 volume to UTF\-8, cnidscheme is cdb:
+.PP
+.nf
+example%\fB uniconv \-c cdb \-f ISO\-8859\-1 \-t UTF8 \-m MAC_ROMAN /path/to/share\fR
+.fi
+.PP
+convert 1.x volume using iso8859\-1 adapted NLS to CAP encoding:
+.PP
+.nf
+example%\fB uniconv \-f ISO\-8859\-ADAPTED \-t ASCII \-m MAC_ROMAN/path/to/share\fR
+.fi
+.PP
+convert UTF\-8 volume to CAP, for MacCyrillic clients:
+.PP
+.nf
+example%\fB uniconv \-f UTF8 \-t ASCII \-m MAC_CYRILLIC /path/to/share\fR
+.fi
+.SH SEE\ ALSO
+\fBAppleVolumes.default\fR(5),\fBafpd\fR(8),\fBiconv\fR(1),\fBcnid_metad\fR(8),\fBcnid_dbd\fR(8)