changeset 283:1fc3b04b39fa

Build and package manual pages for fzfs, fzfs-mount and fzfs-umount. Also put some stub info into the manual page for local-bsdtools.
author Franz Glasner <fzglas.hg@dom66.de>
date Sun, 18 Sep 2022 01:31:47 +0200
parents 7811505d68d4
children 106cd5d9da7e
files Makefile docs/conf.py docs/index.rst docs/man/fzfs-mount.rst docs/man/fzfs-umount.rst docs/man/fzfs.rst pkg-plist sbin/fzfs
diffstat 8 files changed, 154 insertions(+), 30 deletions(-) [+]
line wrap: on
line diff
--- a/Makefile	Sun Sep 18 00:27:04 2022 +0200
+++ b/Makefile	Sun Sep 18 01:31:47 2022 +0200
@@ -81,6 +81,8 @@
 .endfor
 
 post-install-DOCS-on:
-	${INSTALL_DATA} ${WRKSRC}/docs/_build/man/local-bsdtools.1 ${STAGEDIR}${LOCALBASE}/man/man1/local-bsdtools.1
+.for _mp in local-bsdtools.1 fzfs.1 fzfs-mount.1 fzfs-umount.1
+	${INSTALL_DATA} ${WRKSRC}/docs/_build/man/${_mp} ${STAGEDIR}${LOCALBASE}/man/man1/${_mp}
+.endfor
 
 .include <bsd.port.mk>
--- a/docs/conf.py	Sun Sep 18 00:27:04 2022 +0200
+++ b/docs/conf.py	Sun Sep 18 01:31:47 2022 +0200
@@ -53,3 +53,21 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ("index", "local-bsdtools", 'FreeBSD specific administration helper tools', [author], 1),
+    ("man/fzfs", "fzfs", "A ZFS management helper tool", [author], 1),
+    ("man/fzfs-mount", "fzfs-mount", "Mount ZFS datasets recursively", [author], 1),
+    ("man/fzfs-umount", "fzfs-umount", "Unmount ZFS datasets recursively", [author], 1),        
+]
+
+
+# -- Link to manual pages ----------------------------------------------------
+
+manpages_url = "https://www.freebsd.org/cgi/man.cgi?query={page}&sektion={section}"
+
--- a/docs/index.rst	Sun Sep 18 00:27:04 2022 +0200
+++ b/docs/index.rst	Sun Sep 18 01:31:47 2022 +0200
@@ -1,20 +1,30 @@
+.. -*- coding: utf-8; indent-tabs-mode: nil; -*-
+
 .. local-bsdtools documentation master file, created by
    sphinx-quickstart on Sat Sep 17 21:32:09 2022.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+
 
-Welcome to local-bsdtools's documentation!
-==========================================
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+local-bsdtools
+==============
 
 
+See Also
+--------
 
-Indices and tables
-==================
+- :manpage:`bsmtp2dma(1)`
+- :manpage:`check-ports(1)`
+- :manpage:`fjail(1)`
+- :manpage:`ftjail(1)`
+- :manpage:`fpkg(1)`
+- :manpage:`fzfs(1)`
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+  * :manpage:`fzfs-mount(1)`
+  * :manpage:`fzfs-umount(1)`
+
+
+Environment
+-----------
+
+Because the tools use different helper tools like :command:`zfs` or
+:command:`pkg` the relevant environment variables according to this tools
+also apply generally.
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/man/fzfs-mount.rst	Sun Sep 18 01:31:47 2022 +0200
@@ -0,0 +1,53 @@
+.. -*- coding: utf-8; indent-tabs-mode: nil; -*-
+
+:orphan:
+
+
+fzfs-mount
+==========
+
+Synopsis
+--------
+
+**fzfs mount** [-O] [-N] [-P] [-n] [-u] **DATASET** [**MOUNTPOINT**]
+
+
+Description
+-----------
+
+Mount the ZFS dataset **DATASET** and all its children to mountpoint
+**MOUNTPOINT**.
+
+
+Options
+-------
+
+.. program:: fzfs mount
+
+.. option:: -O
+
+   Also mount datasets at mountpoints outside of their "natural"
+   and inherited mountpoints.
+
+.. option:: -N
+
+   Mount at their "natural" configured ZFS mountpoints
+   (the **MOUNTPOINT** argument is not required in this case).
+
+.. option:: -P
+
+   Do not mount the given parent **DATASET** but only its children.
+
+.. option:: -n
+
+   Do not really mount anything but show what would be mounted where.
+
+.. option:: -u
+
+   Alias of :option:`-n`
+
+
+See Also
+--------
+
+:manpage:`fzfs-umount(1)`
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/man/fzfs-umount.rst	Sun Sep 18 01:31:47 2022 +0200
@@ -0,0 +1,27 @@
+.. -*- coding: utf-8; indent-tabs-mode: nil; -*-
+
+:orphan:
+
+
+fzfs-umount
+===========
+
+
+Synopsis
+--------
+
+**fzfs umount DATASET**
+
+**fzfs unmount DATASET**
+
+
+Description
+-----------
+
+Unmount the mounted DATASET and all its children.
+
+
+See Also
+--------
+
+:manpage:`fzfs-mount(1)`
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/man/fzfs.rst	Sun Sep 18 01:31:47 2022 +0200
@@ -0,0 +1,26 @@
+.. -*- coding: utf-8; indent-tabs-mode: nil; -*-
+
+:orphan:
+
+
+fzfs
+====
+
+Synopsis
+--------
+
+**fzfs** -hV
+
+**fzfs subcommand**
+
+
+Subcommands
+-----------
+
+:manpage:`fzfs-mount(1)`
+
+    Recursively mount a ZFS dataset and its children
+
+:manpage:`fzfs-umount(1)`
+
+    Recursively unmount a ZFS datasets and its children
--- a/pkg-plist	Sun Sep 18 00:27:04 2022 +0200
+++ b/pkg-plist	Sun Sep 18 01:31:47 2022 +0200
@@ -7,6 +7,9 @@
 sbin/fpkg
 sbin/fzfs
 %%DOCS%%man/man1/local-bsdtools.1.gz
+%%DOCS%%man/man1/fzfs.1.gz
+%%DOCS%%man/man1/fzfs-mount.1.gz
+%%DOCS%%man/man1/fzfs-umount.1.gz
 @sample %%ETCDIR%%/bsmtp2dma.conf.sample
 @sample %%ETCDIR%%/package-mapping.conf.sample
 @sample %%ETCDIR%%/pkgtools.conf.sample
--- a/sbin/fzfs	Sun Sep 18 00:27:04 2022 +0200
+++ b/sbin/fzfs	Sun Sep 18 01:31:47 2022 +0200
@@ -28,27 +28,12 @@
 
 COMMANDS:
 
-  mount [-O] [-u] [-n] DATASET [MOUNTPOINT]
-
-    Mount the ZFS dataset DATASET and all its children to mountpoint
-    MOUNTPOINT
-
-    -O        Also mount datasets at mountpoints outside of their "natural"
-              and inherited mountpoints
-    -N        Mount at their "natural" configured ZFS mountpoints
-              (MOUNTPOINT is not required)
-    -P        Do not mount the given parent DATASET but only its children
-    -n        Do not really mount but show what would be mounted where
-    -u        Alias of -n
+  mount [-O] [-N] [-P] [-u] [-n] DATASET [MOUNTPOINT]
 
   umount DATASET
 
-    Unmount the mounted DATASET and all its children
-
   unmount
 
-    Alias for `umount'"'"'
-
 '
 
 #