Hi Jeremy,
On Fri, Mar 15, 2024 at 10:58:22AM +1300, Jeremy Baxter wrote:
> Revise intro(1).
Thanks for the patch!
> This manual is very old now and needs some fixing
> up. Mainly this involves clarifying language but also adding more
> information, such as in the introduction of the shell prompt and
> special cases surrounding usage of the cd commmand.
This patch is too big, and changes too much, for a single patch, I
think. Please split the patch into smaller patches that do one thing,
and document those more precisely in the commit messages, instead of
something generic, if possible. See <./CONTRIBUTING.d/patches>:
- Send logically separate patches. For unrelated pages, or for
logically-separate issues in the same page, send separate
emails.
>
> Signed-off-by: Jeremy Baxter <jtbx@xxxxxxxxxxx>
> ---
> man1/intro.1 | 242 +++++++++++++++++++++++++++++----------------------
> 1 file changed, 137 insertions(+), 105 deletions(-)
>
> diff --git a/man1/intro.1 b/man1/intro.1
> index decaab161..19b423210 100644
> --- a/man1/intro.1
> +++ b/man1/intro.1
> @@ -7,40 +7,40 @@
> 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.
Please use semantic newlines (see man-pages(7)):
$ MANWIDTH=72 man man-pages | sed -n '/Use semantic newlines/,/^$/p'
Use semantic newlines
In the source of a manual page, new sentences should be started
on new lines, long sentences should be split into lines at clause
breaks (commas, semicolons, colons, and so on), and long clauses
should be split at phrase boundaries. This convention, sometimes
known as "semantic newlines", makes it easier to see the effect
of patches, which often operate at the level of individual sen‐
tences, clauses, or phrases.
Have a lovely night!
Alex
> .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 you can
> +point and click and drag using a mouse, and hopefully get work done
> +without first reading lots of documentation.
> +The traditional UNIX environment is a command line interface (CLI),
> +where you type commands to tell the computer what to do.
> +This is faster and more powerful than a graphical interface, but requires
> +finding out what commands you have and how to use them.
> +Below is a bare minimum guide 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's not built-in, but 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 +53,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 +99,100 @@ $
> .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.
> -An assignment PS1="What next, master? "
> +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.
> +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
> -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 the file was last
> +modified, as well as the permissions people have for reading and/or changing
> +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
> +The name is from "concatenate and print": all files given as
> parameters are concatenated and sent 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.
> .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, and 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.
> +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 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 example, 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
> +Always using full pathnames would be 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 +205,30 @@ 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.
> +.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
> @@ -208,82 +236,86 @@ makes a new directory.
> .P
> The command
> .I rmdir
> -removes a directory if it is empty, and complains otherwise.
> +removes a directory if it is empty, and outputs an error otherwise.
> .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
> +(with a rather strange syntax) will find files with a given name
> +or other specified properties.
> +For example, "find . \-name tel" would find the file
> +.I tel ,
> +starting the search in the current directory (which is called
> .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
> +The command "find / \-name tel" would do the same, but rather it would
> +start at the root of the directory tree.
> +Large searches on a multi-gigabyte disk can be time-consuming,
> +and 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 runs in the
> .IR foreground ,
> -the others in the
> +while the others run in the
> .IR background .
> The command
> .I ps
> -will show you which processes are active and what numbers these
> +will show you which processes are active and what IDs these
> processes have.
> 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").
> +.I "man pages"
> +like this one, so that the command "man kill" will bring up a manual
> +for the command "kill" (and "man man" will bring up a manual for the
> +command "man").
> 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 get the next page, the "b" key to get
> +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
> .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 some forgotten
> +detail.
> +An introduction with more examples and explanations is useful for newcomers.
> +For this purpose, a lot of GNU/FSF software is provided with info files.
> +Use the command "info info" for an introduction on using the
> +.I info
> +program.
> .P
> -Special topics are often treated in HOWTOs.
> +Special topics are often documented in HOWTOs.
> Look in
> .I /usr/share/doc/howto/en
> -and use a browser if you find HTML files there.
> +and use a web browser if you find HTML files there.
> .\"
> .\" Actual examples? Separate section for each of cat, cp, ...?
> .\" gzip, bzip2, tar, rpm
> --
> 2.44.0
>
--
<https://www.alejandro-colomar.es/>
Attachment:
signature.asc
Description: PGP signature
