Re: [PATCH v2 1/6] intro.1: Revise language

[Alejandro Colomar <alx@kernel.org>]

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

Hi Jeremy,

On Sun, Mar 17, 2024 at 09:08:28PM +1300, Jeremy Baxter wrote:
> ---
>  man1/intro.1 | 222 ++++++++++++++++++++++++++++-----------------------
>  1 file changed, 120 insertions(+), 102 deletions(-)
> 
> diff --git a/man1/intro.1 b/man1/intro.1
> index decaab161..96eb3b7fc 100644
> --- a/man1/intro.1
> +++ b/man1/intro.1
> @@ -7,40 +7,41 @@
>  intro \- introduction to user commands
>  .SH DESCRIPTION
>  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.
> +for example file manipulation tools, shells, compilers,

Why?  A comma should follow 'for example'.
See <https://grammarhow.com/comma-before-or-after-for-example/>.

> +web browsers, file and image viewers, editors, and so on.

editors here meant "file and image editors", so it was correct as it
was.

>  .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 many user commands under UNIX work
> +approximately the same under Linux (along with other UNIX-like systems,
> +such as the BSDs).

Why is this an improvement?  It seems to say the same thing as before.

>  .P
> -Under Linux, there are GUIs (graphical user interfaces), where you
> -can point and click and drag, and hopefully get work done without
> -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.
> +Under Linux, there are graphical user interfaces (GUIs),
> +where, using a mouse, you click and drag buttons and sliders and icons,

You can actually use other things, like a trackball or a trackpad.
Maybe even a joystick.  :)

> +and hopefully get work done without first reading much documentation.
> +The traditional UNIX environment is a command line interface (CLI),
> +where you type commands to tell the computer what to do.
> +The command line interface is faster and more powerful than
> +a graphical interface,
> +but first requires finding out what commands you have and how they are used.

This also seems like a rewrite that doesn't necessarily improve things.

> +A minimal guide is provided below to help you get started.
>  .SS Login
> -In order to start working, you probably first have to open a session by
> -giving your username and password.
> -The program
> +In order to start working, you'll probably have to open a session
> +by typing your username and password.
> +After this, the program

Hmmm, this line is interesting.  With the previous text, it wasn't clear
that the login program gives you a shell after giving your (correct)
username and password.

Maybe I would mention login before talking about the name and pass.
How about this?

	In order to start working,
	you'll probably have to open a session.
	The program
	.BR login (1)
	will wait for you to type your username and password,
	and after that,
	it will start a

>  .BR login (1)
> -now starts a
> +starts a
>  .I shell
>  (command interpreter) for you.
> -In case of a graphical login, you get a screen with menus or icons
> -and a mouse click will start a shell in a window.
> +In case of a graphical login, you'll get a screen with menus and/or icons.
> +By using your mouse to click on one of these menus or icons,
> +you can start a shell in a window.

I think this is unnecessary.

>  See also
>  .BR xterm (1).
>  .SS The shell
> -One types commands to the
> +One types commands into the

LGTM.

>  .IR shell ,
>  the command interpreter.
> -It is not built-in, but is just a program
> -and you can change your shell.
> +It isn't built-in, but it's just a program included with the operating system.

Unnecessary mention of OS, I think.

> +There are many different shells.

Redundant: the next sentence already implies this.

>  Everybody has their own favorite one.
>  The standard one is called
>  .IR sh .
> @@ -53,7 +54,7 @@ See also
>  .BR ksh (1),
>  .BR zsh (1).
>  .P
> -A session might go like:
> +A session might look like this:

Unnecessary, I think.  The previous wording is fine.

>  .P
>  .in +4n
>  .EX
> @@ -99,89 +100,96 @@ $
>  .EE
>  .in
>  .P
> -Here typing Control-D ended the session.
> +Pressing Control-D ended the session.

Unnecessary.  Maybe I'd add a comma after "Here".

>  .P
> -The
> +The symbol

Unnecessary.  I read it meantally as "The dollar here was ...", which is
just fine.

>  .B $
>  here was the command prompt\[em]it is the shell's way of indicating
>  that it is ready for the next command.
> -The prompt can be customized
> -in lots of ways, and one might include stuff like username,
> -machine name, current directory, time, and so on.
> +The prompt can be customized in lots of ways, and one might include

This undoes semantic newlines, which unnecessarily overloads the diff
with little real changes.

> +information like the username, machine name, current directory, the time,
> +and so on.
>  An assignment PS1="What next, master? "
>  would change the prompt as indicated.
>  .P
> -We see that there are commands
> +From this example we can see that there is the command

It's more precise, but the previous wording was simpler, and could be
understood, I think.  I'm not sure I like the change.

>  .I date
> -(that gives date and time), and
> +(which outputs the date and time), and the command
>  .I cal
> -(that gives a calendar).
> +(which outputs a calendar).
>  .P
>  The command
>  .I ls
>  lists the contents of the current directory\[em]it tells you what
>  files you have.
> -With a
> +Given a
>  .I \-l
> -option it gives a long listing,
> -that includes the owner and size and date of the file, and the
> -permissions people have for reading and/or changing the file.
> -For example, the file "tel" here is 37 bytes long, owned by aeb
> -and the owner can read and write it, others can only read it.
> -Owner and permissions can be changed by the commands
> +option
> +.I ls

We're already talking about ls(1); why repeat it?

> +outputs a long listing,
> +which includes the owner of the file, its size, the date it was last
> +modified, as well as the permissions people have for reading and/or
> +writing to the file.
> +For example, the file "tel" here is 37 bytes long, owned by the user aeb.

Semantic newlines.

> +The owner can read and write to it, but others can only read it.
> +The owner and permissions of a file can be changed by the commands
>  .I chown
>  and
> -.IR chmod .
> +.I chmod
> +respectively.

"respectively" should be preceeded by a comma.

>  .P
>  The command
>  .I cat
>  will show the contents of a file.
> -(The name is from "concatenate and print": all files given as
> -parameters are concatenated and sent to "standard output"
> +The name is from "concatenate and print": all files given as

This is actually a parenthetical on the previous sentence, and
parentheses are correct.  What I don't love is starting a new sentence.
Maybe it would be more correct without a preceeding '.', and thus
starting in lowercase, and the last '.' would go outside of the
parentheses, but this is widespread, so I think it's fine.

> +parameters are concatenated and written to "standard output"
>  (see
>  .BR stdout (3)),
>  here
> -the terminal screen.)
> +the terminal screen.
>  .P
>  The command
>  .I cp
> -(from "copy") will copy a file.
> +(from "copy") copies a file.

cat will show
but
cp copies
?

>  .P
>  The command
>  .I mv
> -(from "move"), on the other hand, only renames it.
> +(from "move"), on the other hand, renames a file.

The "on the other hand" part looses its sense without "only", I think.

>  .P
>  The command
>  .I diff
>  lists the differences between two files.
> -Here there was no output because there were no differences.
> +In this example there was no output because there were no differences

Here and in this example are the same thing.  Here is shorter.  Why
change it?  I think it's clear.

> +between the two.

And this is redundant.  The simpler the better, I think.

>  .P
>  The command
>  .I rm
> -(from "remove") deletes the file, and be careful! it is gone.
> -No wastepaper basket or anything.
> +(from "remove") deletes a file, but be careful!
> +Any file you remove with
> +.I rm
> +will be gone forever.

Redundant.

> +No rubbish bin or anything.

Don't you like wastepaper baskets?  :)

Have a lovely day!
Alex

>  Deleted means lost.
>  .P
>  The command
>  .I grep
>  (from "g/re/p") finds occurrences of a string in one or more files.
> -Here it finds Maja's telephone number.
> +In this example, we use it to find Maja's telephone number.
>  .SS Pathnames and the current directory
> -Files live in a large tree, the file hierarchy.
> -Each has a
> +Files live in a large tree, called the file hierarchy.
> +Each file has a
>  .I "pathname"
> -describing the path from the root of the tree (which is called
> -.IR / )
> -to the file.
> -For example, such a full pathname might be
> +describing the location of the file from the root of the tree
> +(whose pathname is
> +.IR / ).
> +For instance, a full pathname might be
>  .IR /home/aeb/tel .
> -Always using full pathnames would be inconvenient, and the name
> -of a file in the current directory may be abbreviated by giving
> -only the last component.
> -That is why
> +Using full pathnames all the time would be very inconvenient.
> +The name of a file in the current directory may be shortened by only
> +using the last component (the part relative to the current directory).
> +That's why
>  .I /home/aeb/tel
> -can be abbreviated
> -to
> +can be shortened to
>  .I tel
>  when the current directory is
>  .IR /home/aeb .
> @@ -194,13 +202,11 @@ The command
>  .I cd
>  changes the current directory.
>  .P
> -Try alternatively
> +Try using the
>  .I cd
>  and
>  .I pwd
> -commands and explore
> -.I cd
> -usage: "cd", "cd .", "cd ..", "cd /", and "cd \[ti]".
> +commands in different ways.
>  .SS Directories
>  The command
>  .I mkdir
> @@ -208,67 +214,79 @@ makes a new directory.
>  .P
>  The command
>  .I rmdir
> -removes a directory if it is empty, and complains otherwise.
> +removes an empty directory. If the directory is not empty,
> +.I rmdir
> +outputs an error message.
>  .P
>  The command
>  .I find
> -(with a rather baroque syntax) will find files with given name
> -or other properties.
> -For example, "find . \-name tel" would find
> -the file
> -.I tel
> -starting in the present directory (which is called
> +(which has a rather strange syntax) will find files with a given name
> +or other specified properties.
> +For example, "find . \-name tel" would find files with the name
> +.I tel ,
> +starting the search in the current directory (which is represented by
>  .IR . ).
> -And "find / \-name tel" would do the same, but starting at the root
> -of the tree.
> -Large searches on a multi-GB disk will be time-consuming,
> -and it may be better to use
> +Using the command "find / \-name tel" would do the same,
> +except it would it would start at the root of the directory tree.
> +Large searches on a multi-gigabyte disk can be time-consuming;
> +if you find yourself doing this, it may be more efficient to use
>  .BR locate (1).
>  .SS Disks and filesystems
>  The command
>  .I mount
> -will attach the filesystem found on some disk (or floppy, or CDROM or so)
> -to the big filesystem hierarchy.
> -And
> +will attach the filesystem found on a disk (or a USB drive, CD-ROM etc.)
> +to a directory in the filesystem hierarchy.
> +When you are finished working with your disk, you can use
>  .I umount
> -detaches it again.
> +to detach it again.
>  The command
>  .I df
> -will tell you how much of your disk is still free.
> +will tell you how much of your disk's space is free.
>  .SS Processes
> -On a UNIX system many user and system processes run simultaneously.
> -The one you are talking to runs in the
> +On a UNIX system, many user and system processes run simultaneously.
> +The one you are currently using (e.g. your shell) runs in the
>  .IR foreground ,
> -the others in the
> +while other processes run in the
>  .IR background .
>  The command
>  .I ps
> -will show you which processes are active and what numbers these
> -processes have.
> +will list active processes and each one's ID.
>  The command
>  .I kill
> -allows you to get rid of them.
> -Without option this is a friendly
> -request: please go away.
> -And "kill \-9" followed by the number
> -of the process is an immediate kill.
> +allows you to stop processes.
> +Running
> +.I kill
> +without any options sends a friendly request to a process:
> +"please clean up and finish now".
> +If this doesn't work, you can use "kill \-9" followed by the ID of the
> +process to immediately kill it; the process will have no time to clean up.
>  Foreground processes can often be killed by typing Control-C.
>  .SS Getting information
>  There are thousands of commands, each with many options.
> -Traditionally commands are documented on
> -.IR "man pages" ,
> -(like this one), so that the command "man kill" will document
> -the use of the command "kill" (and "man man" document the command "man").
> +Traditionally, commands are documented on
> +.I "man pages"
> +like this one.
> +Man pages can be accessed via the
> +.I man
> +command.
> +For example, the command "man kill" will bring up a manual
> +for the "kill" command.
> +"man man" will bring up a manual for
> +.I man
> +itself.
>  The program
>  .I man
> -sends the text through some
> +sends the text through a
>  .IR pager ,
>  usually
>  .IR less .
> -Hit the space bar to get the next page, hit q to quit.
> +Using
> +.IR less ,
> +you can press the space bar to see the next page, the "b" key to see
> +the previous page, and "q" to quit.
>  .P
>  In documentation it is customary to refer to man pages
> -by giving the name and section number, as in
> +by using the name followed by the section number in brackets, as in
>  .BR man (1).
>  Man pages are terse, and allow you to find quickly some forgotten
>  detail.
> @@ -280,10 +298,10 @@ Type "info info"
>  for an introduction on the use of the program
>  .IR info .
>  .P
> -Special topics are often treated in HOWTOs.
> -Look in
> -.I /usr/share/doc/howto/en
> -and use a browser if you find HTML files there.
> +Some topics can be documented in HOWTO files.
> +To find these, look for HTML files in
> +.IR /usr/share/doc/howto/en ,
> +and use a web browser to view them.
>  .\"
>  .\" Actual examples? Separate section for each of cat, cp, ...?
>  .\" gzip, bzip2, tar, rpm
> -- 
> 2.44.0
> 
> 

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

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