helphelp.txt Für Vim Version 9.1. Letzte Änderung: 19.Nov.2024
VIM REFERENZHANDBUCH von Bram Moolenaar
Hilfe zu Hilfedateien helphelp
1. Hilfebefehle online-help
2. Übersetzte Hilfedateien help-translated
3. Hilfedateien schreiben help-writing
==============================================================================
1. Hilfebefehle online-help
help <Help> :h :help <F1> i_<F1> i_<Help>
<Help> oder
:h[elp] Öffnet ein Fenster und zeigt die Hilfedatei im
Nur-Lese-Modus an. Falls bereits ein Hilfefenster
geöffnet ist, wird dieses verwendet. Anderenfalls
erscheint, falls das aktuelle Fenster die volle
Bildschirmbreite verwendet oder mindestens 80 Zeichen
breit ist, das Hilfefenster genau über dem aktuellen
Fenster. Anderenfalls wird das neue Fenster ganz
zuoberst platziert.
Die Option 'helplang' wird verwendet, um eine Sprache
auszuwählen, falls die Haupthilfedatei in mehreren
Sprachen verfügbar ist.
{subject} E149 E661
:h[elp] {Thema} Wie :help, springt zusätzlich zum Tag {Thema}.
Zum Beispiel:
:help options
{Thema} kann Wildcards wie "*", "?" und "[a-z]"
enthalten:
:help z? springt zur Hilfe für irgendeinen "z"-
Befehl
:help z. springt zur Hilfe für "z."
Aber wenn das Tag existiert wird es wörtlich genommen:
:help :? springt zur Hilfe für ":?"
Falls es keine volle Übereinstimmung oder mehrere
Übereinstimmungen für das Muster gibt, wird die
"beste" Übereinstimmung verwendet.
Ein ausgeklügelter Algorithmus wird verwendet um zu
entscheiden, welche Übereinstimmung besser als eine
andere ist. Diese Elemente werden bei der Berechnung
berücksichtigt:
- Eine Übereinstimmung mit derselben Groß-/
Kleinschreibung ist viel besser als eine
Übereinstimmung, wo sie sich unterscheidet.
- Eine Übereinstimmung, die nach einem
nicht-alphanumerischen Zeichen beginnt, ist besser
als eine Übereinstimmung in der Mitte eines Wortes.
- Eine Übereinstimmung am oder nahe dem Beginn des
Tags ist besser als eine Übereinstimmung weiter
hinten.
- Je mehr alphanumerische Zeichen übereinstimmen, umso
besser.
- Je kürzer die Länge der Übereinstimmung, umso
besser.
Die Option 'helplang' wird verwendet, um eine Sprache
auszuwählen, falls {Thema} in verschiedenen Sprachen
verfügbar ist.
Um ein Tag in einer bestimmten Sprache zu finden,
hängen Sie "@ab" an, wobei "ab" der zwei-buchstabige
Sprachcode ist. Siehe help-translated.
Beachten Sie, dass je länger das angegebene {Thema}
ist, desto weniger Übereinstimmungen werden gefunden.
Sie können eine Vorstellung davon, wie all das
funktioniert, bekommen, indem Sie Befehlszeilen-
vervollständigung verwenden (Geben Sie CTRL-D nach
":help Thema" c_CTRL-D) ein.
Falls es mehrere Übereinstimmungen gibt, können Sie
sie durch das Drücken von CTRL-D auflisten lassen.
Beispiel:
:help cont<Ctrl-D>
Statt ":help CTRL-V" einzugeben, um Hilfe für CTRL-V zu
suchen, können Sie das folgende eingeben:
:help ^V
Dies funktioniert auch zusammen mit anderen Zeichen,
um zum Beispiel Hilfe für CTRL-V im Einfügemodus zu
finden:
:help i^V
Es ist ebenfalls möglich erst ":help" einzugeben und
dann ":tag {Muster}" in dem Hilfefenster zu verwenden.
Der Befehl :tnext kann verwendet werden, um zu
anderen Übereinstimmungen zu springen, :tselect um
Übereinstimmungen aufzulisten und eine auszuwählen.
:help index
:tselect /.*mode
Wenn es kein Argument gibt, sehen Sie
Übereinstimmungen für "help", um das Auflisten aller
möglichen Übereinstimmungen zu vermeiden (das wäre
sehr langsam).
Die Zahl der angezeigten Übereinstimmungen ist auf 300
begrenzt.
Dem :help-Befehl kann ein '|' und ein anderer Befehl
folgen, aber Sie brauchen den '|' innerhalb eines
help-Befehls nicht zu markieren. Somit funktioniert
beides:
:help |
:help k| only
Beachten Sie, dass ein Leerzeichen vor dem '|' als
Teil des Arguments zu :help angesehen wird.
Sie können auch <NL> oder <CR> verwenden, um den
help-Befehl von einem nachfolgenden Befehl zu trennen.
Sie müssen zuerst CTRL-V eingeben um das <NL> oder <CR>
einzufügen. Beispiel:
:help so<C-V><CR>only
:h[elp]! [Thema] Wie :help, zieht aber in nicht-englischen
Hilfedateien vor, ein Tag in einer Datei mit derselben
Sprache wie die aktuelle Datei zu finden. Siehe
help-translated.
:helpc :helpclose
:helpc[lose] Schließt ein Hilfefenster, wenn es eines gibt.
Vim versucht, das Fensterlayout zu demselben
Fensterlayout (einschließlich der Cursor-Position)
wiederherzustellen, wie es war bevor anfangs das
Hilfefenster geöffnet wurde. Dies kann das Auslösen
von Autobefehlen verursachen.
:helpg :helpgrep
:helpg[rep] {Muster}[@xx]
Durchsucht alle Hilfedateien und erstellt eine Liste
der Zeilen, in denen {Muster} übereinstimmt. Geht zur
ersten Übereinstimmung.
Das optionale [@xx] gibt an, dass nur Treffer in der
Sprache "xx" gefunden werden sollen.
Sie können mit den quickfix-Befehlen durch die
Treffer navigieren, z.B. :cnext um zum nächsten zu
gehen. Oder `:cwindow verwenden um die Liste der
Treffer im Quickfix-Fenster zu erhalten.
{Muster} wird als Muster in Vims regulären Ausdrücken
verwendet (pattern).
'ignorecase' wird nicht verwendet, fügen Sie "\c"
hinzu, um Groß-/Kleinschreibung zu ignorieren.
Beispiel für eine Suche, die Groß-/Kleinschreibung
unterscheidet:
:helpgrep Uganda
Beispiel für eine Such, die Groß-/Kleinschreibung
ignoriert:
:helpgrep uganda\c
Beispiel für eine Suche in der französischen Hilfe:
:helpgrep backspace@fr
Das Muster unterstützt keine Zeilenumbrüche, es muss
in einer Zeile übereinstimmen. Sie können stattdessen
:grep verwenden, aber dann müssen Sie die Liste der
Hilfedateien auf eine komplizierte Weise beziehen.
Diesem Befehl kann kein weiterer Befehl folgen, alles
wird als Teil des Musters verwendet. Aber Sie können
:execute verwenden falls nötig.
Komprimierte Hilfedateien werden nicht durchsucht
(Fedora komprimiert die Hilfedateien).
:lh :lhelpgrep
:lh[elpgrep] {Muster}[@xx]
Dasselbe wie :helpgrep, außer dass statt der
Quickfix-Liste die Lokationsliste verwendet wird.
Falls das Hilfefenster bereits geöffnet ist, wird die
Lokationsliste für dieses Fenster verwendet.
Anderenfalls wird ein neues Hilfefenster geöffnet und
die Lokationsliste wird für dieses Fenster gesetzt;
die Lokationsliste für das aktuelle Fenster wird dann
nicht verändert.
:exu :exusage
:exu[sage] Zeigt Hilfe zu Ex-Befehlen. Hinzugefügt um den Nvi-
Befehl zu simulieren.
:viu :viusage
:viu[sage] Zeigt Hilfe zu Normalmodusbefehlen. Hinzugefügt um den
Nvi-Befehl zu simulieren.
Wenn :help kein Argument übergeben wird, wird die Datei geöffnet, die mit
der Option 'helpfile' angegeben wird. Anderenfalls wird das angegebene Tag
in
allen "doc/tags"-Dateien in den Verzeichnissen, die mit der Option
'runtimepath' angegeben sind, gesucht.
Fall Sie das Hilfefenster im aktuellen Fenster öffnen möchten, lesen Sie den
Tipp help-curwin.
Die anfängliche Höhe des Hilfefensters kann mit der Option 'helpheight'
festgelegt werden (Vorgabe 20).
help-buffer-options
Wenn der Hilfepuffer erzeugt wird, werden einige lokale Optionen gesetzt, um
sicher zu stellen, dass der Hilfetext wie vorgesehen angezeigt wird:
'iskeyword' nahezu alle ASCII-Zeichen außer ' ', '*', '"' und '|'
'foldmethod' "manual"
'tabstop' 8
'arabic' aus
'binary' aus
'buflisted' aus
'cursorbind' aus
'diff' aus
'foldenable' aus
'list' aus
'modifiable' aus
'number' aus
'relativenumber' aus
'rightleft' aus
'scrollbind' aus
'spell' aus
Springen Sie durch das Verwenden von Tags zu bestimmten Themen. Dies kann auf
zwei Arten geschehen:
- Verwenden Sie den Befehl CTRL-], während Sie auf dem Namen eines Befehls
oder einer Option stehen. Dies funktioniert nur wenn das Tag ein
Schlüsselwort ist. <C-Leftmouse> und g<Leftmouse> funktionieren genauso
wie CTRL-].
Verwenden Sie CTRL-T oder CTRL-O um zurück zu gehen. Verwenden Sie :q, um
das Hilfefenster zu schließen.
Falls es mehrere Treffer für ein Element, nach dem Sie suchen, gibt, können
Sie wie folgt zu jedem von ihnen gehen:
1. Öffnen Sie ein Hilfefenster.
2. Verwenden Sie den Befehl :tag, wobei Sie dem Tag einen Schrägstrich voran
stellen. Zum Beispiel:
:tag /min
3. Verwenden Sie :tnext, um zum nächsten passenden Tag zu gehen.
Es ist möglich, für Erweiterungen und andere Elemente Hilfedateien
hinzuzufügen. Sie brauchen dafür die mit Vim verteilten Hilfedateien nicht
zu ändern. Siehe add-local-help.
Um eine lokale Hilfedatei zu schreiben, siehe write-local-help.
Beachten Sie, dass die Titelzeilen der lokalen Hilfedateien automagisch zum
Abschnitt "LOCAL ADDITIONS" in der Hilfedatei "help.txt" hinzugefügt werden
local-additions. Dies geschieht, wenn die Datei in Vim angezeigt wird,
die Datei selbst wird nicht verändert. Es geschieht durch Durchlaufen aller
Hilfedateien und Holen der ersten Zeile einer jeden. Die Dateien in
$VIMRUNTIME/doc werden übersprungen.
help-xterm-window
Falls Sie die Hilfe in einem neuen XTerm-Fenster haben möchten, können Sie
diesen Befehl verwenden:
:!xterm -e vim +help &
:helpfind :helpf
:helpf{ind} Wie :help, aber verwendet einen Dialog, um das
Argument einzugeben. Nur zur Abwärtskompatilität. Nun
führt es den Menüeintrag ToolBar.FindHelp aus, statt
einen eingebauten Dialog zu verwenden. {Nur wenn Vim
mit +GUI-GTK kompiliert wurde}
:helpt :helptags:
E150 E151 E152 E153 E154 E670
:helpt[ags] [++t] {Verzeichnis}
Generiert die Hilfe-Tags-Datei(en) für {Verzeichnis}.
Wenn {Verzeichnis} ALL ist, dann werden alle "doc"-
Verzeichnisse in 'runtimepath' verwendet.
Alle "*.txt"- und "*.??x"-Dateien im Verzeichnis und
Unterverzeichnissen werden nach einer
Hilfe-Tag-Definition zwischen Sternen durchsucht. Die
"*.??x"-Dateien sind für übersetzte Dokumentation, sie
generieren die Datei "tags-??", siehe
help-translated. Die generierten Tag-Dateien werden
sortiert.
Wenn es Dubletten gibt, wird eine Fehlermeldung
ausgegeben.
Eine vorhandene Tag-Datei wird stillschweigend
überschrieben.
Das optionale Argument "++t" erzwingt das Hinzufügen
des Tags "help-tags". Dies geschieht ebenfalls, wenn
{Verzeichnis} gleich mit $VIMRUNTIME/doc ist.
Um die Hilfe-Tags im Laufzeitverzeichnis neu zu
erstellen (erfordert dort Schreibrecht):
:helptags $VIMRUNTIME/doc
:HelpToc help-TOC help-toc-install
Falls Sie auf eine interaktive Inhaltsangabe von jeder Position in der Datei
zugreifen wollen können Sie die helptoc-Erweiterung verwenden. Laden Sie die
Erweiterung mit:
packadd helptoc
Dann können Sie den Befehl :HelpToc verwenden um ein Aufklappmenü zu
öffnen. Letzteres unterstützt die folgenden Normalbefehle:
Taste| Auswirkung
-----+--------------------------------------------------------
j | Wählt nächsten Eintrag
k | Wählt vorherigen Eintrag
J | wie j und springt zur entsprechenden Zeile im Hauptpuffer
K | wie k und springt zur entsprechenden Zeile im Hauptpuffer
c | Wählt den nächsten Eintrag von der Cursorposition im Hauptpuffer
g | Wählt den ersten Eintrag
G | Wählt den letzten Eintrag
H | Klappt um ein Ebene zu
L | Klappt um ein Ebene auf
p | Gibt aktuellen Eintrag auf der Befehlszeile aus
P | wie p aber automatisch, wann immer sich die Auswahl
| ándert; Geben Sie mehrmals ein um die Fähigkeit ein oder
| auszuschalten
q | Beendet Menü
z | Zeichnet Menü neu mit dem aktuellen Eintrag im Zentrum
+ | Erhöht Breite des Aufklappmenüs
- | Verringert Breite des Aufklappmenüs
? | Zeigt/Versteckt ein Hilfefenster
/ | Sucht ein Muster
<C-O> | Zieht eine halbe Seite nach unten
<C-U> | Zieht eine halbe Seite nach oben
<PageUp> | Zieht eine ganze Seite nach unten
<PageDown> | Zieht eine ganze Seite nach oben
<Home> | Wählt ersten Eintrag
<End> | Wählt letzten Eintrag
Die Erweiterung kann auch in Handbuchseiten, Markdown-Dateien und
Terminal-Puffern eine Inhaltsangabe anbieten. In letzteren sind die Einträge
die zuvor ausgeführten Shell-Befehle. Um diese zu finden wird das folgende
Muster verwendet:
^\w\+@\w\+:\f\+\$\s
Dies soll mit der vorgegebenen Bash-Eingabeaufforderung
übereinstimmen. Falls es nicht mit Ihrer Eingabeaufforderung übereinstimmt
können Sie den regulären Ausdruck mit dem Schlüssel shell_prompt in der
Wörterbuchvariablen g:helptoc ändern:
let g:helptoc = {'shell_prompt': 'Muster passend zur Shell-Aufforderung'}
Tipp: Falls Sie nach Einfügen eines Suchmusters mit dem Befehl / <Esc>
statt <CR> eingeben können Sie dann durch das Eingeben von J oder K
weiteren Zusammenhang für jeden verbleibenden Eintrag.
==============================================================================
2. Übersetzte Hilfedateien help-translated
Es ist möglich, neben den originalen englischen Hilfedateien übersetzte
Hilfedateien hinzuzufügen. Vim sucht nach allen Hilfedateien in
"doc"-Verzeichnissen in 'runtimepath'. Dies ist nur verfügbar, wenn Vim mit
der Fähigkeit +multi_lang kompiliert wurde.
Zu diesem Zeitpunkt sind folgende Übersetzungen verfügbar:
Chinesisch - mehrere Autoren
Französisch - übersetzt von David Blanchet
Italienisch - übersetzt von Antonio Colombo
Japanisch - mehrere Autoren
Polnisch - übersetzt von Mikolaj Machowski
Russisch - übersetzt von Vassily Ragosin
Besuchen Sie die Vim-Website um sie zu finden:
http://www.vim.org/translations.php
Ein Satz übersetzter Hilfedateien besteht aus diesen Dateien:
help.abx
howto.abx
...
tags-ab
"ab" ist der zweibuchstabige Sprach-Code. Somit sind die Namen für
Italienisch
help.itx
howto.itx
...
tags-it
Die Option 'helplang' kann auf die bevorzugte(n) Sprache(n) gesetzt
werden. Die Vorgabe wird entsprechen der Umgebung gesetzt. Vim versucht
zunächst, ein Tag in der/den bevorzugten Sprache(n) zu finden. Englisch wird
verwendet, wenn es nicht gefunden werden kann.
Um ein Tag in einer bestimmten Sprache zu finden hängen Sie ihm "@ab" an,
wobei "ab" der zweibuchstabige Sprachcode ist. Beispiel:
:he user-manual@it
:he user-manual@en
Das erste findet das italienische Anwenderhandbuch, selbst wenn 'helplang'
leer ist. Das zweite findet das englische Anwenderhandbuch, selbst wenn
'helplang' auf "it" gesetzt ist.
Beim Verwenden der Befehlszeilenvervollständigung für den Befehl :help
wird die Erweiterung "@en" nur angezeigt, wenn ein Tag in mehreren Sprachen
existiert. Wenn das Tag nur in Englisch existiert wird "@en" ausgelassen,
Wenn der erste Kandidat eine Erweiterung "@ab" hat und mit der ersten
Sprache in 'helplang' übereinstimmt wird "@ab" ebenfalls ausgelassen.
Beim Verwenden von CTRL-] oder :help! in einer nichtenglischen
Hilfedatei versucht Vim das Tag in derselben Sprache zu finden. Falls es
nicht gefunden wird, wird 'helplang' verwendet, um eine Sprache auszuwählen.
Hilfedateien müssen als Kodierung Latin1 oder UTF-8 verwenden. Vim nimmt an,
dass die Kodierung UTF-8 ist, wenn nicht-ASCII-Zeichen in der ersten Zeile
gefunden werden. Somit müssen Sie die Kopfzeile mit "For Vim version"
übersetzen.
Dieselbe Kodierung ist für die Hilfedateien einer Sprache in einem
Verzeichnis zu verwenden. Sie können verschiedene Kodierungen für
unterschiedliche Sprachen und verschiedene Kodierungen für Hilfedateien in
derselben Sprache aber in unterschiedlichen Verzeichnissen verwenden.
Hinweise an Übersetzer:
- Übersetzen Sie nicht die Tags. Dies macht es möglich, 'helplang' zu
verwenden um die bevorzugte Sprache anzugeben. Sie können neue Tags in Ihrer
Sprache hinzufügen.
- Wenn Sie einen Teil einer Datei nicht übersetzen, fügen Sie unter
Verwendung der "@en"-Notation Tags auf die englische Version hinzu.
- Machen Sie ein Paket mit allen Dateien und der tags-Datei zum Herunterladen
verfügbar. Anwender können es in eines ihrer "doc"-Verzeichnisse legen und
beginnen es zu verwenden. Berichten Sie an das Entwicklerteam so dass es
einen Link auf www.vim.org hinzufügt.
- Verwenden Sie den Befehl :helptags, um die Tags-Dateien zu generieren. Er
findet alle Sprachen in dem angegebenen Verzeichnis.
==============================================================================
3. Hilfedateien schreiben help-writing
Zur einfachen Verwendung sollte eine Vim-Hilfedatei für eine Erweiterung dem
Format der Standard-Vim-Hilfedateien mit Ausnahme der ersten Zeile
folgen. Falls Sie eine neue Hilfedatei schreiben ist es am Besten, eine der
bestehenden Dateien zu Kopieren und sie als Vorlage zu verwenden.
Die erste Zeile in einer Hilfedatei sollte das folgende Format haben:
plugin_name.txt {short description of the plugin}
Das erste Feld ist ein Hilfe-Tag, wohin ":help plugin_name" geht. Der Rest
der Zeile nach einem Tabulator beschreibt den Zweck der Erweiterung auf eine
kurze Weise. Dies erscheint im Abschnitt "LOCAL ADDITIONS" der
Haupthilfedatei. Prüfen Sie, dass sie dort korrekt erscheint:
local-additions.
Falls Sie eine Versionsnummer oder das Datum der letzten Änderung hinzufügen
wollen, setzen Sie diees rechtsbündig in die zweite Zeile.
Platzieren Sie am Ende der Hilfedatei eine Vim-Modeline, um die Optionen
'textwidth' und 'tabstop' und 'filetype' auf "help" zu setzen. Setzen Sie
niemals eine globale Option in solch einer Modeline, dies kann unerwünschte
Konsequenzen haben.
TAGS
Um ein Hilfe-Tag zu definieren, setzen Sie den Namen zwischen Sternchen
(*Tag-Name*). Der Tag-Name sollte unterschiedlich von allen Vim-Tag-Namen
sein und idealerweise mit dem Namen der Vim-Erweiterung beginnen. Der
Tag-Name ist für gewöhnlich rechtsbündig in einer Zeile.
Beim Verweisen auf ein bestehendes Hilfe-Tag und um eine Verknüpfung zu
erzeugen, setzen Sie den Namen zwischen zwei Balken (|),
z.B. help-writing.
Beim Verweisen auf einen Vim-Befehl und um eine Verknüpfung zu erzeugen,
setzen Sie den Namen zwischen zwei Accents Graves oder Backticks,
z.B. :filetype. Sie sehen, dass dies als Befehl hervorgehoben wird, wie
ein Codeblock (siehe nachfolgend).
Beim Verweisen auf eine Vim-Option in der Hilfedatei, stellen Sie den Name
der Option zwischen zwei einfache Anführungszeichen ('), z.B. 'statusline'.
HERVORHEBUNG
Um eine Spaltenüberschrift zu definieren, verwenden Sie ein Tildezeichen am
Ende der Zeile. Dies hebt die Spaltenüberschrift in einer anderen Farbe
hervor. Z.B.:
Um Abschnitte in einer Hilfedatei zu trennen, platzieren Sie eine Folge von
'='-Zeichen beginnend von der ersten Spalte in einer Zeile. Die
Abschnitttrennzeile wird anders hervorgehoben.
Um einen Block von ex-Befehlen wörtlich zu zitieren, stellen Sie ein
größer-als-Zeichen (>) an das Ende der Zeile vor dem Block und ein
kleiner-als-Zeichen (<) als das erste nichtleere Zeichen auf einer dem Block
folgenden Zeile. Jede in Spalte eins beginnende Zeile beendet ebenfalls
implizit den Block von ex-Befehlen vor ihr. Z.B
function Example_Func()
echo "Example"
endfunction
Die folgenden werden in einer Vim-Hilfedatei unterschiedlich hervorgehoben:
- Der Name einer Sondertaste entweder in <>-Notation wie in <PageDown> oder
wie ein Steuerungszeichen wie in CTRL-X
- alles zwischen {geschweiften Klammern}, z.B. {lhs} und {rhs}
Die Wörter "Note", "Notes" und ähnliche erhalten automagisch auffällige
Hervorhebung. Und diese ebenfalls:
*Todo etwas zu erledigendes
*Error etwas falsches
Sie können die Einzelheiten in $VIMRUNTIME/syntax/help.vim finden.
GENDER-NEUTRALE SPRACHE
gender-neutral inclusion
Vim ist für jeden, ganz gleich der Rasse, des Geschlechts oder irgendwas.
Für neue oder aktualisierte Hilfetext wird gender-neutrale Sprache
empfohlen. Einiges an Hilfetext ist viele Jahre alt und es gibt keinen
Zwang ihn zu ändern. Wir machen keinerlei Annahmen über das Geschlecht der
anwendenden Person, ganz gleich wie der Text formuliert ist. Ziel ist dass
der Leser versteht wie Vim funktioniert, der genaue Wortlaut ist
zweitrangig.
Viele technische Online-Richtlinienführer enthalten Abschnitte über
gender-neutrale Sprache. Hier sind einige:
https://developers.google.com/style/pronouns
https://techwhirl.com/gender-neutral-technical-writing/
https://www.skillsyouneed.com/write/gender-neutral-language.html
https://ualr.edu/writingcenter/avoid-sexist-language/
Beachten Sie: gender-neutrale Sprache erfordert nicht das "they" in der
Einzahl.
vim:tw=78:ts=8:noet:ft=help:norl: