r10380: Use pod-style documentation rather then XML-doc, in good perl style.

(This used to be commit fcc1ba97a3dd955208d8d9555ff8dab455239412)

4 files changed, 403 insertions, 623 deletions

diff --git a/source4/pidl/Makefile.PL b/source4/pidl/Makefile.PL
index fa250cabc3..f5cd3e4eff 100755
--- a/source4/pidl/Makefile.PL
+++ b/source4/pidl/Makefile.PL
@@ -3,23 +3,13 @@ WriteMakefile(
     'NAME'	=> 'Parse::Pidl',
     'VERSION_FROM' => 'lib/Parse/Pidl.pm',
 	'EXE_FILES' => [ 'pidl' ],
-	'PMLIBDIRS' => [ 'lib' ],
 	'test' => { 'TESTS' => 'tests/*.pl' }
 );
 
 sub MY::postamble {
 <<'EOT';
-lib/Parse/Pidl/IDL.pm :: idl.yp
-	yapp -s -m 'Parse::Pidl::IDL' -o 'lib/Parse/Pidl/IDL.pm' idl.yp
+lib/Parse/Pidl/IDL.pm: idl.yp
+	yapp -s -m 'Parse::Pidl::IDL' -o lib/Parse/Pidl/IDL.pm idl.yp
 
-doc: pidl.1 pidl.1.html
-
-XSLTPROC=xsltproc
-
-%.1: %.1.xml
-	test -z "$(XSLTPROC)" || $(XSLTPROC) -o $@ http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
-
-%.html: %.xml
-	test -z "$(XSLTPROC)" || $(XSLTPROC) -o $@ http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl $<
 EOT
 }
diff --git a/source4/pidl/README b/source4/pidl/README
index 7458344761..c90105a0ef 100644
--- a/source4/pidl/README
+++ b/source4/pidl/README
@@ -22,11 +22,6 @@ Run Makefile.PL to generate the Makefile.
 
 Then run "make install" (as root) to install.
 
-Documentation:
-==============
-Run 'make doc' to generate the manpage and a HTML version of the manpage.
-This requires the xsltproc utility to be installed.
-
 Internals overview:
 ===================
 
diff --git a/source4/pidl/pidl b/source4/pidl/pidl
index 5d248ce7a3..7ef30c32b7 100755
--- a/source4/pidl/pidl
+++ b/source4/pidl/pidl
@@ -7,6 +7,407 @@
 # Copyright jelmer@samba.org 2005
 # released under the GNU GPL
 
+=head1 NAME
+
+pidl - IDL Compiler written in Perl
+
+=head1 SYNOPSIS
+
+pidl --help
+pidl [--outputdir[=OUTNAME]] [--parse-idl-tree] [--dump-idl-tree] [--dump-ndr-tree] [--ndr-header[=OUTPUT]] [--header[=OUTPUT]] [--ejs[=OUTPUT]] [--swig[=OUTPUT]] [--uint-enums] [--ndr-parser[=OUTPUT]] [--client] [--server] [--dcom-proxy] [--com-header] [--warn-compat] [--quiet] [--verbose] [--template] [--eth-parser[=OUTPUT]] [--diff] [--dump-idl] [<idlfile>.idl]...
+
+=head1 DESCRIPTION
+
+pidl is an IDL compiler written in Perl that aims to be somewhat 
+compatible with the midl compiler. IDL stands for 
+"Interface Definition Language".
+
+pidl can generate stubs for DCE/RPC server code, DCE/RPC 
+client code and ethereal dissectors for DCE/RPC traffic.
+
+IDL compilers like pidl take a description 
+of an interface as their input and use it to generate C 
+(though support for other languages may be added later) code that 
+can use these interfaces, pretty print data sent 
+using these interfaces, or even generate ethereal 
+dissectors that can parse data sent over the 
+wire by these interfaces. 
+
+pidl takes IDL files in the same format as is used by midl, 
+converts it to a .pidl file (which contains pidl's internal representation of the interface) and can then generate whatever output you need.
+.pidl files should be used for debugging purposes only. Write your 
+interface definitions in .idl format.
+
+The goal of pidl is to implement a IDL compiler that can be used 
+while developing the RPC subsystem in Samba (for 
+both marshalling/unmarshalling and debugging purposes).
+
+=head1 OPTIONS
+
+=over 4
+
+=item I<--help>
+
+Show list of available options.</para></listitem>
+		
+=item I<--outputdir OUTNAME>
+
+Write output files to the specified directory.  Defaults to the current 
+directory.
+		
+=item I<--parse-idl-tree>
+
+Read internal tree structure from input files rather 
+then assuming they contain IDL.
+
+=item I<--dump-idl>
+
+Generate a new IDL file. File will be named OUTNAME.idl.</para></listitem>
+
+=item I<--header>
+
+Generate a C header file for the specified interface. Filename defaults to OUTNAME.h.
+
+=item I<--ndr-header>
+
+Generate a C header file with the prototypes for the NDR parsers. Filename defaults to ndr_OUTNAME.h.
+
+=item I<--ndr-parser>
+
+Generate a C file containing NDR parsers. Filename defaults to ndr_OUTNAME.c.
+
+=item I<--server>
+
+Generate boilerplate for the RPC server that implements 
+the interface. Filename defaults to ndr_OUTNAME_s.c.
+
+=item I<--template>
+
+Generate stubs for a RPC server that implements the interface. Output will 
+be written to stdout.
+
+=item I<--eth-parser>
+
+Generate an Ethereal dissector (in C) for the interface. Filename
+defaults to packet-dcerpc-OUTNAME.c. 
+	
+Pidl will read additional data from an ethereal conformance file if present. 
+Such a file should have the same location as the IDL file but with the 
+extension I<cnf> rather then I<idl>. See below for details on the format of 
+this file.
+
+=item I<--diff>
+
+Parse an IDL file,  generate a new IDL file based on the internal data 
+structures and see if there are any differences with the original IDL file. 
+Useful for debugging pidl.
+
+=item I<--dump-idl-tree>
+
+Tell pidl to dump the internal tree representation of an IDL 
+file the to disk. Useful for debugging pidl.
+
+=item I<--dump-ndr-tree>
+
+Tell pidl to dump the internal NDR information tree it generated 
+from the IDL file to disk.  Useful for debugging pidl.
+
+=back
+
+=head1 IDL SYNTAX
+
+IDL files are always preprocessed using the C preprocessor.
+
+Pretty much everything in an interface (the interface itself, functions, 
+parameters) can have attributes (or properties whatever name you give them). 
+Attributes always prepend the element they apply to and are surrounded 
+by square brackets ([]). Multiple attributes are separated by comma's; 
+arguments to attributes are specified between parentheses. 
+
+See the section COMPATIBILITY for the list of attributes that 
+pidl supports.
+
+C-style comments can be used.
+	
+=head2 CONFORMANT ARRAYS
+
+A conformant array is one with that ends in [*] or []. The strange
+things about conformant arrays are:
+
+=over 1
+=item they can only appear as the last element of a structure
+=item the array size appears before the structure itself on the wire. 
+=back
+
+So, in this example:
+
+	typedef struct {
+		long abc;
+		long count;     
+		long foo;
+		[size_is(count)] long s[*];
+	} Struct1;
+
+it appears like this:
+
+	[size_is] [abc] [count] [foo] [s...]
+
+the first [size_is] field is the allocation size of the array, and
+occurs before the array elements and even before the structure
+alignment.
+
+Note that size_is() can refer to a constant, but that doesn't change
+the wire representation. It does not make the array a fixed array.
+
+midl.exe would write the above array as the following C header:
+
+   typedef struct {
+		long abc;
+		long count;     
+		long foo;
+		long s[1];
+	} Struct1;
+
+pidl takes a different approach, and writes it like this:
+
+    typedef struct {
+		long abc;
+		long count;     
+		long foo;
+		long *s;
+	} Struct1;
+
+=head2 VARYING ARRAYS
+
+A varying array looks like this:
+
+	typedef struct {
+		long abc;
+		long count;     
+		long foo;
+		[size_is(count)] long *s;
+	} Struct1;
+
+This will look like this on the wire:
+
+	[abc] [count] [foo] [PTR_s]    [count] [s...]
+
+=head2 FIXED ARRAYS
+
+A fixed array looks like this:
+
+    typedef struct {
+	    long s[10];
+    } Struct1;
+
+The NDR representation looks just like 10 separate long
+declarations. The array size is not encoded on the wire.
+
+pidl also supports "inline" arrays, which are not part of the IDL/NDR
+standard. These are declared like this:
+
+    typedef struct {
+	    uint32 foo;
+	    uint32 count;
+	    uint32 bar;
+	    long s[count];
+    } Struct1;
+
+This appears like this:
+
+	[foo] [count] [bar] [s...]
+
+Fixed arrays are an extension added to support some of the strange
+embedded structures in security descriptors and spoolss. 
+
+This section is by no means complete. See the OpenGroup and MSDN 
+	documentation for additional information.
+
+=head1 COMPATIBILITY WITH MIDL
+
+=head2 Missing features in pidl
+
+The following MIDL features are not (yet) implemented in pidl 
+or are implemented with an incompatible interface:
+
+=over
+=item Asynchronous communication
+=item Typelibs (.tlb files)
+=item Datagram support (ncadg_*)
+=back
+
+=head2 Supported attributes
+
+in, out, ref, length_is, switch_is, size_is, uuid, case, default, string, 
+unique, ptr, pointer_default, v1_enum, object, helpstring, range, local, 
+call_as, endpoint, switch_type, progid, coclass, iid_is.
+
+=head2 PIDL Specific properties
+
+=over 4
+
+=item public
+
+The [public] property on a structure or union is a pidl extension that
+forces the generated pull/push functions to be non-static. This allows
+you to declare types that can be used between modules. If you don't
+specify [public] then pull/push functions for other than top-level
+functions are declared static.
+				
+=item noprint
+
+The [noprint] property is a pidl extension that allows you to specify
+that pidl should not generate a ndr_print_*() function for that
+structure or union. This is used when you wish to define your own
+print function that prints a structure in a nicer manner. A good
+example is the use of [noprint] on dom_sid, which allows the
+pretty-printing of SIDs.
+
+=item value
+
+The [value(expression)] property is a pidl extension that allows you
+to specify the value of a field when it is put on the wire. This
+allows fields that always have a well-known value to be automatically
+filled in, thus making the API more programmer friendly. The
+expression can be any C expression.
+
+=item relative
+
+The [relative] property can be supplied on a pointer. When it is used
+it declares the pointer as a spoolss style "relative" pointer, which
+means it appears on the wire as an offset within the current
+encapsulating structure. This is not part of normal IDL/NDR, but it is
+a very useful extension as it avoids the manual encoding of many
+complex structures.
+
+=item subcontext(length)
+
+Specifies that a size of I<length>
+bytes should be read, followed by a blob of that size, 
+which will be parsed as NDR.
+
+=item flag
+
+Specify boolean options, mostly used for 
+low-level NDR options. Several options 
+can be specified using the | character.
+Note that flags are inherited by substructures!
+
+=item nodiscriminant
+
+The [nodiscriminant] property on a union means that the usual uint16
+discriminent field at the start of the union on the wire is
+omitted. This is not normally allowed in IDL/NDR, but is used for some
+spoolss structures.
+
+=item charset(name)
+
+Specify that the array or string uses the specified 
+charset. If this attribute is specified, pidl will 
+take care of converting the character data from this format 
+to the host format. Commonly used values are UCS2, DOS and UTF8.
+
+=back
+
+=head2 Unsupported MIDL properties
+
+aggregatable, appobject, async_uuid, bindable, control, cpp_quote, 
+defaultbind, defaultcollelem, defaultvalue, defaultvtable, dispinterface, 
+displaybind, dual, entry, first_is, helpcontext, helpfile, helpstringcontext, 
+helpstringdll, hidden, idl_module, idl_quote, id, immediatebind, importlib, 
+import, include, includelib, last_is, lcid, licensed, max_is, module, 
+ms_union, no_injected_text, nonbrowsable, noncreatable, nonextensible, odl, 
+oleautomation, optional, pragma, propget, propputref, propput, readonly, 
+requestedit, restricted, retval, source, transmit_as, uidefault, 
+usesgetlasterror, vararg, vi_progid, wire_marshal. 
+
+=head1 ETHEREAL CONFORMANCE FILES
+
+Pidl needs additional data for ethereal output. This data is read from 
+so-called conformance files. This section describes the format of these 
+files.
+
+Conformance files are simple text files with a single command on each line.
+Empty lines and lines starting with a '#' character are ignored.
+Arguments to commands are seperated by spaces.
+
+The following commands are currently supported:
+
+=over 4
+
+=item TYPE name dissector ft_type base_type mask valsstring alignment
+
+Register new data type with specified name, what dissector function to call 
+and what properties to give header fields for elements of this type.
+
+=item NOEMIT type
+
+Suppress emitting a dissect_type function for the specified type
+
+=item PARAM_VALUE type param
+
+Set parameter to specify to dissector function for given type.
+
+=item HF_FIELD hf title filter ft_type base_type valsstring mask description
+
+Generate a custom header field with specified properties.
+
+=item HF_RENAME old_hf_name new_hf_name
+
+Force the use of new_hf_name when the parser generator was going to 
+use old_hf_name.
+
+This can be used in conjunction with HF_FIELD in order to make more then 
+one element use the same filter name.
+
+=item STRIP_PREFIX prefix
+
+Remove the specified prefix from all function names (if present).
+	
+=item PROTOCOL longname shortname filtername
+
+Change the short-, long- and filter-name for the current interface in
+Ethereal.
+
+=item FIELD_DESCRIPTION field desc
+
+Change description for the specified header field. `field' is the hf name of the field.
+
+=item IMPORT dissector code...
+
+Code to insert when generating the specified dissector. @HF@ and 
+@PARAM@ will be substituted.
+
+=back
+
+=head1 EXAMPLES
+
+	# Generating an ethereal parser
+	$ ./pidl --eth-parser -- atsvc.idl
+	
+	# Generating a TDR parser
+	$ ./pidl --tdr-parser --tdr-header --header -- regf.idl
+
+=head1 VERSION
+
+This man page is correct for version 4.0 of the Samba suite. L<http://www.samba.org/>.
+
+=head1 SEE ALSO
+
+L<http://msdn.microsoft.com/library/en-us/rpc/rpc/field_attributes.asp>
+L<http://wiki.ethereal.com/DCE/RPC>
+yapp(1)
+
+=head1 AUTHOR
+
+pidl was written by Andrew Tridgell, Stefan Metzmacher, Tim Potter and Jelmer 
+Vernooij. 
+
+This manpage was written by Jelmer Vernooij, partially based on the original 
+pidl README by Andrew Tridgell. 
+	
+=cut
+
 use strict;
 use FindBin qw($RealBin);
 use lib "$RealBin";
diff --git a/source4/pidl/pidl.1.xml b/source4/pidl/pidl.1.xml
deleted file mode 100644
index 2ac40efe00..0000000000
--- a/source4/pidl/pidl.1.xml
+++ /dev/null
@@ -1,606 +0,0 @@
-<?xml version="1.0" encoding="iso-8859-1"?>
-<!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
-<refentry id="pidl.1">
-
-<refmeta>
-	<refentrytitle>pidl</refentrytitle>
-	<manvolnum>1</manvolnum>
-</refmeta>
-
-<refnamediv>
-	<refname>pidl</refname>
-	<refpurpose>IDL Compiler written in Perl</refpurpose>
-</refnamediv>
-
-<refsynopsisdiv>
-	<cmdsynopsis>
-		<command>pidl</command>
-		<arg choice="opt">--help</arg>
-		<arg choice="opt">--outputdir OUTNAME</arg>
-		<arg choice="opt">--parse-idl-tree</arg>
-		<arg choice="opt">--dump-idl-tree</arg>
-		<arg choice="opt">--dump-ndr-tree</arg>
-		<arg choice="opt">--ndr-header[=OUTPUT]</arg>
-		<arg choice="opt">--header[=OUTPUT]</arg>
-		<arg choice="opt">--ejs[=OUTPUT]</arg>
-		<arg choice="opt">--swig[=OUTPUT]</arg>
-		<arg choice="opt">--uint-enums</arg>
-		<arg choice="opt">--ndr-parser[=OUTPUT]</arg>
-		<arg choice="opt">--client</arg>
-		<arg choice="opt">--server</arg>
-		<arg choice="opt">--dcom-proxy</arg>
-		<arg choice="opt">--com-header</arg>
-		<arg choice="opt">--warn-compat</arg>
-		<arg choice="opt">--quiet</arg>
-		<arg choice="opt">--verbose</arg>
-		<arg choice="opt">--template</arg>
-		<arg choice="opt">--eth-parser[=OUTPUT]</arg>
-		<arg choice="opt">--diff</arg>
-		<arg choice="opt">--dump-idl</arg>
-		<arg choice="req">idlfile</arg>
-		<arg choice="opt">idlfile2</arg>
-		<arg choice="opt">...</arg>
-	</cmdsynopsis>
-</refsynopsisdiv>
-
-<refsect1>
-	<title>DESCRIPTION</title>
-
-	<para>pidl is an IDL compiler written in Perl that aims to be somewhat 
-		compatible with the midl compiler. IDL stands for 
-		"Interface Definition Language".</para>
-
-	<para>pidl can generate stubs for DCE/RPC server code, DCE/RPC 
-		client code and ethereal dissectors for DCE/RPC traffic.</para>
-
-	<para>IDL compilers like <emphasis>pidl</emphasis> take a description 
-		of an interface as their input and use it to generate C 
-		(though support for other languages may be added later) code that 
-		can use these interfaces, pretty print data sent 
-		using these interfaces, or even generate ethereal 
-		dissectors that can parse data sent over the 
-		wire by these interfaces. </para>
-
-	<para>pidl takes IDL files in the same format as is used by midl, 
-		converts it to a .pidl file (which contains pidl's internal representation of the interface) and can then generate whatever output you need.
-		.pidl files should be used for debugging purposes only. Write your 
-		interface definitions in .idl format.
-	</para>
-
-	<para>
-		The goal of pidl is to implement a IDL compiler that can be used 
-		while developing the RPC subsystem in Samba (for 
-		both marshalling/unmarshalling and debugging purposes).
-	</para>
-
-</refsect1>
-
-<refsect1>
-	<title>OPTIONS</title>
-
-	<variablelist>
-		<varlistentry>
-		<term>--help</term>
-		<listitem><para>
-		Show list of available options.</para></listitem>
-		</varlistentry>
-		
-		<varlistentry>
-		<term>--outputdir OUTNAME</term>
-		<listitem><para>Write output files to the specified directory. 
-				Defaults to the current directory.
-		</para></listitem>
-		</varlistentry>
-		
-		<varlistentry>
-		<term>--parse-idl-tree</term>
-		<listitem><para>
-				Read internal tree structure from input files rather 
-		then assuming they contain IDL.</para></listitem>
-		</varlistentry>
-
-
-		<varlistentry>
-		<term>--dump-idl</term>
-		<listitem><para>
-				Generate a new IDL file. File will be named OUTNAME.idl.</para></listitem>
-		</varlistentry>
-
-
-		<varlistentry>
-		<term>--header</term>
-		<listitem><para>
-				Generate a C header file for the specified interface. Filename defaults to OUTNAME.h.</para></listitem>
-		</varlistentry>
-
-		<varlistentry>
-		<term>--ndr-header</term>
-		<listitem><para>
-				Generate a C header file with the prototypes for the NDR parsers. Filename defaults to ndr_OUTNAME.h.</para></listitem>
-		</varlistentry>
-
-		<varlistentry>
-		<term>--ndr-parser</term>
-		<listitem><para>
-				Generate a C file containing NDR parsers. 
-				Filename defaults to ndr_OUTNAME.c.
-		</para></listitem>
-		</varlistentry>
-
-
-		<varlistentry>
-		<term>--server</term>
-		<listitem><para>
-		Generate boilerplate for the RPC server that implements 
-		the interface. Filename defaults to ndr_OUTNAME_s.c</para></listitem>
-		</varlistentry>
-
-
-		<varlistentry>
-		<term>--template</term>
-		<listitem><para>
-		Generate stubs for a RPC server that implements 
-		the interface. Output will be written to stdout.
-		</para></listitem>
-		</varlistentry>
-
-
-		<varlistentry>
-		<term>--eth-parser</term>
-		<listitem><para>
-		Generate an Ethereal dissector (in C) for the interface. Filename
-		defaults to packet-dcerpc-OUTNAME.c. 
-		</para>
-	
-		<para>Pidl will read additional data 
-			from an ethereal conformance file if present. Such a file should 
-			have the same location as the IDL file but with the extension 
-			<quote>cnf</quote> rather then <quote>idl</quote>. See 
-			below for details on the format of this file.
-		</para></listitem>
-		</varlistentry>
-
-		<varlistentry>
-		<term>--diff</term>
-		<listitem><para>
-				Parse an IDL file,  generate a new IDL file based 
-				on the internal data structures and see if there are 
-				any differences with the 
-		original IDL file. Useful for debugging pidl.</para></listitem>
-		</varlistentry>
-
-
-		<varlistentry>
-		<term>--dump-idl-tree</term>
-		<listitem><para>
-		Tell pidl to dump the internal tree representation of an IDL 
-		file the to disk. Useful 
-		for debugging pidl.</para></listitem>
-		</varlistentry>
-
-		<varlistentry>
-		<term>--dump-ndr-tree</term>
-		<listitem><para>
-				Tell pidl to dump the internal NDR information tree it generated 
-				from the IDL file to disk.  Useful for debugging pidl.</para></listitem>
-		</varlistentry>
-
-	</variablelist>
-</refsect1>
-
-<refsect1>
-	<title>IDL SYNTAX</title>
-
-	<para>IDL files are always preprocessed using the C preprocessor.</para>
-
-	<para>Pretty much everything in an interface (the interface itself,
-		functions, parameters) can have attributes (or properties 
-		whatever name you give them). Attributes 
-		always prepend the element they apply to and are surrounded 
-		by square brackets ([]). Multiple attributes 
-		are separated by comma's; arguments to attributes are 
-		specified between parentheses. </para>
-
-	<para>See the section COMPATIBILITY for the list of attributes that 
-		pidl supports.</para>
-
-	<para>C-style comments can be used.</para>
-	
-<refsect2>
-	<title>CONFORMANT ARRAYS</title>
-
-	<para>
-A conformant array is one with that ends in [*] or []. The strange
-things about conformant arrays are:
-</para>
-
-<simplelist>
-	<member>they can only appear as the last element of a structure</member>
-	<member>the array size appears before the structure itself on the wire. </member>
-</simplelist>
-
-<para>
-	So, in this example:
-</para>
-
-<programlisting>
-	typedef struct {
-		long abc;
-		long count;     
-		long foo;
-		[size_is(count)] long s[*];
-	} Struct1;
-</programlisting>
-
-<para>
-it appears like this:
-</para>
-
-<programlisting>
-[size_is] [abc] [count] [foo] [s...]
-</programlisting>
-
-<para>
-the first [size_is] field is the allocation size of the array, and
-occurs before the array elements and even before the structure
-alignment.
-</para>
-
-<para>
-Note that size_is() can refer to a constant, but that doesn't change
-the wire representation. It does not make the array a fixed array.
-</para>
-
-<para>
-midl.exe would write the above array as the following C header:
-</para>
-
-<programlisting>
-   typedef struct {
-		long abc;
-		long count;     
-		long foo;
-		long s[1];
-	} Struct1;
-</programlisting>
-
-<para>
-pidl takes a different approach, and writes it like this:
-</para>
-
-<programlisting>
-    typedef struct {
-		long abc;
-		long count;     
-		long foo;
-		long *s;
-	} Struct1;
-</programlisting>
-
-</refsect2>
-
-<refsect2>
-	<title>VARYING ARRAYS</title>
-
-<para>
-A varying array looks like this:
-</para>
-
-<programlisting>
-	typedef struct {
-		long abc;
-		long count;     
-		long foo;
-		[size_is(count)] long *s;
-	} Struct1;
-</programlisting>
-
-<para>
-This will look like this on the wire:
-</para>
-
-<programlisting>
-[abc] [count] [foo] [PTR_s]    [count] [s...]
-</programlisting>
-
-</refsect2>
-
-<refsect2>
-	<title>FIXED ARRAYS</title>
-
-<para>
-A fixed array looks like this:
-</para>
-
-<programlisting>
-    typedef struct {
-	    long s[10];
-    } Struct1;
-</programlisting>
-
-<para>
-The NDR representation looks just like 10 separate long
-declarations. The array size is not encoded on the wire.
-</para>
-
-<para>
-pidl also supports "inline" arrays, which are not part of the IDL/NDR
-standard. These are declared like this:
-</para>
-
-<programlisting>
-    typedef struct {
-	    uint32 foo;
-	    uint32 count;
-	    uint32 bar;
-	    long s[count];
-    } Struct1;
-</programlisting>
-
-<para>
-This appears like this:
-</para>
-
-<programlisting>
-[foo] [count] [bar] [s...]
-</programlisting>
-
-<para>
-Fixed arrays are an extension added to support some of the strange
-embedded structures in security descriptors and spoolss. 
-</para>
-
-</refsect2>
-
-<para>This section is by no means complete. See the OpenGroup and MSDN 
-	documentation for additional information.</para>
-</refsect1>
-
-<refsect1>
-	<title>COMPATIBILITY WITH MIDL</title>
-
-	<refsect2>
-		<title>Missing features in pidl</title>
-		<para>
-			The following MIDL features are not (yet) implemented in pidl 
-			or are implemented with an incompatible interface:
-		</para>
-
-		<simplelist>
-			<member>Asynchronous communication</member>
-			<member>Typelibs (.tlb files)</member>
-			<member>Datagram support (ncadg_*)</member>
-		</simplelist>
-	</refsect2>
-
-	<refsect2>
-		<title>Supported properties (attributes is the MIDL term)</title>
-
-		<para>
-			in, out, ref, length_is, switch_is, size_is, uuid, case, default, string, unique, ptr, pointer_default, v1_enum, object, helpstring, range, local, call_as, endpoint, switch_type, progid, coclass, iid_is.
-		</para>
-
-</refsect2>
-
-<refsect2>
-	<title>PIDL Specific properties</title>
-
-<variablelist>
-	<varlistentry><term>public</term>
-		<listitem><para>
-The [public] property on a structure or union is a pidl extension that
-forces the generated pull/push functions to be non-static. This allows
-you to declare types that can be used between modules. If you don't
-specify [public] then pull/push functions for other than top-level
-functions are declared static.
-		</para></listitem>
-	</varlistentry>
-				
-	<varlistentry><term>noprint</term>
-		<listitem><para>
-The [noprint] property is a pidl extension that allows you to specify
-that pidl should not generate a ndr_print_*() function for that
-structure or union. This is used when you wish to define your own
-print function that prints a structure in a nicer manner. A good
-example is the use of [noprint] on dom_sid, which allows the
-pretty-printing of SIDs.
-		</para></listitem>
-	</varlistentry>
-
-	<varlistentry><term>value</term>
-		<listitem><para>
-The [value(expression)] property is a pidl extension that allows you
-to specify the value of a field when it is put on the wire. This
-allows fields that always have a well-known value to be automatically
-filled in, thus making the API more programmer friendly. The
-expression can be any C expression.
-		</para></listitem>
-	</varlistentry>
-		
-	<varlistentry><term>relative</term>
-		<listitem><para>
-The [relative] property can be supplied on a pointer. When it is used
-it declares the pointer as a spoolss style "relative" pointer, which
-means it appears on the wire as an offset within the current
-encapsulating structure. This is not part of normal IDL/NDR, but it is
-a very useful extension as it avoids the manual encoding of many
-complex structures.
-		</para></listitem>
-	</varlistentry>
-
-	<varlistentry><term>subcontext(length)</term>
-		<listitem><para>
-				Specifies that a size of <replaceable>length</replaceable>
-				bytes should be read, followed by a blob of that size, 
-				which will be parsed as NDR.
-		</para></listitem>
-	</varlistentry>
-
-	<varlistentry><term>flag</term>
-		<listitem><para>
-				Specify boolean options, mostly used for 
-				low-level NDR options. Several options 
-				can be specified using the | character.
-				Note that flags are inherited by substructures!
-		</para></listitem>
-	</varlistentry>
-
-	<varlistentry><term>nodiscriminant</term>
-		<listitem><para>
-The [nodiscriminant] property on a union means that the usual uint16
-discriminent field at the start of the union on the wire is
-omitted. This is not normally allowed in IDL/NDR, but is used for some
-spoolss structures.
-		</para></listitem>
-	</varlistentry>
-
-	<varlistentry><term>charset(name)</term>
-		<listitem><para>
-				Specify that the array or string uses the specified 
-				charset. If this attribute is specified, pidl will 
-				take care of converting the character data from this format 
-				to the host format. Commonly used values are UCS2, DOS and UTF8.
-		</para></listitem>
-	</varlistentry>
-</variablelist>
-</refsect2>
-
-<refsect2>
-	<title>Unsupported MIDL properties</title>
-
-<para>aggregatable, appobject, async_uuid, bindable, control, cpp_quote, defaultbind, defaultcollelem, defaultvalue, defaultvtable, dispinterface, displaybind, dual, entry, first_is, helpcontext, helpfile, helpstringcontext, helpstringdll, hidden, idl_module, idl_quote, id, immediatebind, importlib, import, include, includelib, last_is, lcid, licensed, max_is, module, ms_union, no_injected_text, nonbrowsable, noncreatable, nonextensible, odl, oleautomation, optional, pragma, propget, propputref, propput, readonly, requestedit, restricted, retval, source, transmit_as, uidefault, usesgetlasterror, vararg, vi_progid, wire_marshal. </para>
-
-</refsect2>
-
-</refsect1>
-
-<refsect1>
-	<title>ETHEREAL CONFORMANCE FILES</title>
-
-<para>
-Pidl needs additional data for ethereal output. This data is read from 
-so-called conformance files. This section describes the format of these 
-files.</para>
-
-<para>
-Conformance files are simple text files with a single command on each line.
-Empty lines and lines starting with a '#' character are ignored.
-Arguments to commands are seperated by spaces.
-</para>
-
-<para>
-The following commands are currently supported:
-</para>
-
-<variablelist>
-
-<varlistentry>
-	<term>TYPE name dissector ft_type base_type mask valsstring alignment</term>
-	<listitem><para>Register new data type with specified name, what dissector function to call and what properties to give header fields for elements of this type.</para></listitem>
-</varlistentry>
-
-<varlistentry>
-	<term>NOEMIT type</term>
-	<listitem><para>
-	Suppress emitting a dissect_type function for the specified type
-	</para></listitem>
-</varlistentry>
-
-<varlistentry>
-	<term>PARAM_VALUE type param</term>
-	<listitem><para>
-	Set parameter to specify to dissector function for given type.
-	</para></listitem>
-</varlistentry>
-
-<varlistentry>
-	<term>HF_FIELD hf title filter ft_type base_type valsstring mask description</term>
-	<listitem><para>
-	Generate a custom header field with specified properties.
-	</para></listitem>
-</varlistentry>
-
-<varlistentry>
-	<term>HF_RENAME old_hf_name new_hf_name</term>
-	<listitem><para>
-	Force the use of new_hf_name when the parser generator was going to 
-	use old_hf_name.
-	</para>
-
-	<para>
-	This can be used in conjunction with HF_FIELD in order to make more then 
-	one element use the same filter name.
-	</para>
-	</listitem>
-</varlistentry>
-
-<varlistentry>
-	<term>STRIP_PREFIX prefix</term>
-	<listitem><para>
-	Remove the specified prefix from all function names (if present).
-	</para></listitem>
-</varlistentry>
-	
-<varlistentry>
-	<term>PROTOCOL longname shortname filtername</term>
-	<listitem><para>
-	Change the short-, long- and filter-name for the current interface in
-	Ethereal.
-	</para></listitem>
-</varlistentry>
-
-<varlistentry>
-	<term>FIELD_DESCRIPTION field desc</term>
-	<listitem><para>Change description for the specified header field. `field' is the hf name of the field.
-	</para></listitem>
-</varlistentry>
-
-<varlistentry>
-	<term>IMPORT dissector code...</term>
-	<listitem><para>
-	Code to insert when generating the specified dissector. @HF@ and 
-	@PARAM@ will be substituted.
-	</para></listitem>
-</varlistentry>
-
-</variablelist>
-
-</refsect1>
-
-<refsect1>
-	<title>EXAMPLES</title>
-
-	<programlisting>
-	# Generating an ethereal parser
-	$ ./pidl --eth-parser -- atsvc.idl
-	
-	# Generating a TDR parser
-	$ ./pidl --tdr-parser --tdr-header --header -- regf.idl
-	</programlisting>
-
-</refsect1>
-
-<refsect1>
-	<title>VERSION</title>
-
-	<para>This man page is correct for version 4.0 of the Samba suite.</para>
-</refsect1>
-
-<refsect1>
-	<title>SEE ALSO</title>
-
-	<para><ulink url="http://msdn.microsoft.com/library/en-us/rpc/rpc/field_attributes.asp">Field Attributes [Remote Procedure Call]</ulink>, <ulink url="http://wiki.ethereal.com/DCE/RPC">Ethereal Wiki on DCE/RPC</ulink>.</para>
-
-</refsect1>
-
-<refsect1>
-	<title>AUTHOR</title>
-
-	<para>pidl was written by Andrew Tridgell, Stefan Metzmacher, Tim 
-		Potter and Jelmer Vernooij. </para>
-
-	<para>This manpage was written by Jelmer Vernooij, partially based on the original pidl README by Andrew Tridgell. </para>
-	
-</refsect1>
-
-</refentry>