# How to use neon from your application

This section describes how to add &neon; support to an application. If you just want to quickly try out &neon;, use the script.

The &neon; source code is designed to be easily embedded into an application source tree. &neon; has no dependencies on libraries other than an SSL toolkit and XML parser, though the source tree can be configured to have no support for SSL or XML if desired. To configure the &neon; source code some GNU autoconf macros are supplied, which can be used in a number of ways, as follows:

- autoconf macros are distributed in the 'macros' subdirectory of the neon distribution. Use the NEON_LIBRARY macro from your configure.in to check for the presence of the neon library installed on the system. The macro adds an '--with-neon=...' argument to configure, which allows the user to specify a location for the library (the standard /usr and /usr/local directories are checked automatically without having to be specified).

- The 'src' directory of the neon package can be imported directly into your application, if you do not wish to add an external dependency. If you wish to bundle, use the NEON_BUNDLED macro to configure neon in your application: here, the neon sources are bundled in a directory called 'libneon':

      NEON_BUNDLED(libneon, ...)

  If your application supports builds where srcdir != builddir, you should use the NEON_VPATH_BUNDLED macro like this:

      NEON_VPATH_BUNDLED(${srcdir}/libneon, libneon, ...)

  If you use this macro, a '--with-included-neon' option will be added to the generated configure script. This allows the user to force the bundled neon to be used in the application, rather than any neon library found on the system. If you allow neon to be configured this way, you must also configure an XML parser. Use the NEON_XML_PARSER macro to do this.

- The final argument to the _BUNDLED macros is a set of actions which are executed if the bundled build *is* chosen (rather than an external neon which might have been found on the user's system). In here, use either the NEON_LIBTOOL_BUILD or NEON_NORMAL_BUILD macro to set up the neon Makefile appropriately: including adding the neon source directory to the recursive make.

A full fragment might be:

    NEON_BUNDLED(libneon, [
      NEON_NORMAL_BUILD
      NEON_XML_PARSER
      SUBDIRS="libneon $SUBDIRS"
    ])

This means the bundled neon source directory (called 'libneon') is used if no neon is found on the system, and the standard XML parser search is used.

# Standards compliance

&neon; is intended to be compliant with the IETF and W3C standards which it implements, with a few exceptions due to practical necessity or interoperability issues. These exceptions are documented in this section.

## RFC 2518, HTTP Extensions for Distributed Authoring—WebDAV

&neon; is deliberately not compliant with section 23.4.2, and treats property names as a (namespace-URI, name) pair. This is generally considered to be correct behaviour by the WebDAV working group, and is likely to formally adopted in a future revision of the specification.

## RFC 2616, Hypertext Transfer Protocol—HTTP/1.1

There is some confusion in this specification about the use of the identity transfer-coding. &neon; treats the presence of any `Transfer-Encoding` response header as an indication that the response message uses the chunked transfer-coding. This was the suggested resolution proposed by Larry Masinter.

## RFC 2617, HTTP Authentication: Basic and Digest Access Authentication

&neon; is not strictly compliant with the quoting rules given in the grammar for the `Authorization` header. The grammar requires that the `qop` and `algorithm` parameters are not quoted, however one widely deployed server implementation (Microsoft® IIS 5) rejects the request if these parameters are not quoted. &neon; sends these parameters with quotes—this is not known to cause any problems with other server implementations.

## Namespaces in XML

The &neon; XML parser interface will accept and parse without error some XML documents which are well-formed according to the XML specification but do not conform to the "Namespaces in XML" specification . Specifically: the restrictions on the first character of the `NCName` rule are not all implemented; &neon; will allow any `CombiningChar`, `Extender` and some characters from the `Digit` class in this position.