Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

--- tachtler:asciidoc_tor [2019/09/04 11:31] – klaus
+++ tachtler:asciidoc_tor [2019/09/04 12:41] (aktuell) – [Asciidoc(tor)] klaus
@@ Zeile 1: / Zeile 1: @@
 ====== Asciidoc(tor) ======
-[[https://asciidoctor.org/|{{:tachtler:index:asciidoctor-48x48.png }}]] [[https://asciidoctor.org/|Asciidoctor]] ist eine schnelle, quelloffene Textverarbeitungs- und Publikationswerkzeugkette zur Konvertierung von AsciiDoc-Inhalten in **HTML5**, **DocBook**, **PDF**, **''man''-Pages** und andere Formate. [[https://asciidoctor.org/|Asciidoctor]] ist in Rubin geschrieben und läuft auf allen gängigen Betriebssystemen. Das [[https://asciidoctor.org/|Asciidoctor]]-Projekt wird auf [[https://github.com/asciidoctor/asciidoctor|GitHub - Asciidoctor]] gehostet.
+[[https://asciidoctor.org/|{{:tachtler:index:asciidoctor-48x48.png }}]] [[https://asciidoctor.org/|Asciidoctor]] ist eine schnelle, quelloffene Textverarbeitungs- und Publikationswerkzeugkette zur Konvertierung von AsciiDoc-Inhalten in **HTML5**, **DocBook**, **PDF**, **''man''-Pages** und andere Formate. [[https://asciidoctor.org/|Asciidoctor]] ist in [[https://www.ruby-lang.org/de/|Ruby]] geschrieben und läuft auf allen gängigen Betriebssystemen. Das [[https://asciidoctor.org/|Asciidoctor]]-Projekt wird auf [[https://github.com/asciidoctor/asciidoctor|GitHub - Asciidoctor]] gehostet.
 ^ Beschreibung      ^ Externer Link                                                                          ^
@@ Zeile 386: / Zeile 386: @@
 Eine der spezielleren Anwendungen von **AsciiDoc** ist es, als Abkürzung für die Generierung von **''man''-Pages** (kurz für Manual Pages) für Unix und Unix-ähnliche Betriebssysteme zu dienen.
-Eine **''man''-Page** ist in der Roff-Satzsprache kodiert. Durch die Einhaltung einer bestimmten Struktur in der **''man''-Page** Quellcode-Datei kann der **''man**''-Befehl** den Inhalt analysieren und ein formatiertes Dokument in einem textuellen (Befehlszeilen-)Seitendarstellung präsentieren. Die **''man''-Page**-Seiten bieten einen einheitlichen Hilfskatalog für alle Befehle im System. Eine vollständige Beschreibung finden Sie auf der Roff-Manualseite (oder über die Befehle ''man roff'' oder ''man 7 man'' ein).
+Eine **''man''-Page** ist in der Roff-Satzsprache kodiert. Durch die Einhaltung einer bestimmten Struktur in der **''man''-Page** Quellcode-Datei kann der **''man''-Befehl** den Inhalt analysieren und ein formatiertes Dokument in einem textuellen (Befehlszeilen-)Seitendarstellung präsentieren. Die **''man''-Page**-Seiten bieten einen einheitlichen Hilfskatalog für alle Befehle im System. Eine vollständige Beschreibung finden Sie auf der Roff-Manualseite (oder über die Befehle ''man roff'' oder ''man 7 man'' ein).
 [[https://asciidoctor.org/|Asciidoctor]] kann **roff-formatierte** **''man''-Pages** erzeugen, wenn die Struktur des **AsciiDoc-Dokuments** mit der **Manpage-Doctype-Struktur übereinstimmt**.
@@ Zeile 395: / Zeile 395: @@
 </code>
-:!: **HINWEIS** - **Der ''man''-Page Converter setzt den Namen der Ausgabedatei auf ''progname.1'', wobei __progname__ der __Name des Befehls und 1 die Volumennummer ist__, wie durch den Doctitle des Quelldokuments definiert wurde.
+:!: **HINWEIS** - **Der ''man''-Page Converter setzt den Namen der Ausgabedatei auf ''progname.1'', wobei __progname__ der __Name des Befehls und 1 die Volumennummer ist__, wie durch den Doctitle des Quelldokuments definiert wurde.**
 Bei der Konvertierung in das ''man''-Page-Format werden die Titel aller Level-0- und Level-1-Abschnitte von [[https://asciidoctor.org/|Asciidoctor]] in Großbuchstaben geschrieben. Dadurch wird die Eingabe von Abschnittsüberschriften in Großbuchstaben erspart. Es macht das Dokument auch auf andere Ausgabeformate portierbar, da dieser Stil nur in der Ausgabe der Manualseite benötigt wird, um den Konventionen zu entsprechen.
@@ Zeile 405: / Zeile 405: @@
 # asciidoctor source.adoc
 </code>
-Nachfolgend eine exemplarische ''man''-Page, die in **AsciiDoc** für den exemplarischen Befehl ''test'' erstellt werden soll und als Vorlage dienen kann:
+Nachfolgend eine ''man''-Page **Vorlage**, die in **AsciiDoc** für den exemplarischen Befehl ''test'' erstellt werden soll:
 <code>
+= test(1)
+Vorname Nachname
+v1.0.0
+:doctype: manpage
+:manmanual: TEST
+:mansource: TEST
+:man-linkstyle: pass:[blue R < >]
+== Name
+test - description of the command
+== Synopsis
+*test* [_OPTION_]... _FILE_...
+== Options
+*-o, --out-file*=_OUT_FILE_::
+  Write result to file _OUT_FILE_.
+== Exit status
+*0*::
+  Success.
+  Execution was successful.
+*1*::
+  Failure.
+  Execution was NOT successful.
+== Resources
+*Project web site:* http://www.tachtler.net
+== Copying
+Copyright (C) 2008 {author}. +
+Free use of this software is granted under the terms of the MIT License.
 </code>
+Der **''man''-Page-Doctype** hat die folgenden **__erforderlichen__** Teile:
+=== Dokumenten Kopf (Document Header) ===
+Ein **''man''-Page-Dokumentenkopf** ist obligatorisch. Die Titelzeile enthält den Namen der Manual-Seite, gefolgt von der manuellen Abschnittsnummer in runden Klammern. Der Titelname sollte keine Leerzeichen enthalten. Die manuelle Abschnittsnummer ist eine einzelne Ziffer, optional gefolgt von einem einzelnen Zeichen.
+=== Der Abschnitt NAME (NAME Section) ===
+Der erste Abschnitt der Manual-Seite ist obligatorisch, muss den Titel "NAME" tragen und einen einzelnen Absatz (in der Regel eine einzige Zeile) enthalten, der aus einer Liste von einem oder mehreren Komma getrennten Befehlsnamen besteht, die durch ein Strichzeichen vom Befehlszweck getrennt sind. Der Bindestrich muss auf beiden Seiten mindestens ein Leerzeichen aufweisen.
+=== Die Sektion SYNOPSIS (SYNOPSIS Section) ===
+Der zweite Abschnitt der ''man''-Page ist obligatorisch und muss den Titel "SYNOPSIS" tragen.
+Die nachfolgenden Abschnitte sind optional, aber typische Abschnitte sind
+  * "SEE ALSO"
+  * "BUGS REPORTS"
+  * "AUTHORS"
+  * "COPYRIGHT"
+Es gibt mehrere eingebaute Dokumentattribute, die nur ''man''-Pages betreffen. Wenn sie verwendet werden, müssen sie im Dokumenten Kopf (Document Header) gesetzt werden.
+^ Attribute Name    ^ Beschreibung                                                ^ Beispielwert             ^
+| ''mantitle''      | Alternative Möglichkeit, den Namen der Manpage festzulegen. | ''TEST(1)''              |
+| ''manvolnum''     | Nummer de ''man''-Page Sektion ("SECTION")                  | ''1''                    |
+| ''manname''       | Alternative Möglichkeit, den Befehlsnamen festzulegen.      | ''test''                 |
+| ''manpurpose''    | Alternative Möglichkeit, den Zweck des Befehls festzulegen. | ''Befehlsbeschreibung''  |
+| ''man-linkstyle'' | Style der Links in der ''man''-Page-Ausgabe.\\ Eine gültige Link-Formatsequenz.  | ''blue R <>'' |
+| ''mansource''     | Die Quelle, auf die sich die Manual-Seite bezieht. Bei der Erstellung von **DocBook** wird es zu einem **DocBook ''refmiscinfo''-Attribut** und erscheint in der Fußzeile. | ''Test''  |
+| ''manversion''    | Die Version der ''man''-Page. Standardmäßig wird die ''revnumber'' verwendet, wenn nichts angegeben ist. Bei der Erstellung von **DocBook** wird es zu einem **DocBook ''refmiscinfo''-Attribut** und erscheint in der Fußzeile. Wird von [[https://asciidoctor.org/|Asciidoctor]] nicht verwendet. | ''1.0.0''  |
+| ''manmanual''     | Manueller Name. Bei der Erstellung von **DocBook** wird es zu einem **DocBook ''refmiscinfo''-Attribut** und erscheint in der Fußzeile. | ''Test Manual'' |
+Ein vollständiges Beispiel befindet sich unter [[https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/man/asciidoctor.adoc|AsciiDoc-Quelltext]] der ''man''-Page [[https://asciidoctor.org/|Asciidoctor]]. Die ''man''-Page für [[https://asciidoctor.org/|Asciidoctor]] wird mit dem in [[https://asciidoctor.org/|Asciidoctor]] integrierten ''man''-Page Konverter erzeugt.