Difference between revisions of "Documentation Primer/Manual/DocBook Reference/Synopsis"

Latest revision as of 11:37, 9 September 2012

Other languages:

English

[edit] The synopsis elements

<cmdsynopsis>

Example: How to markup a command synopsis

<cmdsynopsis>
<command>more</command>
<group choice="opt"><option>-d</option>
<option>l</option><option>f</option>
<option>p</option><option>c</option>
<option>s</option><option>u</option>
</group>
<arg>-num</arg>
<arg>+/ pattern</arg>
<arg>+ linenum</arg>
<arg rep="repeat"><replaceable>file</replaceable></arg>
</cmdsynopsis>

This should generate:

more [-dlfpcsu][-num][+/ pattern][+ linenum][file]

There are several very nice examples in the Duck book at www.docbook.org <funcsynopsis>

Example: How to markup a function synopsis

<funcsynopsis>
<funcprototype>
<funcdef>void <function>setFile</function></funcdef>
<paramdef>QString <parameter>file</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<funcsynopsis>
<funcprototype>
<funcdef>void <function>setAutoResize</function></funcdef>
<paramdef>bool <parameter><replaceable>val</replaceable></parameter></paramdef>
</funcprototype>
</funcsynopsis>

<funcsynopsis>
<funcprototype>
<funcdef>QString <function>getVideoCodec</function></funcdef><void/>
</funcprototype>
</funcsynopsis>

These would generate the following, respectively.

void setFile(file);
QString file;

void setAutoResize(val);
bool val;

QString getVideoCodec();

A function synopsis can contain the following:

<funcprototype>

Contains a prototype of the function. It can contain <void>, <varargs>, <paramdef> or most commonly, a <funcdef> which actually defines the function.

<funcdef>

A function and it's return type.

<funcparams>

Contains the list of parameters for the function.

<paramdef>

Information about the parameters of a function.

<void>

An empty element in a function indicating there are no arguments.

<varargs>

An empty element in a function indicating there are multiple arguments, without specifically listing them. This is generally represented with an ellipsis (...). For example int max(...);

<funcsynopsisinfo>

Not used in KDE documentation.

<arg>

Used inside <cmdsynopsis>. Since most KDE applications are &GUI; only, you won't see this very often. See the entry for <cmdsynopsis> for a full explanation and example.

<group>

Group

<sbr>

sbr

<synopfragment>

synopfragment

<modifier>

A modifier modifies a class, field, or method synopsis. Examples are the words "public", "private" or "virtual"

<fieldsynopsis>

A field synopsis.

• ← Admonitions - Tips, hints, and Warnings
• ↑ Back to Menu ↑
• Markup for programming →