Converted manpage to Restructured Text

6 files changed, 253 insertions, 288 deletions

diff --git a/.travis.yml b/.travis.yml
index ce246c4..a732c24 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -12,6 +12,7 @@ addons:
     - clang
     - gcc
     - gcc-6
+    - python-docutils
 before_install:
    - pip install pip==8.1.1 && pip3 install pip==8.1.1
 install: test/travis-install.sh
diff --git a/Makefile.am b/Makefile.am
index 6ec8e65..1ae5006 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -17,14 +17,10 @@ sshfs_CFLAGS = $(SSHFS_CFLAGS)
 sshfs_CPPFLAGS = -D_REENTRANT -DFUSE_USE_VERSION=31 -DLIBDIR=\"$(libdir)\" \
                  -DIDMAP_DEFAULT="\"$(IDMAP_DEFAULT)\""
 
-EXTRA_DIST = sshfs.1.in meson.build ChangeLog.rst
-CLEANFILES = sshfs.1 sshfs.1.tmp
+EXTRA_DIST = sshfs.rst sshfs.1 meson.build ChangeLog.rst
+CLEANFILES = sshfs.1
 
 dist_man_MANS = sshfs.1
 
-sshfs.1: sshfs.1.in
-	$(AM_V_GEN)sed \
-	    -e 's/[@]IDMAP_DEFAULT@/$(IDMAP_DEFAULT)/g' \
-	    -e 's/[@]UNMOUNT_COMMAND@/$(UNMOUNT_COMMAND)/g' \
-	    <$(srcdir)/sshfs.1.in >sshfs.1.tmp || exit 1; \
-	mv sshfs.1.tmp sshfs.1
+sshfs.1: sshfs.rst
+	rst2man sshfs.rst sshfs.1
diff --git a/README.rst b/README.rst
index 1ec2d72..cef05de 100644
--- a/README.rst
+++ b/README.rst
@@ -91,41 +91,6 @@ point, so if you depend on using autotools for some reason please let
 the sshfs developers know!
 
 
-Caveats
--------
-
-Rename
-~~~~~~
-
-Some SSH servers do not support atomically overwriting the destination
-when renaming a file. In this case you will get an error when you
-attempt to rename a file and the destination already exists. A
-workaround is to first remove the destination file, and then do the
-rename. SSHFS can do this automatically if you call it with `-o
-workaround=rename`. However, in this case it is still possible that
-someone (or something) recreates the destination file after SSHFS has
-removed it, but before SSHFS had the time to rename the old file. In
-this case, the rename will still fail.
-
-Hardlinks
-~~~~~~~~~
-
-If the SSH server supports the *hardlinks* extension, SSHFS will allow
-you to create hardlinks. However, hardlinks will always appear as
-individual files when seen through an SSHFS mount, i.e. they will
-appear to have different inodes and an *st_nlink* value of 1.
-
-
-O_APPEND
-~~~~~~~~
-
-When writeback caching is enabled, SSHFS cannot reliably support the
-``O_APPEND`` open flag and thus signals an error on open.  To enable
-support for unreliable ``O_APPEND`` (which may overwrite data if the
-file changes on the server at a bad time), mount the file system with
-``-o unreliable_append``.
-
-
 Getting Help
 ------------
 
diff --git a/meson.build b/meson.build
index 1aff672..315f330 100644
--- a/meson.build
+++ b/meson.build
@@ -25,6 +25,8 @@ if not cc.compiles(code, args: [ '-O0', '-Werror=unused-result' ])
 endif
 
 
+rst2man = find_program('rst2man', required: false)
+  
 cfg = configuration_data()
 
 cfg.set_quoted('PACKAGE_VERSION', meson.project_version())
@@ -39,9 +41,6 @@ else
   cfg.set_quoted('IDMAP_DEFAULT', 'none')
 endif
 
-configure_file(input: 'sshfs.1.in',
-               output: 'sshfs.1',
-               configuration : cfg)
 configure_file(output: 'config.h',
                configuration : cfg)
 
@@ -56,9 +55,14 @@ executable('sshfs', sshfs_sources,
            install: true,
            install_dir: get_option('bindir'))
 
-# This is a little ugly. Is there a better way to tell Meson that the
-# manpage is in the build directory?
-install_man(join_paths(meson.current_build_dir(), 'sshfs.1'))
+if rst2man.found()
+    custom_target('manpages', input: [ 'sshfs.rst' ], output: [ 'sshfs.1' ],
+                  command: [rst2man, '@INPUT@', '@OUTPUT@'], install: true,
+                  install_dir: join_paths(get_option('mandir'), '1'))
+else
+    message('rst2man not found, not building manual page.')
+endif
+
 
 subdir('test')
 
diff --git a/sshfs.1.in b/sshfs.1.in
deleted file mode 100644
index 20fbd17..0000000
--- a/sshfs.1.in
+++ /dev/null
@@ -1,239 +0,0 @@
-.TH SSHFS "1" "April 2008" "SSHFS version 2.0" "User Commands"
-.SH NAME
-SSHFS \- filesystem client based on ssh
-.SH SYNOPSIS
-.SS mounting
-.TP
-\fBsshfs\fP [\fIuser\fP@]\fBhost\fP:[\fIdir\fP] \fBmountpoint\fP [\fIoptions\fP]
-.SS unmounting
-.TP
-\fB@UNMOUNT_COMMAND@ mountpoint\fP
-.SH DESCRIPTION
-SSHFS (Secure SHell FileSystem) is a file system for Linux (and other
-operating systems with a FUSE implementation, such as Mac OS X or FreeBSD)
-capable of operating on files on a remote computer using just a secure
-shell login on the remote computer. On the local computer where the SSHFS
-is mounted, the implementation makes use of the FUSE (Filesystem in
-Userspace) kernel module. The practical effect of this is that the end user
-can seamlessly interact with remote files being securely served over SSH
-just as if they were local files on his/her computer. On the remote
-computer the SFTP subsystem of SSH is used.
-.PP
-If \fIhost\fP is a numeric IPv6 address, it needs to be enclosed in
-square brackets.
-.SH OPTIONS
-.SS "general options:"
-.TP
-\fB\-o\fR opt,[opt...]
-mount options
-.TP
-\fB\-h\fR   \fB\-\-help\fR
-print help
-.TP
-\fB\-V\fR   \fB\-\-version\fR
-print version
-.SS "SSHFS options:"
-.TP
-\fB\-p\fR PORT
-equivalent to '\-o port=PORT'
-.TP
-\fB\-C\fR
-equivalent to '\-o compression=yes'
-.TP
-\fB\-F\fR ssh_configfile
-specifies alternative ssh configuration file
-.TP
-\fB\-1\fR
-equivalent to '\-o ssh_protocol=1'
-.TP
-\fB\-o\fR reconnect
-reconnect to server
-.TP
-\fB\-o\fR delay_connect
-delay connection to server
-.TP
-\fB\-o\fR sshfs_sync
-synchronous writes
-.TP
-\fB\-o\fR no_readahead
-synchronous reads (no speculative readahead)
-.TP
-\fB\-o\fR sync_readdir
-synchronous readdir
-.TP
-\fB\-o\fR sshfs_debug
-print some debugging information
-.TP
-\fB\-o\fR workaround=LIST
-colon separated list of workarounds
-.RS 8
-.TP
-none
-no workarounds enabled
-.TP
-[no]rename
-fix renaming to existing file (default: off)
-.TP
-[no]nodelaysrv
-set nodelay tcp flag in ssh (default: off)
-.TP
-[no]truncate
-fix truncate for old servers (default: off)
-.TP
-[no]buflimit
-fix buffer fillup bug in server (default: on)
-.RE
-.TP
-\fB\-o\fR idmap=TYPE
-user/group ID mapping (default: @IDMAP_DEFAULT@)
-.RS 8
-.TP
-none
-no translation of the ID space
-.TP
-user
-only translate UID/GID of connecting user
-.TP
-file
-translate UIDs/GIDs based upon the contents of \fBuidfile \fR and
-\fBgidfile\fR
-.RE
-.TP
-\fB\-o\fR uidfile=FILE
-file containing username:uid mappings for \fBidmap=file\fR
-.RE
-.TP
-\fB\-o\fR gidfile=FILE
-file containing groupname:gid mappings for \fBidmap=file\fR
-.RE
-.TP
-\fB\-o\fR nomap=TYPE
-with idmap=file, how to handle missing mappings
-.RS 8
-.TP
-ignore
-don't do any re-mapping
-.TP
-error
-return an error (default)
-.RE
-.TP
-\fB\-o\fR ssh_command=CMD
-execute CMD instead of 'ssh'
-.TP
-\fB\-o\fR ssh_protocol=N
-ssh protocol to use (default: 2)
-.TP
-\fB\-o\fR sftp_server=SERV
-path to sftp server or subsystem (default: sftp)
-.TP
-\fB\-o\fR directport=PORT
-directly connect to PORT bypassing ssh
-.TP
-\fB\-o\fR slave
-communicate over stdin and stdout bypassing network
-.TP
-\fB\-o\fR disable_hardlink
-link(2) will return with errno set to ENOSYS.  Hard links don't currently work
-perfectly on sshfs, and this confuses some programs.  If that happens try
-disabling hard links with this option.
-.TP
-\fB\-o\fR transform_symlinks
-transform absolute symlinks to relative
-.TP
-\fB\-o\fR follow_symlinks
-follow symlinks on the server
-.TP
-\fB\-o\fR no_check_root
-don't check for existence of 'dir' on server
-.TP
-\fB\-o\fR password_stdin
-read password from stdin (only for pam_mount!)
-.TP
-\fB\-o\fR SSHOPT=VAL
-ssh options (see man ssh_config)
-.SS "FUSE options:"
-.TP
-\fB\-d\fR   \fB\-o\fR debug
-enable debug output (implies \fB\-f\fR)
-.TP
-\fB\-f\fR
-foreground operation
-.TP
-\fB\-s\fR
-disable multi\-threaded operation
-.TP
-\fB\-o\fR allow_other
-allow access to other users
-.TP
-\fB\-o\fR allow_root
-allow access to root
-.HP
-\fB\-o\fR default_permissions
-enable permission checking by kernel
-.TP
-\fB\-o\fR fsname=NAME
-set filesystem name
-.TP
-\fB\-o\fR subtype=NAME
-set filesystem type
-.TP
-\fB\-o\fR max_read=N
-set maximum size of read requests
-.TP
-\fB\-o\fR kernel_cache
-cache files in kernel
-.TP
-\fB\-o\fR [no]auto_cache
-enable caching based on modification times
-.TP
-\fB\-o\fR umask=M
-set file permissions (octal)
-.TP
-\fB\-o\fR uid=N
-set file owner
-.TP
-\fB\-o\fR gid=N
-set file group
-.TP
-\fB\-o\fR entry_timeout=T
-cache timeout for names (1.0s)
-.TP
-\fB\-o\fR negative_timeout=T
-cache timeout for deleted names (0.0s)
-.TP
-\fB\-o\fR attr_timeout=T
-cache timeout for attributes (1.0s)
-.TP
-\fB\-o\fR ac_attr_timeout=T
-auto cache timeout for attributes (attr_timeout)
-.TP
-\fB\-o\fR modules=M1[:M2...]
-names of modules to push onto filesystem stack
-.TP
-\fB\-o\fR max_write=N
-set maximum size of write requests
-.SS "Module options:"
-.TP
-[subdir]
-.TP
-\fB\-o\fR subdir=DIR
-prepend this directory to all paths (mandatory)
-.TP
-\fB\-o\fR [no]rellinks
-transform absolute symlinks to relative
-.TP
-[iconv]
-.TP
-\fB\-o\fR from_code=CHARSET
-original encoding of file names (default: UTF-8)
-.TP
-\fB\-o\fR to_code=CHARSET
-new encoding of the file names (default: ISO-8859-2)
-.PD
-.SH "AUTHORS"
-.LP
-SSHFS has been written by Miklos Szeredi <miklos@szeredi.hu>.
-.LP
-This man page was written by Bartosz Fenski <fenio@debian.org> for the
-Debian GNU/Linux distribution (but it may be used by others).
diff --git a/sshfs.rst b/sshfs.rst
new file mode 100644
index 0000000..f768fa0
--- /dev/null
+++ b/sshfs.rst
@@ -0,0 +1,238 @@
+=======
+ SSHFS
+=======
+
+---------------------------------------------
+ filesystem client based on SSH
+---------------------------------------------
+
+:Manual section: 1
+:Manual group: User Commands
+
+Synopsis
+========
+
+To mount a filesystem::
+
+   sshfs [user@]host:[dir] mountpoint [options]
+
+If *host* is a numeric IPv6 address, it needs to be enclosed in square
+brackets.
+
+To unmount it::
+
+  fusermount3 -u mountpoint   # Linux
+  umount mountpoint           # OS X, FreeBSD
+
+Description
+===========
+
+SSHFS allows you to mount a remote filesystem using SSH (more
+precisely, the SFTP subsystem). Most SSH servers support and enable
+this SFTP access by default, so SSHFS is very simple to use - there's
+nothing to do on the server-side.
+
+SSHFS uses FUSE (Filesystem in Userspace) and should work on any
+operating system that provides a FUSE implementation. Currently,
+this includes Linux, FreeBSD and Mac OS X.
+
+It is recommended to run SSHFS as regular user (not as root).  For
+this to work the mountpoint must be owned by the user.  If username is
+omitted SSHFS will use the local username. If the directory is
+omitted, SSHFS will mount the (remote) home directory.  If you need to
+enter a password sshfs will ask for it (actually it just runs ssh
+which ask for the password if needed).
+
+
+Options
+=======
+
+
+-o opt,[opt...]
+   mount options, see below for details. A a variety of SSH options can
+   be given here as well, see the manual pages for *sftp(1)* and
+   *ssh_config(5)*.
+
+-h, --help
+   print help and exit.
+
+-V, --version
+   print version information and exit.
+
+-d, --debug
+   print debugging information.
+
+-p PORT
+   equivalent to '-o port=PORT'
+
+-f
+   do not daemonize, stay in foreground.
+
+-s
+   Single threaded operation.
+
+-C
+   equivalent to '-o compression=yes'
+
+-F ssh_configfile
+   specifies alternative ssh configuration file
+
+-1
+   equivalent to '-o ssh_protocol=1'
+
+-o reconnect
+   automatically reconnect to server if connection is
+   interrupted. Attempts to access files that were opened before the
+   reconnection will give errors and need to be re-opened.
+
+-o delay_connect
+   Don't immediately connect to server, wait until mountpoint is first
+   accessed.
+
+-o sshfs_sync
+   synchronous writes. This will slow things down, but may be useful
+   in some situations.
+
+-o no_readahead
+   Only read exactly the data that was requested, instead of
+   speculatively reading more to anticipate the next read request.
+
+-o sync_readdir
+   synchronous readdir. This will slow things down, but may be useful
+   in some situations.
+
+-o workaround=LIST
+   Enable the specified workaround. See the `Caveats` section below
+   for some additional information. Possible values are:
+
+   :rename: Emulate overwriting an existing file by deleting and
+        renaming.
+   :truncate: Work around servers that don't support truncate by
+        coping the whole file, truncating it locally, and sending it
+        back.
+   :fstat: Work around broken servers that don't support *fstat()* by
+           using *stat* instead.
+   :buflimit: Work around OpenSSH "buffer fillup" bug.
+
+-o idmap=TYPE
+   How to map remote UID/GIDs to local values. Possible values are:
+
+   :none: no translation of the ID space (default).
+
+   :user: map the UID/GID of the remote user to UID/GID of the
+            mounting user.
+
+   :file: translate UIDs/GIDs based upon the contents of `--uidfile`
+            and `--gidfile`.
+
+-o uidfile=FILE
+   file containing ``username:uid`` mappings for `-o idmap=file`
+
+-o gidfile=FILE
+   file containing ``groupname:gid`` mappings for `-o idmap=file`
+
+-o nomap=TYPE
+   with idmap=file, how to handle missing mappings:
+
+   :ignore: don't do any re-mapping
+   :error:  return an error (default)
+
+-o ssh_command=CMD
+   execute CMD instead of 'ssh'
+
+-o ssh_protocol=N
+   ssh protocol to use (default: 2)
+
+-o sftp_server=SERV
+   path to sftp server or subsystem (default: sftp)
+
+-o directport=PORT
+   directly connect to PORT bypassing ssh
+
+-o slave
+   communicate over stdin and stdout bypassing network
+
+-o disable_hardlink
+   `link(2)` will return with errno set to ENOSYS.  Hard links
+   don't currently work perfectly on sshfs, and this confuses some
+   programs.  If that happens try disabling hard links with this
+   option.
+
+-o transform_symlinks
+   transform absolute symlinks on remote side to relative symlinks.
+
+-o follow_symlinks
+   follow symlinks on the server, i.e. present them as regular
+   files on the client.
+
+-o no_check_root
+   don't check for existence of 'dir' on server
+
+-o password_stdin
+   read password from stdin (only for pam_mount!)
+
+In addition, SSHFS accepts several options common to all FUSE file
+systems. These are described in the `mount.fuse` manpage (look
+for "general", "libfuse specific", and "high-level API" options).
+
+Caveats / Workarounds
+=====================
+
+Hardlinks
+~~~~~~~~~
+
+If the SSH server supports the *hardlinks* extension, SSHFS will allow
+you to create hardlinks. However, hardlinks will always appear as
+individual files when seen through an SSHFS mount, i.e. they will
+appear to have different inodes and an *st_nlink* value of 1.
+
+
+Rename
+~~~~~~
+
+Some SSH servers do not support atomically overwriting the destination
+when renaming a file. In this case you will get an error when you
+attempt to rename a file and the destination already exists. A
+workaround is to first remove the destination file, and then do the
+rename. SSHFS can do this automatically if you call it with `-o
+workaround=rename`. However, in this case it is still possible that
+someone (or something) recreates the destination file after SSHFS has
+removed it, but before SSHFS had the time to rename the old file. In
+this case, the rename will still fail.
+
+
+O_APPEND
+~~~~~~~~
+
+When writeback caching is enabled, SSHFS cannot reliably support the
+``O_APPEND`` open flag and thus signals an error on open.  To enable
+support for unreliable ``O_APPEND`` (which may overwrite data if the
+file changes on the server at a bad time), mount the file system with
+``-o unreliable_append``.
+
+
+See also
+========
+
+The `mount.fuse(8)` manpage.
+
+Getting Help
+============
+
+If you need help, please ask on the <fuse-sshfs@lists.sourceforge.net>
+mailing list (subscribe at
+https://lists.sourceforge.net/lists/listinfo/fuse-sshfs).
+
+Please report any bugs on the GitHub issue tracker at
+https://github.com/libfuse/libfuse/issues.
+
+
+Authors
+=======
+
+SSHFS is currently maintained by Nikolaus Rath <Nikolaus@rath.org>,
+and was created by Miklos Szeredi <miklos@szeredi.hu>.
+
+This man page was originally written by Bartosz Fenski
+<fenio@debian.org> for the Debian GNU/Linux distribution (but it may
+be used by others).