events
news
The Linux Foundation
 
 
WrittenSpecificationStyle

From The Linux Foundation

Contents

Written Specification Style Guide

This document contains:

  • Synopsis markup in SGML
- examples for command markup
- examples for function markup
  • Common LSB usages
- notes on man page text development
- tags to be phased into general use prior to LSB v2.0
- corrections to tags now in general use
- often-used spec phrases

This document:

  • is based on DocBook 4.2 markup principles and examples as illustrated in official DocBook documentation:
- "!DocBook - The Definitive Guide" by N.Walsh & L.Muellner (O'Reilly)
- [1]
  • is the start of a formal style guide for LSB content contributors
  • will be used for updates to existing specification texts
  • may be used for development of new content
  • is a work-in-progress and will be updated as needed to reflect current text development goals

Some of the document is aimed at being legal for !DocBook-XML. If we decide to do this more consistently, the following are all issues:

  • quotes around attributes, e.g. <arg choice="plain"> not <arg choice=plain>
  • all element, attribute, and entity names must be in lowercase
  • Trailing slashes for empty elements, for example <xref /> not <xref> (See Chapter 2 of the DocBook book; Appendix B also might help but isn't as clear on the case sensitivity point). NOTE --- the current docbook utils do not correctly handle <xref />, so don't use it!

Question: what does the <DATE> tag mean (in <REFSYNOPSISDIVINFO>, <REFSECT1INFO>, and so on)? Is it the date that particular page was last modified (in which case we have a lot of habits to change if we want this to get done manually)? Do we really want these <DATE> tags (I suspect not)?


General comment on what is marked up and why:

In addition to the obvious, like displaying italics/typewriter/etc with some sort of usefulness, markup is intended for being used in an index (most obviously, things like <command> and <function>). The following sections give specifics on things which are marked up. Some things which treated as ordinary text (that is, not marked up or spelled differently from customary English usage) are:

  • Names of characters (e.g. space, colon, etc).
  • Zero, one and other really common numbers. More obscure data values (such as +131071 in adjtimex) can optionally be marked up as <literal> for indexing.

In general, all markup should contain meta-information about what is being marked up and why. There is a difference between, for exmple, <emphasis>avail_in</emphasis>, <varname>avail_in</varname>, <structfield>avail_in</structfield> and <parameter>avail_in</parameter>, even though all (might) have the exact same appearance in the rendered text page. NEVER use <emphasis> tags unless all you are doing is stressing a word.

SYNOPSIS MARKUP IN SGML

The following <CMDSYNOPSIS> and <FUNCSYNOPSIS> tag structures

  • replace* the <SYNOPSIS> structures in older LSB specifications.

CMDSYNOPSIS EXAMPLE

A command (fictional) requiring:

  • standard argument
  • argument with input
  • nested arguments
  • mutually exclusive arguments
  • required bracketed argument
  • required unbracketed argument
  • required unbracketed repeating argument

Desired effect

abc [-d] [-e file] [month [year]] [-f | -g] {directory} group file...

Syntax 

<CMDSYNOPSIS>
: <COMMAND>abc</COMMAND>
: <ARG>-d</ARG>
: <ARG>-e <REPLACEABLE>file</REPLACEABLE></ARG>
: <ARG>month <ARG>year</ARG></ARG>
: <GROUP>
: <ARG>-f</ARG>
: <ARG>-g</ARG>
: </GROUP>
: <ARG CHOICE=REQ><REPLACEABLE>directory</REPLACEABLE></ARG>
: <ARG CHOICE=PLAIN><REPLACEABLE>group</REPLACEABLE></ARG>
: <ARG REP=REPEAT CHOICE=PLAIN><REPLACEABLE>file</REPLACEABLE></ARG>
</CMDSYNOPSIS>

Notes The use of <replaceable> tags is actually optional, and may be phased out. In a <cmdsynopsis>, an <arg> is always replaceable, and will always be rendered consistently. Adding <replaceable> actually ends up obscuring information.

---

FUNCTION SYNOPSIS EXAMPLE

Function requiring header file

Desired effect

int abc(int arg1);

Syntax 

<FUNCSYNOPSIS>
<FUNCSYNOPSISINFO>
</FUNCSYNOPSISINFO>
: <FUNCPROTOTYPE>
: <FUNCDEF>int
: <FUNCTION>abc</FUNCTION></FUNCDEF>
: <PARAMDEF>int
: <PARAMETER><REPLACEABLE>arg1</REPLACEABLE></PARAMETER></PARAMDEF>
: </FUNCPROTOTYPE>
</FUNCSYNOPSIS>

Notes

  • The target of this illustration is in the text:
#include <xyz.h>
  • The <funcsynopsis> (in fact the entire <refsynopsisdiv> section) can be generated from the database using the 
    mksynop
    perl script. Since the database does not contain argument names, mksynop invents names "arg0", "arg1" etc, and these will need subsequent editing.

---

SYNOPSIS EXAMPLE - Function requiring absolute arguments only

Desired effect

int abc(int arg1, int arg2);

Syntax 

<FUNCSYNOPSIS>
: <FUNCPROTOTYPE>
: <FUNCDEF>int
<FUNCTION>abc</FUNCTION></FUNCDEF>
: <PARAMDEF>int
: <PARAMETER><REPLACEABLE>arg1</REPLACEABLE></PARAMETER></PARAMDEF>
: <PARAMDEF>int
: <PARAMETER><REPLACEABLE>arg2</REPLACEABLE></PARAMETER></PARAMDEF>
: </FUNCPROTOTYPE>
</FUNCSYNOPSIS>

Notes

  • The target of this illustration is in the text: int arg1, int arg2
  • The definition clause for this type may be done using funcsynopsis or synopsis syntax, depending upon requirements of the document.

---

SYNOPSIS EXAMPLE - Function requiring variable arguments only

Desired effect

int abc(...);

Syntax 

<FUNCSYNOPSIS>
: <FUNCPROTOTYPE>
: <FUNCDEF>int
: <FUNCTION>abc</FUNCTION></FUNCDEF>
: <VARARGS>
: </FUNCPROTOTYPE>
</FUNCSYNOPSIS>

Notes

  • The target of this illustration is in the text: ...
  • The varargs markup requires no closing tag and generates any necessary function-based punctuation.
  • The varargs markup is used to specify variable arguments only when the function contains no absolute arguments. (See "Function requiring both absolute and variable arguments" for alternate specification of variable arguments.)

---

SYNOPSIS EXAMPLE - Function requiring both absolute and variable arguments

Desired effect

int abc(char *arg1, ...);

Syntax 

<FUNCSYNOPSIS>
: <FUNCPROTOTYPE>
: <FUNCDEF>int
: <FUNCTION>abc</FUNCTION></FUNCDEF>
: <PARAMDEF>char *
: <PARAMETER><REPLACEABLE>arg1</REPLACEABLE></PARAMETER></PARAMDEF>
: <VARARGS>
: </FUNCPROTOTYPE>
</FUNCSYNOPSIS>

'''Notes'''
* The target of this illustration is in the text: char *arg1, ...
* Ellipses are used to specify variable arguments only when the function also contains absolute arguments. (See "Function requiring variable  arguments only" for alternate specification of variable arguments.)

'''SPECIAL LSB EXTENSION NOTE'''

The syntax above is not officially part of !DocBook 4.1 (though it is accepted at later version). In order for this to process correctly, the book ''must'' start with the following SGML declarations:
<pre>
<!DOCTYPE BOOK PUBLIC "-//OASIS//DTD [[DocBook]] V4.1//EN" [
<!ENTITY % funcprototype.element "IGNORE">
<!ELEMENT [[FuncPrototype]] - O ([[FuncDef]], (Void | ([[ParamDef]]*, [[VarArgs]]?)))>

---

SYNOPSIS EXAMPLE - Function requiring zero arguments

Desired effect

int abc(void);

Syntax 

<FUNCSYNOPSIS>
: <FUNCPROTOTYPE>
: <FUNCDEF>int
: <FUNCTION>abc</FUNCTION></FUNCDEF>
: <VOID>
: </FUNCPROTOTYPE>
</FUNCSYNOPSIS>

Notes

  • The target of this illustration is in the text: void
  • The void markup requires no closing tag and generates any necessary function-based punctuation.

---


SYNOPSIS EXAMPLE - Function that is defined as a structure

Desired effect

struct hostent *abc(const char arg1);

Syntax 

<FUNCSYNOPSIS>
: <FUNCPROTOTYPE>
: <FUNCDEF>struct
: <FUNCTION>
: <STRUCTNAME>hostent</STRUCTNAME> *abc</FUNCTION></FUNCDEF>
: <PARAMDEF>const char
: <PARAMETER><REPLACEABLE>arg1</REPLACEABLE></PARAMETER></PARAMDEF>
: </FUNCPROTOTYPE>
</FUNCSYNOPSIS>

Notes

  • The target of this illustration is in the text: struct hostent *abc

---

SYNOPSIS EXAMPLE - Function that uses a structure as a parameter

Desired effect

int abc(const char * restrict arg1, struct hostent * restrict arg2');

Syntax 

<FUNCSYNOPSIS>
: <FUNCPROTOTYPE>
: <FUNCDEF>int
: <FUNCTION>abc</FUNCTION></FUNCDEF>
: <PARAMDEF>const char * restrict
: <PARAMETER><REPLACEABLE>arg1</REPLACEABLE></PARAMETER></PARAMDEF>
: <PARAMDEF>struct hostent * restrict
: <PARAMETER>arg2</PARAMETER></PARAMDEF>
: </FUNCPROTOTYPE>
</FUNCSYNOPSIS>

Notes

  • The target of this illustration is in the text: struct hostent * restrict arg2

---

SYNOPSIS EXAMPLE - Function that uses a function as a parameter

Desired effect

int abc(int def, int (*ghi) (const char *, int));

Syntax 

<FUNCSYNOPSIS>
: <FUNCPROTOTYPE>
: <FUNCDEF>int
: <FUNCTION>abc</FUNCTION></FUNCDEF>
: <PARAMDEF>int
: <PARAMETER><REPLACEABLE>def</REPLACEABLE></PARAMETER></PARAMDEF>
: <PARAMDEF>int
: <FUNCPARAMS>*ghi</FUNCPARAMS>
: <FUNCPARAMS>const char *, int</FUNCPARAMS></PARAMDEF>
: </FUNCPROTOTYPE>
</FUNCSYNOPSIS>

Notes

  • The target of this illustration is in the text: int (*ghi) (const char *, int)


SYNOPSIS EXAMPLE - Structure with preceding name

Desired effect 

struct abc_status
{
: const char  *abc_field1;
: void        *abc_field2;
};

Syntax 

<SYNOPSIS>
struct <STRUCTNAME>abc_status</STRUCTNAME>
{
: const char  <STRUCTFIELD>*abc_field1</STRUCTFIELD>;
: void        <STRUCTFIELD>*abc_field2</STRUCTFIELD>;
};
</SYNOPSIS>

Notes

  • The definition clause for this type requires synopsis syntax.

---

SYNOPSIS EXAMPLE - Structure with trailing name

Desired effect 

typedef struct
{
: const char  *abc_field1;
: void        *abc_field2;
: const char  *abc_field3;
: void        *abc_field4;
} abc_info;

Syntax 

<SYNOPSIS>
typedef struct
{
: const char  <STRUCTFIELD>*abc_field1</STRUCTFIELD>;
: void        <STRUCTFIELD>*abc_field2</STRUCTFIELD>;
: const char  <STRUCTFIELD>*abc_field3</STRUCTFIELD>;
: void        <STRUCTFIELD>*abc_field4</STRUCTFIELD>;
} <STRUCTNAME>abc_info</STRUCTNAME>;
</SYNOPSIS>

Notes

  • For consistency, the LSB will use the funcsynopsis syntax to specify any required include or define clauses.
  • The definition clause for this type requires synopsis syntax.

---

SYNOPSIS EXAMPLE - Single variable

Desired effect

int __xyz;

Syntax 

<FUNCSYNOPSIS>
<FUNCSYNOPSISINFO>
</FUNCSYNOPSISINFO>
</FUNCSYNOPSIS>
<SYNOPSIS>
int <VARNAME>__xyz</VARNAME>;
</SYNOPSIS>

Notes

  • The target of this illustration is in the text: int __xyz
  • For consistency, the LSB will use the funcsynopsis syntax to specify any required include or define clauses.
  • The definition clause for this type requires synopsis syntax.

---


NOTES ON MAN PAGE TEXT DEVELOPMENT

  • External to the Synopsis, references to function names must appear sans "()". The () is added by the stylesheet, and must never appear explicitly in the source sgml. In the function synopsis, always use the <void> tag.
  • Function prototypes should not include any "extern" storage qualifier
  • __const and __restrict should be written as const and restrict; the underbar versions of these names are transitional while some versions of some compilers might not understand these ISO C 99 qualifiers. However, since we depend on SUSv3, which in turn depends on ISO C99, it is reasonable to ue the full C99 terms everywhere.
  • Leading underbars in names should be restricted to where they are required in the binary file only; for example in the name of a function. Arguments need never use leading underbars.
  • Command or function elements identified in the synopsis (name, parameter) need not be type-labeled in subsequent text. For example: the phrase "the getopt function" may appear simply as "getopt".
  • On exception, type-labels will be used in these cases:
  • to avoid misidentification of similarly-named command or function elements.
  • to qualify names of functions/elements that are not specified in the Synopsis.
  • to improve readability.
  • Where possible, Description text should describe initially what the function/command does, not its error conditions. For example, "The memmem() function finds the start ...", "The newgrp command changes the current group ...", and not "The memmem() function returns -1 if the argument is NULL".
  • The use of pronouns ("It", "This") to begin the first sentences of Description paragraphs will be avoided.


TAGS TO BE PHASED INTO GENERAL USE PRIOR TO LSB V2.0

  • <ACRONYM>
  • <ACTION>
  • <APPLICATION>
  • <CONSTANT>
  • <ERRORCODE>, <ERRORNAME> and <ERRORTYPE>
  • <EXAMPLE>
  • <FILENAME>
  • <IMPORTANT>
  • <INTERFACENAME>
  • <LITERAL>
  • <OPTION>
  • <QUOTE> and <BLOCKQUOTE>
  • <RETURNVALUE>
  • <STRUCTNAME> and <STRUCTFIELD>
  • <SYMBOL>
  • <TOKEN>
  • <VARNAME>


CORRECTIONS TO TAGS NOW IN GENERAL USE

  • <EMPHASIS> will be replaced whenever a more appropriate tag is required.
  • <REPLACEABLE> will be replaced whenever a more appropriate tag is required; used only to indicate user-specified text.
  • <LITERAL> used only to indicate a literal data value, a generic bit of data (the same data would be represented in volume text by <COMPUTEROUTPUT> or <USERINPUT>).

OFTEN-USED SPEC PHRASES

Return Values: 

<PARA>
On success, <RETURNVALUE>0</RETURNVALUE> is returned.
On error, <RETURNVALUE>-1</RETURNVALUE> is returned and
the global variable <VARNAME>errno</VARNAME> is set appropriately.
</PARA>

Cross references to POSIX: 

<PARA>
<FUNCTION>open</FUNCTION> is as specified in <XREF LINKEND="STD.SUSv3">,
but with differences as listed below.
</PARA>

Cross reference to POSIX with extensions: 

<PARA>
<FUNCTION>daylight</FUNCTION> is as specified in <XREF LINKEND="STD.SUSv3">,
with the following extensions.
</PARA>

Binary only interfaces: 

<PARA>
<FUNCTION>__getpagesize</FUNCTION> is not in the source standard;
it is only in the binary standard.
</PARA>

Aliases: 

<PARA>
<FUNCTION>__getpagesize</FUNCTION> has the same specification as
<FUNCTION>getpagesize</FUNCTION>.
</PARA>

<PARA>
<FUNCTION>__getpagesize</FUNCTION> is an alias for
<FUNCTION>getpagesize</FUNCTION> - get current page size.
</PARA>

VARIABLES, ARRAY ITEMS

For these types, <VARNAME> is used in the same context as <FUNCTION> for functions and interfaces. Example: 

<PARA>
<VARNAME>__environ</VARNAME> is an alias for <VARNAME>environ</VARNAME>
- user environment.
</PARA>

DEPRECATION SAMPLES 

<REFNAMEDIV>
<REFNAME>fstatfs
</REFNAME>
<REFPURPOSE>(deprecated)
</REFPURPOSE>
</REFNAMEDIV>

<PARA>
<FUNCTION>__dcgettext</FUNCTION> has been deprecated from the
<ACRONYM>LSB</ACRONYM> because it is no longer used by
<FUNCTION>dcgettext</FUNCTION>. Originally, it was intended
only for the binary standard.
</PARA>

<PARA>
<FUNCTION>fstatfs</FUNCTION> is expected to disappear from a future
version of the <ACRONYM>LSB</ACRONYM>; applications should call the
<FUNCTION>fstatvfs</FUNCTION> interface.
</PARA>

To add comments to this page, click on [wiki:WrittenSpecificationStyle/Comments User Comments] and select edit.

[[Include(WrittenSpecificationStyle/Comments)]]

Retrieved from "http://www.linuxfoundation.org/en/WrittenSpecificationStyle"

[Article] [Discussion] [View source] [History]

Copyright © 2008 Linux Foundation. All rights reserved.
LSB is a trademark of the Linux Foundation. Linux is a registered trademark of Linus Torvalds.

Please see our privacy policy.