Re: [dm-crypt] Do you accept contributions to manpage via patch?

[Milan Broz <gmazyland@gmail.com>]

On 20/10/2020 21:53, Jörg Kastning wrote:
> 
> I've renamed "BASIC COMMANDS" to "BASIC ACTIONS" because the commands
> are called action in the SYNOPSIS, too. Furthermore I changed a sentence
> saying that luksFormat would work on unmapped luks containers, only. And
> last but not least I've added the Section "EXAMPLE" with six examples of
> common use cases.

Hi,

thanks for the patch. I would better use word "command" in future, but for now
it is ok (we will split man page in future and unify terminology a little bit later).

But I have some notes before I can merge this.

- the example section - one example how to use --type is perhaps ok, but definitely
normal user should never use this option. I will remove it from example 2 and 3.
It has no meaning there anyway, the format is set during luksFormat only.
(And LUKS2 is default format in many distros already.)

- example 5 needs a strong warning, this command make the LUKS device unusable.
(but still detected as LUKS block device). It is really meant only for data destruction
by removing all volume keys slots from header.

- please, is really your name in the man page necessary?
There are a lot of contributors not mentioned there.
This is quite trivial change and we track authors of such small changes through git
commits only (I will reformat it so you are the patch author in git; or you can use
use git format-patch)

But in general, yes, we are missing the examples section there... strange :)

Thanks,
Milan


*** 1490,1495 ****
--- 1490,1514 ----
   .TP
   .B "\-\-help, \-?"
   Show help text and default parameters.
+ .SH EXAMPLE
+ .TP
+ Example 1: Create LUKS 2 container on block device /dev/sdX.
+ sudo cryptsetup --type luks2 luksFormat /dev/sdX
+ .TP
+ Example 2: Add an additional passphrase to key slot 5.
+ sudo cryptsetup --type luks2 luksAddKey --key-slot 5 /dev/sdX
+ .TP
+ Example 3: Create LUKS header backup and save it to file.
+ sudo cryptsetup --type luks2 luksHeaderBackup /dev/sdX --header-backup-file /var/tmp/NameOfBackupFile
+ .TP
+ Example 4: Open LUKS contaner on /dev/sdX and map it to sdX_crypt.
+ sudo cryptsetup open /dev/sdX sdX_crypt
+ .TP
+ Example 5: Erase all key slots on /dev/sdX.
+ sudo cryptsetup erase /dev/sdX
+ .TP
+ Example 6: Restore LUKS header from backup file.
+ sudo cryptsetup luksHeaderRestore /dev/sdX --header-backup-file /var/tmp/NameOfBackupFile
   .SH RETURN CODES
   Cryptsetup returns 0 on success and a non-zero value on error.
   
***************
*** 1710,1715 ****
--- 1729,1736 ----
   Man page extensions by Milan Broz <gmazyland@gmail.com>.
   .br
   Man page rewrite and extension by Arno Wagner <arno@wagner.name>.
+ .br
+ Add Examples and minor rewrite by Joerg Kastning <jkastning@my-it-brain.de>.
   .SH COPYRIGHT
   Copyright \(co 2004 Jana Saout
   .br