runtime(vimtutor): Add a second chapter
fixes: #5719
closes: #5729
Signed-off-by: Paul Desmond Parker <pauldesmondparker@gmail.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>
diff --git a/runtime/doc/usr_01.txt b/runtime/doc/usr_01.txt
index 9902691..604e26b 100644
--- a/runtime/doc/usr_01.txt
+++ b/runtime/doc/usr_01.txt
@@ -120,8 +120,11 @@
On MS-Windows you can find it in the Program/Vim menu. Or execute
vimtutor.bat in the $VIMRUNTIME directory.
-This will make a copy of the tutor file, so that you can edit it without
-the risk of damaging the original.
+This will make a copy of chapter 1 tutor file, so that you can edit it without
+the risk of damaging the original. To continue with chapter 2, you can use
+the following command: >
+ vimtutor -c 2
+<
There are a few translated versions of the tutor. To find out if yours is
available, use the two-letter language code. For French: >
diff --git a/runtime/doc/version9.txt b/runtime/doc/version9.txt
index d016ccf..999a09c 100644
--- a/runtime/doc/version9.txt
+++ b/runtime/doc/version9.txt
@@ -41605,6 +41605,7 @@
- the |help-TOC| package is included to ease navigating the documentation.
- an interactive tutor plugin has been included |vim-tutor-mode|, can be
started via |:Tutor|
+- improve the |vimtutor| and add a second chapter for more advanced tips
*added-9.2*
Added ~
diff --git a/runtime/doc/vimtutor.1 b/runtime/doc/vimtutor.1
index a71bc02..3d3f32b 100644
--- a/runtime/doc/vimtutor.1
+++ b/runtime/doc/vimtutor.1
@@ -1,16 +1,18 @@
-.TH VIMTUTOR 1 "2024 August 12"
+.TH VIMTUTOR 1 "2024 November 03"
.SH NAME
vimtutor \- the Vim tutor
.SH SYNOPSIS
.br
-.B vimtutor [\-g] [language]
+.B vimtutor [\-l | \-\-language ISO639] [\-c | \-\-chapter NUMBER] [\-g | \-\-gui] [ISO639]
+.br
+.B vimtutor [\-h | \-\-help]
+.br
+.B vimtutor [\-\-list]
.SH DESCRIPTION
.B Vimtutor
starts the
.B Vim
tutor.
-It copies the tutor file first, so that it can be modified without changing
-the original file.
.PP
The
.B Vimtutor
@@ -28,34 +30,91 @@
If a tutor in this language is available, it will be used.
Otherwise the English version will be used.
.PP
+.B Vimtutor
+only opens temporary copies of the original tutor files, there is no danger of overwriting the lessons.
+.PP
.B Vim
-is always started in Vi compatible mode.
+is always started in
+.B Vi
+compatible mode.
+.SH OPTIONS
+.TP
+.BR \-l ", " \-\-language =\fIISO639\fR
+Set the two or three letter language code. E.g. 'it', 'es', 'bar'. Defaults to language of locale if available, else to English.
+.TP
+.BR \-c ", " \-\-chapter =\fINUMBER\fR
+Set the one or two digit chapter number. Defaults to chapter one.
+.TP
+.BR \-g ", " \-\-gui
+Start
+.B vimtutor
+in the GUI version of vim if available, otherwise fallback to console vim.
+.TP
+.BR \-h ", " \-\-help
+Display usage information.
+.TP
+.BR \-\-list
+Display chapters and languages.
+.SH EXAMPLES
+To start
+.B vimtutor
+in German on chapter one:
+.PP
+.nf
+.RS
+vimtutor de
+.RE
+.fi
+.PP
+In English on chapter two:
+.PP
+.nf
+.RS
+vimtutor -c2
+.RE
+.fi
+.PP
+Longform command for Bavarian in the GUI on chapter one:
+.PP
+.nf
+.RS
+vimtutor --language bar --chapter 1 --gui
+.RE
+.fi
.SH FILES
.TP 15
/usr/local/share/vim/vim??/tutor/tutor[.language]
The
.B Vimtutor
-text file(s).
-.br
-.I vim??
-is short version number, like vim91 for
-.B Vim 9.1
+chapter one text file(s).
.TP 15
-/usr/local/share/vim/vim??/tutor/tutor.vim
-The Vim script used to copy the
-.B Vimtutor
-text file.
-.SH AUTHOR
+/usr/local/share/vim/vim??/tutor/tutor02[.language]
The
.B Vimtutor
-was originally written for Vi by Michael C. Pierce and Robert K. Ware,
-Colorado School of Mines using ideas supplied by Charles Smith,
-Colorado State University.
-E-mail: bware@mines.colorado.edu (now invalid).
-.br
-It was modified for
+chapter two text file(s).
+.TP 15
+/usr/local/share/vim/vim??/tutor/tutor.vim
+The
+.B Vim
+script used to copy the
+.B Vimtutor
+chapter one text file.
+.TP 15
+/usr/local/share/vim/vim??/tutor/tutor02.vim
+The
+.B Vim
+script used to copy the
+.B Vimtutor
+chapter two text file.
+.SH AUTHOR
+.B The Vi Tutorial
+was originally written for Vi by Michael C. Pierce and Robert K. Ware, Colorado School of Mines using ideas supplied by Charles Smith, Colorado State University.
+.B E-mail: bware@mines.colorado.edu.
+.PP
+Modified for
.B Vim
by Bram Moolenaar.
-For the names of the translators see the tutor files.
+.PP
+Translation contributors are listed in the tutor files.
.SH SEE ALSO
vim(1)
diff --git a/runtime/doc/vimtutor.man b/runtime/doc/vimtutor.man
index f1e113e..459542e 100644
--- a/runtime/doc/vimtutor.man
+++ b/runtime/doc/vimtutor.man
@@ -1,16 +1,16 @@
VIMTUTOR(1) General Commands Manual VIMTUTOR(1)
-
-
NAME
vimtutor - the Vim tutor
SYNOPSIS
- vimtutor [-g] [language]
+ vimtutor [-l | --language ISO639] [-c | --chapter NUMBER] [-g | --gui]
+ [ISO639]
+ vimtutor [-h | --help]
+ vimtutor [--list]
DESCRIPTION
- Vimtutor starts the Vim tutor. It copies the tutor file first, so that
- it can be modified without changing the original file.
+ Vimtutor starts the Vim tutor.
The Vimtutor is useful for people that want to learn their first Vim
commands.
@@ -21,31 +21,73 @@
The optional [language] argument is the two-letter name of a language,
like "it" or "es". If the [language] argument is missing, the language
- of the current locale will be used. If a tutor in this language is
- available, it will be used. Otherwise the English version will be
+ of the current locale will be used. If a tutor in this language is
+ available, it will be used. Otherwise the English version will be
used.
+ Vimtutor only opens temporary copies of the original tutor files, there
+ is no danger of overwriting the lessons.
+
Vim is always started in Vi compatible mode.
+OPTIONS
+ -l, --language=ISO639
+ Set the two or three letter language code. E.g. 'it', 'es',
+ 'bar'. Defaults to language of locale if available, else to Eng‐
+ lish.
+
+ -c, --chapter=NUMBER
+ Set the one or two digit chapter number. Defaults to chapter
+ one.
+
+ -g, --gui
+ Start vimtutor in the GUI version of vim if available, otherwise
+ fallback to console vim.
+
+ -h, --help
+ Display usage information.
+
+ --list Display chapters and languages.
+
+EXAMPLES
+ To start vimtutor in German on chapter one:
+
+ vimtutor de
+
+ In English on chapter two:
+
+ vimtutor -c2
+
+ Longform command for Bavarian in the GUI on chapter one:
+
+ vimtutor --language bar --chapter 1 --gui
+
FILES
/usr/local/share/vim/vim??/tutor/tutor[.language]
- The Vimtutor text file(s).
- vim?? is short version number, like vim91 for Vim 9.1
+ The Vimtutor chapter one text file(s).
+
+ /usr/local/share/vim/vim??/tutor/tutor02[.language]
+ The Vimtutor chapter two text file(s).
/usr/local/share/vim/vim??/tutor/tutor.vim
- The Vim script used to copy the Vimtutor text file.
+ The Vim script used to copy the Vimtutor chapter one
+ text file.
+
+ /usr/local/share/vim/vim??/tutor/tutor02.vim
+ The Vim script used to copy the Vimtutor chapter two
+ text file.
AUTHOR
- The Vimtutor was originally written for Vi by Michael C. Pierce and
- Robert K. Ware, Colorado School of Mines using ideas supplied by
- Charles Smith, Colorado State University. E-mail: bware@mines.col‐
- orado.edu (now invalid).
- It was modified for Vim by Bram Moolenaar. For the names of the trans‐
- lators see the tutor files.
+ The Vi Tutorial was originally written for Vi by Michael C. Pierce and
+ Robert K. Ware, Colorado School of Mines using ideas supplied by
+ Charles Smith, Colorado State University. E-mail: bware@mines.col‐
+ orado.edu.
+
+ Modified for Vim by Bram Moolenaar.
+
+ Translation contributors are listed in the tutor files.
SEE ALSO
vim(1)
-
-
- 2024 August 12 VIMTUTOR(1)
+ 2024 November 03 VIMTUTOR(1)