[patch] intro.8: tfix

[patch] intro.8: tfix

[saulery-GANU6spQydw]

From: Stéphane Aulery <saulery-GANU6spQydw@public.gmane.org>

Signed-off-by: Stéphane Aulery <saulery-GANU6spQydw@public.gmane.org>
---
 man8/intro.8 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man8/intro.8 b/man8/intro.8
index 20023c4..dab9af4 100644
--- a/man8/intro.8
+++ b/man8/intro.8
@@ -35,7 +35,7 @@ which either can be or are used only by the superuser,
 like system-administration commands, daemons,
 and hardware-related commands.
 
-As with the commands in described Section 1, the commands described
+As with the commands described in Section 1, the commands described
 in this section terminate with an exit status that indicates
 whether the command succeeded or failed.
 See
-- 
2.1.4

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[patch] intro.2: tfix

[saulery-GANU6spQydw]

From: Stéphane Aulery <saulery-GANU6spQydw@public.gmane.org>

Signed-off-by: Stéphane Aulery <saulery-GANU6spQydw@public.gmane.org>
---
 man2/intro.2 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/man2/intro.2 b/man2/intro.2
index b65bdfc..d0d18dc 100644
--- a/man2/intro.2
+++ b/man2/intro.2
@@ -46,7 +46,7 @@ copying arguments and the unique system call number to the
 registers where the kernel expects them;
 .IP *
 trapping to kernel mode,
-at which point the kernel does the real work of the system call; and
+at which point the kernel does the real work of the system call;
 .IP *
 setting
 .I errno
@@ -55,7 +55,7 @@ CPU to user mode.
 .LP
 However, in a few cases, a wrapper function may do rather more than this,
 for example, performing some preprocessing
-of the arguments of arguments before trapping to kernel mode,
+of the arguments before trapping to kernel mode,
 or postprocessing of values returned by the system call.
 Where this is the case, the manual pages in Section 2 generally
 try to note the details of both the (usually GNU) C library API
-- 
2.1.4

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[patch] man-pages.7: improve the definition of sections in accordance with intro pages

[saulery-GANU6spQydw]

From: Stéphane Aulery <saulery-GANU6spQydw@public.gmane.org>

Signed-off-by: Stéphane Aulery <saulery-GANU6spQydw@public.gmane.org>
---
 man7/man-pages.7 | 24 +++++++++++++-----------
 1 file changed, 13 insertions(+), 11 deletions(-)

diff --git a/man7/man-pages.7 b/man7/man-pages.7
index ceead84..e17434e 100644
--- a/man7/man-pages.7
+++ b/man7/man-pages.7
@@ -48,32 +48,34 @@ for authors writing man pages for other projects.
 .PP
 The manual Sections are traditionally defined as follows:
 .TP 10
-.B 1 Commands (Programs)
+.B 1 User commands (Programs)
 Those commands that can be executed by the user from within
 a shell.
 .TP
 .B 2 System calls
-Those functions which must be performed by the kernel.
+Those functions which wrap operations performed by the kernel.
 .TP
 .B 3 Library calls
-Most of the
+All library functions excluding the system call wrappers
+(Most of the
 .I libc
-functions.
+functions).
 .TP
 .B 4 Special files (devices)
 Files found in
-.IR /dev .
+.I /dev
+which allow to access to devices through the kernel.
 .TP
-.B 5 File formats and conventions
-The format for
-.I /etc/passwd
-and other human-readable files.
+.B 5 File formats and configuration
+Describes various human-readable file formats and configuration files.
 .TP
 .B 6 Games
+Games and funny little programs available on the system.
 .TP
 .B 7 Overview, conventions, and miscellaneous
-Overviews of various topics, conventions and protocols,
-character set standards, and miscellaneous other things.
+Overviews or descriptions of various topics, conventions and protocols,
+character set standards, the standard filesystem layout, and miscellaneous
+other things.
 .TP
 .B 8 System management commands
 Commands like
-- 
2.1.4

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[patch] intro.1: Improve help for newcommers

[saulery-GANU6spQydw]

From: Stéphane Aulery <saulery-GANU6spQydw@public.gmane.org>

- 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

Signed-off-by: Stéphane Aulery <saulery-GANU6spQydw@public.gmane.org>
---
 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"
 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),
 (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).
 .\"
 .\" Actual examples? Separate section for each of cat, cp, ...?
 .\" gzip, bzip2, tar, rpm
 .SH SEE ALSO
-.BR standards (7)
+.BR ash (1),
+.BR bash (1),
+.BR cal (1),
+.BR cat (1),
+.BR cd (1),
+.BR chmod (1),
+.BR chown (1),
+.BR chsh (1),
+.BR cp (1),
+.BR csh (1),
+.BR dash (1),
+.BR date (1),
+.BR df (1),
+.BR diff (1),
+.BR elinks (1),
+.BR find (1),
+.BR grep (1),
+.BR info (1),
+.BR kill (1),
+.BR ksh (1),
+.BR less (1),
+.BR locate (1),
+.BR ls (1),
+.BR lynx (1),
+.BR links (1),
+.BR lynx (1),
+.BR man (1),
+.BR mkdir (1),
+.BR mv (1),
+.BR pager (1),
+.BR ps (1),
+.BR pwd (1),
+.BR rm (1),
+.BR rmdir (1),
+.BR su (1),
+.BR vi (1),
+.BR vim (1),
+.BR vimtutor (1),
+.BR w3m (1),
+.BR zsh (1),
+.BR login (1),
+.BR xterm (1),
+.BR intro (2),
+.BR wait (2),
+.BR intro (3),
+.BR stdout (3),
+.BR intro (4),
+.BR intro (5),
+.BR intro (6),
+.BR intro (7),
+.BR man-pages (7),
+.BR standards (7),
+.BR intro (8),
+.BR mount (8),
+.BR shutdown (8),
+.BR umount (8).
-- 
2.1.4

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [patch] intro.2: tfix

[Michael Kerrisk (man-pages)]

On 02/27/2015 01:26 AM, saulery-GANU6spQydw@public.gmane.org wrote:
> From: Stéphane Aulery <saulery-GANU6spQydw@public.gmane.org>

Thanks, Stéphane. Applied.

Cheers,

Michael


> Signed-off-by: Stéphane Aulery <saulery-GANU6spQydw@public.gmane.org>
> ---
>  man2/intro.2 | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/man2/intro.2 b/man2/intro.2
> index b65bdfc..d0d18dc 100644
> --- a/man2/intro.2
> +++ b/man2/intro.2
> @@ -46,7 +46,7 @@ copying arguments and the unique system call number to the
>  registers where the kernel expects them;
>  .IP *
>  trapping to kernel mode,
> -at which point the kernel does the real work of the system call; and
> +at which point the kernel does the real work of the system call;
>  .IP *
>  setting
>  .I errno
> @@ -55,7 +55,7 @@ CPU to user mode.
>  .LP
>  However, in a few cases, a wrapper function may do rather more than this,
>  for example, performing some preprocessing
> -of the arguments of arguments before trapping to kernel mode,
> +of the arguments before trapping to kernel mode,
>  or postprocessing of values returned by the system call.
>  Where this is the case, the manual pages in Section 2 generally
>  try to note the details of both the (usually GNU) C library API
> 


-- 
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-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [patch] intro.8: tfix

[Michael Kerrisk (man-pages)]

On 02/27/2015 01:26 AM, saulery-GANU6spQydw@public.gmane.org wrote:
> From: Stéphane Aulery <saulery-GANU6spQydw@public.gmane.org>

Thanks, Stéphane. Applied.

Cheers,

Michael

> Signed-off-by: Stéphane Aulery <saulery-GANU6spQydw@public.gmane.org>
> ---
>  man8/intro.8 | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/man8/intro.8 b/man8/intro.8
> index 20023c4..dab9af4 100644
> --- a/man8/intro.8
> +++ b/man8/intro.8
> @@ -35,7 +35,7 @@ which either can be or are used only by the superuser,
>  like system-administration commands, daemons,
>  and hardware-related commands.
>  
> -As with the commands in described Section 1, the commands described
> +As with the commands described in Section 1, the commands described
>  in this section terminate with an exit status that indicates
>  whether the command succeeded or failed.
>  See
> 


-- 
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-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [patch] man-pages.7: improve the definition of sections in accordance with intro pages

[Michael Kerrisk (man-pages)]

On 02/27/2015 01:26 AM, saulery-GANU6spQydw@public.gmane.org wrote:
> From: Stéphane Aulery <saulery-GANU6spQydw@public.gmane.org>

Thanks, Stéphane. Applied.

Cheers,

Michael


> Signed-off-by: Stéphane Aulery <saulery-GANU6spQydw@public.gmane.org>
> ---
>  man7/man-pages.7 | 24 +++++++++++++-----------
>  1 file changed, 13 insertions(+), 11 deletions(-)
> 
> diff --git a/man7/man-pages.7 b/man7/man-pages.7
> index ceead84..e17434e 100644
> --- a/man7/man-pages.7
> +++ b/man7/man-pages.7
> @@ -48,32 +48,34 @@ for authors writing man pages for other projects.
>  .PP
>  The manual Sections are traditionally defined as follows:
>  .TP 10
> -.B 1 Commands (Programs)
> +.B 1 User commands (Programs)
>  Those commands that can be executed by the user from within
>  a shell.
>  .TP
>  .B 2 System calls
> -Those functions which must be performed by the kernel.
> +Those functions which wrap operations performed by the kernel.
>  .TP
>  .B 3 Library calls
> -Most of the
> +All library functions excluding the system call wrappers
> +(Most of the
>  .I libc
> -functions.
> +functions).
>  .TP
>  .B 4 Special files (devices)
>  Files found in
> -.IR /dev .
> +.I /dev
> +which allow to access to devices through the kernel.
>  .TP
> -.B 5 File formats and conventions
> -The format for
> -.I /etc/passwd
> -and other human-readable files.
> +.B 5 File formats and configuration
> +Describes various human-readable file formats and configuration files.
>  .TP
>  .B 6 Games
> +Games and funny little programs available on the system.
>  .TP
>  .B 7 Overview, conventions, and miscellaneous
> -Overviews of various topics, conventions and protocols,
> -character set standards, and miscellaneous other things.
> +Overviews or descriptions of various topics, conventions and protocols,
> +character set standards, the standard filesystem layout, and miscellaneous
> +other things.
>  .TP
>  .B 8 System management commands
>  Commands like
> 


-- 
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-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [patch] intro.1: Improve help for newcommers

[Michael Kerrisk (man-pages)]

Hello Stéphane,

On 02/27/2015 01:26 AM, saulery-GANU6spQydw@public.gmane.org wrote:
> From: Stéphane Aulery <saulery-GANU6spQydw@public.gmane.org>
> 
> - 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-GANU6spQydw@public.gmane.org>
> ---
>  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-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] intro.1: some improvements

[Stéphane Aulery]

- Add a section Logout and poweroff and change login/logout by open/close session
- Add ref. to other common shells dash(1), ksh(1)
- Add a ref. to stdout(3)
- Separate cp and mv descriptions
- Add examples of special cases of cd
- Add su(1) and shutdown(8) ref. for section Logout and poweroff
- Move Control-D to section Logout and poweroff
- Fix some little format errors

Signed-off-by: Stéphane Aulery <saulery-GANU6spQydw@public.gmane.org>
---
 man1/intro.1 | 59 ++++++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 44 insertions(+), 15 deletions(-)

diff --git a/man1/intro.1 b/man1/intro.1
index e9daccf..4b95871 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,19 @@ 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,12 +96,14 @@ 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:
 .LP
-A session might go like
-
 .RS
 .nf
 .RB "knuth login: " aeb
@@ -134,7 +147,7 @@ maja    0501\-1136285
 $
 .fi
 .RE
-and here typing Control-D ended the session.
+.LP
 The
 .B $
 here was the command prompt\(emit is the shell's way of indicating
@@ -171,15 +184,19 @@ 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", here
+parameters are concatenated and sent to "standard output"
+(see
+.BR stdout (3)),
+here
 the terminal screen.)
 .LP
 The command
 .I cp
 (from "copy") will copy a file.
-On the other hand, the command
+.LP
+The command
 .I mv
-(from "move") only renames it.
+(from "move"), on the other hand, only renames it.
 .LP
 The command
 .I diff
@@ -223,7 +240,14 @@ prints the current directory.
 The command
 .I cd
 changes the current directory.
-Try "cd /" and "pwd" and "cd" and "pwd".
+.LP
+Try alternatively
+.I cd
+and
+.I pwd
+commands and explore
+.I cd
+usage: "cd", "cd .", "cd ..", "cd /" and "cd ~".
 .SS Directories
 The command
 .I mkdir
@@ -315,11 +339,16 @@ and use a browser if you find HTML files there.
 .BR bash (1),
 .BR chsh (1),
 .BR csh (1),
+.BR dash (1),
+.BR ksh (1),
 .BR locate (1),
 .BR login (1),
 .BR man (1),
+.BR su (1),
 .BR xterm (1),
 .BR zsh(1),
 .BR wait (2),
+.BR stdout (3),
 .BR man-pages (7),
-.BR standards (7)
+.BR standards (7),
+.BR shutdown (8)
-- 
2.1.4

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] intro.1: some improvements

[Michael Kerrisk (man-pages)]

Hello Stéphane,

I applied most of the patch, but...

On 03/09/2015 09:26 PM, Stéphane Aulery wrote:
> - Add a section Logout and poweroff and change login/logout by open/close session

... not this first piece. See comments below.

> - Add ref. to other common shells dash(1), ksh(1)
> - Add a ref. to stdout(3)
> - Separate cp and mv descriptions
> - Add examples of special cases of cd
> - Add su(1) and shutdown(8) ref. for section Logout and poweroff
> - Move Control-D to section Logout and poweroff
> - Fix some little format errors
> 
> Signed-off-by: Stéphane Aulery <saulery-GANU6spQydw@public.gmane.org>
> ---
>  man1/intro.1 | 59 ++++++++++++++++++++++++++++++++++++++++++++---------------
>  1 file changed, 44 insertions(+), 15 deletions(-)
> 
> diff --git a/man1/intro.1 b/man1/intro.1
> index e9daccf..4b95871 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,19 @@ 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).

I'm not sure that we really need most of the above piece. I mean, in these 
days of GUI and laptops. Most of us use the GUI or close the lid to 
shutdown/suspend.

Cheers,

Michael


>  .SS The shell
>  One types commands to the
>  .IR shell ,
> @@ -85,12 +96,14 @@ 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:
>  .LP
> -A session might go like
> -
>  .RS
>  .nf
>  .RB "knuth login: " aeb
> @@ -134,7 +147,7 @@ maja    0501\-1136285
>  $
>  .fi
>  .RE
> -and here typing Control-D ended the session.
> +.LP
>  The
>  .B $
>  here was the command prompt\(emit is the shell's way of indicating
> @@ -171,15 +184,19 @@ 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", here
> +parameters are concatenated and sent to "standard output"
> +(see
> +.BR stdout (3)),
> +here
>  the terminal screen.)
>  .LP
>  The command
>  .I cp
>  (from "copy") will copy a file.
> -On the other hand, the command
> +.LP
> +The command
>  .I mv
> -(from "move") only renames it.
> +(from "move"), on the other hand, only renames it.
>  .LP
>  The command
>  .I diff
> @@ -223,7 +240,14 @@ prints the current directory.
>  The command
>  .I cd
>  changes the current directory.
> -Try "cd /" and "pwd" and "cd" and "pwd".
> +.LP
> +Try alternatively
> +.I cd
> +and
> +.I pwd
> +commands and explore
> +.I cd
> +usage: "cd", "cd .", "cd ..", "cd /" and "cd ~".
>  .SS Directories
>  The command
>  .I mkdir
> @@ -315,11 +339,16 @@ and use a browser if you find HTML files there.
>  .BR bash (1),
>  .BR chsh (1),
>  .BR csh (1),
> +.BR dash (1),
> +.BR ksh (1),
>  .BR locate (1),
>  .BR login (1),
>  .BR man (1),
> +.BR su (1),
>  .BR xterm (1),
>  .BR zsh(1),
>  .BR wait (2),
> +.BR stdout (3),
>  .BR man-pages (7),
> -.BR standards (7)
> +.BR standards (7),
> +.BR shutdown (8)
> 


-- 
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-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] intro.1: some improvements

[Stéphane Aulery]

Hello Michael,

Le mardi 10 mars 2015 à 07:09:10, Michael Kerrisk (man-pages) a écrit :
> 
> I applied most of the patch, but...
> 
> On 03/09/2015 09:26 PM, Stéphane Aulery wrote:
> > - Add a section Logout and poweroff and change login/logout by open/close session
> 
> ... not this first piece. See comments below.
> 
> > +.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).
> 
> I'm not sure that we really need most of the above piece. I mean, in these 
> days of GUI and laptops. Most of us use the GUI or close the lid to 
> shutdown/suspend.

I use startx / shutdown, so it does not shock me. This addition and the
other I have proposed that the reader knows what to do if X does not
start.

If you do not want, no problem, but now the page is incoherent:

- Control-D was moved to the non-added portion
- Su (1), shutdown (8) in excess in SEE ALSO

Regards,

-- 
Stéphane Aulery
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] intro.1: some improvements

[Michael Kerrisk (man-pages)]

Hi Stéphane

[I'll reorder the text a mail a little for ease of reply]

>> I'm not sure that we really need most of the above piece. I mean, in these 
>> days of GUI and laptops. Most of us use the GUI or close the lid to 
>> shutdown/suspend.
> 
> I use startx / shutdown, so it does not shock me. This addition and the
> other I have proposed that the reader knows what to do if X does not
> start.

Okay. So, some observations:

1. I've never been a huge fan of the extended intro.1 page. I just think
   it's a little out of place as man page. For the most part, tutorials
   are best put somewhere else. That said, the intro(1) page was already
   there when I arrived as maintainer, and I'm not so disturbed by
   the tutorial content that I want to eliminate it. I will even take
   reasonable additions to it.

2. I don't want this page to grow enormous.

3. I'd like it to focus on the commonly used commands. Or, where it 
   covers less commonly used commands, then a few words of explanation
   are in order. For example, one could say: "Although the X Windows
   system is commonly started automatically, and the system is shut down
   or suspended through a graphical interface, there are commands that
   can be used from the shell to perform each of these steps..."
   See what I mean?

> If you do not want, no problem, but now the page is incoherent:
> 
> - Control-D was moved to the non-added portion
> - Su (1), shutdown (8) in excess in SEE ALSO

Good point. So, some clean up is needed. Could you take a look?
But see comments below.

> Le mardi 10 mars 2015 à 07:09:10, Michael Kerrisk (man-pages) a écrit :
>>
>> I applied most of the patch, but...
>>
>> On 03/09/2015 09:26 PM, Stéphane Aulery wrote:
>>> - Add a section Logout and poweroff and change login/logout by open/close session
>>
>> ... not this first piece. See comments below.

So, a metacomment. This piece really would have been better as a
separate patch, since it's rather a new topi, and then we could
have started this conversation sooner, and also avoided the small
incoherent piece that we now have.

I would probably take a patch that covers this stuff, but addresses my 
idea above. But see also the comments below.

>>> +.SS Logout and poweroff
>>> +When you work is finished,
>>> +you can press Control-D to close the current session.

This text is confusing. What is the "current session"?

>>> +This does not turn off the machine.

What is "This"? I think it's confusing to bring together the
discussion of terminating a shell session and shutting down the system.

>>> +Only superusers have access to this command.

What is "this command"?

>>> +If you are the single user you can also not log off

What is "the single user"?

>>> +and becoming a superuser by typing the command
>>> +.BR su (1).

In general, I can't understand what the last sentence is trying 
to say...

>>> +Also you must type yours password.

s/yours/your/

>>> +Finally enter the command "shutdown -P +1",
>>> +which will turn off the computer after one minute.
>>> +See
>>> +.BR shutdown (8).

So, you see pat of my problem was also that I think the text 
still needed much work. I should have explained that, but I 
left off to so, since I was not convinced we need this stuff 
in general. (But, if you want to do the work to make something,
I will probably take it.)

I'd propose this, if you want to try and add these pieces:

* Split any discussion of closing a shell session off into a 
  separate piece.
* Explain startx if you want.
* Explain shutdown if you want.

But, I think all of these pieces are more or less
orthogonal and should be explained separately.

Thanks,

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-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] intro.1: Fix errors introduced by the commit 6732bb8b0d550262dbd73de4d0789dd9f9ad294b

[Stéphane Aulery]

- Restoration of the explanation session end.
- Delete two supernumerary references.

Signed-off-by: Stéphane Aulery <saulery-GANU6spQydw@public.gmane.org>
---
 man1/intro.1 | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/man1/intro.1 b/man1/intro.1
index 9e3fa15..e509d03 100644
--- a/man1/intro.1
+++ b/man1/intro.1
@@ -135,6 +135,8 @@ $
 .fi
 .RE
 .LP
+Here typing Control-D ended the session.
+.LP
 The
 .B $
 here was the command prompt\(emit is the shell's way of indicating
@@ -331,11 +333,9 @@ and use a browser if you find HTML files there.
 .BR locate (1),
 .BR login (1),
 .BR man (1),
-.BR su (1),
 .BR xterm (1),
-.BR zsh(1),
+.BR zsh (1),
 .BR wait (2),
 .BR stdout (3),
 .BR man-pages (7),
-.BR standards (7),
-.BR shutdown (8)
+.BR standards (7)
-- 
2.1.4

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] intro.1: some improvements

[Stéphane Aulery]

Hi Michael,

Le mardi 10 mars 2015 à 09:53:23, Michael Kerrisk (man-pages) a écrit :
> 
> Okay. So, some observations:
> 
> 1. I've never been a huge fan of the extended intro.1 page. I just think
>    it's a little out of place as man page. For the most part, tutorials
>    are best put somewhere else. That said, the intro(1) page was already
>    there when I arrived as maintainer, and I'm not so disturbed by
>    the tutorial content that I want to eliminate it. I will even take
>    reasonable additions to it.

To be honest, I was a bit stunned when I saw this tutorial that will not
say his name in the introductory page. But why not ! Improve it then. It
could either be deleted or moved to a new page. I wonder why there is not
historically a section for howtos.


> So, you see pat of my problem was also that I think the text 
> still needed much work. I should have explained that, but I 
> left off to so, since I was not convinced we need this stuff 
> in general.

Thank you, I understand your point of view. In this case I totally inclined
to simply delete the tutorial, and replace it with, perhaps, a subject
index of user commands (most used). It would be much more useful.

Meanwhile, I sent a patch to correct inconsistencies.

Regards,

-- 
Stéphane Aulery
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] intro.1: Fix errors introduced by the commit 6732bb8b0d550262dbd73de4d0789dd9f9ad294b

[Michael Kerrisk (man-pages)]

On 03/10/2015 10:06 PM, Stéphane Aulery wrote:
> - Restoration of the explanation session end.
> - Delete two supernumerary references.


Thanks, Stéphane. Applied.

Cheers,

Michael



> Signed-off-by: Stéphane Aulery <saulery-GANU6spQydw@public.gmane.org>
> ---
>  man1/intro.1 | 8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)
> 
> diff --git a/man1/intro.1 b/man1/intro.1
> index 9e3fa15..e509d03 100644
> --- a/man1/intro.1
> +++ b/man1/intro.1
> @@ -135,6 +135,8 @@ $
>  .fi
>  .RE
>  .LP
> +Here typing Control-D ended the session.
> +.LP
>  The
>  .B $
>  here was the command prompt\(emit is the shell's way of indicating
> @@ -331,11 +333,9 @@ and use a browser if you find HTML files there.
>  .BR locate (1),
>  .BR login (1),
>  .BR man (1),
> -.BR su (1),
>  .BR xterm (1),
> -.BR zsh(1),
> +.BR zsh (1),
>  .BR wait (2),
>  .BR stdout (3),
>  .BR man-pages (7),
> -.BR standards (7),
> -.BR shutdown (8)
> +.BR standards (7)
> 


-- 
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-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html