Permalink
Browse files

Add documentation based on AsciiDoc tools

Each function is decribed in one txt file. The file libmodbus.txt
offers an overview of the library.

It's possible to generate HTML and man outputs from the txt file.
The documentation can be generated only if you have the required
tools (asciidoc and xmlto).

Better results are obtained with AsciiDoc v8.6+
  • Loading branch information...
1 parent acd36e6 commit 6254ede9156095ee0300076bf92c930066ce542f @stephane committed Mar 25, 2011
View
@@ -1,5 +1,5 @@
EXTRA_DIST = MIGRATION README.rst libmodbus.spec
-SUBDIRS = src tests
+SUBDIRS = src doc tests
pkgconfigdir = $(libdir)/pkgconfig
pkgconfig_DATA = libmodbus.pc
View
@@ -0,0 +1,44 @@
+dnl ##############################################################################
+dnl # AC_LIBMODBUS_CHECK_DOC_BUILD #
+dnl # Check whether to build documentation and install man-pages #
+dnl ##############################################################################
+AC_DEFUN([AC_LIBMODBUS_CHECK_DOC_BUILD], [{
+ # Allow user to disable doc build
+ AC_ARG_WITH([documentation], [AS_HELP_STRING([--without-documentation],
+ [disable documentation build even if asciidoc and xmlto are present [default=no]])])
+
+ if test "x$with_documentation" = "xno"; then
+ ac_libmodbus_build_doc="no"
+ ac_libmodbus_install_man="no"
+ else
+ # Determine whether or not documentation should be built and installed.
+ ac_libmodbus_build_doc="yes"
+ ac_libmodbus_install_man="yes"
+ # Check for asciidoc and xmlto and don't build the docs if these are not installed.
+ AC_CHECK_PROG(ac_libmodbus_have_asciidoc, asciidoc, yes, no)
+ AC_CHECK_PROG(ac_libmodbus_have_xmlto, xmlto, yes, no)
+ if test "x$ac_libmodbus_have_asciidoc" = "xno" -o "x$ac_libmodbus_have_xmlto" = "xno"; then
+ ac_libmodbus_build_doc="no"
+ # Tarballs built with 'make dist' ship with prebuilt documentation.
+ if ! test -f doc/modbus.7; then
+ ac_libmodbus_install_man="no"
+ AC_MSG_WARN([You are building an unreleased version of libmodbus and asciidoc or xmlto are not installed.])
+ AC_MSG_WARN([Documentation will not be built and manual pages will not be installed.])
+ fi
+ fi
+
+ # Do not install man pages if on mingw
+ if test "x$ac_libmodbus_on_mingw32" = "xyes"; then
+ ac_libmodbus_install_man="no"
+ fi
+ fi
+
+ AC_MSG_CHECKING([whether to build documentation])
+ AC_MSG_RESULT([$ac_libmodbus_build_doc])
+
+ AC_MSG_CHECKING([whether to install manpages])
+ AC_MSG_RESULT([$ac_libmodbus_install_man])
+
+ AM_CONDITIONAL(BUILD_DOC, test "x$ac_libmodbus_build_doc" = "xyes")
+ AM_CONDITIONAL(INSTALL_MAN, test "x$ac_libmodbus_install_man" = "xyes")
+}])
View
@@ -79,6 +79,9 @@ AC_CHECK_HEADERS([ \
netdb.h \
])
+# Check whether to build docs / install man pages
+AC_LIBMODBUS_CHECK_DOC_BUILD
+
# Checks for header files.
AC_HEADER_STDC
@@ -125,6 +128,7 @@ AC_CONFIG_FILES([
Makefile
src/Makefile
src/modbus-version.h
+ doc/Makefile
tests/Makefile
libmodbus.pc
])
View
@@ -0,0 +1,71 @@
+MAN3 = \
+ modbus_close.3 \
+ modbus_connect.3 \
+ modbus_flush.3 \
+ modbus_free.3 \
+ modbus_get_header_length.3 \
+ modbus_get_timeout_begin.3 \
+ modbus_get_timeout_end.3 \
+ modbus_new_rtu.3 \
+ modbus_new_tcp_pi.3 \
+ modbus_new_tcp.3 \
+ modbus_read_bits.3 \
+ modbus_read_input_bits.3 \
+ modbus_read_input_registers.3 \
+ modbus_read_registers.3 \
+ modbus_set_debug.3 \
+ modbus_set_error_recovery.3 \
+ modbus_set_slave.3 \
+ modbus_set_timeout_begin.3 \
+ modbus_set_timeout_end.3 \
+ modbus_strerror.3 \
+ modbus_write_bits.3 \
+ modbus_write_bit.3 \
+ modbus_write_registers.3 \
+ modbus_write_register.3
+MAN7 = libmodbus.7
+
+MAN_DOC = $(MAN3) $(MAN7)
+
+MAN_TXT = $(MAN3:%.3=%.txt)
+MAN_TXT += $(MAN7:%.7=%.txt)
+MAN_HTML = $(MAN_TXT:%.txt=%.html)
+
+if INSTALL_MAN
+dist_man_MANS = $(MAN_DOC)
+doc : $(MAN_DOC)
+endif
+
+EXTRA_DIST = asciidoc.conf $(MAN_TXT)
+if BUILD_DOC
+EXTRA_DIST += $(MAN_HTML)
+html : $(MAN_HTML)
+endif
+
+MAINTAINERCLEANFILES = $(MAN_DOC) $(MAN_HTML)
+
+dist-hook : $(MAN_DOC) $(MAN_HTML)
+
+html: $(MAN_HTML)
+
+if BUILD_DOC
+SUFFIXES=.html .txt .xml .1 .3 .7
+
+.txt.html:
+ asciidoc -d manpage -b xhtml11 -f asciidoc.conf \
+ -alibmodbus_version=@LIBMODBUS_VERSION@ $<
+.txt.xml:
+ asciidoc -d manpage -b docbook -f asciidoc.conf \
+ -alibmodbus_version=@LIBMODBUS_VERSION@ $<
+.xml.1:
+ xmlto man $<
+.xml.3:
+ xmlto man $<
+.xml.7:
+ xmlto man $<
+
+clean:
+ rm -f *.1 *.3 *.7
+ rm -f *.html
+
+endif
View
@@ -0,0 +1,51 @@
+[paradef-default]
+literal-style=template="literalparagraph"
+
+[macros]
+(?su)[\\]?(?P<name>linkmb):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
+
+ifdef::backend-docbook[]
+[linkmb-inlinemacro]
+{0%{target}}
+{0#<citerefentry>}
+{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
+{0#</citerefentry>}
+endif::backend-docbook[]
+
+ifdef::backend-xhtml11[]
+[linkmb-inlinemacro]
+<a href="{target}.html">{target}{0?({0})}</a>
+endif::backend-xhtml11[]
+
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[header]
+template::[header-declarations]
+<refentry>
+<refmeta>
+<refentrytitle>{mantitle}</refentrytitle>
+<manvolnum>{manvolnum}</manvolnum>
+<refmiscinfo class="source">libmodbus</refmiscinfo>
+<refmiscinfo class="version">{libmodbus_version}</refmiscinfo>
+<refmiscinfo class="manual">Libmodbus Manual</refmiscinfo>
+</refmeta>
+<refnamediv>
+ <refname>{manname}</refname>
+ <refpurpose>{manpurpose}</refpurpose>
+</refnamediv>
+endif::backend-docbook[]
+endif::doctype-manpage[]
+
+ifdef::backend-xhtml11[]
+[footer]
+</div>
+{disable-javascript%<div id="footnotes"><hr /></div>}
+<div id="footer">
+<div id="footer-text">
+libmodbus {libmodbus_version}<br />
+Last updated {docdate} {doctime}
+</div>
+</div>
+</body>
+</html>
+endif::backend-xhtml11[]
View
@@ -0,0 +1,184 @@
+libmodbus(7)
+============
+
+
+NAME
+----
+libmodbus - fast and portable Modbus library
+
+
+SYNOPSIS
+--------
+*#include <modbus.h>*
+
+*cc* \`pkg-config --cflags --libs libmodbus` 'files'
+
+
+DESCRIPTION
+-----------
+libmodbus is a library to send/receive data with a device which respects the
+Modbus protocol. This library contains various backends to communicate over
+different networks (eg. serial in RTU mode or Ethernet in TCP/IPv6). The
+http://www.modbus.org site provides documentation about the protocol at
+http://www.modbus.org/specs.php.
+
+libmodbus provides an abstraction of the lower communication layers and offers
+the same API on all supported platforms.
+
+This documentation presents an overview of libmodbus concepts, describes how
+libmodbus abstracts Modbus communication with different hardware and platforms
+and provides a reference manual for the functions provided by the libmodbus
+library.
+
+
+Contexts
+~~~~~~~~
+The Modbus protocol contains many variants (eg. serial RTU or Ehternet TCP), to
+ease the implementation of a variant, the library was designed to use a backend
+for each variant. The backends are also a convenient way to fulfill other
+requirements (eg. real-time operations). Each backend offers a specific function
+to create a new 'modbus_t' context. The 'modbus_t' context is an opaque
+structure containing all necessary information to etablish a connection with
+others Modbus devices according to the selected variant.
+
+You can choose the best context for your needs among:
+
+RTU Context
+^^^^^^^^^^^
+The RTU backend (Remote Terminal Unit) is used in serial communication and makes
+use of a compact, binary representation of the data for protocol
+communication. The RTU format follows the commands/data with a cyclic redundancy
+check checksum as an error check mechanism to ensure the reliability of
+data. Modbus RTU is the most common implementation available for Modbus. A
+Modbus RTU message must be transmitted continuously without inter-character
+hesitations (extract from Wikipedia, Modbus, http://en.wikipedia.org/wiki/Modbus
+(as of Mar. 13, 2011, 20:51 GMT).
+
+Many Modbus devices can be connected together on the same physical link so you
+need to define which slave is concerned by the message with
+linkmb:modbus_set_slave[3]. If you're running a slave (server) the slave number
+is used to filter messages.
+
+Create a Modbus RTU context::
+ linkmb:modbus_new_rtu[3]
+
+TCP (IPv4) Context
+^^^^^^^^^^^^^^^^^^
+The TCP backend implements a Modbus variant used for communications over
+TCP/IPv4 networks. It does not require a checksum calculation as lower layer
+takes care of the same.
+
+Create a Modbus TCP context::
+ linkmb:modbus_new_tcp[3]
+
+
+TCP PI (IPv4 and IPv6) Context
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The TCP PI (Protocol Indepedent) backend implements a Modbus variant used for
+communications over TCP IPv4 and IPv6 networks. It does not require a checksum
+calculation as lower layer takes care of the same.
+
+Contrary to the TCP IPv4 only backend, the TCP PI backend offers hostname
+resolution but it consumes about 1Kb of additional memory.
+
+Create a Modbus TCP context::
+ linkmb:modbus_new_tcp_pi[3]
+
+
+Common
+^^^^^^
+Before using any libmodbus functions, the caller must allocate and initialize a
+'modbus_t' context with functions explained above, then the following functions
+are provided to modify and free a 'context':
+
+Free libmodbus context::
+ linkmb:modbus_free[3]
+
+Context setters and getters::
+ linkmb:modbus_set_debug[3]
+ linkmb:modbus_set_error_recovery[3]
+ linkmb:modbus_set_slave[3]
+ linkmb:modbus_get_timeout_begin[3]
+ linkmb:modbus_set_timeout_begin[3]
+ linkmb:modbus_get_timeout_end[3]
+ linkmb:modbus_set_timeout_end[3]
+ linkmb:modbus_get_header_length[3]
+
+A libmodbus 'context' is thread safe and may be shared among as many application
+threads as necessary, without any additional locking required on the part of the
+caller.
+
+
+Connection
+~~~~~~~~~~
+The following functions are provided to establish and close a connection with
+Modbus devices:
+
+Establish a connection::
+ linkmb:modbus_connect[3]
+
+Close a connection::
+ linkmb:modbus_close[3]
+
+Flush a connection::
+ linkmb:modbus_flush[3]
+
+
+Data
+~~~~
+The Modbus protocol defines different data types and functions to read and write
+them from/to remote devices.
+
+Read data::
+ linkmb:modbus_read_bits[3]
+ linkmb:modbus_read_input_bits[3]
+ linkmb:modbus_read_registers[3]
+ linkmb:modbus_read_input_registers[3]
+
+Write data::
+ linkmb:modbus_write_bit[3]
+ linkmb:modbus_write_register[3]
+ linkmb:modbus_write_bits[3]
+ linkmb:modbus_write_registers[3]
+
+
+ERROR HANDLING
+--------------
+The libmodbus functions handle errors using the standard conventions found on
+POSIX systems. Generally, this means that upon failure a libmodbus function
+shall return either a NULL value (if returning a pointer) or a negative value
+(if returning an integer), and the actual error code shall be stored in the
+'errno' variable.
+
+The _modbus_strerror()_ function is provided to translate libmodbus-specific
+error codes into error message strings; for details refer to
+linkmb:modbus_strerror[3].
+
+
+MISCELLANEOUS
+-------------
+The _LIBMODBUS_VERSION_STRING_ constant indicates the libmodbus version the
+program has been compiled against. The variables 'libmodbus_version_major',
+'libmodbus_version_minor', 'libmodbus_version_micro' give the version the
+program is linked against.
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>
+
+
+RESOURCES
+---------
+Main web site: <http://www.libmodbus.org/>
+
+Report bugs on the issue tracker at
+<http://github.com/stephane/libmodbus/issues>.
+
+
+COPYING
+-------
+Free use of this software is granted under the terms of the GNU Lesser General
+Public License (LGPL). For details see the files `COPYING` and `COPYING.LESSER`
+included with the libmodbus distribution.
Oops, something went wrong.

0 comments on commit 6254ede

Please sign in to comment.