Mercurial > hg > dav / changeset

--- a/docs/man/dav-sync.1.man	Sun Jul 01 16:45:03 2018 +0200
+++ b/docs/man/dav-sync.1.man	Sun Jul 01 17:14:17 2018 +0200
@@ -14,59 +14,147 @@
 .PP
 TODO
 .SH COMMANDS
-.PP
-pull [\f[B]\-cldr\f[]] [\f[B]\-t\f[] \f[I]tags\f[]] \f[I]directory\f[]
-.PP
-push [\f[B]\-cldr\f[]] [\f[B]\-t\f[] \f[I]tags\f[]] \f[I]directory\f[]
-.PP
-archive [\f[B]\-cld\f[]] [\f[B]\-t\f[] \f[I]tags\f[]] \f[I]directory\f[]
-.PP
-resolve\-conflicts \f[I]directory\f[]
-.PP
-delete\-conflicts \f[I]directory\f[]
-.PP
-trash\-info \f[I]directory\f[]
-.PP
-empty\-trash \f[I]directory\f[]
-.PP
-add\-tag [\f[B]\-s\f[] \f[I]syncdir\f[]] \f[I]file\f[] \f[I]tag\f[]
-.PP
-remove\-tag [\f[B]\-s\f[] \f[I]syncdir\f[]] \f[I]file\f[] \f[I]tag\f[]
-.PP
-set\-tags [\f[B]\-s\f[] \f[I]syncdir\f[]] \f[I]file\f[] \f[I]tags\f[]
-.PP
-list\-tags [\f[B]\-s\f[] \f[I]syncdir\f[]] \f[I]file\f[]
+.TP
+.B pull [\f[B]\-cldr\f[]] [\f[B]\-t\f[] \f[I]tags\f[]] \f[I]directory\f[]
+Pulls all changes from the server.
+All new or modified files are downloaded and all files deleted on the
+server are deleted locally.
+If a file is also locally modified and conflict detection is not
+disabled, the local file is renamed and an entry in the conflict
+database is added.
+.RS
+.RE
+.TP
+.B push [\f[B]\-cldr\f[]] [\f[B]\-t\f[] \f[I]tags\f[]] \f[I]directory\f[]
+Pushes all local changes to the server.
+This uploads all locally modified files and deletes all locally deleted
+files on the server.
+If conflict detection is not disabled, all files that are also modified
+on the server will be skipped.
+.RS
+.RE
+.TP
+.B archive [\f[B]\-cld\f[]] [\f[B]\-t\f[] \f[I]tags\f[]] \f[I]directory\f[]
+Uploads all new and modified files to the server.
+The command is similar to the push command (with the same conflict
+behavior), however it does not delete files on the server.
+.RS
+.RE
+.TP
+.B resolve\-conflicts \f[I]directory\f[]
+Removes conflict entries from the database.
+This does not merge any files.
+All files which are marked as conflict are normal files after running
+this command.
+In other words: by executing this command you assert that \f[B]you\f[]
+have resolved the conflicts.
+.RS
+.RE
+.TP
+.B delete\-conflicts \f[I]directory\f[]
+Deletes all files that are marked as a conflict.
+This will always delete the files and does not move them to the trash
+directory.
+Use this command with caution.
+.RS
+.RE
+.TP
+.B trash\-info \f[I]directory\f[]
+Shows the trash directory path for a \f[I]directory\f[], the number of
+files currently in the trash and the space they consume.
+.RS
+.RE
+.TP
+.B empty\-trash \f[I]directory\f[]
+Removes all files from the trash of the given \f[I]directory\f[].
+.RS
+.RE
+.TP
+.B add\-tag [\f[B]\-s\f[] \f[I]syncdir\f[]] \f[I]file\f[] \f[I]tag\f[]
+Adds a \f[I]tag\f[] to a SyncDirectory \f[I]file\f[].
+The \f[I]file\f[] argument must denote a local file path.
+.RS
+.RE
+.TP
+.B remove\-tag [\f[B]\-s\f[] \f[I]syncdir\f[]] \f[I]file\f[] \f[I]tag\f[]
+Removes a \f[I]tag\f[] from a SyncDirectory \f[I]file\f[].
+See \f[B]add\-tag\f[].
+.RS
+.RE
+.TP
+.B set\-tags [\f[B]\-s\f[] \f[I]syncdir\f[]] \f[I]file\f[] \f[I]tags\f[]
+Sets the list of \f[I]tags\f[] for a SyncDirectory \f[I]file\f[].
+This command behaves, as if you would remove all tags with
+\f[B]remove\-tag\f[] and add the \f[I]tags\f[] with \f[B]add\-tag\f[].
+.RS
+.RE
+.TP
+.B list\-tags [\f[B]\-s\f[] \f[I]syncdir\f[]] \f[I]file\f[]
+List all tags for the specified \f[I]file\f[].
+.RS
+.RE
+.SH CONFIGURATION COMMANDS
+.TP
+.B add\-directory
+Runs an interactive assistant to create a SyncDirectory.
+.RS
+.RE
+.TP
+.B list\-directories
+Lists all available SyncDirectories.
+.RS
+.RE
+.TP
+.B check\-config
+Validates the \f[B]$HOME/.dav/sync.xml\f[] configuration file.
+.RS
+.RE
+.TP
+.B check\-repositories
+Checks if every repository used by sync\-directories is configured and
+available.
+This command outputs the status for each repository.
+It returns zero when all repositories are all available and non\-zero
+otherwise.
+.RS
+.RE
 .SH GENERAL OPTIONS
 .PP
 The following options can be used with all commands.
 .TP
-.B \f[B]\-v\f[]
+.B \-v
 Verbose output.
 .RS
 .RE
 .SH COMMAND OPTIONS
 .TP
-.B \f[B]\-c\f[]
+.B \-c
 Disable conflict detection.
 .RS
 .RE
 .TP
-.B \f[B]\-d\f[]
+.B \-d
 Don\[aq]t lock the repository.
 .RS
 .RE
 .TP
-.B \f[B]\-l\f[]
+.B \-l
 Lock the repository before access.
 .RS
 .RE
 .TP
-.B \f[B]\-t\f[] \f[I]tags\f[]
+.B \-s \f[I]syncdir\f[]
+If multiple SyncDirectories contain a local file, this option must be
+used to resolve the ambiguity.
+.RS
+.RE
+.TP
+.B \-t \f[I]tags\f[]
 Only sync files which have the specified tags.
 .RS
 .RE
 .TP
-.B \f[B]\-r\f[]
+.B \-r
 Remove ressources not matching the tag filter.
 .RS
 .RE

--- a/docs/man/dav.1.man	Sun Jul 01 16:45:03 2018 +0200
+++ b/docs/man/dav.1.man	Sun Jul 01 17:14:17 2018 +0200
@@ -12,151 +12,245 @@
 .PP
 TODO
 .SH COMMANDS
-.PP
-list [\f[B]\-altdepcR\f[]] [\f[B]\-u\f[] \f[I]date\f[]] \f[I]url\f[]
-.PP
-get [\f[B]\-pcRK\f[]] [\f[B]\-o\f[] \f[I]file\f[]] [\f[B]\-u\f[]
-\f[I]date\f[]] \f[I]url\f[]
-.PP
-put [\f[B]\-pcR\f[]] [\f[B]\-k\f[] \f[I]key\f[]] [\f[B]\-L\f[]
-\f[I]lock\f[]] \f[I]url\f[] \f[I]file\f[]
+.TP
+.B list [\f[B]\-altdepcR\f[]] [\f[B]\-u\f[] \f[I]date\f[]] \f[I]url\f[]
+Lists the files at \f[I]url\f[].
+.RS
+.RE
+.TP
+.B get [\f[B]\-pcRK\f[]] [\f[B]\-o\f[] \f[I]file\f[]] [\f[B]\-u\f[] \f[I]date\f[]] \f[I]url\f[]
+Downloads a resource from \f[I]url\f[].
+.RS
+.RE
+.TP
+.B put [\f[B]\-pcR\f[]] [\f[B]\-k\f[] \f[I]key\f[]] [\f[B]\-L\f[] \f[I]lock\f[]] \f[I]url\f[] \f[I]file\f[]
+Uploads a resource to \f[I]url\f[].
+.RS
+.RE
+.TP
+.B mkdir [\f[B]\-pc\f[]] [\f[B]\-k\f[] \f[I]key\f[]] [\f[B]\-L\f[] \f[I]lock\f[]] \f[I]url\f[]
+Creates a new collection at \f[I]url\f[].
+.RS
+.RE
+.TP
+.B remove [\f[B]\-pc\f[]] [\f[B]\-L\f[] \f[I]lock\f[]] \f[I]url\f[]
+Deletes a resource or collection at \f[I]url\f[]
+.RS
+.RE
+.TP
+.B copy [\f[B]\-pcO\f[]] [\f[B]\-L\f[] \f[I]lock\f[]] \f[I]srcurl\f[] \f[I]desturl\f[]
+Copies a resource or collection from \f[I]srcurl\f[] to
+\f[I]desturl\f[].
+.RS
+.RE
+.TP
+.B move [\f[B]\-pcO\f[]] [\f[B]\-L\f[] \f[I]lock\f[]] \f[I]srcurl\f[] \f[I]desturl\f[]
+Moves a resource or collection from \f[I]srcurl\f[] to \f[I]desturl\f[].
+.RS
+.RE
+.TP
+.B export [\f[B]\-pc\f[]] [\f[B]\-o\f[] \f[I]file\f[]] [\f[B]\-u\f[] \f[I]date\f[]] \f[I]url\f[]
+Exports a resource or collection to a \f[B]tar(5)\f[] archive.
+By default the data is written to \f[I]stdout\f[], but you may specify a
+\f[I]file\f[] with the \f[B]\-o\f[] option.
+.RS
+.RE
+.TP
+.B import [\f[B]\-pc\f[]] [\f[B]\-k\f[] \f[I]key\f[]] [\f[B]\-L\f[] \f[I]lock\f[]] \f[I]url\f[] \f[I]file\f[]
+Uploads and extracts the contents of the \f[B]tar(5)\f[] archive
+\f[I]file\f[] to \f[I]url\f[].
+.RS
+.RE
+.TP
+.B get\-property [\f[B]\-pcx\f[]] [\f[B]\-n\f[] \f[I]uri\f[]] \f[I]url\f[] \f[I]property\f[]
+Gets a specific resource property.
+Every WebDAV property has a name and an XML namespace.
+A namespace can be specified with the \f[B]\-n\f[] option or with a
+prefixed name.
+The prefix and property name are separated by a colon \f[I]:\f[] as
+usual.
+.RS
 .PP
-mkdir [\f[B]\-pc\f[]] [\f[B]\-k\f[] \f[I]key\f[]] [\f[B]\-L\f[]
-\f[I]lock\f[]] \f[I]url\f[]
-.PP
-remove [\f[B]\-pc\f[]] [\f[B]\-L\f[] \f[I]lock\f[]] \f[I]url\f[]
-.PP
-copy [\f[B]\-pcO\f[]] [\f[B]\-L\f[] \f[I]lock\f[]] \f[I]srcurl\f[]
-\f[I]desturl\f[]
-.PP
-move [\f[B]\-pcO\f[]] [\f[B]\-L\f[] \f[I]lock\f[]] \f[I]srcurl\f[]
-\f[I]desturl\f[]
+If the \f[B]\-x\f[] option is specified, a valid XML document containing
+the value is printed on \f[I]stdout\f[].
 .PP
-export [\f[B]\-pc\f[]] [\f[B]\-o\f[] \f[I]file\f[]] [\f[B]\-u\f[]
-\f[I]date\f[]] \f[I]url\f[]
-.PP
-import [\f[B]\-pc\f[]] [\f[B]\-k\f[] \f[I]key\f[]] [\f[B]\-L\f[]
-\f[I]lock\f[]] \f[I]url\f[] \f[I]file\f[]
-.PP
-get\-property [\f[B]\-pcx\f[]] [\f[B]\-n\f[] \f[I]uri\f[]] \f[I]url\f[]
-\f[I]property\f[]
-.PP
-set\-property [\f[B]\-pcx\f[]] [\f[B]\-L\f[] \f[I]lock\f[]]
-[\f[B]\-n\f[] \f[I]uri\f[]] \f[I]url\f[] \f[I]property\f[]
-[\f[I]value\f[]]
-.PP
-remove\-property [\f[B]\-pc\f[]] [\f[B]\-n\f[] \f[I]uri\f[]]
-\f[I]url\f[] \f[I]property\f[]
-.PP
-lock [\f[B]\-pc\f[]] [\f[B]\-T\f[] \f[I]timeout\f[]] \f[I]url\f[]
-.PP
-unlock [\f[B]\-pc\f[]] [\f[B]\-L\f[] \f[I]lock\f[]] \f[I]url\f[]
-.PP
-info [\f[B]\-pc\f[]] \f[I]url\f[]
-.PP
-date [\f[I]url\f[]]
+If the property contains XML data and the \f[B]\-x\f[] option is not
+specified, the value is printed on \f[I]stderr\f[] in an XML\-like
+format.
+.RE
+.TP
+.B set\-property [\f[B]\-pcx\f[]] [\f[B]\-L\f[] \f[I]lock\f[]] [\f[B]\-n\f[] \f[I]uri\f[]] \f[I]url\f[] \f[I]property\f[] [\f[I]value\f[]]
+Sets a resource property to the specified value.
+See \f[B]get\-property\f[] for details.
+If no \f[I]value\f[] is specified, it is read from \f[I]stdin\f[].
+.RS
+.RE
+.TP
+.B remove\-property [\f[B]\-pc\f[]] [\f[B]\-n\f[] \f[I]uri\f[]] \f[I]url\f[] \f[I]property\f[]
+Removes a resource property.
+.RS
+.RE
+.TP
+.B lock [\f[B]\-pc\f[]] [\f[B]\-T\f[] \f[I]timeout\f[]] \f[I]url\f[]
+Creates a lock on the resource at \f[I]url\f[].
+The lock is an exclusive write lock with infinite depth.
+If the resource is sucessfully locked, a lock token for this resource is
+printed to \f[I]stdout\f[].
+This lock token should be saved to unlock the resource eventually.
+.RS
+.RE
+.TP
+.B unlock [\f[B]\-pc\f[]] [\f[B]\-L\f[] \f[I]lock\f[]] \f[I]url\f[]
+Unlocks the resource at \f[I]url\f[] with a lock token.
+If \f[I]lock\f[] is not specified, the token is read from
+\f[I]stdin\f[].
+.RS
+.RE
+.TP
+.B info [\f[B]\-pc\f[]] \f[I]url\f[]
+Prints some information and lists al properties for the resource at
+\f[I]url\f[].
+.RS
+.RE
+.TP
+.B date [\f[I]url\f[]]
+Gets the time from the server providing the resource denoted by
+\f[I]url\f[].
+If \f[I]url\f[] is not specified, this command prints the local time.
+This command is useful, if the server clock and the local clock are not
+in sync.
+.RS
+.RE
+.SH CONFIGURATION COMMANDS
+.TP
+.B add\-repository
+This command runs an interactive assistant that creates a repository
+configuration.
+.RS
+.RE
+.TP
+.B remove\-repository \f[I]name\f[]
+Removes the repository with the specified \f[I]name\f[] from the
+configuration.
+.RS
+.RE
+.TP
+.B list\-repositories
+Lists all currently configured repositories.
+.RS
+.RE
+.TP
+.B check\-config
+Validates the \f[B]$HOME/.dav/config.xml\f[] configuration file.
+.RS
+.RE
 .SH GENERAL OPTIONS
 .PP
 The following options can be used with all commands.
 .TP
-.B \f[B]\-i\f[]
+.B \-i
 Disable cert verification.
 .RS
 .RE
 .TP
-.B \f[B]\-N\f[]
+.B \-N
 Disable authentication prompt.
 .RS
 .RE
 .TP
-.B \f[B]\-v\f[]
+.B \-v
 Verbose output.
 .RS
 .RE
 .SH COMMAND OPTIONS
 .TP
-.B \f[B]\-a\f[]
+.B \-a
 Show all files.
 .RS
 .RE
 .TP
-.B \f[B]\-c\f[]
+.B \-c
 Enable full encryption.
 .RS
 .RE
 .TP
-.B \f[B]\-d\f[]
+.B \-d
 Order by last modified date.
 .RS
 .RE
 .TP
-.B \f[B]\-e\f[]
+.B \-e
 Show extended flags.
 .RS
 .RE
 .TP
-.B \f[B]\-K\f[]
+.B \-K
 Keep already present files.
 .RS
 .RE
 .TP
-.B \f[B]\-k\f[] \f[I]key\f[]
+.B \-k \f[I]key\f[]
 Key to use for encryption.
 .RS
 .RE
 .TP
-.B \f[B]\-l\f[]
+.B \-l
 Print resources in long list format.
 .RS
 .RE
 .TP
-.B \f[B]\-L\f[] \f[I]lock\f[]
+.B \-L \f[I]lock\f[]
 Specificy lock token.
 .RS
 .RE
 .TP
-.B \f[B]\-n\f[] \f[I]uri\f[]
+.B \-n \f[I]uri\f[]
 Specify namespace \f[I]uri\f[].
+There are two namespaces configured by default.
 .RS
+.IP "1." 3
+\f[I]D\f[] for the \f[I]DAV:\f[] namespace
+.IP "2." 3
+\f[I]idav\f[] for the \f[I]http://davutils.org/\f[] namespace
 .RE
 .TP
-.B \f[B]\-o\f[] \f[I]file\f[]
+.B \-o \f[I]file\f[]
 Write output to \f[I]file\f[].
 Use \[aq]\-\[aq] for stdout.
 .RS
 .RE
 .TP
-.B \f[B]\-O\f[]
+.B \-O
 Override resources.
 .RS
 .RE
 .TP
-.B \f[B]\-p\f[]
+.B \-p
 Don\[aq]t encrypt or decrypt files.
 .RS
 .RE
 .TP
-.B \f[B]\-R\f[]
+.B \-R
 Recursively do the operation for all children.
 .RS
 .RE
 .TP
-.B \f[B]\-t\f[]
+.B \-t
 Print content type.
 .RS
 .RE
 .TP
-.B \f[B]\-T\f[] \f[I]sec\f[]
+.B \-T \f[I]sec\f[]
 Timeout in seconds.
 .RS
 .RE
 .TP
-.B \f[B]\-u\f[] \f[I]date\f[]
+.B \-u \f[I]date\f[]
 Get resources which are modified since the specified \f[I]date\f[].
 .RS
 .RE
 .TP
-.B \f[B]\-x\f[]
+.B \-x
 XML property content.
 .RS
 .RE

--- a/docs/src/dav.1.md	Sun Jul 01 16:45:03 2018 +0200
+++ b/docs/src/dav.1.md	Sun Jul 01 17:14:17 2018 +0200
@@ -17,101 +17,155 @@
 # COMMANDS
 
 list [**-altdepcR**] [**-u** *date*] *url*
+:   Lists the files at *url*.
 
 get [**-pcRK**] [**-o** *file*] [**-u** *date*] *url*
+:   Downloads a resource from *url*.
 
 put [**-pcR**] [**-k** *key*] [**-L** *lock*] *url* *file*
+:   Uploads a resource to *url*.
 
 mkdir [**-pc**] [**-k** *key*] [**-L** *lock*] *url*
+:   Creates a new collection at *url*.
 
 remove [**-pc**] [**-L** *lock*] *url*
+:   Deletes a resource or collection at *url*
 
 copy [**-pcO**] [**-L** *lock*] *srcurl* *desturl*
+:   Copies a resource or collection from *srcurl* to *desturl*.
 
 move [**-pcO**] [**-L** *lock*] *srcurl* *desturl*
+:   Moves a resource or collection from *srcurl* to *desturl*.
 
 export [**-pc**] [**-o** *file*] [**-u** *date*] *url*
+:   Exports a resource or collection to a **tar(5)** archive. By default the
+    data is written to *stdout*, but you may specify a *file* with the **-o**
+    option.
 
 import [**-pc**] [**-k** *key*] [**-L** *lock*] *url* *file*
+:   Uploads and extracts the contents of the **tar(5)** archive *file* to *url*.
 
 get-property [**-pcx**] [**-n** *uri*] *url* *property*
+:   Gets a specific resource property. Every WebDAV property has a name and an
+    XML namespace. A namespace can be specified with the **-n** option or with
+    a prefixed name. The prefix and property name are separated by a colon
+    *:* as usual.
+    
+    If the **-x** option is specified, a valid XML document containing the
+    value is printed on *stdout*.
+    
+    If the property contains XML data and the **-x** option is not specified, 
+    the value is printed on *stderr* in an XML-like format.
 
 set-property [**-pcx**] [**-L** *lock*] [**-n** *uri*] *url* *property* [*value*]
+:   Sets a resource property to the specified value. See **get-property** for
+    details. If no *value* is specified, it is read from *stdin*.
 
 remove-property [**-pc**] [**-n** *uri*] *url* *property*
+:   Removes a resource property.
 
 lock [**-pc**] [**-T** *timeout*] *url*
+:   Creates a lock on the resource at *url*. The lock is an exclusive write
+    lock with infinite depth. If the resource is sucessfully locked, a lock
+    token for this resource is printed to *stdout*. This lock token should be
+    saved to unlock the resource eventually.
 
 unlock [**-pc**] [**-L** *lock*] *url*
+:   Unlocks the resource at *url* with a lock token. If *lock* is not
+    specified, the token is read from *stdin*.
 
 info [**-pc**] *url*
+:   Prints some information and lists al properties for the resource at *url*.
 
 date [*url*]
+:   Gets the time from the server providing the resource denoted by *url*.
+    If *url* is not specified, this command prints the local time.
+    This command is useful, if the server clock and the local clock are not
+    in sync.
+
+# CONFIGURATION COMMANDS
+
+add-repository
+:   This command runs an interactive assistant that creates a repository
+    configuration.
+
+remove-repository *name*
+:   Removes the repository with the specified *name* from the configuration.
+
+list-repositories
+:   Lists all currently configured repositories.
+
+check-config
+:   Validates the **$HOME/.dav/config.xml** configuration file.
 
 # GENERAL OPTIONS
 
 The following options can be used with all commands.
 
-**-i**
+-i
 :   Disable cert verification.
 
-**-N**
+-N
 :   Disable authentication prompt.
 
-**-v**
+-v
 :   Verbose output.
 
 # COMMAND OPTIONS
 
-**-a**
+-a
 :   Show all files.
 
-**-c**
+-c
 :   Enable full encryption.
 
-**-d**
+-d
 :   Order by last modified date.
 
-**-e**
+-e
 :   Show extended flags.
 
-**-K**
+-K
 :   Keep already present files.
 
-**-k** *key*
+-k *key*
 :   Key to use for encryption.
 
-**-l**
+-l
 :   Print resources in long list format.
 
-**-L** *lock*
+-L *lock*
 :   Specificy lock token.
 
-**-n** *uri* 
-:   Specify namespace *uri*.
+-n *uri* 
+:   Specify namespace *uri*. There are two namespaces configured by default.
 
-**-o** *file*
+    1. *D* for the *DAV:* namespace
+
+    2. *idav* for the *http://davutils.org/* namespace
+
+-o *file*
 :   Write output to *file*. Use '-' for stdout.
 
-**-O**
+-O
 :   Override resources.
 
-**-p**
+-p
 :   Don't encrypt or decrypt files.
 
-**-R**
+-R
 :   Recursively do the operation for all children.
 
-**-t**
+-t
 :   Print content type.
 
-**-T** *sec*
+-T *sec*
 :   Timeout in seconds.
 
-**-u** *date*
+-u *date*
 :   Get resources which are modified since the specified *date*.
 
-**-x**
+-x
 :   XML property content.