Re: add extract example to tar(1) man page

2023-08-03 Thread Jason McIntyre
ok!
jmc

On 3 August 2023 17:16:44 BST, aisha  wrote:
>On 23/08/03 04:26PM, Jason McIntyre wrote:
>> On Thu, Aug 03, 2023 at 11:05:16AM -0400, aisha wrote:
>> > On 23/08/03 10:51AM, aisha wrote:
>> > > On 23/08/03 09:45AM, Stuart Henderson wrote:
>> > > > On 2023/08/03 07:23, Jason McIntyre wrote:
>> > > > > On Wed, Aug 02, 2023 at 05:52:02PM -0400, aisha wrote:
>
>> yes, thanks! ok.
>> 
>> but you should change the text from
>> 
>>  Create a gzip(1) compressed archive ... to a file called...
>> to
>>  Create a gzip(1) compressed archive, called XXX, containing the
>>  files ...
>> 
>> as i suggested, because the syntax "create ... to a file" reads badly.
>> 
>
>Thanks, fixed.
>
>OK?
>
>Index: tar.1
>===
>RCS file: /cvs/src/bin/pax/tar.1,v
>retrieving revision 1.64
>diff -u -p -r1.64 tar.1
>--- tar.1  31 Mar 2022 17:27:14 -  1.64
>+++ tar.1  3 Aug 2023 16:14:11 -
>@@ -331,16 +331,16 @@ and
> .Pp
> .Dl $ tar c bonvole sekve
> .Pp
>-Output a
>+Create a
> .Xr gzip 1
>-compressed archive containing the files
>+compressed archive, called
>+.Pa foriru.tar.gz ,
>+containing the files
> .Pa bonvole
> and
>-.Pa sekve
>-to a file called
>-.Pa foriru.tar.gz :
>+.Pa sekve :
> .Pp
>-.Dl $ tar zcf foriru.tar.gz bonvole sekve
>+.Dl $ tar czf foriru.tar.gz bonvole sekve
> .Pp
> Verbosely create an archive, called
> .Pa backup.tar.gz ,
>@@ -349,7 +349,7 @@ of all files matching the shell
> function
> .Pa *.c :
> .Pp
>-.Dl $ tar zcvf backup.tar.gz *.c
>+.Dl $ tar cvzf backup.tar.gz *.c
> .Pp
> Verbosely list, but do not extract, all files ending in
> .Pa .jpeg
>@@ -358,6 +358,13 @@ from a compressed archive named
> Note that the glob pattern has been quoted to avoid expansion by the shell:
> .Pp
> .Dl $ tar tvzf backup.tar.gz '*.jpeg'
>+.Pp
>+Verbosely extract an archive, called
>+.Pa foo.tar.gz ,
>+to the directory
>+.Pa /var/foo :
>+.Pp
>+.Dl $ tar xvzf foo.tar.gz -C /var/foo
> .Pp
> For more detailed examples, see
> .Xr pax 1 .
>


Re: add extract example to tar(1) man page

2023-08-03 Thread aisha
On 23/08/03 04:26PM, Jason McIntyre wrote:
> On Thu, Aug 03, 2023 at 11:05:16AM -0400, aisha wrote:
> > On 23/08/03 10:51AM, aisha wrote:
> > > On 23/08/03 09:45AM, Stuart Henderson wrote:
> > > > On 2023/08/03 07:23, Jason McIntyre wrote:
> > > > > On Wed, Aug 02, 2023 at 05:52:02PM -0400, aisha wrote:

> yes, thanks! ok.
> 
> but you should change the text from
> 
>   Create a gzip(1) compressed archive ... to a file called...
> to
>   Create a gzip(1) compressed archive, called XXX, containing the
>   files ...
> 
> as i suggested, because the syntax "create ... to a file" reads badly.
> 

Thanks, fixed.

OK?

Index: tar.1
===
RCS file: /cvs/src/bin/pax/tar.1,v
retrieving revision 1.64
diff -u -p -r1.64 tar.1
--- tar.1   31 Mar 2022 17:27:14 -  1.64
+++ tar.1   3 Aug 2023 16:14:11 -
@@ -331,16 +331,16 @@ and
 .Pp
 .Dl $ tar c bonvole sekve
 .Pp
-Output a
+Create a
 .Xr gzip 1
-compressed archive containing the files
+compressed archive, called
+.Pa foriru.tar.gz ,
+containing the files
 .Pa bonvole
 and
-.Pa sekve
-to a file called
-.Pa foriru.tar.gz :
+.Pa sekve :
 .Pp
-.Dl $ tar zcf foriru.tar.gz bonvole sekve
+.Dl $ tar czf foriru.tar.gz bonvole sekve
 .Pp
 Verbosely create an archive, called
 .Pa backup.tar.gz ,
@@ -349,7 +349,7 @@ of all files matching the shell
 function
 .Pa *.c :
 .Pp
-.Dl $ tar zcvf backup.tar.gz *.c
+.Dl $ tar cvzf backup.tar.gz *.c
 .Pp
 Verbosely list, but do not extract, all files ending in
 .Pa .jpeg
@@ -358,6 +358,13 @@ from a compressed archive named
 Note that the glob pattern has been quoted to avoid expansion by the shell:
 .Pp
 .Dl $ tar tvzf backup.tar.gz '*.jpeg'
+.Pp
+Verbosely extract an archive, called
+.Pa foo.tar.gz ,
+to the directory
+.Pa /var/foo :
+.Pp
+.Dl $ tar xvzf foo.tar.gz -C /var/foo
 .Pp
 For more detailed examples, see
 .Xr pax 1 .



Re: add extract example to tar(1) man page

2023-08-03 Thread Jason McIntyre
On Thu, Aug 03, 2023 at 11:05:16AM -0400, aisha wrote:
> On 23/08/03 10:51AM, aisha wrote:
> > On 23/08/03 09:45AM, Stuart Henderson wrote:
> > > On 2023/08/03 07:23, Jason McIntyre wrote:
> > > > On Wed, Aug 02, 2023 at 05:52:02PM -0400, aisha wrote:
> > > > > Hi,
> > > > >   Someone - https://www.youtube.com/watch?v=NQ5uD5x8vzg - mentioned 
> > > > > that our man page for tar(1) doesn't have an extract example, so I 
> > > > > thought it would be good to add a simple one which highlights a 
> > > > > common use case.
> > > > > 
> > > > > OK?
> > > > > 
> > > > 
> > > > hi.
> > > > 
> > > > the examples section is small enough that i suppose it wouldn;t be a
> > > > problem to add another one.
> > > 
> > > as it must be specified in a non-obvious place on the command line and
> > > it's not currently explained particularly clearly, I'd welcome an example
> > > using -C.
> > > 
> > > > it does add another example with a similar set of options though, all in
> > > > a different order. i wonder whether we should try and push the action as
> > > > the first option, so people can see what we're doing. so "cXXX" when the
> > > > example is to create, "tXXX" when listing? then keep the "vzf" options
> > > > that are so common in the same order?
> > > > 
> > > > then the second example is probably more helpful as "Create a gzip(1)
> > > > compressed archive blah.tgz".
> > > > 
> > > > i know this isn;t what you're posting about, so feel free to leave alone
> > > > if you don;t want to tackle that.
> > > > 
> > > > one more thing. you could as easily remove the text "the folder", but
> > > > i'd be tempted to use "directory", as that's more standard for our docs,
> > > > and how -C itself describes it.
> > > 
> > > strongly agree on options order and "directory".
> > 
> > Thanks for the comments!
> > Here's the updated patch.
> > 
> > OK?
> > 
> 
> Small change to address the backup/-p comments, I've removed the word -backup 
> from the tar archive name
> 
> OK?
> 

yes, thanks! ok.

but you should change the text from

Create a gzip(1) compressed archive ... to a file called...
to
Create a gzip(1) compressed archive, called XXX, containing the
files ...

as i suggested, because the syntax "create ... to a file" reads badly.

jmc

> Index: tar.1
> ===
> RCS file: /cvs/src/bin/pax/tar.1,v
> retrieving revision 1.64
> diff -u -p -r1.64 tar.1
> --- tar.1 31 Mar 2022 17:27:14 -  1.64
> +++ tar.1 3 Aug 2023 15:02:49 -
> @@ -331,7 +331,7 @@ and
>  .Pp
>  .Dl $ tar c bonvole sekve
>  .Pp
> -Output a
> +Create a
>  .Xr gzip 1
>  compressed archive containing the files
>  .Pa bonvole
> @@ -340,7 +340,7 @@ and
>  to a file called
>  .Pa foriru.tar.gz :
>  .Pp
> -.Dl $ tar zcf foriru.tar.gz bonvole sekve
> +.Dl $ tar czf foriru.tar.gz bonvole sekve
>  .Pp
>  Verbosely create an archive, called
>  .Pa backup.tar.gz ,
> @@ -349,7 +349,7 @@ of all files matching the shell
>  function
>  .Pa *.c :
>  .Pp
> -.Dl $ tar zcvf backup.tar.gz *.c
> +.Dl $ tar cvzf backup.tar.gz *.c
>  .Pp
>  Verbosely list, but do not extract, all files ending in
>  .Pa .jpeg
> @@ -358,6 +358,13 @@ from a compressed archive named
>  Note that the glob pattern has been quoted to avoid expansion by the shell:
>  .Pp
>  .Dl $ tar tvzf backup.tar.gz '*.jpeg'
> +.Pp
> +Verbosely extract an archive, called
> +.Pa foo.tar.gz ,
> +to the directory
> +.Pa /var/foo :
> +.Pp
> +.Dl $ tar xvzf foo.tar.gz -C /var/foo
>  .Pp
>  For more detailed examples, see
>  .Xr pax 1 .



Re: add extract example to tar(1) man page

2023-08-03 Thread aisha
On 23/08/03 10:51AM, aisha wrote:
> On 23/08/03 09:45AM, Stuart Henderson wrote:
> > On 2023/08/03 07:23, Jason McIntyre wrote:
> > > On Wed, Aug 02, 2023 at 05:52:02PM -0400, aisha wrote:
> > > > Hi,
> > > >   Someone - https://www.youtube.com/watch?v=NQ5uD5x8vzg - mentioned 
> > > > that our man page for tar(1) doesn't have an extract example, so I 
> > > > thought it would be good to add a simple one which highlights a common 
> > > > use case.
> > > > 
> > > > OK?
> > > > 
> > > 
> > > hi.
> > > 
> > > the examples section is small enough that i suppose it wouldn;t be a
> > > problem to add another one.
> > 
> > as it must be specified in a non-obvious place on the command line and
> > it's not currently explained particularly clearly, I'd welcome an example
> > using -C.
> > 
> > > it does add another example with a similar set of options though, all in
> > > a different order. i wonder whether we should try and push the action as
> > > the first option, so people can see what we're doing. so "cXXX" when the
> > > example is to create, "tXXX" when listing? then keep the "vzf" options
> > > that are so common in the same order?
> > > 
> > > then the second example is probably more helpful as "Create a gzip(1)
> > > compressed archive blah.tgz".
> > > 
> > > i know this isn;t what you're posting about, so feel free to leave alone
> > > if you don;t want to tackle that.
> > > 
> > > one more thing. you could as easily remove the text "the folder", but
> > > i'd be tempted to use "directory", as that's more standard for our docs,
> > > and how -C itself describes it.
> > 
> > strongly agree on options order and "directory".
> 
> Thanks for the comments!
> Here's the updated patch.
> 
> OK?
> 

Small change to address the backup/-p comments, I've removed the word -backup 
from the tar archive name

OK?

Index: tar.1
===
RCS file: /cvs/src/bin/pax/tar.1,v
retrieving revision 1.64
diff -u -p -r1.64 tar.1
--- tar.1   31 Mar 2022 17:27:14 -  1.64
+++ tar.1   3 Aug 2023 15:02:49 -
@@ -331,7 +331,7 @@ and
 .Pp
 .Dl $ tar c bonvole sekve
 .Pp
-Output a
+Create a
 .Xr gzip 1
 compressed archive containing the files
 .Pa bonvole
@@ -340,7 +340,7 @@ and
 to a file called
 .Pa foriru.tar.gz :
 .Pp
-.Dl $ tar zcf foriru.tar.gz bonvole sekve
+.Dl $ tar czf foriru.tar.gz bonvole sekve
 .Pp
 Verbosely create an archive, called
 .Pa backup.tar.gz ,
@@ -349,7 +349,7 @@ of all files matching the shell
 function
 .Pa *.c :
 .Pp
-.Dl $ tar zcvf backup.tar.gz *.c
+.Dl $ tar cvzf backup.tar.gz *.c
 .Pp
 Verbosely list, but do not extract, all files ending in
 .Pa .jpeg
@@ -358,6 +358,13 @@ from a compressed archive named
 Note that the glob pattern has been quoted to avoid expansion by the shell:
 .Pp
 .Dl $ tar tvzf backup.tar.gz '*.jpeg'
+.Pp
+Verbosely extract an archive, called
+.Pa foo.tar.gz ,
+to the directory
+.Pa /var/foo :
+.Pp
+.Dl $ tar xvzf foo.tar.gz -C /var/foo
 .Pp
 For more detailed examples, see
 .Xr pax 1 .



Re: add extract example to tar(1) man page

2023-08-03 Thread aisha
On 23/08/03 09:45AM, Stuart Henderson wrote:
> On 2023/08/03 07:23, Jason McIntyre wrote:
> > On Wed, Aug 02, 2023 at 05:52:02PM -0400, aisha wrote:
> > > Hi,
> > >   Someone - https://www.youtube.com/watch?v=NQ5uD5x8vzg - mentioned that 
> > > our man page for tar(1) doesn't have an extract example, so I thought it 
> > > would be good to add a simple one which highlights a common use case.
> > > 
> > > OK?
> > > 
> > 
> > hi.
> > 
> > the examples section is small enough that i suppose it wouldn;t be a
> > problem to add another one.
> 
> as it must be specified in a non-obvious place on the command line and
> it's not currently explained particularly clearly, I'd welcome an example
> using -C.
> 
> > it does add another example with a similar set of options though, all in
> > a different order. i wonder whether we should try and push the action as
> > the first option, so people can see what we're doing. so "cXXX" when the
> > example is to create, "tXXX" when listing? then keep the "vzf" options
> > that are so common in the same order?
> > 
> > then the second example is probably more helpful as "Create a gzip(1)
> > compressed archive blah.tgz".
> > 
> > i know this isn;t what you're posting about, so feel free to leave alone
> > if you don;t want to tackle that.
> > 
> > one more thing. you could as easily remove the text "the folder", but
> > i'd be tempted to use "directory", as that's more standard for our docs,
> > and how -C itself describes it.
> 
> strongly agree on options order and "directory".

Thanks for the comments!
Here's the updated patch.

OK?

Index: tar.1
===
RCS file: /cvs/src/bin/pax/tar.1,v
retrieving revision 1.64
diff -u -p -r1.64 tar.1
--- tar.1   31 Mar 2022 17:27:14 -  1.64
+++ tar.1   3 Aug 2023 14:46:23 -
@@ -331,7 +331,7 @@ and
 .Pp
 .Dl $ tar c bonvole sekve
 .Pp
-Output a
+Create a
 .Xr gzip 1
 compressed archive containing the files
 .Pa bonvole
@@ -340,7 +340,7 @@ and
 to a file called
 .Pa foriru.tar.gz :
 .Pp
-.Dl $ tar zcf foriru.tar.gz bonvole sekve
+.Dl $ tar czf foriru.tar.gz bonvole sekve
 .Pp
 Verbosely create an archive, called
 .Pa backup.tar.gz ,
@@ -349,7 +349,7 @@ of all files matching the shell
 function
 .Pa *.c :
 .Pp
-.Dl $ tar zcvf backup.tar.gz *.c
+.Dl $ tar cvzf backup.tar.gz *.c
 .Pp
 Verbosely list, but do not extract, all files ending in
 .Pa .jpeg
@@ -358,6 +358,13 @@ from a compressed archive named
 Note that the glob pattern has been quoted to avoid expansion by the shell:
 .Pp
 .Dl $ tar tvzf backup.tar.gz '*.jpeg'
+.Pp
+Verbosely extract an archive, called
+.Pa foo-backup.tar.gz ,
+to the directory
+.Pa /var/foo :
+.Pp
+.Dl $ tar xvzf foo-backup.tar.gz -C /var/foo
 .Pp
 For more detailed examples, see
 .Xr pax 1 .



Re: add extract example to tar(1) man page

2023-08-03 Thread Stuart Henderson
On 2023/08/03 07:23, Jason McIntyre wrote:
> On Wed, Aug 02, 2023 at 05:52:02PM -0400, aisha wrote:
> > Hi,
> >   Someone - https://www.youtube.com/watch?v=NQ5uD5x8vzg - mentioned that 
> > our man page for tar(1) doesn't have an extract example, so I thought it 
> > would be good to add a simple one which highlights a common use case.
> > 
> > OK?
> > 
> 
> hi.
> 
> the examples section is small enough that i suppose it wouldn;t be a
> problem to add another one.

as it must be specified in a non-obvious place on the command line and
it's not currently explained particularly clearly, I'd welcome an example
using -C.

> it does add another example with a similar set of options though, all in
> a different order. i wonder whether we should try and push the action as
> the first option, so people can see what we're doing. so "cXXX" when the
> example is to create, "tXXX" when listing? then keep the "vzf" options
> that are so common in the same order?
> 
> then the second example is probably more helpful as "Create a gzip(1)
> compressed archive blah.tgz".
> 
> i know this isn;t what you're posting about, so feel free to leave alone
> if you don;t want to tackle that.
> 
> one more thing. you could as easily remove the text "the folder", but
> i'd be tempted to use "directory", as that's more standard for our docs,
> and how -C itself describes it.

strongly agree on options order and "directory".

> jmc
> 
> > Index: tar.1
> > ===
> > RCS file: /cvs/src/bin/pax/tar.1,v
> > retrieving revision 1.64
> > diff -u -p -r1.64 tar.1
> > --- tar.1   31 Mar 2022 17:27:14 -  1.64
> > +++ tar.1   2 Aug 2023 21:47:12 -
> > @@ -359,6 +359,13 @@ Note that the glob pattern has been quot
> >  .Pp
> >  .Dl $ tar tvzf backup.tar.gz '*.jpeg'
> >  .Pp
> > +Verbosely extract an archive, called
> > +.Pa foo-backup.tar.gz ,
> > +to the folder
> > +.Pa /var/foo :
> > +.Pp
> > +.Dl $ tar xzvf foo-backup.tar.gz -C /var/foo
> > +.Pp
> >  For more detailed examples, see
> >  .Xr pax 1 .
> >  .Sh DIAGNOSTICS
> > 
> 



Re: add extract example to tar(1) man page

2023-08-03 Thread Peter J. Philipp
On Thu, Aug 03, 2023 at 08:29:31AM +0200, Peter J. Philipp wrote:
> On Thu, Aug 03, 2023 at 07:23:45AM +0100, Jason McIntyre wrote:
> > On Wed, Aug 02, 2023 at 05:52:02PM -0400, aisha wrote:
> > > Hi,
> > >   Someone - https://www.youtube.com/watch?v=NQ5uD5x8vzg - mentioned that 
> > > our man page for tar(1) doesn't have an extract example, so I thought it 
> > > would be good to add a simple one which highlights a common use case.
> > > 
> > > OK?
> > > 
> > 
> > hi.
> > 
> > the examples section is small enough that i suppose it wouldn;t be a
> > problem to add another one.
> > 
> > it does add another example with a similar set of options though, all in
> > a different order. i wonder whether we should try and push the action as
> > the first option, so people can see what we're doing. so "cXXX" when the
> > example is to create, "tXXX" when listing? then keep the "vzf" options
> > that are so common in the same order?
> 
> I wouldn't restore a .tgz without the -p flag.  Particularily on backups.
> Perhaps the OP forgot to add it.
> 
> Best Regards,
> -peter

Someone privately strongly disagreed on this.  So I retract this.

Best,
-peter



Re: add extract example to tar(1) man page

2023-08-03 Thread Peter J. Philipp
On Thu, Aug 03, 2023 at 07:23:45AM +0100, Jason McIntyre wrote:
> On Wed, Aug 02, 2023 at 05:52:02PM -0400, aisha wrote:
> > Hi,
> >   Someone - https://www.youtube.com/watch?v=NQ5uD5x8vzg - mentioned that 
> > our man page for tar(1) doesn't have an extract example, so I thought it 
> > would be good to add a simple one which highlights a common use case.
> > 
> > OK?
> > 
> 
> hi.
> 
> the examples section is small enough that i suppose it wouldn;t be a
> problem to add another one.
> 
> it does add another example with a similar set of options though, all in
> a different order. i wonder whether we should try and push the action as
> the first option, so people can see what we're doing. so "cXXX" when the
> example is to create, "tXXX" when listing? then keep the "vzf" options
> that are so common in the same order?

I wouldn't restore a .tgz without the -p flag.  Particularily on backups.
Perhaps the OP forgot to add it.

Best Regards,
-peter


> then the second example is probably more helpful as "Create a gzip(1)
> compressed archive blah.tgz".
> 
> i know this isn;t what you're posting about, so feel free to leave alone
> if you don;t want to tackle that.
> 
> one more thing. you could as easily remove the text "the folder", but
> i'd be tempted to use "directory", as that's more standard for our docs,
> and how -C itself describes it.
> 
> jmc
> 
> > Index: tar.1
> > ===
> > RCS file: /cvs/src/bin/pax/tar.1,v
> > retrieving revision 1.64
> > diff -u -p -r1.64 tar.1
> > --- tar.1   31 Mar 2022 17:27:14 -  1.64
> > +++ tar.1   2 Aug 2023 21:47:12 -
> > @@ -359,6 +359,13 @@ Note that the glob pattern has been quot
> >  .Pp
> >  .Dl $ tar tvzf backup.tar.gz '*.jpeg'
> >  .Pp
> > +Verbosely extract an archive, called
> > +.Pa foo-backup.tar.gz ,
> > +to the folder
> > +.Pa /var/foo :
> > +.Pp
> > +.Dl $ tar xzvf foo-backup.tar.gz -C /var/foo
> > +.Pp
> >  For more detailed examples, see
> >  .Xr pax 1 .
> >  .Sh DIAGNOSTICS
> > 
> 

-- 
Over thirty years experience on Unix-like Operating Systems starting with QNX.



Re: add extract example to tar(1) man page

2023-08-03 Thread Jason McIntyre
On Wed, Aug 02, 2023 at 05:52:02PM -0400, aisha wrote:
> Hi,
>   Someone - https://www.youtube.com/watch?v=NQ5uD5x8vzg - mentioned that our 
> man page for tar(1) doesn't have an extract example, so I thought it would be 
> good to add a simple one which highlights a common use case.
> 
> OK?
> 

hi.

the examples section is small enough that i suppose it wouldn;t be a
problem to add another one.

it does add another example with a similar set of options though, all in
a different order. i wonder whether we should try and push the action as
the first option, so people can see what we're doing. so "cXXX" when the
example is to create, "tXXX" when listing? then keep the "vzf" options
that are so common in the same order?

then the second example is probably more helpful as "Create a gzip(1)
compressed archive blah.tgz".

i know this isn;t what you're posting about, so feel free to leave alone
if you don;t want to tackle that.

one more thing. you could as easily remove the text "the folder", but
i'd be tempted to use "directory", as that's more standard for our docs,
and how -C itself describes it.

jmc

> Index: tar.1
> ===
> RCS file: /cvs/src/bin/pax/tar.1,v
> retrieving revision 1.64
> diff -u -p -r1.64 tar.1
> --- tar.1 31 Mar 2022 17:27:14 -  1.64
> +++ tar.1 2 Aug 2023 21:47:12 -
> @@ -359,6 +359,13 @@ Note that the glob pattern has been quot
>  .Pp
>  .Dl $ tar tvzf backup.tar.gz '*.jpeg'
>  .Pp
> +Verbosely extract an archive, called
> +.Pa foo-backup.tar.gz ,
> +to the folder
> +.Pa /var/foo :
> +.Pp
> +.Dl $ tar xzvf foo-backup.tar.gz -C /var/foo
> +.Pp
>  For more detailed examples, see
>  .Xr pax 1 .
>  .Sh DIAGNOSTICS
>