Permalink
Browse files

Begin the slow process of writing docs.

  • Loading branch information...
nevali committed Sep 2, 2010
1 parent 9222b00 commit 23678c3cff85a833d3f9ddb441ded056155c7522
Showing with 195 additions and 2 deletions.
  1. +2 −2 .gitignore
  2. +2 −0 Makefile.am
  3. +14 −0 configure.ac
  4. +1 −0 doc/.gitignore
  5. +33 −0 doc/Makefile.am
  6. +67 −0 doc/radiodns_create.3
  7. +76 −0 doc/radiodns_create.xml
View
@@ -15,13 +15,13 @@
.deps
.libs
.dirstamp
+Makefile
+Makefile.in
/config.h
/config.h.in
/config.log
/stamp-h1
/stamp-h2
-/Makefile
-/Makefile.in
/aclocal.m4
/autom4te.cache
/configure
View
@@ -16,6 +16,8 @@
DIST_SUBDIRS = buildtools
+SUBDIRS = doc
+
EXTRA_DIST = LICENSE NOTICE README.GIT \
libradiodns.pc.in libradiodns-uninstalled.pc.in
View
@@ -53,10 +53,24 @@ AC_SUBST([RESOLVER_LIBS])
AC_SUBST([EXTRA_LIBS])
LIBS="$orig_LIBS"
+have_db2x=no
+AC_CHECK_PROG(db2x_xsltproc,db2x_xsltproc,db2x_xsltproc)
+AC_CHECK_PROG(db2x_manxml,db2x_manxml,db2x_manxml)
+
+if test x"$db2x_xsltproc" = x"" || test x"$db2x_manxml" = x"" ; then
+ AC_MSG_RESULT([warning: docbook2x was not found; documentation will not be rebuilt])
+else
+ have_db2x=yes
+fi
+AM_CONDITIONAL([HAVE_DB2X],[test x"$have_db2x" = x"yes"])
+AC_SUBST([db2x_xsltproc])
+AC_SUBST([db2x_manxml])
+
AC_CONFIG_HEADER([config.h])
AC_CONFIG_FILES([Makefile
libradiodns.pc
libradiodns-uninstalled.pc
+doc/Makefile
buildtools/Makefile
buildtools/ext/Makefile
])
View
@@ -0,0 +1 @@
+*.mxml
View
@@ -0,0 +1,33 @@
+## libradiodns: The RadioDNS helper library
+##
+## Copyright 2010 Mo McRoberts.
+##
+## Licensed under the Apache License, Version 2.0 (the "License");
+## you may not use this file except in compliance with the License.
+## You may obtain a copy of the License at
+##
+## http://www.apache.org/licenses/LICENSE-2.0
+##
+## Unless required by applicable law or agreed to in writing, software
+## distributed under the License is distributed on an "AS IS" BASIS,
+## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+## See the License for the specific language governing permissions and
+## limitations under the License.
+
+man_MANS = radiodns_create.3
+
+## Distribute the manpages along with the source to save people needing
+## docbook2x
+
+EXTRA_DIST = $(man_MANS) \
+ radiodns_create.xml
+
+if HAVE_DB2X
+
+.mxml.3:
+ $(db2x_manxml) $<
+
+.xml.mxml:
+ $(db2x_xsltproc) -s man $< -o $@
+
+endif
View
@@ -0,0 +1,67 @@
+'\" -*- coding: us-ascii -*-
+.if \n(.g .ds T< \\FC
+.if \n(.g .ds T> \\F[\n[.fam]]
+.de URL
+\\$2 \(la\\$1\(ra\\$3
+..
+.if \n(.g .mso www.tmac
+.TH radiodns_create 3 "2 September 2010" "" ""
+.SH NAME
+radiodns_create \- Create a new RadioDNS context for a domain name
+.SH SYNOPSIS
+'nh
+.nf
+\*(T<#include <libradiodns.h>, \-lradiodns\*(T>
+.fi
+.sp 1
+.PP
+.fi
+.ad l
+\*(T<radiodns_context_t *\fBradiodns_create\fR\*(T> \kx
+.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
+'in \n(.iu+\nxu
+\*(T<(const char *\fIdnsdomain\fR);\*(T>
+'in \n(.iu-\nxu
+.ad b
+'hy
+.SH DESCRIPTION
+The \*(T<\fBradiodns_create\fR\*(T> family of functions create
+a new RadioDNS context which can be used as a handle for performing
+application discovery.
+.PP
+The \*(T<\fBradiodns_create\fR\*(T> function in particular
+creates a context using the specified DNS domain name,
+\*(T<dnsdomain\*(T>. This is in contrast to the other
+functions in the family, such as
+\*(T<\fBradiodns_create_amss\fR\*(T>, which use the supplied
+parameters to \fIgenerate\fR a domain name.
+.PP
+Once a context has been created, its target domain name can be
+discovered using \*(T<\fBradiodns_resolve_target\fR\*(T>. The
+target domain name is the fully-qualified domain name which, in
+the event of \*(T<dnsdomain\*(T> (or its generated
+equivalent) being a CNAME or
+DNAME, is ultimately referred to, accounting
+for chains of CNAME records.
+.PP
+For example, if \*(T<\fBradiodns_create\fR\*(T> was called
+with a \*(T<dnsdomain\*(T> value of
+\*(T<foo.example.com\*(T>, and
+\*(T<foo.example.com\*(T> was a CNAME
+referring to \*(T<bar.example.org\*(T>, and this was not
+itself a CNAME or DNAME,
+then the target domain name for the context would be
+\*(T<bar.example.org\*(T>.
+.PP
+Application discovery can be performed on a context using
+\*(T<\fBradiodns_resolve_app\fR\*(T>. This function queries
+DNS for specifically-named records which are children of the
+target associated with the context. Further details are included
+in the description of the \*(T<\fBradiodns_resolve_app\fR\*(T>
+function itself.
+.SH "RETURN VALUE"
+On success, \*(T<\fBradiodns_resolve_app\fR\*(T> returns an
+initialized context pointer. On failure, \*(T<NULL\*(T> is
+returned and \*(T<errno\*(T> is set appropriately. The returned
+context should be freed once no longer needed with
+\*(T<\fBradiodns_destroy\fR\*(T>.
View
@@ -0,0 +1,76 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<refentry id="radiodns_create">
+ <refmeta>
+ <refentrytitle>radiodns_create</refentrytitle>
+ <manvolnum>3</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>radiodns_create</refname>
+ <refpurpose>Create a new RadioDNS context for a domain name</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcsynopsisinfo>#include &lt;libradiodns.h&gt;, -lradiodns</funcsynopsisinfo>
+ <funcprototype>
+ <funcdef>radiodns_context_t *<function>radiodns_create</function></funcdef>
+ <paramdef>const char *<parameter>dnsdomain</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsection>
+ <title>DESCRIPTION</title>
+ <para>
+ The <function>radiodns_create</function> family of functions create
+ a new RadioDNS context which can be used as a handle for performing
+ application discovery.
+ </para>
+ <para>
+ The <function>radiodns_create</function> function in particular
+ creates a context using the specified DNS domain name,
+ <parameter>dnsdomain</parameter>. This is in contrast to the other
+ functions in the family, such as
+ <function>radiodns_create_amss</function>, which use the supplied
+ parameters to <emphasis>generate</emphasis> a domain name.
+ </para>
+ <para>
+ Once a context has been created, its target domain name can be
+ discovered using <function>radiodns_resolve_target</function>. The
+ target domain name is the fully-qualified domain name which, in
+ the event of <parameter>dnsdomain</parameter> (or its generated
+ equivalent) being a <constant>CNAME</constant> or
+ <constant>DNAME</constant>, is ultimately referred to, accounting
+ for chains of <constant>CNAME</constant> records.
+ </para>
+ <para>
+ For example, if <function>radiodns_create</function> was called
+ with a <parameter>dnsdomain</parameter> value of
+ <literal>foo.example.com</literal>, and
+ <literal>foo.example.com</literal> was a <constant>CNAME</constant>
+ referring to <literal>bar.example.org</literal>, and this was not
+ itself a <constant>CNAME</constant> or <constant>DNAME</constant>,
+ then the target domain name for the context would be
+ <literal>bar.example.org</literal>.
+ </para>
+ <para>
+ Application discovery can be performed on a context using
+ <function>radiodns_resolve_app</function>. This function queries
+ DNS for specifically-named records which are children of the
+ target associated with the context. Further details are included
+ in the description of the <function>radiodns_resolve_app</function>
+ function itself.
+ </para>
+ </refsection>
+ <refsection>
+ <title>RETURN VALUE</title>
+ <para>
+ On success, <function>radiodns_resolve_app</function> returns an
+ initialized context pointer. On failure, <literal>NULL</literal> is
+ returned and <varname>errno</varname> is set appropriately. The returned
+ context should be freed once no longer needed with
+ <function>radiodns_destroy</function>.
+ </para>
+ </refsection>
+</refentry>

0 comments on commit 23678c3

Please sign in to comment.