[PATCH] intro.1: Improve wording in initial introduction

[PATCH] intro.1: Improve wording in initial introduction

[Jeremy Baxter]

---
 man/man1/intro.1 | 31 +++++++++++++++++--------------
 1 file changed, 17 insertions(+), 14 deletions(-)

diff --git a/man/man1/intro.1 b/man/man1/intro.1
index decaab161..4d9e81c5a 100644
--- a/man/man1/intro.1
+++ b/man/man1/intro.1
@@ -10,9 +10,9 @@ Section 1 of the manual describes user commands and tools,
 for example, file manipulation tools, shells, compilers,
 web browsers, file and image viewers and editors, and so on.
 .SH NOTES
-Linux is a flavor of UNIX, and as a first approximation
-all user commands under UNIX work precisely the same under
-Linux (and FreeBSD and lots of other UNIX-like systems).
+Linux is a flavor of UNIX, and user commands under UNIX
+work similarly under Linux (and lots of other UNIX-like systems too,
+like FreeBSD).
 .P
 Under Linux, there are GUIs (graphical user interfaces), where you
 can point and click and drag, and hopefully get work done without
@@ -20,15 +20,17 @@ first reading lots of documentation.
 The traditional UNIX environment
 is a CLI (command line interface), where you type commands to
 tell the computer what to do.
-That is faster and more powerful,
-but requires finding out what the commands are.
-Below a bare minimum, to get started.
+This is faster and more powerful,
+but requires finding out what the commands are and how to use them.
+Below is a bare minimum guide to get you started.
 .SS Login
-In order to start working, you probably first have to open a session by
-giving your username and password.
+In order to start working,
+you'll probably first have to open a session.
 The program
 .BR login (1)
-now starts a
+will wait for you to type your username and password,
+and after that,
+it will start a
 .I shell
 (command interpreter) for you.
 In case of a graphical login, you get a screen with menus or icons
@@ -36,12 +38,13 @@ and a mouse click will start a shell in a window.
 See also
 .BR xterm (1).
 .SS The shell
-One types commands to the
+One types commands into the
 .IR shell ,
 the command interpreter.
-It is not built-in, but is just a program
-and you can change your shell.
-Everybody has their own favorite one.
+It is not built-in,
+but is just another program.
+You can change your shell,
+and everybody has their own favorite one.
 The standard one is called
 .IR sh .
 See also
@@ -53,7 +56,7 @@ See also
 .BR ksh (1),
 .BR zsh (1).
 .P
-A session might go like:
+A session might look like this:
 .P
 .in +4n
 .EX
-- 
2.45.2

Re: [PATCH] intro.1: Improve wording in initial introduction

[Alejandro Colomar]

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

Hi Jeremy,

On Mon, Jun 17, 2024 at 10:29:17AM GMT, Jeremy Baxter wrote:
> ---

For readers of the list, this is a continuation of
<https://lore.kernel.org/linux-man/CZX4Y18EKIWK.1YLSFJIPJG2YA@disroot.org/>

>  man/man1/intro.1 | 31 +++++++++++++++++--------------
>  1 file changed, 17 insertions(+), 14 deletions(-)
> 
> diff --git a/man/man1/intro.1 b/man/man1/intro.1
> index decaab161..4d9e81c5a 100644
> --- a/man/man1/intro.1
> +++ b/man/man1/intro.1
> @@ -10,9 +10,9 @@ Section 1 of the manual describes user commands and tools,
>  for example, file manipulation tools, shells, compilers,
>  web browsers, file and image viewers and editors, and so on.
>  .SH NOTES
> -Linux is a flavor of UNIX, and as a first approximation
> -all user commands under UNIX work precisely the same under
> -Linux (and FreeBSD and lots of other UNIX-like systems).
> +Linux is a flavor of UNIX, and user commands under UNIX
> +work similarly under Linux (and lots of other UNIX-like systems too,
> +like FreeBSD).

I like the changes in this paragraph, except for the removal of "as a
first approximation".  Not a big deal, though.

>  .P
>  Under Linux, there are GUIs (graphical user interfaces), where you
>  can point and click and drag, and hopefully get work done without
> @@ -20,15 +20,17 @@ first reading lots of documentation.
>  The traditional UNIX environment
>  is a CLI (command line interface), where you type commands to
>  tell the computer what to do.
> -That is faster and more powerful,
> -but requires finding out what the commands are.
> -Below a bare minimum, to get started.
> +This is faster and more powerful,
> +but requires finding out what the commands are and how to use them.
> +Below is a bare minimum guide to get you started.

LGTM.

>  .SS Login
> -In order to start working, you probably first have to open a session by
> -giving your username and password.
> +In order to start working,
> +you'll probably first have to open a session.

LGTM.

>  The program
>  .BR login (1)
> -now starts a
> +will wait for you to type your username and password,
> +and after that,
> +it will start a
>  .I shell
>  (command interpreter) for you.

LGTM.

>  In case of a graphical login, you get a screen with menus or icons
> @@ -36,12 +38,13 @@ and a mouse click will start a shell in a window.
>  See also
>  .BR xterm (1).
>  .SS The shell
> -One types commands to the
> +One types commands into the
>  .IR shell ,
>  the command interpreter.

LGTM.

> -It is not built-in, but is just a program
> -and you can change your shell.
> -Everybody has their own favorite one.
> +It is not built-in,
> +but is just another program.

I would maybe use a ';'?

	It is not built-in;
	it is just another program.

> +You can change your shell,
> +and everybody has their own favorite one.
>  The standard one is called
>  .IR sh .

LGTM.

>  See also
> @@ -53,7 +56,7 @@ See also
>  .BR ksh (1),
>  .BR zsh (1).
>  .P
> -A session might go like:
> +A session might look like this:

LGTM.

>  .P
>  .in +4n
>  .EX
> -- 
> 2.45.2

I think I'll apply this patch.  Let me meditate it to-night.  I CCed
Doug, in case he has any comments (it would be great to hear his
feedback).

Have a lovely night!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] intro.1: Improve wording in initial introduction

[Jeremy Baxter]

Alejandro Colomar <alx@kernel.org> writes:
>> -Linux is a flavor of UNIX, and as a first approximation
>> -all user commands under UNIX work precisely the same under
>> -Linux (and FreeBSD and lots of other UNIX-like systems).
>> +Linux is a flavor of UNIX, and user commands under UNIX
>> +work similarly under Linux (and lots of other UNIX-like systems too,
>> +like FreeBSD).
>
> I like the changes in this paragraph, except for the removal of "as a
> first approximation".  Not a big deal, though.

I don't hear "as a first approximation" spoken often and it just brings
more cognitive overhead to the content in my opinion.

>> -It is not built-in, but is just a program
>> -and you can change your shell.
>> -Everybody has their own favorite one.
>> +It is not built-in,
>> +but is just another program.
>
> I would maybe use a ';'?
>
> 	It is not built-in;
> 	it is just another program.

That's better, I'll use that in v2.

> I think I'll apply this patch.  Let me meditate it to-night.  I CCed
> Doug, in case he has any comments (it would be great to hear his
> feedback).
>
> Have a lovely night!
> Alex

Sweet, thanks for the review.