1 This is help2man-de.info.tmp, produced by makeinfo version 6.8 from
4 Diese Datei dokumentiert den GNU-Befehl ‘help2man’, der einfache
5 Handbuchseiten aus der Ausgabe von ‘--help’ und ‘--version’ anderer
8 Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2009, 2010,
9 2011, 2012, 2013, 2014, 2015, 2020, 2021 Free Software Foundation, Inc.
11 Es ist Ihnen gestattet, wortwörtliche Kopien dieses Handbuchs
12 anzufertigen und weiterzugeben, sofern der Urheberrechtshinweis und
13 dieser Lizenzhinweis in allen Kopien enthalten ist.
15 Es ist Ihnen gestattet, veränderte Kopien dieses Handbuchs
16 anzufertigen und unter den Bedingungen des wortwörtlichen Kopierens
17 weiterzugeben, sofern das gesamte sich ergebende Werk unter den
18 Bedingungen eines Lizenzhinweises steht, welche zu denen des
19 ursprünglichen Werkes identisch sind.
21 Es ist Ihnen gestattet, Übersetzungen dieses Handbuchs in eine andere
22 Sprache anzufertigen und unter den oben genannten Bedingungen für
23 veränderte Versionen weiterzugeben, mit der Ausnahme, dass dieser
24 Lizenzhinweis in einer von der Foundation genehmigten Version angegeben
26 INFO-DIR-SECTION Software-Entwicklung
28 * help2man-de: (help2man-de). Automatische Erstellung von
33 File: help2man-de.info.tmp, Node: Top, Next: Überblick, Up: (dir)
38 ‘help2man’ erzeugt einfache Handbuchseiten aus der Ausgabe von ‘--help’
39 und ‘--version’ anderer Befehle.
43 * Überblick:: Überblick über ‘help2man’.
44 * Aufruf von help2man:: Ausführen von ‘help2man’.
45 * Empfehlungen für --help:: Empfohlene Formatierung für die
47 * Einbeziehen von Text:: Verarbeitung von zusätzlichem Text in
49 * Verwendung in Makefiles:: Verwendung von ‘help2man’ mit‘make’.
50 * Lokalisierte Handbuchseiten:: Erstellen von Handbuchseiten
51 inverschiedenen Sprachen.
52 * Beispiel:: Beispiel für die Ausgabe
54 * Rückmeldungen:: Fehler melden oder Vorschläge
56 * Bezugsquellen:: ‘help2man’ beziehen.
59 File: help2man-de.info.tmp, Node: Überblick, Next: Aufruf von help2man, Prev: Top, Up: Top
61 1 Überblick über ‘help2man’
62 ***************************
64 ‘help2man’ ist ein Werkzeug zum automatischen Erzeugen einfacher
65 Handbuchseiten aus Programmausgaben.
67 Zwar sind Unix-Handbuchseiten optional für GNU-Programme, doch andere
68 Projekte, wie Debian, fordern sie (*note (standards)Man Pages::)
70 Dieses Programm will Software-Entwicklern eine einfache Möglichkeit
71 bereitstellen, eine Handbuchseite in ihren Veröffentlichungen
72 mitzuliefern, ohne das Dokument selbst pflegen zu müssen.
74 Aus einem Programm, das mit den Argumenten ‘--help’ und ‘--version’
75 standardkonforme Ausgaben erzeugt, kann ‘help2man’ diese Ausgaben so neu
76 arrangieren, dass eine Unix-Handbuchseite entsteht.
79 File: help2man-de.info.tmp, Node: Aufruf von help2man, Next: Empfehlungen für --help, Prev: Überblick, Up: Top
81 2 Ausführen von ‘help2man’
82 **************************
84 Das Format zur Ausführung von ‘help2man’ lautet:
86 help2man [OPTION]... AUSFÜHRBARE_DATEI
88 ‘help2man’ unterstützt die folgenden Optionen:
92 verwendet die ZEICHENKETTE als Kurzbeschreibung im ‘NAME’-Abschnitt
95 Per Vorgabe – in Ermangelung von etwas Besserem – enthält dieser
96 Abschnitt die Deklaration ‘manual page for PROGRAM VERSION’.
98 Diese Option übergeht eine einzubeziehende Datei ‘[Name]’ Abschnitt
99 (*note Einbeziehen von Text::).
102 ‘--section ABSCHNITT’
103 ABSCHNITT wird als Abschnittsbezeichnung der Handbuchseite
104 verwendet. Der vorgegebene Abschnitt ist 1.
108 setzt den Namen des Abschnitts der Handbuchsammlung auf ABSCHNITT,
109 welcher dann als zentrierte Überschrift der Handbuchseite verwendet
110 wird. Als Vorgabe wird ‘User Commands’ für Seiten in Abschnitt 1,
111 ‘Games’ für Abschnitt 6 und ‘System Administration Utilities’ für
112 die Abschnitte 8 und 1M verwendet.
116 Die Programmquelle wird als Fußzeile der Seite verwendet und
117 enthält außerdem oft den Namen der Organisation oder der
118 Programmsammlung, zu der das Programm gehört. Als Vorgaben werden
119 hier der Name des Pakets und die Versionsnummer verwendet.
121 ‘-L SPRACHEINSTELLUNG’
122 ‘--locale=SPRACHEINSTELLUNG’
123 Wählt die Spracheinstellung für die Ausgabe (Vorgabe ist ‘C’).
124 Sowohl das Programm als auch ‘help2man’ müssen die gewählte
125 Spracheinstellung unterstützen (*note Lokalisierte
130 Bezieht Material aus DATEI ein (*note Einbeziehen von Text::).
133 ‘--opt-include=DATEI’
134 Eine Variante von ‘--include’ zur Verwendung in Makefile-Regeln,
135 die die Existenz der DATEI nicht zwingend voraussetzt.
139 Die Ausgabe wird in die DATEI geschrieben, anstatt sie in die
140 Standardausgabe (‘stdout’) zu schreiben.
144 Name des Texinfo-Handbuchs.
148 Der ‘SEE ALSO’-Abschnitt, der den Leser auf ein Texinfo-Handbuch
149 verweist, wird unterdrückt.
153 Entfernt das ‘lt-’-Präfix aus den Instanzen des Programmnamens in
154 der Synopsis (der Befehl ‘libtool’ erstellt Wrapper-Skripte im
155 Build-Verzeichnis, die den Befehl ‘foo’ als ‘.libs/lt-foo’
160 Zeigt die Hilfe oder Versionsinformationen an.
162 Per Vorgabe übergibt ‘help2man’ die Standardoptionen ‘--help’ und
163 ‘--version’ an die ausführbare Datei. Alternativen können wie folgt
167 ‘--help-option=OPTION’
168 Zeichenkette für die Hilfe-Option.
171 ‘--version-option=OPTION’
172 Zeichenkette für die Versionsausgabe.
174 ‘--version-string=ZEICHENKETTE’
175 Versions-Zeichenkette.
177 ‘--no-discard-stderr’
178 Dies bezieht die an die Standardfehlerausgabe (stderr) geleiteten
179 Ausgaben beim Einlesen der Optionen ein.
182 File: help2man-de.info.tmp, Node: Empfehlungen für --help, Next: Einbeziehen von Text, Prev: Aufruf von help2man, Up: Top
184 3 Empfehlungen für ‘--help’
185 ***************************
187 Nachfolgend finden Sie Empfehlungen dafür, was in der Ausgabe der Option
188 ‘--help’ Ihres Programms enthalten sein sollte. Wenn Sie diesen
189 Empfehlungen folgen, hat ‘help2man’ bessere Chancen, eine respektable
190 Handbuchseite zu erzeugen, was wiederum den Benutzern zugute kommt.
192 Siehe *Note (standards)Command-Line Interfaces:: und *note
193 (standards)Man Pages:: für die offiziellen GNU-Standards bezüglich der
194 Option ‘--help’ und Handbuchseiten.
196 • Ein Überblick darüber, wie das Programm aufgerufen werden kann.
197 Falls unterschiedliche Anwendungsfälle unterschiedliche Aufrufe
198 erfordern, dann listen Sie diese alle auf. Beispiel (gekürzt):
200 Usage: cp [OPTION]... SOURCE DEST
201 or: cp [OPTION]... SOURCE... DIRECTORY
204 Verwenden Sie ‘argv[0]’ für den Programmnamen in diesen
205 Übersichten, so wie es ist, ohne Entfernen der Pfadkomponenten.
206 Dies steht im Gegensatz zum kanonischen (konstanten) Namen des
207 Programms, wie er in ‘--version’ verwendet wird.
209 • Eine sehr knappe Erklärung der Funktion des Programms,
210 einschließlich Vorgabe- oder typisches Verhalten. Hier als
213 Copy SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY.
215 • Eine Liste von Optionen, die in Spalte 2 eingerückt wird. Falls
216 das Programm aus einem einzelnen Zeichen bestehende Kurzoptionen
217 unterstützt, führen Sie diese zuerst auf, gefolgt von den
218 entsprechenden Langoptionen (falls vorhanden). Wenn die Option ein
219 Argument akzeptiert, fügen Sie dieses hinzu und geben ihm einen
220 aussagekräftigen Namen. Ordnen Sie die Beschreibungen in einer
221 übersichtlichen Spalte an, falls gewünscht. Damit ‘help2man’ die
222 Beschreibungen korrekt erkennen kann, müssen diese durch mindestens
223 zwei Leerzeichen von den Optionen getrennt werden. Die
224 Fortsetzungen in weiteren Zeilen müssen an der gleichen
225 Zeichenposition (in der gleichen Spalte) wie in der ersten Zeile
228 Nachfolgend ein (bearbeiteter) Auszug aus ‘cp’, der eine Kurzoption
229 mit der entsprechenden Langoption, eine Nur-Langoption und eine
230 Nur-Kurzoption zeigt:
232 -a, --archive same as -dpR
233 --backup[=CONTROL] make a backup of each ...
234 -b like --backup but ...
236 Falls Ihr Programm zahlreiche Optionen akzeptiert, ist es
237 wünschenswert, die Optionsliste in Abschnitte wie ‘Global’, ‘Output
238 control’ oder was auch immer für den Einzelfall sinnvoll erscheint,
239 zu gliedern. Praktischerweise sollten die Optionen innerhalb der
240 Abschnitte alphabetisch geordnet werden (zuerst nach den Namen der
241 Kurz-, dann der Langoptionen) oder auch innerhalb der Gesamtliste,
242 wenn keine Abschnitte vorgesehen sind.
244 • Zusätzliche Informationen zum Verhalten des Programms, zum Beispiel
245 anwendbare Umgebungsvariablen, weitere Erklärungen der Optionen
246 usw. Für das Programm ‘cp’ wären das etwa die Umgebungsvariable
247 ‘VERSION_CONTROL’ und Erklärungen zur Behandlung von
250 • Ein oder mehrere Beispiele zur üblichen Anwendung, nach Ihrem
251 Ermessen. Ein gutes Beispiel erspart Ihnen tausend beschreibende
252 Worte, daher ist dies ausdrücklich zu empfehlen.
254 • Abschließend eine Zeile, die eine E-Mail-Adresse zum Melden von
255 Fehlern enthält. Typischerweise hat diese E-MAIL-ADRESSE die Form
256 ‘bug-PROGRAMM@gnu.org’. Verwenden Sie diese Form, wo immer es
257 möglich ist. Es ist außerdem sinnvoll, die Adresse der Homepage
258 des Programms, andere Mailinglisten u.a. zu erwähnen.
260 In den Programmierschnittstellen ‘argp’ und ‘popt’ können Sie
261 Optionsbeschreibungen für ‘--help’ in der gleichen Struktur angeben wie
262 für den Rest der Optionsdefinition. Ziehen Sie in Erwägung, diese
263 Routinen für das Parsen von Optionen anstelle von ‘getopt’ zu verwenden.
265 Standardmäßig versucht ‘help2man’ mittels heuristischer Analysen die
266 entsprechenden Abschnitte der Handbuchseite zu ermitteln. Wenn eine
267 Zeile ‘Options:’ enthält, wird der darauf folgende Text dem Abschnitt
268 ‘OPTIONS’ zugeordnet, auf die gleiche Weise wird eine Zeile, die mit
269 ‘Copyright’ beginnt, im Abschnitt ‘COPYRIGHT’ verarbeitet. Außerdem
270 beginnt mit einer Zeile, die ‘*Wörter*’ enthält, ein neuer Abschnitt,
271 und mit ‘Wörter:’ ein neuer Unterabschnitt.
274 File: help2man-de.info.tmp, Node: Einbeziehen von Text, Next: Verwendung in Makefiles, Prev: Empfehlungen für --help, Up: Top
276 4 Verarbeitung von zusätzlichem Text in der Ausgabe
277 ***************************************************
279 Zusätzlicher statischer Text kann mit den Optionen ‘--include’ und
280 ‘--opt-include’ in die erzeugte Handbuchseite einbezogen werden (*note
281 Aufruf von help2man::). Zwar sind die Namen dieser Dateien frei
282 wählbar, jedoch sollten sie aus Konsistenzgründen die Endung ‘.h2m’ (für
283 Include-Dateien für ‘help2man’) erhalten.
285 Das Format der mit dieser Option einzubeziehenden Dateien ist simpel:
293 Blöcke aus wörtlichem *roff-Text werden entweder beim Start durch
294 Angabe von ‘[Abschnitt]’ (unabhängig von Groß-/Kleinschreibung) in die
295 Ausgabe eingefügt oder nach einem passenden Absatz-‘/Muster/’.
297 Die Muster benutzen reguläre Ausdrücke in Perl-Syntax, auf die die
298 Modifikatoren ‘i’, ‘s’ oder ‘m’ folgen können (*note perlre(1):
299 (*manpages*)perlre.).
301 Zeilen vor dem ersten Abschnitt oder Muster, die mit ‘-’ beginnen,
302 werden als Optionen verarbeitet. Alles andere wird stillschweigend
303 ignoriert und kann für Kommentare, RCS-Schlüsselwörter und ähnliches
306 Die Abschnitte werden (sofern vorhanden) in dieser Reihenfolge
322 Alle in der Include-Datei aufgeführten ‘[name]’- oder
323 ‘[synopsis]’-Abschnitte ersetzen jene, die automatisch generiert werden.
324 Sie können jedoch dieses Verhalten bei Bedarf außer Kraft setzen,
325 beispielsweise mit der Option ‘--name’.
327 Andere Abschnitte werden der automatisch erzeugten Ausgabe für die
328 oben angegebenen Standardabschnitte vorangestellt oder unter _other_
329 (oben) in der Reihenfolge, in der sie in der eingefügten Datei
330 vorgefunden werden, eingefügt.
332 Die Textplatzierung innerhalb des Abschnitts kann mit der Syntax
333 ‘[<Abschnitt]’, ‘[=Abschnitt]’ oder ‘[>Abschnitt]’ explizit angegeben
334 werden. Diese Angaben beziehen sich auf die Platzierung vor, die
335 Ersetzung durch beziehungsweise die Platzierung nach dem standardmäßig
339 File: help2man-de.info.tmp, Node: Verwendung in Makefiles, Next: Lokalisierte Handbuchseiten, Prev: Einbeziehen von Text, Up: Top
341 5 Verwendung von ‘help2man’ mit ‘make’
342 **************************************
344 Eine empfehlenswerte Vorgehensweise für die Verwendung von ‘help2man’ in
345 Makefiles ist es, die Handbuchseite nicht aus der Binärdatei, sondern
346 aus den Inhalten der Quelldateien zu erzeugen, in denen die Ausgaben von
347 ‘--help’ und ‘--version’ definiert sind.
349 Dieser Weg ermöglicht es, dass die Handbuchseite von den
350 Projektbetreuern erzeugt und in die Veröffentlichungen integriert wird,
351 ohne dass ‘help2man’ auf dem System des Endnutzers installiert sein
354 Beispiel für eine Regel für das fiktive Programm ‘prog’:
356 prog.1: $(srcdir)/main.c
357 -$(HELP2MAN) --output=$@ --name='an example program' ./prog
359 Der Wert von ‘HELP2MAN’ kann in ‘configure.in’ entweder
360 folgendermaßen festgelegt werden:
362 AM_MISSING_PROG(HELP2MAN, help2man)
364 für ‘automake’, oder etwa so:
366 AC_PATH_PROG(HELP2MAN, help2man, false // No help2man //)
368 für ‘autoconf’ allein.
371 File: help2man-de.info.tmp, Node: Lokalisierte Handbuchseiten, Next: Beispiel, Prev: Verwendung in Makefiles, Up: Top
373 6 Erstellen von Handbuchseiten in verschiedenen Sprachen
374 ********************************************************
376 Handbuchseiten können für jede Sprache erzeugt werden, für die sowohl
377 für das Programm selbst als auch für ‘help2man’ Übersetzungen verfügbar
378 sind. Verwenden Sie hierzu die Option ‘--locale’ (‘-L’).
380 help2man -L fr_FR@euro -o cp.fr.1 cp
382 Auf <http://translationproject.org/domain/help2man.html> finden Sie
383 die gegenwärtig von ‘help2man’ unterstützten Sprachen. In *note
384 Rückmeldungen:: ist beschrieben, wie Sie weitere Übersetzungen
387 6.1 Ändern des Ortes der Übersetzungskataloge
388 =============================================
390 Beim Erzeugen lokalisierter Handbuchseiten aus dem Build-Verzeichnis
391 eines Programms ist es sehr wahrscheinlich, dass die in den
392 Standardpfaden installierten Übersetzungen (sofern diese überhaupt
393 installiert sind) für die Version des zu erstellenden Programms nicht
396 ‘help2man’ liefert eine vorladbare Bibliotheksdatei mit, die die
397 Aufrufe von ‘bindtextdomain’ abfängt. Der Ort der Meldungskataloge wird
398 dann über die Variable ‘$TEXTDOMAIN’ eingelesen und übergeht dabei den
399 durch ‘$LOCALEDIR’ bezeichneten Ort.
401 Beispielsweise können Sie mit
403 mkdir -p tmp/fr/LC_MESSAGES
404 cp po/fr.gmo tmp/fr/LC_MESSAGES/PROGRAMM.mo
405 LD_PRELOAD="/usr/lib/help2man/bindtextdomain.so" \
407 TEXTDOMAIN=PROGRAMM \
408 help2man -L fr_FR@euro -i PROGRAMM.fr.h2m -o PROGRAMM.fr.1 PROGRAMM
411 das PROGRAMM veranlassen, den Meldungskatalog aus ‘tmp’ und nicht wie
412 üblich aus ‘/usr/share/locale’ einzulesen.
415 • Die Verallgemeinerung von ‘fr_FR@euro’ zu ‘fr’ im obigen Beispiel
416 wird durch ‘gettext’ vorgenommen. Falls eine spezifischere
417 Spracheinstellung verfügbar ist, wird diese zugeordnet.
419 • Dieser Preload wurde lediglich mit ‘eglibc’ 2.11.2 und ‘gettext’
420 0.18.1.1 auf einem GNU/Linux-System getestet. Bitte melden Sie es,
421 wenn es für Ihre Zwecke funktioniert, oder auch nicht (*note
425 File: help2man-de.info.tmp, Node: Beispiel, Next: Rückmeldungen, Prev: Lokalisierte Handbuchseiten, Up: Top
427 7 Beispielausgabe von ‘help2man’
428 ********************************
430 Nehmen wir an, ein fiktives Programm ‘foo’ erzeugt die folgenden
436 Copyright (C) 2011 Free Software Foundation, Inc.
437 This is free software; see the source for copying conditions. There is NO
438 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
440 Written by A. Programmer.
442 GNU `foo' does nothing interesting except serve as an example for
445 Usage: foo [OPTION]...
448 -a, --option an option
449 -b, --another-option[=VALUE]
452 --help display this help and exit
453 --version output version information and exit
457 foo --option the same thing, giving `--option'
459 Report bugs to <bug-gnu-utils@gnu.org>.
461 ‘help2man’ erstellt den ‘nroff’-Quelltext für eine Handbuchseite, die
462 etwa folgendermaßen formatiert wird:
464 FOO(1) User Commands FOO(1)
467 foo - manual page for foo 1.1
473 GNU `foo' does nothing interesting except serve as an example for
480 -b, --another-option[=VALUE]
483 --help display this help and exit
486 output version information and exit
492 the same thing, giving `--option'
495 Written by A. Programmer.
498 Report bugs to <bug-gnu-utils@gnu.org>.
501 Copyright © 2011 Free Software Foundation, Inc.
502 This is free software; see the source for copying conditions.
503 There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
507 The full documentation for foo is maintained as a Texinfo manual.
508 If the info and foo programs are properly installed at your site,
513 should give you access to the complete manual.
515 foo 1.1 May 2011 FOO(1)
518 File: help2man-de.info.tmp, Node: Rückmeldungen, Next: Bezugsquellen, Prev: Beispiel, Up: Top
520 8 Fehler melden oder Vorschläge einbringen
521 ******************************************
523 Falls Sie auf Probleme stoßen oder Vorschläge zum Programm oder zu
524 diesem Handbuch haben, melden Sie dies bitte an <bug-help2man@gnu.org>.
526 Hinweis an Übersetzer: Die Übersetzungen werden beim Translation
527 Project (http://translationproject.org/) betreut. Auf
528 <http://translationproject.org/html/translators.html> finden Sie Details
532 File: help2man-de.info.tmp, Node: Bezugsquellen, Prev: Rückmeldungen, Up: Top
534 9 ‘help2man’ beziehen
535 *********************
537 Die neueste Version dieses Programms kann online von den
538 GNU-Spiegelservern bezogen werden:
540 <http://ftpmirror.gnu.org/help2man/>
542 Sollte die automatische Weiterleitung fehlschlagen, finden Sie die
543 Liste der Spiegelserver hier:
545 <http://www.gnu.org/order/ftp.html>
547 Eventuell können Sie den FTP-Hauptserver des GNU-Projekts nutzen:
548 <http://ftp.gnu.org/gnu/help2man/>
553 Node: Überblick
\7f2404
554 Node: Aufruf von help2man
\7f3217
555 Node: Empfehlungen für --help
\7f6649
556 Node: Einbeziehen von Text
\7f11390
557 Node: Verwendung in Makefiles
\7f13768
558 Node: Lokalisierte Handbuchseiten
\7f14928
559 Node: Beispiel
\7f17221
560 Node: Rückmeldungen
\7f19885
561 Node: Bezugsquellen
\7f20424