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

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

[Jeremy Baxter]

---
 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,
+web browsers, file and image viewers, 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 many user commands under UNIX work
+approximately the same under Linux (along with other UNIX-like systems,
+such as the BSDs).
 .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,
+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.
+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
 .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.
 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.
+It isn't built-in, but it's just a program included with the operating system.
+There are many different shells.
 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:
 .P
 .in +4n
 .EX
@@ -99,89 +100,96 @@ $
 .EE
 .in
 .P
-Here typing Control-D ended the session.
+Pressing Control-D ended the session.
 .P
-The
+The symbol
 .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
+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
 .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
+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.
+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.
 .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
+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.
 .P
 The command
 .I mv
-(from "move"), on the other hand, only renames it.
+(from "move"), on the other hand, renames a file.
 .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
+between the two.
 .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.
+No rubbish bin or anything.
 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

[PATCH v2 2/6] intro.1: Document the meaning of the PS1 variable

[Jeremy Baxter]

It still doesn't explain what a variable is but I think
shell variables are out of scope of this manual.
---
 man1/intro.1 | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/man1/intro.1 b/man1/intro.1
index 96eb3b7fc..090678750 100644
--- a/man1/intro.1
+++ b/man1/intro.1
@@ -109,7 +109,10 @@ that it is ready for the next command.
 The prompt can be customized in lots of ways, and one might include
 information like the username, machine name, current directory, the time,
 and so on.
-An assignment PS1="What next, master? "
+It can be changed by setting the value of the "PS1" (prompt string 1)
+variable.
+An assignment
+.B PS1="What next, master?\ "
 would change the prompt as indicated.
 .P
 From this example we can see that there is the command
-- 
2.44.0

[PATCH v2 3/6] intro.1: Explain the meaning of a directory

[Jeremy Baxter]

---
 man1/intro.1 | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/man1/intro.1 b/man1/intro.1
index 090678750..f0a8d98e0 100644
--- a/man1/intro.1
+++ b/man1/intro.1
@@ -180,6 +180,9 @@ The command
 In this example, we use it to find Maja's telephone number.
 .SS Pathnames and the current directory
 Files live in a large tree, called the file hierarchy.
+In this hierarchy, there are many
+.IR directories ;
+a directory is simply a file that can hold other files as opposed to text.
 Each file has a
 .I "pathname"
 describing the location of the file from the root of the tree
-- 
2.44.0

[PATCH v2 4/6] intro.1: Demonstrate special cases of the cd command

[Jeremy Baxter]

---
 man1/intro.1 | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/man1/intro.1 b/man1/intro.1
index f0a8d98e0..8102640ba 100644
--- a/man1/intro.1
+++ b/man1/intro.1
@@ -213,6 +213,25 @@ Try using the
 and
 .I pwd
 commands in different ways.
+.I cd .
+changes the current directory to the path to the current directory;
+this does nothing.
+.I cd ..
+changes the current directory to the parent directory of the current
+directory.
+For instance, if our current directory is
+.I /home/aeb
+and we change the current directory to
+.IR .. ,
+the current directory will now be
+.IR /home .
+.I cd /
+changes the current directory to the root of the hierarchy.
+.I cd \[ti]
+changes the current directory to the user's home; if I am logged in as
+.IR aeb ,
+this command will change my current directory to
+.IR /home/aeb .
 .SS Directories
 The command
 .I mkdir
-- 
2.44.0

[PATCH v2 5/6] intro.1: Define a process ID

[Jeremy Baxter]

---
 man1/intro.1 | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/man1/intro.1 b/man1/intro.1
index 8102640ba..72f28bc2e 100644
--- a/man1/intro.1
+++ b/man1/intro.1
@@ -275,7 +275,8 @@ while other processes run in the
 .IR background .
 The command
 .I ps
-will list active processes and each one's ID.
+will list active processes and each one's ID,
+a number which can uniquely identify a process from others.
 The command
 .I kill
 allows you to stop processes.
-- 
2.44.0

[PATCH v2 6/6] intro.1: Revise paragraph documenting GNU texinfo

[Jeremy Baxter]

---
 man1/intro.1 | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/man1/intro.1 b/man1/intro.1
index 72f28bc2e..5aad9d4e7 100644
--- a/man1/intro.1
+++ b/man1/intro.1
@@ -314,15 +314,17 @@ the previous page, and "q" to quit.
 In documentation it is customary to refer to man pages
 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.
-For newcomers an introductory text with more examples
-and explanations is useful.
 .P
-A lot of GNU/FSF software is provided with info files.
-Type "info info"
-for an introduction on the use of the program
-.IR info .
+Man pages are concise, and allow you to quickly find a forgotten detail.
+They're designed to be a complete reference manual for a program.
+Usually you'd want a guide/tutorial when learning how to use software,
+rather than a long exhaustive reference manual.
+For this purpose a lot of GNU software comes with
+.I info
+manuals, which are designed to be more of an introduction for newcomers.
+Use the command "info info" for a first introduction on using the
+.I info
+program.
 .P
 Some topics can be documented in HOWTO files.
 To find these, look for HTML files in
-- 
2.44.0

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

[Alejandro Colomar]

[-- 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 --]

Re: [PATCH v2 2/6] intro.1: Document the meaning of the PS1 variable

[Alejandro Colomar]

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

On Sun, Mar 17, 2024 at 09:08:30PM +1300, Jeremy Baxter wrote:
> It still doesn't explain what a variable is but I think
> shell variables are out of scope of this manual.
> ---
>  man1/intro.1 | 5 ++++-
>  1 file changed, 4 insertions(+), 1 deletion(-)
> 
> diff --git a/man1/intro.1 b/man1/intro.1
> index 96eb3b7fc..090678750 100644
> --- a/man1/intro.1
> +++ b/man1/intro.1
> @@ -109,7 +109,10 @@ that it is ready for the next command.
>  The prompt can be customized in lots of ways, and one might include
>  information like the username, machine name, current directory, the time,
>  and so on.
> -An assignment PS1="What next, master? "
> +It can be changed by setting the value of the "PS1" (prompt string 1)
> +variable.

I think this is too long, and the existing text is informative enough.

> +An assignment
> +.B PS1="What next, master?\ "
>  would change the prompt as indicated.
>  .P
>  From this example we can see that there is the command
> -- 
> 2.44.0
> 
> 

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

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

Re: [PATCH v2 3/6] intro.1: Explain the meaning of a directory

[Alejandro Colomar]

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

On Sun, Mar 17, 2024 at 09:08:31PM +1300, Jeremy Baxter wrote:
> ---
>  man1/intro.1 | 3 +++
>  1 file changed, 3 insertions(+)
> 
> diff --git a/man1/intro.1 b/man1/intro.1
> index 090678750..f0a8d98e0 100644
> --- a/man1/intro.1
> +++ b/man1/intro.1
> @@ -180,6 +180,9 @@ The command
>  In this example, we use it to find Maja's telephone number.
>  .SS Pathnames and the current directory
>  Files live in a large tree, called the file hierarchy.
> +In this hierarchy, there are many
> +.IR directories ;
> +a directory is simply a file that can hold other files as opposed to text.

This might confuse more than it helps.  What does "hold" mean?  Does the
directory hold the file data?  As in a .tar archive?  No.

In any case, this subsection doesn't seem to treat how directories are
represented in the filesystem, but rather how they are presented to the
user in path names.

>  Each file has a
>  .I "pathname"
>  describing the location of the file from the root of the tree
> -- 
> 2.44.0
> 
> 

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

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

Re: [PATCH v2 4/6] intro.1: Demonstrate special cases of the cd command

[Alejandro Colomar]

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

On Sun, Mar 17, 2024 at 09:08:32PM +1300, Jeremy Baxter wrote:
> ---
>  man1/intro.1 | 19 +++++++++++++++++++
>  1 file changed, 19 insertions(+)
> 
> diff --git a/man1/intro.1 b/man1/intro.1
> index f0a8d98e0..8102640ba 100644
> --- a/man1/intro.1
> +++ b/man1/intro.1
> @@ -213,6 +213,25 @@ Try using the
>  and
>  .I pwd
>  commands in different ways.
> +.I cd .
> +changes the current directory to the path to the current directory;
> +this does nothing.

. and .. are not a special case of cd.  They are a special case of the
file system.

> +.I cd ..
> +changes the current directory to the parent directory of the current
> +directory.
> +For instance, if our current directory is
> +.I /home/aeb
> +and we change the current directory to
> +.IR .. ,
> +the current directory will now be
> +.IR /home .
> +.I cd /
> +changes the current directory to the root of the hierarchy.
> +.I cd \[ti]
> +changes the current directory to the user's home; if I am logged in as
> +.IR aeb ,
> +this command will change my current directory to
> +.IR /home/aeb .
>  .SS Directories
>  The command
>  .I mkdir
> -- 
> 2.44.0
> 
> 

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

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

Re: [PATCH v2 6/6] intro.1: Revise paragraph documenting GNU texinfo

[Alejandro Colomar]

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

Hi Jeremy,

On Sun, Mar 17, 2024 at 09:08:34PM +1300, Jeremy Baxter wrote:
> ---
>  man1/intro.1 | 18 ++++++++++--------
>  1 file changed, 10 insertions(+), 8 deletions(-)
> 
> diff --git a/man1/intro.1 b/man1/intro.1
> index 72f28bc2e..5aad9d4e7 100644
> --- a/man1/intro.1
> +++ b/man1/intro.1
> @@ -314,15 +314,17 @@ the previous page, and "q" to quit.
>  In documentation it is customary to refer to man pages
>  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.
> -For newcomers an introductory text with more examples
> -and explanations is useful.
>  .P
> -A lot of GNU/FSF software is provided with info files.
> -Type "info info"
> -for an introduction on the use of the program
> -.IR info .
> +Man pages are concise, and allow you to quickly find a forgotten detail.
> +They're designed to be a complete reference manual for a program.
> +Usually you'd want a guide/tutorial when learning how to use software,
> +rather than a long exhaustive reference manual.
> +For this purpose a lot of GNU software comes with
> +.I info
> +manuals, which are designed to be more of an introduction for newcomers.
> +Use the command "info info" for a first introduction on using the

Redundant: introductions are first, of course.  :)

Have a lovely day!
Alex

> +.I info
> +program.
>  .P
>  Some topics can be documented in HOWTO files.
>  To find these, look for HTML files in
> -- 
> 2.44.0
> 

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

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

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

[Jeremy Baxter]

On Mon Mar 18, 2024 at 3:47 AM NZDT, Alejandro Colomar wrote:
> >  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/>.

I wasn't aware of this rule sorry. Reading it aloud gave me the
impression that the comma is an unnecessary pause in the sentence.

> > +web browsers, file and image viewers, editors, and so on.
>
> editors here meant "file and image editors", so it was correct as it
> was.

I read that wrong, my bad.

> >  .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.

"as a first approximation" is not a phrase I hear often and may be
unclear to some people.

Our user commands under Linux do not work "precisely the same" as they
did in UNIX's time due to extensions and the like. I should've used
"more or less" here rather than "approximately", I think it gets the
point across better.

> >  .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.  :)

Alright, I'll include that in v3.

> > +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.

The main thing improved here is the text "That is faster and more
powerful, but requires finding out what the commands are." which
sounds weird referring to the CLI as "that". The second part of the
sentence is also a bit unclear and illiterate. I'll strip out all the
unrelated bits in the next patch.

> > +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

Sounds good, I think that's a much better approach.

> >  .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.

Yeah you're right, I'll leave as-is.

> >  .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.

I had a hard time with this one. Do you think it's okay to remove
this entirely? It doesn't add much and is a bit awkward to word.

> > +There are many different shells.
>
> Redundant: the next sentence already implies this.

Ah yeah that's right, good catch!

> >  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.

The original wording sounds unprofessional and a little "ad hoc". I
think this type of wording should be avoided because they can make the
rest of the phrase sound unclear, or make the speaker sound
inexperienced.

> >  .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".

Done.

> >  .P
> > -The
> > +The symbol
>
> Unnecessary.  I read it meantally as "The dollar here was ...", which is
> just fine.

Removed.

> >  .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.

Didn't notice that, fixed.

> > +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.

Hmm okay then. The previous wording sounds a bit "off" to me,
but there are no real issues with it and it can be understood
easier. :D

> >  .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?

Fixed.

> > +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.

Fixed.

> > +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.

Fixed.

> >  .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.

I think your idea sounds better, done.

> > +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
> ?

I think it sounds better to use the "x does this" form rather than the
"x will do this" form, similar to what they have in the utilities' own
man pages. What do you think? Should I change cat's description to
adhere to the rest or just keep all of them as they were?

> >  .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.

I removed "only" because I was going to change it to refer to "a file"
rather than "it", and "mv, on the other hand, only renames a file"
sounds a bit awkward and lengthy to me.

Here, I actually don't think that the sentence loses its sense, it
sounds fine and is just contrasting from what cp does.

> >  .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.

Yeah, you're right... I actually don't know why I had to change this.

> > +between the two.
>
> And this is redundant.  The simpler the better, I think.

Removed.

> >  .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.

Removed.

> > +No rubbish bin or anything.
>
> Don't you like wastepaper baskets?  :)

Well they're mostly used interchangeably, "wastepaper basket" is fine.

> Have a lovely day!
> Alex

Likewise, thanks!

> >  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
> > 
> > 



 ~Jeremy

Re: [PATCH v2 2/6] intro.1: Document the meaning of the PS1 variable

[Jeremy Baxter]

On Mon Mar 18, 2024 at 4:00 AM NZDT, Alejandro Colomar wrote:
> On Sun, Mar 17, 2024 at 09:08:30PM +1300, Jeremy Baxter wrote:
> > It still doesn't explain what a variable is but I think
> > shell variables are out of scope of this manual.
> > ---
> >  man1/intro.1 | 5 ++++-
> >  1 file changed, 4 insertions(+), 1 deletion(-)
> > 
> > diff --git a/man1/intro.1 b/man1/intro.1
> > index 96eb3b7fc..090678750 100644
> > --- a/man1/intro.1
> > +++ b/man1/intro.1
> > @@ -109,7 +109,10 @@ that it is ready for the next command.
> >  The prompt can be customized in lots of ways, and one might include
> >  information like the username, machine name, current directory, the time,
> >  and so on.
> > -An assignment PS1="What next, master? "
> > +It can be changed by setting the value of the "PS1" (prompt string 1)
> > +variable.
>
> I think this is too long, and the existing text is informative enough.

I think you're right, I'll drop this.

 ~Jeremy

> > +An assignment
> > +.B PS1="What next, master?\ "
> >  would change the prompt as indicated.
> >  .P
> >  From this example we can see that there is the command
> > -- 
> > 2.44.0
> > 
> > 

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

[G. Branden Robinson]

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

At 2024-03-19T08:50:21+1300, Jeremy Baxter wrote:
> > cat will show
> > but
> > cp copies
> > ?
> 
> I think it sounds better to use the "x does this" form rather than the
> "x will do this" form, similar to what they have in the utilities' own
> man pages. What do you think? Should I change cat's description to
> adhere to the rest or just keep all of them as they were?

Two rules I've been applying to my man page revisions for a while are:

* Favor active voice over passive.
* Favor present tense over future.

This is "favor", not "always use", but, other things being equal...

Regards,
Branden

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

Re: [PATCH v2 3/6] intro.1: Explain the meaning of a directory

[Jeremy Baxter]

On Mon Mar 18, 2024 at 4:05 AM NZDT, Alejandro Colomar wrote:
> On Sun, Mar 17, 2024 at 09:08:31PM +1300, Jeremy Baxter wrote:
> > ---
> >  man1/intro.1 | 3 +++
> >  1 file changed, 3 insertions(+)
> > 
> > diff --git a/man1/intro.1 b/man1/intro.1
> > index 090678750..f0a8d98e0 100644
> > --- a/man1/intro.1
> > +++ b/man1/intro.1
> > @@ -180,6 +180,9 @@ The command
> >  In this example, we use it to find Maja's telephone number.
> >  .SS Pathnames and the current directory
> >  Files live in a large tree, called the file hierarchy.
> > +In this hierarchy, there are many
> > +.IR directories ;
> > +a directory is simply a file that can hold other files as opposed to text.
>
> This might confuse more than it helps.  What does "hold" mean?  Does the
> directory hold the file data?  As in a .tar archive?  No.
>
> In any case, this subsection doesn't seem to treat how directories are
> represented in the filesystem, but rather how they are presented to the
> user in path names.

What do you think about this?

  In this hierarchy, there are many
  .IR directories ;
  a directory is simple a file that contains other files,
  rather than text.
  For example, if we have a file called
  .I tel
  in the directory
  .IR /home/aeb ,
  we can refer to it by the pathname
  .IR /home/aeb/tel .

I think this section is still important because previously there was
no explanation for this, and most people are accustomed to using the
word "folder".

 ~Jeremy

> >  Each file has a
> >  .I "pathname"
> >  describing the location of the file from the root of the tree
> > -- 
> > 2.44.0
> > 
> > 

Re: [PATCH v2 3/6] intro.1: Explain the meaning of a directory

[Alejandro Colomar]

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

Hi Jeremy,

On Tue, Mar 19, 2024 at 08:57:07AM +1300, Jeremy Baxter wrote:
> On Mon Mar 18, 2024 at 4:05 AM NZDT, Alejandro Colomar wrote:
> > On Sun, Mar 17, 2024 at 09:08:31PM +1300, Jeremy Baxter wrote:
> > > ---
> > >  man1/intro.1 | 3 +++
> > >  1 file changed, 3 insertions(+)
> > > 
> > > diff --git a/man1/intro.1 b/man1/intro.1
> > > index 090678750..f0a8d98e0 100644
> > > --- a/man1/intro.1
> > > +++ b/man1/intro.1
> > > @@ -180,6 +180,9 @@ The command
> > >  In this example, we use it to find Maja's telephone number.
> > >  .SS Pathnames and the current directory
> > >  Files live in a large tree, called the file hierarchy.
> > > +In this hierarchy, there are many
> > > +.IR directories ;
> > > +a directory is simply a file that can hold other files as opposed to text.
> >
> > This might confuse more than it helps.  What does "hold" mean?  Does the
> > directory hold the file data?  As in a .tar archive?  No.
> >
> > In any case, this subsection doesn't seem to treat how directories are
> > represented in the filesystem, but rather how they are presented to the
> > user in path names.
> 
> What do you think about this?
> 
>   In this hierarchy, there are many
>   .IR directories ;
>   a directory is simple a file that contains other files,
>   rather than text.
>   For example, if we have a file called
>   .I tel
>   in the directory
>   .IR /home/aeb ,
>   we can refer to it by the pathname
>   .IR /home/aeb/tel .
> 
> I think this section is still important because previously there was
> no explanation for this, and most people are accustomed to using the
> word "folder".

Hmm, it's good that you mention this.  When explaining directories to
friends used to Windows (and GUI) terms, I noticed that it's unfamiliar
to them.

I actually thought about it, and the term "directory" tells you what it
is quite precisely:

Like a directory of phones, it's just a piece of paper where you note
down the phones of people.  Directories, similarly, contain lists of
files.  They don't "hold" nor "contain" the files.

Cheers,
Alex

> 
>  ~Jeremy
> 
> > >  Each file has a
> > >  .I "pathname"
> > >  describing the location of the file from the root of the tree
> > > -- 
> > > 2.44.0
> > > 
> > > 
> 

-- 
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.

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

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

[Alejandro Colomar]

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

Hi Jeremy, Branden,

On Mon, Mar 18, 2024 at 02:56:57PM -0500, G. Branden Robinson wrote:
> At 2024-03-19T08:50:21+1300, Jeremy Baxter wrote:
> > > cat will show
> > > but
> > > cp copies
> > > ?
> > 
> > I think it sounds better to use the "x does this" form rather than the
> > "x will do this" form, similar to what they have in the utilities' own
> > man pages. What do you think? Should I change cat's description to
> > adhere to the rest or just keep all of them as they were?
> 
> Two rules I've been applying to my man page revisions for a while are:
> 
> * Favor active voice over passive.
> * Favor present tense over future.
> 
> This is "favor", not "always use", but, other things being equal...

For intro(1), we could make an exception.  A less formal voice might
seem more friendly to newcomers.  Don't you think?

BTW Jeremy, you could send less changes.  I'm not very happy about such
huge changes suddenly.  How about fixing what you feel is most obvious
that should be fixed, say 20 lines or so, and in a month or so we can
discuss another patch set for this page?

Have a lovely day!
Alex

> 
> Regards,
> Branden



-- 
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.

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

Re: [PATCH v2 3/6] intro.1: Explain the meaning of a directory

[Jeremy Baxter]

Hi Alex,

On Tue Mar 19, 2024 at 10:57 AM NZDT, Alejandro Colomar wrote:
> Hi Jeremy,
>
> On Tue, Mar 19, 2024 at 08:57:07AM +1300, Jeremy Baxter wrote:
> > On Mon Mar 18, 2024 at 4:05 AM NZDT, Alejandro Colomar wrote:
> > > On Sun, Mar 17, 2024 at 09:08:31PM +1300, Jeremy Baxter wrote:
> > > > ---
> > > >  man1/intro.1 | 3 +++
> > > >  1 file changed, 3 insertions(+)
> > > > 
> > > > diff --git a/man1/intro.1 b/man1/intro.1
> > > > index 090678750..f0a8d98e0 100644
> > > > --- a/man1/intro.1
> > > > +++ b/man1/intro.1
> > > > @@ -180,6 +180,9 @@ The command
> > > >  In this example, we use it to find Maja's telephone number.
> > > >  .SS Pathnames and the current directory
> > > >  Files live in a large tree, called the file hierarchy.
> > > > +In this hierarchy, there are many
> > > > +.IR directories ;
> > > > +a directory is simply a file that can hold other files as opposed to text.
> > >
> > > This might confuse more than it helps.  What does "hold" mean?  Does the
> > > directory hold the file data?  As in a .tar archive?  No.
> > >
> > > In any case, this subsection doesn't seem to treat how directories are
> > > represented in the filesystem, but rather how they are presented to the
> > > user in path names.
> > 
> > What do you think about this?
> > 
> >   In this hierarchy, there are many
> >   .IR directories ;
> >   a directory is simple a file that contains other files,
> >   rather than text.
> >   For example, if we have a file called
> >   .I tel
> >   in the directory
> >   .IR /home/aeb ,
> >   we can refer to it by the pathname
> >   .IR /home/aeb/tel .
> > 
> > I think this section is still important because previously there was
> > no explanation for this, and most people are accustomed to using the
> > word "folder".
>
> Hmm, it's good that you mention this.  When explaining directories to
> friends used to Windows (and GUI) terms, I noticed that it's unfamiliar
> to them.
>
> I actually thought about it, and the term "directory" tells you what it
> is quite precisely:
>
> Like a directory of phones, it's just a piece of paper where you note
> down the phones of people.  Directories, similarly, contain lists of
> files.  They don't "hold" nor "contain" the files.

I've never thought of it that way before, good point.
I'll write something along those lines for the next patch, thanks.

 ~Jeremy

>
> Cheers,
> Alex
>
> > 
> >  ~Jeremy
> > 
> > > >  Each file has a
> > > >  .I "pathname"
> > > >  describing the location of the file from the root of the tree
> > > > -- 
> > > > 2.44.0
> > > > 
> > > > 
> > 

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

[Jeremy Baxter]

On Tue Mar 19, 2024 at 11:05 AM NZDT, Alejandro Colomar wrote:
> Hi Jeremy, Branden,
>
> On Mon, Mar 18, 2024 at 02:56:57PM -0500, G. Branden Robinson wrote:
> > At 2024-03-19T08:50:21+1300, Jeremy Baxter wrote:
> > > > cat will show
> > > > but
> > > > cp copies
> > > > ?
> > > 
> > > I think it sounds better to use the "x does this" form rather than the
> > > "x will do this" form, similar to what they have in the utilities' own
> > > man pages. What do you think? Should I change cat's description to
> > > adhere to the rest or just keep all of them as they were?
> > 
> > Two rules I've been applying to my man page revisions for a while are:
> > 
> > * Favor active voice over passive.
> > * Favor present tense over future.
> > 
> > This is "favor", not "always use", but, other things being equal...
>
> For intro(1), we could make an exception.  A less formal voice might
> seem more friendly to newcomers.  Don't you think?
>
> BTW Jeremy, you could send less changes.  I'm not very happy about such
> huge changes suddenly.  How about fixing what you feel is most obvious
> that should be fixed, say 20 lines or so, and in a month or so we can
> discuss another patch set for this page?

No worries, splitting the patch over time sounds good.
Sorry for the inconvenience.

 ~Jeremy

>
> Have a lovely day!
> Alex
>
> > 
> > Regards,
> > Branden