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

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

[Jörg Kastning]

Hello,
Do you accept contributions to the cryptsetup manpage via patch sent by 
email?

I don't have a GitLab account and therefore not able to submit a merge 
request. So I would like to submit a patch(1) by mail.

Before doing so I would like to know whether you accept those or not.

Regards,
Joerg

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

[Milan Broz]

On 18/10/2020 13:54, Jörg Kastning wrote:
> Do you accept contributions to the cryptsetup manpage via patch sent by
> email?

Hi,

sure, you can send it by email (either to this list or to me directly).

If you have a GitHub account, you can create PR there for the cryptsetup git mirror
(But I will export patches and import them manually later.)

Thanks,
Milan

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

[Jörg Kastning]

[-- Attachment #1: Type: text/plain, Size: 720 bytes --]

On 18.10.20 16:18, Milan Broz wrote:
> On 18/10/2020 13:54, Jörg Kastning wrote:
>> Do you accept contributions to the cryptsetup manpage via patch sent by
>> email?
> 
> Hi,
> 
> sure, you can send it by email (either to this list or to me directly).


Hi,

You'll find the manpage patch attached.

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.

Please, let me know what you think about the patch and whether you are 
going to merge it.

Regards,
Joerg

[-- Attachment #2: cryptsetup.8-patch-2020-10-20 --]
[-- Type: text/plain, Size: 3121 bytes --]

*** cryptsetup.8	2020-10-18 16:28:13.000000000 +0200
--- cryptsetup.8-patch	2020-10-20 21:43:25.026366419 +0200
***************
*** 63,69 ****
  container creation. If you do not know how to do that, the
  cryptsetup FAQ describes several options.
  
! .SH BASIC COMMANDS
  The following are valid actions for all supported device types.
  
  \fIopen\fR <device> <name> \-\-type <device_type>
--- 63,69 ----
  container creation. If you do not know how to do that, the
  cryptsetup FAQ describes several options.
  
! .SH BASIC ACTIONS
  The following are valid actions for all supported device types.
  
  \fIopen\fR <device> <name> \-\-type <device_type>
***************
*** 280,286 ****
  give '-' as file name, which results in the passphrase being read
  from stdin and the safety-question being skipped.
  
! You can only call luksFormat on a LUKS device that is not mapped.
  
  To use LUKS2, specify \fI\-\-type luks2\fR.
  
--- 280,286 ----
  give '-' as file name, which results in the passphrase being read
  from stdin and the safety-question being skipped.
  
! In case the device you are going to call luksFormat on already contains a LUKS device that is mapped, you have to close the device first in order to be able to format it.
  
  To use LUKS2, specify \fI\-\-type luks2\fR.
  
***************
*** 838,844 ****
  .TP
  .B "\-\-type <device-type>
  Specifies required device type, for more info
! read \fIBASIC COMMANDS\fR section.
  .TP
  .B "\-\-hash, \-h \fI<hash\-spec>\fR"
  Specifies the passphrase hash for \fIopen\fR (for plain and
--- 838,844 ----
  .TP
  .B "\-\-type <device-type>
  Specifies required device type, for more info
! read \fIBASIC ACTIONS\fR section.
  .TP
  .B "\-\-hash, \-h \fI<hash\-spec>\fR"
  Specifies the passphrase hash for \fIopen\fR (for plain and
***************
*** 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

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

[Milan Broz]

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

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

[Jörg Kastning]

Am 22. Oktober 2020 10:36:07 MESZ schrieb Milan Broz <gmazyland@gmail.com>:
>On 20/10/2020 21:53, Jörg Kastning wrote:
[...] 
>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.

That's OK for me.

>- 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.

Would you like to add the warning? If you like I can add it an resubmit the patch again.

>- 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 :)

It's not necessary to mention my name in the manpage. I put it there because I didn't find any contribution guidelines and didn't know where else to put it. If you Set it as commit author I'm fine with it.

Regards,
Joerg 

>*** 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
>_______________________________________________
>dm-crypt mailing list
>dm-crypt@saout.de
>https://www.saout.de/mailman/listinfo/dm-crypt

-- 
E-Mail: joerg.kastning@my-it-brain.de
Twitter: https://twitter.com/JoergKastning
Internet: https://www.my-it-brain.de
Threema-ID: K2Y6W49N
OpenPGP-ID: 7A302E30
OpenPGP-Fingerabdruck:
2026 DF56 89B6 F79A E776 B15B 55E2 83FB 7A30 2E30

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

[Milan Broz]

On 22/10/2020 11:37, Jörg Kastning wrote:
> 
> 
> Am 22. Oktober 2020 10:36:07 MESZ schrieb Milan Broz <gmazyland@gmail.com>:
>> On 20/10/2020 21:53, Jörg Kastning wrote:
> [...]
>> 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.
> 
> That's OK for me.
> 
>> - 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.
> 
> Would you like to add the warning? If you like I can add it an resubmit the patch again.

Yes, if you can, please resubmit it.

(And the best would be if it is in git format-patch format, but I can reformat it later if you do not use git.)

Thanks
Milan

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

[Jörg Kastning]

Am 22. Oktober 2020 11:56:20 MESZ schrieb Milan Broz <gmazyland@gmail.com>:
>On 22/10/2020 11:37, Jörg Kastning wrote:
>> 
>> Would you like to add the warning? If you like I can add it an
>resubmit the patch again.
>
>Yes, if you can, please resubmit it.
>
>(And the best would be if it is in git format-patch format, but I can
>reformat it later if you do not use git.)

Sure. I've signed up for Gitlab. I'll send you a merge request when I'm ready.

Regards,
Jörg 

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

[Jörg Kastning]

Hi Milan,

Just wanna ask if you saw the merge request [0] on GitLab, already. What 
do you think about it? Are you going to accept it in this form?

[0] https://gitlab.com/cryptsetup/cryptsetup/-/merge_requests/115

Regards,
Joerg

On 22.10.20 18:05, Jörg Kastning wrote:
> 
> 
> Am 22. Oktober 2020 11:56:20 MESZ schrieb Milan Broz <gmazyland@gmail.com>:
>> On 22/10/2020 11:37, Jörg Kastning wrote:
>>>
>>> Would you like to add the warning? If you like I can add it an
>> resubmit the patch again.
>>
>> Yes, if you can, please resubmit it.
>>
>> (And the best would be if it is in git format-patch format, but I can
>> reformat it later if you do not use git.)
> 
> Sure. I've signed up for Gitlab. I'll send you a merge request when I'm ready.
> 
> Regards,
> Jörg
> 

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

[Milan Broz]

On 05/11/2020 21:02, Jörg Kastning wrote:
> Hi Milan,
> 
> Just wanna ask if you saw the merge request [0] on GitLab, already. What 
> do you think about it? Are you going to accept it in this form?

Yes, please stand by, once I can get back to devel work I will comment or merge it.

Thanks,
Milan

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

[Arno Wagner]

Hi Milan,

if you want me to review or comment on this, please let me know.

Regards,
Arno

On Thu, Nov 05, 2020 at 21:30:09 CET, Milan Broz wrote:
> On 05/11/2020 21:02, Jörg Kastning wrote:
> > Hi Milan,
> > 
> > Just wanna ask if you saw the merge request [0] on GitLab, already. What 
> > do you think about it? Are you going to accept it in this form?
> 
> Yes, please stand by, once I can get back to devel work I will comment or merge it.
> 
> Thanks,
> Milan
> _______________________________________________
> dm-crypt mailing list
> dm-crypt@saout.de
> https://www.saout.de/mailman/listinfo/dm-crypt

-- 
Arno Wagner,     Dr. sc. techn., Dipl. Inform.,    Email: arno@wagner.name
GnuPG: ID: CB5D9718  FP: 12D6 C03B 1B30 33BB 13CF  B774 E35C 5FA1 CB5D 9718
----
A good decision is based on knowledge and not on numbers. -- Plato

If it's in the news, don't worry about it.  The very definition of 
"news" is "something that hardly ever happens." -- Bruce Schneier

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

[Milan Broz]

On 05/11/2020 23:50, Arno Wagner wrote:
> Hi Milan,
> 
> if you want me to review or comment on this, please let me know.

Hi,

there was some discussion on that issue, but I merged that already.

The documentation will need a lot of work in the future
(mainly for the new features for the following releases with examples).

If anyone would like to contribute, please send patches :-)

Thanks,
Milan