Hello Stéphane,
On 02/27/2015 01:26 AM, saulery@xxxxxxx wrote:
> From: Stéphane Aulery <saulery@xxxxxxx>
>
> - Cite man pages of all commands
> - Explain how to logout and shutdown in a new subsection
> - Appoint more options (shell, browser, cd, stdout)
> - New subsection: Editing files
> - Prompt is not % but $
> - Better highlighting
Again, this patch is a bit too busy, and I would prefer
separate, ordered pieces. Could you resubmit just the
formatting fixes and other mechanical changes first,
and then we can look at the content additions.
See some specific comments below.
> Signed-off-by: Stéphane Aulery <saulery@xxxxxxx>
> ---
> man1/intro.1 | 221 ++++++++++++++++++++++++++++++++++++++++++-----------------
> 1 file changed, 158 insertions(+), 63 deletions(-)
>
> diff --git a/man1/intro.1 b/man1/intro.1
> index 20d36d7..f7633b6 100644
> --- a/man1/intro.1
> +++ b/man1/intro.1
> @@ -60,12 +60,10 @@ That is faster and more powerful,
> but requires finding out what the commands are.
> Below a bare minimum, to get started.
> .SS Login
> -In order to start working, you probably first have to login,
> -that is, give your username and password.
> -See also
> -.BR login (1).
> +In order to start working, you probably first have to open a session by giving
> +your username and password.
> The program
> -.I login
> +.BR login (1)
> now starts a
> .I shell
> (command interpreter) for you.
> @@ -73,6 +71,15 @@ 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.
> See also
> .BR xterm (1).
> +.SS Logout and poweroff
> +When you work is finished, you can press Control-D to close the current
> +session. This does not turn off the machine. Only superusers have access to
> +this command. If you are the single user you can also not log off and becoming
> +a superuser by typing the command
> +.BR su (1).
> +Also you must type yours password. Finally enter the command "shutdown -P +1",
> +which will turn off the computer after one minute. See
> +.BR shutdown (8).
> .SS The shell
> One types commands to the
> .IR shell ,
> @@ -85,19 +92,21 @@ The standard one is called
> See also
> .BR ash (1),
> .BR bash (1),
> +.BR chsh (1),
> .BR csh (1),
> -.BR zsh (1),
> -.BR chsh (1).
> +.BR dash (1),
> +.BR ksh (1),
> +.BR zsh (1).
> .LP
> -A session might go like
> +A session might go like:
>
> .RS
> .nf
> .BI "knuth login: " aeb
> .BI "Password: " ********
> -.BI "% " date
> +.BI "$ " date
> Tue Aug 6 23:50:44 CEST 2002
> -.BI "% " cal
> +.BI "$ " cal
> August 2002
> Su Mo Tu We Th Fr Sa
> 1 2 3
> @@ -106,37 +115,36 @@ Su Mo Tu We Th Fr Sa
> 18 19 20 21 22 23 24
> 25 26 27 28 29 30 31
>
> -.BI "% " ls
> +.BI "$ " ls
> bin tel
> -.BI "% " "ls \-l"
> +.BI "$ " "ls \-l"
> total 2
> drwxrwxr\-x 2 aeb 1024 Aug 6 23:51 bin
> \-rw\-rw\-r\-\- 1 aeb 37 Aug 6 23:52 tel
> -.BI "% " "cat tel"
> +.BI "$ " "cat tel"
> maja 0501\-1136285
> peter 0136\-7399214
> -.BI "% " "cp tel tel2"
> -.BI "% " "ls \-l"
> +.BI "$ " "cp tel tel2"
> +.BI "$ " "ls \-l"
> total 3
> drwxr\-xr\-x 2 aeb 1024 Aug 6 23:51 bin
> \-rw\-r\-\-r\-\- 1 aeb 37 Aug 6 23:52 tel
> \-rw\-r\-\-r\-\- 1 aeb 37 Aug 6 23:53 tel2
> -.BI "% " "mv tel tel1"
> -.BI "% " "ls \-l"
> +.BI "$ " "mv tel tel1"
> +.BI "$ " "ls \-l"
> total 3
> drwxr\-xr\-x 2 aeb 1024 Aug 6 23:51 bin
> \-rw\-r\-\-r\-\- 1 aeb 37 Aug 6 23:52 tel1
> \-rw\-r\-\-r\-\- 1 aeb 37 Aug 6 23:53 tel2
> -.BI "% " "diff tel1 tel2"
> -.BI "% " "rm tel1"
> -.BI "% " "grep maja tel2"
> +.BI "$ " "diff tel1 tel2"
> +.BI "$ " "rm tel1"
> +.BI "$ " "grep maja tel2"
Actualyl, as long as you are doing these fixes. I prefer user
input to be bold (which is the norm in other pages). Thus:
.RB "$ " "grep maja tel2"
and so on.
> maja 0501\-1136285
> -.B "% "
> +.B "$ "
> .fi
> .RE
> -and here typing Control-D ended the session.
> The
> -.B "% "
> +.B "$ "
> here was the command prompt\(emit is the shell's way of indicating
> that it is ready for the next command.
> The prompt can be customized
> @@ -146,13 +154,13 @@ An assignment PS1="What next, master? "
> would change the prompt as indicated.
> .LP
> We see that there are commands
> -.I date
> +.BR date (1)
> (that gives date and time), and
> -.I cal
> +.BR cal (1)
> (that gives a calendar).
> .LP
> The command
> -.I ls
> +.BR ls (1)
> lists the contents of the current directory\(emit tells you what
> files you have.
> With a
> @@ -163,75 +171,90 @@ 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
> -.I chown
> +.BR chown (1)
> and
> -.IR chmod .
> +.BR chmod (1).
> .LP
> The command
> -.I cat
> +.BR cat (1)
> 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", here
> -the terminal screen.)
> +parameters are concatenated and sent to "standard output" (see
> +.BR stdout (3)
> +), here the terminal screen.)
> .LP
> The command
> -.I cp
> +.BR cp (1)
> (from "copy") will copy a file.
> -On the other hand, the command
> -.I mv
> -(from "move") only renames it.
> .LP
> The command
> -.I diff
> +.BR mv (1)
> +(from "move"), on the other hand, only renames it.
> +.LP
> +The command
> +.BR diff (1)
> lists the differences between two files.
> Here there was no output because there were no differences.
> .LP
> The command
> -.I rm
> +.BR rm (1)
> (from "remove") deletes the file, and be careful! it is gone.
> No wastepaper basket or anything.
> Deleted means lost.
> .LP
> The command
> -.I grep
> +.BR grep (1)
> (from "g/re/p") finds occurrences of a string in one or more files.
> Here it finds Maja's telephone number.
> .SS Pathnames and the current directory
> Files live in a large tree, the file hierarchy.
> Each has a
> -.I "pathname"
> -describing the path from the root of the tree (which is called /)
> +.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 /home/aeb/tel.
> +For example, such 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 "/home/aeb/tel" can be abbreviated
> -to "tel" when the current directory is "/home/aeb".
> +That is why
> +.I /home/aeb/tel
> +can be abbreviated
> +to
> +.I tel
> +when the current directory is
> +.IR /home/aeb .
> .LP
> The command
> -.I pwd
> +.BR pwd (1)
> prints the current directory.
> .LP
> The command
> -.I cd
> +.BR cd (1)
> changes the current directory.
> -Try "cd /" and "pwd" and "cd" and "pwd".
> +.LP
> +Try alternatively
> +.IR cd " and " pwd
> +commands and explore cd usage: "cd", "cd .", "cd ..", "cd /", and "cd ~".
> .SS Directories
> The command
> -.I mkdir
> +.BR mkdir (1)
> makes a new directory.
> .LP
> The command
> -.I rmdir
> +.BR rmdir (1)
> removes a directory if it is empty, and complains otherwise.
> .LP
> The command
> -.I find
> +.BR find (1)
> (with a rather baroque syntax) will find files with given name
> or other properties.
> For example, "find . \-name tel" would find
> -the file "tel" starting in the present directory (which is called ".").
> +the file
> +.I tel
> +starting in the present 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,
> @@ -239,14 +262,14 @@ and it may be better to use
> .BR locate (1).
> .SS Disks and filesystems
> The command
> -.I mount
> +.BR mount (8)
> will attach the filesystem found on some disk (or floppy, or CDROM or so)
> to the big filesystem hierarchy.
> And
> -.I umount
> +.BR umount (8)
> detaches it again.
> The command
> -.I df
> +.BR df (1)
> will tell you how much of your disk is still free.
> .SS Processes
> On a UNIX system many user and system processes run simultaneously.
> @@ -255,29 +278,41 @@ The one you are talking to runs in the
> the others in the
> .IR background .
> The command
> -.I ps
> +.BR ps (1)
> will show you which processes are active and what numbers these
> processes have.
> The command
> -.I kill
> +.BR kill (1)
> 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.
> Foreground processes can often be killed by typing Control-C.
> +.SS Editing files
> +The traditional file editor of the Unix world is
> +.BR vi (1),
> +an its improved version
> +.BR vim (1).
> +This is why it is good to know at least its basic commands in an emergency.
> +See
> +.BR vimtutor (1)
> +to learn the survival commands.
> .SS Getting information
> There are thousands of commands, each with many options.
> Traditionally commands are documented on
> -.IR "man pages" ,
> +.BR man-pages (7),
Drop that last change.
> (like this one), so that the command "man kill" will document
> -the use of the command "kill" (and "man man" document the command "man").
> +the use of the command
> +.I kill
> +(and "man man" document the command
> +.IR man ).
> The program
> -.I man
> +.BR man (1)
> sends the text through some
> -.IR pager ,
> +.BR pager (1),
> usually
> -.IR less .
> +.BR less (1).
> Hit the space bar to get the next page, hit q to quit.
> .LP
> In documentation it is customary to refer to man pages
> @@ -290,14 +325,74 @@ and explanations is useful.
> .LP
> A lot of GNU/FSF software is provided with info files.
> Type "info info"
> -for an introduction on the use of the program "info".
> +for an introduction on the use of the program
> +.BR info (1).
> .LP
> 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.
> +and use a browser if you find HTML files there. The most common text based web browsers are:
> +.BR elinks (1),
> +.BR links (1),
> +.BR lynx (1)
> +.BR w3m (1).
I am not so convinced we need to list the text-based browsers...
> .\"
> .\" Actual examples? Separate section for each of cat, cp, ...?
> .\" gzip, bzip2, tar, rpm
> .SH SEE ALSO
I don't think we need these SEE ALSO additions, really,
except maybe the following:
> +.BR bash (1),
> +.BR man (1),
> +.BR man-pages (7),
> +.BR standards (7),
Cheers,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
