From 10aeee95d01bed3608c8a6b760d9023206eacc2b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>
Date: Sat, 23 Sep 2023 13:43:55 +0200
Subject: [PATCH] =?UTF-8?q?man:=20rename=20systemd-cryptsetup@.service=20?=
 =?UTF-8?q?=E2=86=92=20systemd-cryptsetup?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

We already had the other name as alias, so this just changes what is the "main"
name. The text is adjusted to describe the command briefly.
---
 man/rules/meson.build                         |  4 +-
 ...up@.service.xml => systemd-cryptsetup.xml} | 48 ++++++++++++++-----
 2 files changed, 38 insertions(+), 14 deletions(-)
 rename man/{systemd-cryptsetup@.service.xml => systemd-cryptsetup.xml} (69%)

diff --git a/man/rules/meson.build b/man/rules/meson.build
index 2884cc32b41..7e145ac0b17 100644
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -914,9 +914,9 @@ manpages = [
  ['systemd-creds', '1', [], ''],
  ['systemd-cryptenroll', '1', [], 'HAVE_LIBCRYPTSETUP'],
  ['systemd-cryptsetup-generator', '8', [], 'HAVE_LIBCRYPTSETUP'],
- ['systemd-cryptsetup@.service',
+ ['systemd-cryptsetup',
   '8',
-  ['systemd-cryptsetup'],
+  ['systemd-cryptsetup@.service'],
   'HAVE_LIBCRYPTSETUP'],
  ['systemd-debug-generator', '8', [], ''],
  ['systemd-delta', '1', [], ''],
diff --git a/man/systemd-cryptsetup@.service.xml b/man/systemd-cryptsetup.xml
similarity index 69%
rename from man/systemd-cryptsetup@.service.xml
rename to man/systemd-cryptsetup.xml
index 91a4f2eb9d8..493236da83d 100644
--- a/man/systemd-cryptsetup@.service.xml
+++ b/man/systemd-cryptsetup.xml
@@ -3,38 +3,62 @@
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
-<refentry id="systemd-cryptsetup@.service" conditional='HAVE_LIBCRYPTSETUP'>
+<refentry id="systemd-cryptsetup" conditional='HAVE_LIBCRYPTSETUP'>
 
   <refentryinfo>
-    <title>systemd-cryptsetup@.service</title>
+    <title>systemd-cryptsetup</title>
     <productname>systemd</productname>
   </refentryinfo>
 
   <refmeta>
-    <refentrytitle>systemd-cryptsetup@.service</refentrytitle>
+    <refentrytitle>systemd-cryptsetup</refentrytitle>
     <manvolnum>8</manvolnum>
   </refmeta>
 
   <refnamediv>
+    <refname>systemd-cryptsetup</refname>
     <refname>systemd-cryptsetup@.service</refname>
     <!-- <refname>system-systemd\x2dcryptsetup.slice</refname> — this causes meson to go haywire because it
          thinks this is a (windows) path. Let's just not create the alias for this name, and only include it
          in the synopsis. -->
-    <refname>systemd-cryptsetup</refname>
     <refpurpose>Full disk decryption logic</refpurpose>
   </refnamediv>
 
   <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>systemd-cryptsetup</command>
+      <arg choice="opt" rep="repeat">OPTIONS</arg>
+      <arg choice="plain">attach</arg>
+      <arg choice="plain">VOLUME</arg>
+      <arg choice="plain">SOURCE-DEVICE</arg>
+      <arg choice="opt">KEY-FILE</arg>
+      <arg choice="opt">CONFIG</arg>
+    </cmdsynopsis>
+
+    <cmdsynopsis>
+      <command>systemd-cryptsetup</command>
+      <arg choice="opt" rep="repeat">OPTIONS</arg>
+      <arg choice="plain">detach</arg>
+      <arg choice="plain">VOLUME</arg>
+    </cmdsynopsis>
+
     <para><filename>systemd-cryptsetup@.service</filename></para>
     <para><filename>system-systemd\x2dcryptsetup.slice</filename></para>
-    <para><filename>systemd-cryptsetup</filename></para>
   </refsynopsisdiv>
 
   <refsect1>
     <title>Description</title>
 
-    <para><filename>systemd-cryptsetup@.service</filename> is a service responsible for setting up encrypted
-    block devices. It is instantiated for each device that requires decryption for access.</para>
+    <para><filename>systemd-cryptsetup</filename> is used to set up (with <command>attach</command>) and tear
+    down (with <command>detach</command>) access to an encrypted block device. It is primarily used via
+    <filename>systemd-cryptsetup@.service</filename> during early boot, but may also be be called manually.
+    The positional arguments <parameter>VOLUME</parameter>, <parameter>SOURCEDEVICE</parameter>,
+    <parameter>KEY-FILE</parameter>, and <parameter>CRYPTTAB-OPTIONS</parameter> have the same meaning as the
+    fields in <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+    </para>
+
+    <para><filename>systemd-cryptsetup@.service</filename> is a service responsible for providing access to
+    encrypted block devices. It is instantiated for each device that requires decryption.</para>
 
     <para><filename>systemd-cryptsetup@.service</filename> instances are part of the
     <filename>system-systemd\x2dcryptsetup.slice</filename> slice, which is destroyed only very late in the
@@ -51,9 +75,9 @@
     translated into <filename>systemd-cryptsetup@.service</filename> units by
     <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 
-    <para>In order to unlock a volume a password or binary key is
-    required. <filename>systemd-cryptsetup@.service</filename> tries to acquire a suitable password or binary
-    key via the following mechanisms, tried in order:</para>
+    <para>In order to unlock a volume a password or binary key is required.
+    <filename>systemd-cryptsetup@.service</filename> tries to acquire a suitable password or binary key via
+    the following mechanisms, tried in order:</para>
 
     <orderedlist>
       <listitem><para>If a key file is explicitly configured (via the third column in
@@ -67,8 +91,8 @@
       too, if a PKCS#11/FIDO2/TPM2 token/device is configured, any key found this way is decrypted before
       use.</para></listitem>
 
-      <listitem><para>If the <varname>try-empty-password</varname> option is specified it is then attempted
-      to unlock the volume with an empty password.</para></listitem>
+      <listitem><para>If the <varname>try-empty-password</varname> option is specified then unlocking the
+      volume with an empty password is attempted.</para></listitem>
 
       <listitem><para>The kernel keyring is then checked for a suitable cached password from previous
       attempts.</para></listitem>