Re: rdsetroot.8: sync synopsis with usage, improve wording
On Fri, Jan 20, 2023 at 05:00:37PM +, Klemens Nanni wrote: > Alright, sorry for the noise. > > Is this minimal sync plus stdout mention fine? > > Index: rdsetroot.8 > === > RCS file: /cvs/src/usr.sbin/rdsetroot/rdsetroot.8,v > retrieving revision 1.2 > diff -u -p -r1.2 rdsetroot.8 > --- rdsetroot.8 5 Apr 2019 21:44:32 - 1.2 > +++ rdsetroot.8 20 Jan 2023 16:58:56 - > @@ -45,6 +45,11 @@ Debug. > Rather than inserting, extract the > .Ar disk.fs > image. > +If > +.Ar disk.fs > +is not speficied, s/speficied/specified otherwise ok.
Re: rdsetroot.8: sync synopsis with usage, improve wording
ok by me.
jmc
On 20 January 2023 17:00:37 GMT, Klemens Nanni wrote:
>Alright, sorry for the noise.
>
>Is this minimal sync plus stdout mention fine?
>
>Index: rdsetroot.8
>===
>RCS file: /cvs/src/usr.sbin/rdsetroot/rdsetroot.8,v
>retrieving revision 1.2
>diff -u -p -r1.2 rdsetroot.8
>--- rdsetroot.85 Apr 2019 21:44:32 - 1.2
>+++ rdsetroot.820 Jan 2023 16:58:56 -
>@@ -45,6 +45,11 @@ Debug.
> Rather than inserting, extract the
> .Ar disk.fs
> image.
>+If
>+.Ar disk.fs
>+is not speficied,
>+.Nm
>+writes to standard output.
> The disk can be made accessible using
> .Xr vnconfig 8 ,
> filesystems can be manipulated, and finally re-inserted into the RAMDISK
> kernel.
>Index: rdsetroot.c
>===
>RCS file: /cvs/src/usr.sbin/rdsetroot/rdsetroot.c,v
>retrieving revision 1.3
>diff -u -p -r1.3 rdsetroot.c
>--- rdsetroot.c24 Oct 2021 21:24:19 - 1.3
>+++ rdsetroot.c20 Jan 2023 16:58:58 -
>@@ -294,6 +294,6 @@ usage(void)
> {
> extern char *__progname;
>
>- fprintf(stderr, "usage: %s [-dx] bsd [fs]\n", __progname);
>+ fprintf(stderr, "usage: %s [-dx] kernel [disk.fs]\n", __progname);
> exit(1);
> }
>
Re: rdsetroot.8: sync synopsis with usage, improve wording
Alright, sorry for the noise.
Is this minimal sync plus stdout mention fine?
Index: rdsetroot.8
===
RCS file: /cvs/src/usr.sbin/rdsetroot/rdsetroot.8,v
retrieving revision 1.2
diff -u -p -r1.2 rdsetroot.8
--- rdsetroot.8 5 Apr 2019 21:44:32 - 1.2
+++ rdsetroot.8 20 Jan 2023 16:58:56 -
@@ -45,6 +45,11 @@ Debug.
Rather than inserting, extract the
.Ar disk.fs
image.
+If
+.Ar disk.fs
+is not speficied,
+.Nm
+writes to standard output.
The disk can be made accessible using
.Xr vnconfig 8 ,
filesystems can be manipulated, and finally re-inserted into the RAMDISK
kernel.
Index: rdsetroot.c
===
RCS file: /cvs/src/usr.sbin/rdsetroot/rdsetroot.c,v
retrieving revision 1.3
diff -u -p -r1.3 rdsetroot.c
--- rdsetroot.c 24 Oct 2021 21:24:19 - 1.3
+++ rdsetroot.c 20 Jan 2023 16:58:58 -
@@ -294,6 +294,6 @@ usage(void)
{
extern char *__progname;
- fprintf(stderr, "usage: %s [-dx] bsd [fs]\n", __progname);
+ fprintf(stderr, "usage: %s [-dx] kernel [disk.fs]\n", __progname);
exit(1);
}
Re: rdsetroot.8: sync synopsis with usage, improve wording
On Fri, Jan 20, 2023 at 02:51:31PM +, Jason McIntyre wrote: > On Fri, Jan 20, 2023 at 12:35:05PM +, Klemens Nanni wrote: > > 19.01.2023 19:11, Jason McIntyre ??: > > > On Thu, Jan 19, 2023 at 06:50:14PM +, Klemens Nanni wrote: > > >> $ man -h rdsetroot > > >> rdsetroot [-dx] kernel [disk.fs] > > >> vs. > > >> $ rdsetroot > > >> usage: rdsetroot [-dx] bsd [fs] > > >> > > > > > > i have to say i think the man page has better argument names, but i've > > > nothing against your changes. just as long as they match. > > > > Either way is fine, just let them match. > > > > >> Clarify that -x uses stdout (could be a default file like ktrace(1) does) > > >> and switch 'standard in/output' to more common '.Va stdin/out' like the > > >> related vnconfig(8) does. > > >> > > > > > > i'm fine with your diff, but i think that "reads from standard input" is > > > much easier to understand than the change you propose. > > > > Sure, new version with both points incorporated. > > > > Feedback? OK? > > > > > > > > jmc > > > > > >> Explaining how disk images can round trip through rdsetroot and vnconfig > > >> is vaguely useful, imho, even less so in the description of -x, so > > >> briefly > > >> mention the relation and let readers follow the reference for more. > > > > > > Index: rdsetroot.8 > > === > > RCS file: /cvs/src/usr.sbin/rdsetroot/rdsetroot.8,v > > retrieving revision 1.2 > > diff -u -p -r1.2 rdsetroot.8 > > --- rdsetroot.8 5 Apr 2019 21:44:32 - 1.2 > > +++ rdsetroot.8 20 Jan 2023 12:33:31 - > > @@ -24,30 +24,29 @@ > > .Nm rdsetroot > > .Op Fl dx > > .Ar kernel > > -.Op Ar disk.fs > > +.Op Ar disk > > well, disk.fs and your original proposal (fs) both hinted that you want > a filesystem. i'm less sure about "disk". you aren;t concerned about > that? i really don;t see an issue with how it is now. I agree. Just "disk" isn't very clear that it's intended to be a filesystem image. > > > .Sh DESCRIPTION > > The > > .Nm > > -utility inserts the file > > -.Ar disk.fs > > -into the reserved space inside a RAMDISK kernel. > > +utility inserts the disk image > > +.Ar disk > > +into the reserved space inside the RAMDISK kernel > > +.Ar bsd . > > if you stick with "kernel" you'll need to make that change here too. It reads better as "a RAMDISK kernel", rather than, "the RAMDISK kernel", unless you also change it to "the specified RAMDISK kernel". Overall, I think that this diff reduces the readability of the manual page rather than improves it. The useful parts are to make the argument names match between manual and command, and to clarify that -x writes to standard output if no output file is specified. The rest is just churn. I'm doubtful that it's even useful to explicitly state that the image can be manipulated and then re-inserted. It's fairly obvious.
Re: rdsetroot.8: sync synopsis with usage, improve wording
On Fri, Jan 20, 2023 at 12:35:05PM +, Klemens Nanni wrote:
> 19.01.2023 19:11, Jason McIntyre ??:
> > On Thu, Jan 19, 2023 at 06:50:14PM +, Klemens Nanni wrote:
> >>$ man -h rdsetroot
> >>rdsetroot [-dx] kernel [disk.fs]
> >> vs.
> >>$ rdsetroot
> >>usage: rdsetroot [-dx] bsd [fs]
> >>
> >
> > i have to say i think the man page has better argument names, but i've
> > nothing against your changes. just as long as they match.
>
> Either way is fine, just let them match.
>
> >> Clarify that -x uses stdout (could be a default file like ktrace(1) does)
> >> and switch 'standard in/output' to more common '.Va stdin/out' like the
> >> related vnconfig(8) does.
> >>
> >
> > i'm fine with your diff, but i think that "reads from standard input" is
> > much easier to understand than the change you propose.
>
> Sure, new version with both points incorporated.
>
> Feedback? OK?
>
> >
> > jmc
> >
> >> Explaining how disk images can round trip through rdsetroot and vnconfig
> >> is vaguely useful, imho, even less so in the description of -x, so briefly
> >> mention the relation and let readers follow the reference for more.
>
>
> Index: rdsetroot.8
> ===
> RCS file: /cvs/src/usr.sbin/rdsetroot/rdsetroot.8,v
> retrieving revision 1.2
> diff -u -p -r1.2 rdsetroot.8
> --- rdsetroot.8 5 Apr 2019 21:44:32 - 1.2
> +++ rdsetroot.8 20 Jan 2023 12:33:31 -
> @@ -24,30 +24,29 @@
> .Nm rdsetroot
> .Op Fl dx
> .Ar kernel
> -.Op Ar disk.fs
> +.Op Ar disk
well, disk.fs and your original proposal (fs) both hinted that you want
a filesystem. i'm less sure about "disk". you aren;t concerned about
that? i really don;t see an issue with how it is now.
> .Sh DESCRIPTION
> The
> .Nm
> -utility inserts the file
> -.Ar disk.fs
> -into the reserved space inside a RAMDISK kernel.
> +utility inserts the disk image
> +.Ar disk
> +into the reserved space inside the RAMDISK kernel
> +.Ar bsd .
if you stick with "kernel" you'll need to make that change here too.
jmc
> If
> -.Ar disk.fs
> -is not specified,
> -.Nm
> -reads from standard input.
> +.Ar disk
> +is not specified, standard input is used.
> +Disk images can be used with
> +.Xr vnconfig 8 .
> .Pp
> The options are as follows:
> .Bl -tag -width Ds
> .It Fl d
> Debug.
> .It Fl x
> -Rather than inserting, extract the
> -.Ar disk.fs
> -image.
> -The disk can be made accessible using
> -.Xr vnconfig 8 ,
> -filesystems can be manipulated, and finally re-inserted into the RAMDISK
> kernel.
> +Extract the disk image.
> +If
> +.Ar disk
> +is not specified, standard output is used.
> .El
> .Sh SEE ALSO
> .Xr config 8 ,
> Index: rdsetroot.c
> ===
> RCS file: /cvs/src/usr.sbin/rdsetroot/rdsetroot.c,v
> retrieving revision 1.3
> diff -u -p -r1.3 rdsetroot.c
> --- rdsetroot.c 24 Oct 2021 21:24:19 - 1.3
> +++ rdsetroot.c 20 Jan 2023 12:33:33 -
> @@ -294,6 +294,6 @@ usage(void)
> {
> extern char *__progname;
>
> - fprintf(stderr, "usage: %s [-dx] bsd [fs]\n", __progname);
> + fprintf(stderr, "usage: %s [-dx] kernel [disk]\n", __progname);
> exit(1);
> }
>
Re: rdsetroot.8: sync synopsis with usage, improve wording
19.01.2023 19:11, Jason McIntyre пишет:
> On Thu, Jan 19, 2023 at 06:50:14PM +, Klemens Nanni wrote:
>> $ man -h rdsetroot
>> rdsetroot [-dx] kernel [disk.fs]
>> vs.
>> $ rdsetroot
>> usage: rdsetroot [-dx] bsd [fs]
>>
>
> i have to say i think the man page has better argument names, but i've
> nothing against your changes. just as long as they match.
Either way is fine, just let them match.
>> Clarify that -x uses stdout (could be a default file like ktrace(1) does)
>> and switch 'standard in/output' to more common '.Va stdin/out' like the
>> related vnconfig(8) does.
>>
>
> i'm fine with your diff, but i think that "reads from standard input" is
> much easier to understand than the change you propose.
Sure, new version with both points incorporated.
Feedback? OK?
>
> jmc
>
>> Explaining how disk images can round trip through rdsetroot and vnconfig
>> is vaguely useful, imho, even less so in the description of -x, so briefly
>> mention the relation and let readers follow the reference for more.
Index: rdsetroot.8
===
RCS file: /cvs/src/usr.sbin/rdsetroot/rdsetroot.8,v
retrieving revision 1.2
diff -u -p -r1.2 rdsetroot.8
--- rdsetroot.8 5 Apr 2019 21:44:32 - 1.2
+++ rdsetroot.8 20 Jan 2023 12:33:31 -
@@ -24,30 +24,29 @@
.Nm rdsetroot
.Op Fl dx
.Ar kernel
-.Op Ar disk.fs
+.Op Ar disk
.Sh DESCRIPTION
The
.Nm
-utility inserts the file
-.Ar disk.fs
-into the reserved space inside a RAMDISK kernel.
+utility inserts the disk image
+.Ar disk
+into the reserved space inside the RAMDISK kernel
+.Ar bsd .
If
-.Ar disk.fs
-is not specified,
-.Nm
-reads from standard input.
+.Ar disk
+is not specified, standard input is used.
+Disk images can be used with
+.Xr vnconfig 8 .
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl d
Debug.
.It Fl x
-Rather than inserting, extract the
-.Ar disk.fs
-image.
-The disk can be made accessible using
-.Xr vnconfig 8 ,
-filesystems can be manipulated, and finally re-inserted into the RAMDISK
kernel.
+Extract the disk image.
+If
+.Ar disk
+is not specified, standard output is used.
.El
.Sh SEE ALSO
.Xr config 8 ,
Index: rdsetroot.c
===
RCS file: /cvs/src/usr.sbin/rdsetroot/rdsetroot.c,v
retrieving revision 1.3
diff -u -p -r1.3 rdsetroot.c
--- rdsetroot.c 24 Oct 2021 21:24:19 - 1.3
+++ rdsetroot.c 20 Jan 2023 12:33:33 -
@@ -294,6 +294,6 @@ usage(void)
{
extern char *__progname;
- fprintf(stderr, "usage: %s [-dx] bsd [fs]\n", __progname);
+ fprintf(stderr, "usage: %s [-dx] kernel [disk]\n", __progname);
exit(1);
}
Re: rdsetroot.8: sync synopsis with usage, improve wording
On Thu, Jan 19, 2023 at 06:50:14PM +, Klemens Nanni wrote: > $ man -h rdsetroot > rdsetroot [-dx] kernel [disk.fs] > vs. > $ rdsetroot > usage: rdsetroot [-dx] bsd [fs] > i have to say i think the man page has better argument names, but i've nothing against your changes. just as long as they match. > Clarify that -x uses stdout (could be a default file like ktrace(1) does) > and switch 'standard in/output' to more common '.Va stdin/out' like the > related vnconfig(8) does. > i'm fine with your diff, but i think that "reads from standard input" is much easier to understand than the change you propose. jmc > Explaining how disk images can round trip through rdsetroot and vnconfig > is vaguely useful, imho, even less so in the description of -x, so briefly > mention the relation and let readers follow the reference for more. > > Feedback? Objection? OK? > > Index: rdsetroot.8 > === > RCS file: /cvs/src/usr.sbin/rdsetroot/rdsetroot.8,v > retrieving revision 1.2 > diff -u -p -r1.2 rdsetroot.8 > --- rdsetroot.8 5 Apr 2019 21:44:32 - 1.2 > +++ rdsetroot.8 19 Jan 2023 18:39:03 - > @@ -23,31 +23,34 @@ > .Sh SYNOPSIS > .Nm rdsetroot > .Op Fl dx > -.Ar kernel > -.Op Ar disk.fs > +.Ar bsd > +.Op Ar fs > .Sh DESCRIPTION > The > .Nm > -utility inserts the file > -.Ar disk.fs > -into the reserved space inside a RAMDISK kernel. > +utility inserts the disk image > +.Ar fs > +into the reserved space inside the RAMDISK kernel > +.Ar bsd . > If > -.Ar disk.fs > +.Ar fs > is not specified, > -.Nm > -reads from standard input. > +.Va stdin > +is used. > +Disk images can be used with > +.Xr vnconfig 8 . > .Pp > The options are as follows: > .Bl -tag -width Ds > .It Fl d > Debug. > .It Fl x > -Rather than inserting, extract the > -.Ar disk.fs > -image. > -The disk can be made accessible using > -.Xr vnconfig 8 , > -filesystems can be manipulated, and finally re-inserted into the RAMDISK > kernel. > +Extract the disk image. > +If > +.Ar fs > +is not specified, > +.Va stdout > +is used. > .El > .Sh SEE ALSO > .Xr config 8 , >
