Debian Codegraph @

deps/libneon/doc/using.xml

raw
1 <sect1 id="using">
2 <title>How to use neon from your application</title>
3
4 <para>This section describes how to add &neon; support to an
5 application. If you just want to quickly try out &neon;, use
6 the <xref linkend="refconfig"/> script.</para>
7
8 <para>The &neon; source code is designed to be easily embedded
9 into an application source tree. &neon; has no dependencies on
10 libraries other than an SSL toolkit and XML parser, though the
11 source tree can be configured to have no support for SSL or XML
12 if desired. To configure the &neon; source code some <ulink
13 url="http://www.gnu.org/software/autoconf/">GNU autoconf</ulink>
14 macros are supplied, which can be used in a number of ways, as
15 follows:</para>
16
17 <itemizedlist>
18 <listitem>
19
20 <para>autoconf macros are distributed in the 'macros'
21 subdirectory of the neon distribution. Use the NEON_LIBRARY
22 macro from your configure.in to check for the presence of
23 the neon library installed on the system. The macro adds an
24 '--with-neon=...' argument to configure, which allows the
25 user to specify a location for the library (the standard
26 /usr and /usr/local directories are checked automatically
27 without having to be specified).</para></listitem>
28
29 <listitem><para>The 'src' directory of the neon package can be
30 imported directly into your application, if you do not wish
31 to add an external dependency. If you wish to bundle, use
32 the NEON_BUNDLED macro to configure neon in your application:
33 here, the neon sources are bundled in a directory called
34 'libneon':</para>
35
36 <programlisting>NEON_BUNDLED(libneon, ...)</programlisting>
37
38 <para>If your application supports builds where srcdir != builddir,
39 you should use the NEON_VPATH_BUNDLED macro like this:</para>
40
41 <programlisting>NEON_VPATH_BUNDLED(${srcdir}/libneon, libneon, ...)</programlisting>
42
43 <para>If you use this macro, a '--with-included-neon' option
44 will be added to the generated configure script. This
45 allows the user to force the bundled neon to be used in the
46 application, rather than any neon library found on the
47 system. If you allow neon to be configured this way, you
48 must also configure an XML parser. Use the NEON_XML_PARSER
49 macro to do this.</para></listitem>
50
51 <listitem><para>The final argument to the _BUNDLED macros is a
52 set of actions which are executed if the bundled build *is*
53 chosen (rather than an external neon which might have been
54 found on the user's system). In here, use either the
55 NEON_LIBTOOL_BUILD or NEON_NORMAL_BUILD macro to set up the
56 neon Makefile appropriately: including adding the neon source
57 directory to the recursive make.</para></listitem>
58
59 </itemizedlist>
60
61 <para>A full fragment might be:</para>
62
63 <programlisting>NEON_BUNDLED(libneon, [
64 NEON_NORMAL_BUILD
65 NEON_XML_PARSER
66 SUBDIRS="libneon $SUBDIRS"
67 ])</programlisting>
68
69 <para>This means the bundled neon source directory (called 'libneon')
70 is used if no neon is found on the system, and the standard XML
71 parser search is used.</para>
72
73 </sect1>
74
75 <sect1 id="compliance">
76 <title>Standards compliance</title>
77
78 <para>&neon; is intended to be compliant with the IETF and W3C
79 standards which it implements, with a few exceptions due to
80 practical necessity or interoperability issues. These
81 exceptions are documented in this section.</para>
82
83 <sect2><title>RFC 2518, HTTP Extensions for Distributed Authoring&mdash;WebDAV</title>
84
85 <para>&neon; is deliberately not compliant with section
86 23.4.2, and treats property names as a (namespace-URI, name)
87 pair. This is <ulink
88 url="http://lists.w3.org/Archives/Public/w3c-dist-auth/1999OctDec/0343.html">generally
89 considered</ulink> to be correct behaviour by the WebDAV
90 working group, and is likely to formally adopted in a future
91 revision of the specification.</para></sect2>
92
93 <sect2><title>RFC 2616, Hypertext Transfer Protocol&mdash;HTTP/1.1</title>
94
95 <para>There is some confusion in this specification about the
96 use of the <quote>identity</quote>
97 <firstterm>transfer-coding</firstterm>. &neon; ignores the
98 <literal>Transfer-Encoding</literal> response header if it
99 contains only the (now deprecated) <quote>identity</quote>
100 token, and will determine the response message length as if
101 the header was not present. &neon; will give an error if a
102 response includes a <literal>Transfer-Encoding</literal>
103 header with a value other than <quote>identity</quote> or
104 <quote>chunked</quote>.</para></sect2>
105
106 <sect2>
107 <title>RFC 2617, HTTP Authentication: Basic and Digest Access Authentication</title>
108
109 <para>&neon; is not strictly compliant with the quoting rules
110 given in the grammar for the <literal>Authorization</literal>
111 header. The grammar requires that the <literal>qop</literal>
112 and <literal>algorithm</literal> parameters are not quoted,
113 however one widely deployed server implementation
114 (Microsoft&reg; IIS 5) rejects the request if these parameters
115 are not quoted. &neon; sends these parameters with
116 quotes&mdash;this is not known to cause any problems with
117 other server implementations.</para></sect2>
118
119 <sect2>
120 <title>Namespaces in XML</title>
121
122 <para>The &neon; XML parser interface will accept and parse
123 without error some XML documents which are well-formed
124 according to the XML specification but do not conform to the
125 "Namespaces in XML" specification <xref
126 linkend="bib.xmlnames"/>. Specifically: the restrictions on
127 the first character of the <literal>NCName</literal> rule are
128 not all implemented; &neon; will allow any
129 <literal>CombiningChar</literal>, <literal>Extender</literal>
130 and some characters from the <literal>Digit</literal> class in
131 this position.</para> </sect2>
132
133 <!-- a few RFC2818/3280 issues: rules about when to cache
134 sessions in the face of unclean shutdown are strict, neon is
135 probably not compliant: document or fix. Likewise SSL
136 shutdown issues in general. Cert hostname checks allow
137 wildcard "*." syntax which is less than 2818 but more than
138 3280 requires. -->
139
140 </sect1>