Befehlssynopsen (cmdsynopsis)

(Auszug aus "DocBook-XML: Medienneutrales und plattformunabhängiges Publizieren" von Thomas Schraitle)

Um die Syntax eines Befehls auszuzeichnen, gibt es das Element cmdsynopsis. Dieses können Sie innerhalb einer Manpage einsetzen.

Um die Befehlssyntax darzustellen, werden folgende Elemente benötigt: command für den zu beschreibenden Befehl, arg für die Argumente, group für Gruppierungen und <sbr/> für einen expliziten Zeilenumbruch.

Beispiel: Anwenden von cmdsynopsis

<cmdsynopsis>
  <command>touch</command>
  <arg choice="opt" rep="repeat">OPTION</arg>
  <arg choice="plain" rep="repeat"><replaceable>DATEI</replaceable></arg>
</cmdsynopsis>

touch [OPTION...] DATEI ...

Zeile 2: Der zu beschreibende Befehl.
Zeile 3: Ein optionales, wiederholbares Argument. Die Wiederholung wird mit rep angegeben.
Zeile 4: Ein "normales" Argument mit einem Platzhalter.

Kompliziertere Beispiele werden mit arg erzeugt:

Beispiel: Verschachtelungen mit arg

<cmdsynopsis>
   <command>scp</command>
   <arg>OPTIONS</arg>
   <arg choice="opt">
   <arg choice="opt">user@</arg>
   <arg choice="plain">host1:</arg>
   <arg choice="plain">file1</arg>
   <arg rep="repeat"/>
</cmdsynopsis>

scp [OPTIONS] [ [user@] host1: ] file1 [...]

Falls die Optionen zu lang werden, ermöglicht <sbr/> einen Zeilenumbruch an der gewünschten Stelle:

Beispiel: Zeilenumbruch mit <sbr/>

<cmdsynopsis>    
   <command>ssh</command>   
   <arg>-b <option>bind_address</option></arg>    
   <sbr/>    
   <arg>-S <option>ctl_path</option></arg>   
</cmdsynopsis>

ssh [-b bind_address]
[-S ctl_path]

Durch group lassen sich Optionen zusammenfassen:

Beispiel: Gruppieren von Optionen mit group

<cmdsynopsis>    
  <command>chgrp</command>    
  <arg>-R       
    <group>            
      <arg>-H</arg>          
      <arg>-L</arg>          
      <arg>-P</arg>            
    </group>        
  </arg>   
</cmdsynopsis>

chgrp [-R [[-H] | [-L] | [-P]] ]

Falls die Anzahl der Optionen zuviel werden, ist es praktisch hierfür das Element synopfragment zu verwenden und mittels synopfragmentref darauf zu verweisen:

Beispiel: Optionen aufspalten mit synopfragment

<cmdsynopsis>
    <command>convert</command>
    <arg choice="plain"><replaceable>input-file</replaceable></arg> 
    <group> 
       <synopfragmentref linkend="syn.convert.options">OPTIONS</synopfragmentref>
    </group>
    <arg choice="plain"><replaceable>output-file</replaceable></arg>
    <synopfragment ANKER="syn.convert.options">
       <arg>-antialias</arg>
       <arg>-border <replaceable>geometry</replaceable></arg>
       <arg>-clip</arg>
       <arg>-colorspace</arg>
    </synopfragment>
</cmdsynopsis>

Ersetzen Sie den Platzhalter ANKER durch id in DocBook 4 und xml:id in DocBook 5.

convert input-file [(1) OPTIONS] output-file
(1) [-antialias] [-border geometry] [-clip] [-colorspace]

  

<< zurück vor >>
Tipp der data2type-Redaktion:
Zum Thema DocBook bieten wir auch folgende Schulungen zur Vertiefung und professionellen Fortbildung an:

Copyright © 2009 Millin Verlag
Für Ihren privaten Gebrauch dürfen Sie die Online-Version ausdrucken.
Ansonsten unterliegt dieses Kapitel aus dem Buch "DocBook-XML: Medienneutrales und plattformunabhängiges Publizieren" denselben Bestimmungen, wie die gebundene Ausgabe: Das Werk einschließlich aller seiner Teile ist urheberrechtlich geschützt. Alle Rechte vorbehalten einschließlich der Vervielfältigung, Übersetzung, Mikroverfilmung sowie Einspeicherung und Verarbeitung in elektronischen Systemen.

Millin Verlag, Siebengebirgsring 36, 53797 Lohmar, info(at)millin.de