linux-kernel - Re: [PATCH] Documentation: sysrq: convert to third person

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <87v95fpiox.fsf@meer.lwn.net>
Date:   Mon, 12 Jul 2021 11:04:30 -0600
From:   Jonathan Corbet <corbet@....net>
To:     Cengiz Can <cengiz@...nel.wtf>
Cc:     linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
        Cengiz Can <cengiz@...nel.wtf>
Subject: Re: [PATCH] Documentation: sysrq: convert to third person

Cengiz Can <cengiz@...nel.wtf> writes:

> Two parts of the sysrq documentation have sentences written from a first
> person's point of view.
>
> Documentation is generally written from a third person's view in a
> formal way.
>
> Convert those senteces to be less personal and generic.

So this seems like a fine change, but I have one little gripe...

> Signed-off-by: Cengiz Can <cengiz@...nel.wtf>
> ---
>  Documentation/admin-guide/sysrq.rst | 12 +++++++-----
>  1 file changed, 7 insertions(+), 5 deletions(-)
>
> diff --git a/Documentation/admin-guide/sysrq.rst b/Documentation/admin-guide/sysrq.rst
> index 60ce5f5ebab6..0a178ef0111d 100644
> --- a/Documentation/admin-guide/sysrq.rst
> +++ b/Documentation/admin-guide/sysrq.rst
> @@ -72,7 +72,7 @@ On PowerPC
>  
>  On other
>  	If you know of the key combos for other architectures, please
> -        let me know so I can add them to this section.
> +	submit a patch to be included in this section.
>  
>  On all
>  	Write a character to /proc/sysrq-trigger.  e.g.::
> @@ -205,10 +205,12 @@ frozen (probably root) filesystem via the FIFREEZE ioctl.
>  Sometimes SysRq seems to get 'stuck' after using it, what can I do?
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>  
> -That happens to me, also. I've found that tapping shift, alt, and control
> -on both sides of the keyboard, and hitting an invalid sysrq sequence again
> -will fix the problem. (i.e., something like :kbd:`alt-sysrq-z`). Switching to
> -another virtual console (:kbd:`ALT+Fn`) and then back again should also help.
> +When this happens, try tapping shift, alt and control on both sides of the
> +keyboard, and hitting an invalid sysrq sequence again. (i.e., something like
> +:kbd:`alt-sysrq-z`).
> +
> +Switching to another virtual console (:kbd:`ALT+Fn`) and then back again
> +should also help.

The :kbd: stuff is a pretty good example of the sort of extra markup we
try to avoid when we can.  It adds little to the formatted docs and
worsens the reading experience for plain-text.  It sure would be nice if
we could make that kind of stuff go away when we're in the neighborhood.

Anyway, I've applied the patch.

Thanks,

jon