Fix parsing of int (x*).

[cdecl99.git] / doc / man / cdecl99.1

diff --git a/doc/man/cdecl99.1 b/doc/man/cdecl99.1
index e5f15602c67c6db86258231e6cea9479bb0a2b1c..eca715f0d4e85b0ce0f35f17af416becee70a183 100644 (file)
--- a/doc/man/cdecl99.1
+++ b/doc/man/cdecl99.1
@@ -3,7 +3,7 @@
 .Dt CDECL99 \&1 "Cdecl99 User's Manual"
 .Sh NAME
 .Nm cdecl99
 .Dt CDECL99 \&1 "Cdecl99 User's Manual"
 .Sh NAME
 .Nm cdecl99

-.Nd Make sense of C declaratiosns
+.Nd Make sense of C declarations

 .Sh SYNOPSIS
 .Nm
 .Op Fl q
 .Sh SYNOPSIS
 .Nm
 .Op Fl q


@@ -39,7 +39,7 @@ Suppress the welcome message when starting
 Run in batch (non-interactive) mode.  Execute the commands provided on standard
 input as usual, but do not print any prompts.  Exit with status 0 if and only
 if all commands complete successfully.
 Run in batch (non-interactive) mode.  Execute the commands provided on standard
 input as usual, but do not print any prompts.  Exit with status 0 if and only
 if all commands complete successfully.

-
+.Pp

 This option implies
 .Fl -quiet .
 .It Fl i , -interactive
 This option implies
 .Fl -quiet .
 .It Fl i , -interactive


@@ -50,7 +50,7 @@ Execute
 as if it were entered at the prompt, then exit.  This option can be specified
 multiple times; all commands are run in the same order as specified on the
 command line.
 as if it were entered at the prompt, then exit.  This option can be specified
 multiple times; all commands are run in the same order as specified on the
 command line.

-
+.Pp

 This option implies
 .Fl -batch .
 .It Fl f , -file Ar file
 This option implies
 .Fl -batch .
 .It Fl f , -file Ar file


@@ -63,7 +63,7 @@ and
 are specified, any
 .Fl -file
 option is ignored.
 are specified, any
 .Fl -file
 option is ignored.

-
+.Pp

 This option implies
 .Fl -batch .
 .It Fl V , -version
 This option implies
 .Fl -batch .
 .It Fl V , -version


@@ -81,7 +81,7 @@ the argument.  Whitespace preceding the command name is ignored.
 Translates a given C declaration or type name into something resembling
 English.
 .It simplify Ar declaration
 Translates a given C declaration or type name into something resembling
 English.
 .It simplify Ar declaration

-Simplifies a given C decalaration or type name by eliminating redundant
+Simplifies a given C declaration or type name by eliminating redundant

 components.
 .It declare Ar identifier No as Ar english-decl
 Translates an English declaration into C code.
 components.
 .It declare Ar identifier No as Ar english-decl
 Translates an English declaration into C code.


@@ -99,58 +99,59 @@ format is based on the one used in
 .Xr cdecl 1 ,
 and is described by the following context-free grammar.  This grammar is for
 illustrative purposes only: it is ambiguous and doesn't capture all the nuances
 .Xr cdecl 1 ,
 and is described by the following context-free grammar.  This grammar is for
 illustrative purposes only: it is ambiguous and doesn't capture all the nuances

-of the C language.  In this grammar,
-.Fa underlined words
-are nonterminals, \[*e] represents the empty string, and both
+of the C language.  In this grammar, nonterminals are represented
+.Va [ thusly ] ,
+\[*e] represents the empty string, and both

 .Li |
 and successive \[->] under the same nonterminal indicate alternation.  All
 other symbols are terminals.  The nonterminals
 .Li |
 and successive \[->] under the same nonterminal indicate alternation.  All
 other symbols are terminals.  The nonterminals

-.Fa identifier , type-specifier , type-qualifier , storage-class-specifier
+.Va [ identifier ] , [ type-specifier ] ,
+.Va [ type-qualifier ] , [ storage-class-specifier ]

 and
 and

-.Fa function-specifier
+.Va [ function-specifier ]

 are defined as in C.
 are defined as in C.

-.Bl -column -offset indent ".Fa english-decl" ""
-.It Fa english      Ta \[->] Ta Li declare Fa identifier Li as Fa english-decl
-.It                 Ta \[->] Ta Li type Fa english-decl
-.It Fa english-decl Ta \[->] Ta Fa sf-specs declarator
-.It Fa declarator   Ta \[->] Ta Fa qualifiers Li pointer to Fa declarator
-.It                 Ta \[->] Ta Li array Fa size Li of Fa declarator
-.It                 Ta \[->] Ta Li function Fa parameters Li returning Fa declarator
-.It                 Ta \[->] Ta Fa tq-specs
-.It Fa qualifiers   Ta \[->] Ta Fa type-qualifier qualifiers | No \[*e]
-.It Fa tq-specs     Ta \[->] Ta Fa type-qualifier tq-specs
-.It                 Ta \[->] Ta Fa type-specifier tq-specs
+.Bl -column -offset indent ".Va english-decl" ""
+.It Va english      Ta \[->] Ta Li declare Va [ identifier ] Li as Va [ english-decl ]
+.It                 Ta \[->] Ta Li type Va [ english-decl ]
+.It Va english-decl Ta \[->] Ta Va [ sf-specs ] [ declarator ]
+.It Va declarator   Ta \[->] Ta Va [ qualifiers ] Li pointer to Va [ declarator ]
+.It                 Ta \[->] Ta Li array Va [ size ] Li of Va [ declarator ]
+.It                 Ta \[->] Ta Li function Va [ parameters ] Li returning Va [ declarator ]
+.It                 Ta \[->] Ta Va [ tq-specs ]
+.It Va qualifiers   Ta \[->] Ta Va [ type-qualifier ] [ qualifiers ] | No \[*e]
+.It Va tq-specs     Ta \[->] Ta Va [ type-qualifier ] [ tq-specs ]
+.It                 Ta \[->] Ta Va [ type-specifier ] [ tq-specs ]

 .It                 Ta \[->] Ta \[*e]
 .It                 Ta \[->] Ta \[*e]

-.It Fa sf-specs     Ta \[->] Ta Fa storage-class-specifier sf-specs
-.It                 Ta \[->] Ta Fa function-specifier sf-specs
+.It Va sf-specs     Ta \[->] Ta Va [ storage-class-specifier ] [ sf-specs ]
+.It                 Ta \[->] Ta Va [ function-specifier ] [ sf-specs ]

 .It                 Ta \[->] Ta \[*e]
 .It                 Ta \[->] Ta \[*e]

-.It Fa size         Ta \[->] Ta Fa integer | Fa identifier | Li * | No \[*e]
-.It Fa parameters   Ta \[->] Ta Po Fa param-list Pc
-.It                 Ta \[->] Ta Po Fa param-list Li , ... Pc
+.It Va size         Ta \[->] Ta Va [ integer ] | Va [ identifier ] | Li * | No \[*e]
+.It Va parameters   Ta \[->] Ta Po Va [ param-list ] Pc
+.It                 Ta \[->] Ta Po Va [ param-list ] Li , ... Pc

 .It                 Ta \[->] Ta \[*e]
 .It                 Ta \[->] Ta \[*e]

-.It Fa param-list   Ta \[->] Ta Fa parameter | Fa parameter Li , Fa param-list
-.It Fa parameter    Ta \[->] Ta Fa identifier Li as Fa english-decl
-.It                 Ta \[->] Ta Fa english-decl
+.It Va param-list   Ta \[->] Ta Va [ parameter ] | Va [ parameter ] Li , Va [ param-list ]
+.It Va parameter    Ta \[->] Ta Va [ identifier ] Li as Va [ english-decl ]
+.It                 Ta \[->] Ta Va [ english-decl ]

 .El
 .Sh RESOLVING AMBIGUITIES
 The C context-free grammar has many ambiguities regarding declarations.
 Ordinarily, these ambiguities are resolved by the context in which the
 declaration appears, such as which typedef names are currently in scope.
 .El
 .Sh RESOLVING AMBIGUITIES
 The C context-free grammar has many ambiguities regarding declarations.
 Ordinarily, these ambiguities are resolved by the context in which the
 declaration appears, such as which typedef names are currently in scope.

-
+.Pp

 For example, the meaning of the declaration
 .Ic int f(int (foo))
 depends on whether or not a typedef named
 For example, the meaning of the declaration
 .Ic int f(int (foo))
 depends on whether or not a typedef named

-.Fa foo
+.Va foo

 is in scope.  If such a typedef is in scope, this declares
 is in scope.  If such a typedef is in scope, this declares

-.Fa f
+.Va f

 as a function that takes (after adjustment) a pointer to a function that takes
 a
 as a function that takes (after adjustment) a pointer to a function that takes
 a

-.Fa foo
+.Va foo

 and returns an int, returning an int.  If there is no such typedef, then this
 declares
 and returns an int, returning an int.  If there is no such typedef, then this
 declares

-.Fa f
+.Va f

 as a function that takes an int and returns an int.
 as a function that takes an int and returns an int.

-
+.Pp

 Since
 .Nm
 isn't a C compiler, on several occasions it has to arbitrarily pick one of two
 Since
 .Nm
 isn't a C compiler, on several occasions it has to arbitrarily pick one of two


@@ -158,11 +159,48 @@ possibilities.  The rule that is generally applied is that
 .Nm
 will choose the alternative with the simplest explanation.  Thus, f is
 interpreted as a function which takes an int and returns an int.
 .Nm
 will choose the alternative with the simplest explanation.  Thus, f is
 interpreted as a function which takes an int and returns an int.

+.Sh EXAMPLES
+.Bl -tag -width Output:
+.It Input:
+.Li explain int x;
+.It Output:
+.Li declare x as int
+.It Input:
+.Li explain static int* x, y;
+.It Output:
+.Li declare x as static pointer to int
+.sp 0
+.Li declare y as static int
+.It Input:
+.Li explain extern int printf(const char *fmt, ...);
+.It Output:
+.Li declare printf as extern function (fmt as pointer to const char, ...) returning int
+.It Input:
+.Li explain size_t volatile * const (* restrict)[1][2][3]
+.It Output:
+.Li type restrict pointer to array 1 of array 2 of array 3 of const pointer to volatile int
+.It Input:
+.Li declare x as int
+.It Output:
+.Li int x
+.It Input:
+.Li type function (pointer to const char) returning size_t
+.It Output:
+.Li size_t (const char *)
+.It Input:
+.Li declare f as inline function (g as pointer to array 6 of pointer to const char) returning pointer to function (int, ...) returning int
+.It Output:
+.Li inline int (*f(const char *(*g)[6]))(int, ...)
+.It Input:
+.Li simplify const int const ((*restrict x))
+.It Output:
+.Li const int * restrict x
+.El

 .Sh AUTHORS
 Nick Bowler <nbowler@draconx.ca>
 .Sh COPYRIGHT
 Copyright \(co 2011 Nick Bowler
 .Sh AUTHORS
 Nick Bowler <nbowler@draconx.ca>
 .Sh COPYRIGHT
 Copyright \(co 2011 Nick Bowler

-
+.Pp

 Permission is granted to copy, distribute and/or modify this manual under the
 terms of the Do What The Fuck You Want To Public License, version 2.
 .Sh SEE ALSO
 Permission is granted to copy, distribute and/or modify this manual under the
 terms of the Do What The Fuck You Want To Public License, version 2.
 .Sh SEE ALSO