[PATCH 1/4] setarch: differentiate between "unrecognized" and "cannot set"

[PATCH 1/4] setarch: differentiate between "unrecognized" and "cannot set"

[Benno Schulenberg]

When the provided string does not match any architecture that
setarch knows about, the response stays "Unrecognized architecture",
but when trying to set the specified architecture does not have any
effect, then respond with "Kernel cannot set architecture to...".

Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
---
 sys-utils/setarch.c |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/sys-utils/setarch.c b/sys-utils/setarch.c
index 8e52179..a09625c 100644
--- a/sys-utils/setarch.c
+++ b/sys-utils/setarch.c
@@ -247,7 +247,7 @@ static int set_arch(const char *pers, unsigned long options, int list)
 			&& strcmp(un.machine, "i586")
 			&& strcmp(un.machine, "i686")
 			&& strcmp(un.machine, "athlon")))
-			errx(EXIT_FAILURE, _("%s: Unrecognized architecture"), pers);
+			errx(EXIT_FAILURE, _("Kernel cannot set architecture to %s"), pers);
 	}
 	return 0;
 }
-- 
1.7.0.4

[PATCH 2/4] docs: mention that setarch may not be able to set all listed architectures

[Benno Schulenberg]

Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
---
 sys-utils/setarch.8 |    9 +++++----
 1 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/sys-utils/setarch.8 b/sys-utils/setarch.8
index a9a126a..d0f1cba 100644
--- a/sys-utils/setarch.8
+++ b/sys-utils/setarch.8
@@ -24,11 +24,12 @@ It also allows to set various personality options.
 The default \fIprogram\fR is \fB/bin/sh\fR.
 .SH OPTIONS
 .TP
-\fB\-\-list\fR
-List the architectures that can be set.
+.B \-\-list
+List the architectures that \fBsetarch\fR knows about.  Whether \fBsetarch\fR
+can actually set each of these architectures depends on the running kernel.
 .TP
-\fB\-\-uname\-2.6\fR
-Causes the program to see a kernel version number beginning with 2.6.
+.B \-\-uname-2.6
+Causes the \fIprogram\fR to see a kernel version number beginning with 2.6.
 .TP
 .BR \-v , " \-\-verbose"
 Be verbose.
-- 
1.7.0.4

Re: [PATCH 2/4] docs: mention that setarch may not be able to set all listed architectures

[JWP]

On 01/10/2015 08:41 AM, Benno Schulenberg wrote:
> Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
> ---
>  sys-utils/setarch.8 |    9 +++++----
>  1 files changed, 5 insertions(+), 4 deletions(-)
> 
> diff --git a/sys-utils/setarch.8 b/sys-utils/setarch.8
> index a9a126a..d0f1cba 100644
> --- a/sys-utils/setarch.8
> +++ b/sys-utils/setarch.8
> @@ -24,11 +24,12 @@ It also allows to set various personality options.
>  The default \fIprogram\fR is \fB/bin/sh\fR.
>  .SH OPTIONS
>  .TP
> -\fB\-\-list\fR
> -List the architectures that can be set.
> +.B \-\-list
> +List the architectures that \fBsetarch\fR knows about.  Whether \fBsetarch\fR
> +can actually set each of these architectures depends on the running kernel.
>  .TP
> -\fB\-\-uname\-2.6\fR
> -Causes the program to see a kernel version number beginning with 2.6.
> +.B \-\-uname-2.6

This is incorrect. Options are always constructed with minus signs never a hyphens.
The only time a hyphen should be used in man-pages is for normally hyphenated 
dictionary words. Commands, options, variables, paths, urls, etc. all use the
minus sign character. For troff that is \-.

groff(7)
       \-     The - (minus) sign in the current font.


> +Causes the \fIprogram\fR to see a kernel version number beginning with 2.6.
>  .TP
>  .BR \-v , " \-\-verbose"
>  Be verbose.
> 

Re: [PATCH 2/4] docs: mention that setarch may not be able to set all listed architectures

[Benno Schulenberg]

On Sun, Jan 11, 2015, at 17:19, JWP wrote:
> On 01/10/2015 08:41 AM, Benno Schulenberg wrote:
> > -\fB\-\-uname\-2.6\fR
> > -Causes the program to see a kernel version number beginning with 2.6.
> > +.B \-\-uname-2.6
> 
> This is incorrect. Options are always constructed with minus signs never a hyphens.
> The only time a hyphen should be used in man-pages is for normally hyphenated 
> dictionary words. Commands, options, variables, paths, urls, etc. all use the
> minus sign character.

You are right.  However, on a terminal both hyphen and minus sign render
to 0x2d.  When printed, the characters are rendered differently, and then
I prefer to see a tiny hyphen instead of a minus sign in hyphenated options.
And since you cannot copy and paste from a printed document, it doesn't
matter that the more readable hyphen is used instead of the correct minus
sign.

See also 'git log -p --author=bjarniig' and search for "to '-'", and also
http://www.spinics.net/lists/util-linux-ng/msg09260.html near the end.

If you maintain that the correct \- should be used, there will be a
large patch to make.

Benno

-- 
http://www.fastmail.com - Same, same, but different...

Re: [PATCH 2/4] docs: mention that setarch may not be able to set all listed architectures

[JWP]

On 01/11/2015 12:07 PM, Benno Schulenberg wrote:
> 
> On Sun, Jan 11, 2015, at 17:19, JWP wrote:
>> On 01/10/2015 08:41 AM, Benno Schulenberg wrote:
>>> -\fB\-\-uname\-2.6\fR
>>> -Causes the program to see a kernel version number beginning with 2.6.
>>> +.B \-\-uname-2.6
>>
>> This is incorrect. Options are always constructed with minus signs never a hyphens.
>> The only time a hyphen should be used in man-pages is for normally hyphenated 
>> dictionary words. Commands, options, variables, paths, urls, etc. all use the
>> minus sign character.
> 
> You are right.  However, on a terminal both hyphen and minus sign render
> to 0x2d.  When printed, the characters are rendered differently, and then
> I prefer to see a tiny hyphen instead of a minus sign in hyphenated options.
> And since you cannot copy and paste from a printed document, it doesn't
> matter that the more readable hyphen is used instead of the correct minus
> sign.

The world is going paperless, favoring print manuals over online is going the
wrong direction. Just because it uses the same glyph on your terminal does not
mean the same will be true for every application that renders a man-page.

However, the more important point is not what glyph is printed, but how troff 
formats a hyphen vs a minus sign. We do not want line breaks made mid: command,
command string, option, variable, url, etc. It could be argued that when
they are located near the left margin, such as in TP context, it would not
cause formatting issues, but they need to be kept consistent through out the
document and are often later used mid-paragraph.

If one of them is split with a hyphen at line end, how does one know if the
hyphen was added for formatting, or if it is part of the name?

I ran into that exact problem with persistent_clock_is_local in the hwclock 
man-page. That is why I added the \% you asked about.

> 
> See also 'git log -p --author=bjarniig' and search for "to '-'", and also
> http://www.spinics.net/lists/util-linux-ng/msg09260.html near the end.

      Change '\-' (minus) to '-' (code "hyphen-minus", rendered with the
      glyph 'hyphen' in troff), if it is a part of a compound word.

Yes, I said that compound words are the only place to use the hyphen. Dictionary
compound words. Most options do not form legitimate compound words, and even if
they did you should not hyphenate them. They need to be presented as they are used,
on paper or otherwise.

Then later in commit 2ad6d4f Mr. Gislason says:

      Change '-' to '\-', if it indicates an option
      Change '--' to '\-\-', if it indicates an option

I hope he did not then make a minus in the 'word' of the option a hyphen.


> 
> If you maintain that the correct \- should be used, there will be a
> large patch to make.
> 
> Benno
> 

Re: [PATCH 2/4] docs: mention that setarch may not be able to set all listed architectures

[karel Zak]

On Sun, Jan 11, 2015 at 01:43:21PM -0500, JWP wrote:
> On 01/11/2015 12:07 PM, Benno Schulenberg wrote:
> > 
> > On Sun, Jan 11, 2015, at 17:19, JWP wrote:
> >> On 01/10/2015 08:41 AM, Benno Schulenberg wrote:
> >>> -\fB\-\-uname\-2.6\fR
> >>> -Causes the program to see a kernel version number beginning with 2.6.
> >>> +.B \-\-uname-2.6
> >>
> >> This is incorrect. Options are always constructed with minus signs never a hyphens.
> >> The only time a hyphen should be used in man-pages is for normally hyphenated 
> >> dictionary words. Commands, options, variables, paths, urls, etc. all use the
> >> minus sign character.
> > 
> > You are right.  However, on a terminal both hyphen and minus sign render
> > to 0x2d.  When printed, the characters are rendered differently, and then
> > I prefer to see a tiny hyphen instead of a minus sign in hyphenated options.
> > And since you cannot copy and paste from a printed document, it doesn't
> > matter that the more readable hyphen is used instead of the correct minus
> > sign.
> 
> The world is going paperless, favoring print manuals over online is going the
> wrong direction. Just because it uses the same glyph on your terminal does not
> mean the same will be true for every application that renders a man-page.
> 
> However, the more important point is not what glyph is printed, but how troff 
> formats a hyphen vs a minus sign. We do not want line breaks made mid: command,

 For me is important to use in man pages the same option names (same
 chars) like we have in source code where I see 0x2d, and I'd like
 like to minimize variability in the man pages, it's better to be
 consistent than be perfect.

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: [PATCH 2/4] docs: mention that setarch may not be able to set all listed architectures

[Karel Zak]

On Sat, Jan 10, 2015 at 02:41:33PM +0100, Benno Schulenberg wrote:
>  sys-utils/setarch.8 |    9 +++++----
>  1 files changed, 5 insertions(+), 4 deletions(-)

 Applied (with minus:-), thanks.

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

[PATCH 3/4] setarch: accept the option --list in any position

[Benno Schulenberg]

Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
---
 sys-utils/setarch.c |    7 ++++++-
 1 files changed, 6 insertions(+), 1 deletions(-)

diff --git a/sys-utils/setarch.c b/sys-utils/setarch.c
index a09625c..a60d2b0 100644
--- a/sys-utils/setarch.c
+++ b/sys-utils/setarch.c
@@ -44,7 +44,8 @@
 /* Options without equivalent short options */
 enum {
 	OPT_4GB = CHAR_MAX + 1,
-	OPT_UNAME26
+	OPT_UNAME26,
+	OPT_LIST
 };
 
 #define turn_on(_flag, _opts) \
@@ -277,6 +278,7 @@ int main(int argc, char *argv[])
 		{"3gb",			no_argument,	NULL,	'3'},
 		{"4gb",			no_argument,	NULL,	OPT_4GB},
 		{"uname-2.6",		no_argument,	NULL,	OPT_UNAME26},
+		{"list",		no_argument,	NULL,	OPT_LIST},
 		{NULL,			0,		NULL,	0}
 	};
 
@@ -360,6 +362,9 @@ int main(int argc, char *argv[])
 		case OPT_UNAME26:
 			turn_on(UNAME26, options);
 			break;
+		case OPT_LIST:
+			set_arch(argv[0], 0L, 1);
+			return EXIT_SUCCESS;
 		default:
 			show_usage(NULL);
 		}
-- 
1.7.0.4

Re: [PATCH 3/4] setarch: accept the option --list in any position

[Karel Zak]

On Sat, Jan 10, 2015 at 02:41:34PM +0100, Benno Schulenberg wrote:
>  sys-utils/setarch.c |    7 ++++++-
>  1 files changed, 6 insertions(+), 1 deletions(-)

 I have applied a little different version with some additional
 cleanups. Note that I think --list should be available only for
 "setarch" but no for arch specific symlinks.

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

[PATCH 4/4] setarch: in the usage text only mention options that actually do something

[Benno Schulenberg]

It is enough that --4gb is mentioned in the man page.

Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
---
 sys-utils/setarch.c |    1 -
 1 files changed, 0 insertions(+), 1 deletions(-)

diff --git a/sys-utils/setarch.c b/sys-utils/setarch.c
index a60d2b0..96fd183 100644
--- a/sys-utils/setarch.c
+++ b/sys-utils/setarch.c
@@ -111,7 +111,6 @@ static void __attribute__((__noreturn__)) show_help(void)
 	fputs(_(" -X, --read-implies-exec  turns on READ_IMPLIES_EXEC\n"), stdout);
 	fputs(_(" -Z, --mmap-page-zero     turns on MMAP_PAGE_ZERO\n"), stdout);
 	fputs(_(" -3, --3gb                limits the used address space to a maximum of 3 GB\n"), stdout);
-	fputs(_("     --4gb                ignored (for backward compatibility only)\n"), stdout);
 	fputs(_("     --uname-2.6          turns on UNAME26\n"), stdout);
 	fputs(_(" -v, --verbose            say what options are being switched on\n"), stdout);
 	fputs(_("     --list               list settable architectures, and exit\n"), stdout);
-- 
1.7.0.4

Re: [PATCH 4/4] setarch: in the usage text only mention options that actually do something

[Karel Zak]

On Sat, Jan 10, 2015 at 02:41:35PM +0100, Benno Schulenberg wrote:
> It is enough that --4gb is mentioned in the man page.
...
> -	fputs(_("     --4gb                ignored (for backward compatibility only)\n"), stdout);

I'm not sure about this kind of change. If I good remember than for
example in RH we have some QA tests to compare man page and --help.

IMHO if we have any feature/option than it's better to keep it
documented on all places.

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: [PATCH 1/4] setarch: differentiate between "unrecognized" and "cannot set"

[Karel Zak]

On Sat, Jan 10, 2015 at 02:41:32PM +0100, Benno Schulenberg wrote:
>  sys-utils/setarch.c |    2 +-
>  1 files changed, 1 insertions(+), 1 deletions(-)

 Applied, thanks.

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com