examples/*: adding example binaries man page support

This commmit adds the build of man pages for the binaries from the
example/ folder, in detail these are coap-client.5, coap-rd.5 and
coap-server.5.
The source of the man pages is written in asciidoc so the build
environment must have access to a installed asciidoc package.
This commit is contained in:
Carsten Schoenert committed 2015-06-22 21:25:43 +02:00
1 parent cb55cb44da
commit 3e9afb1460
5 files changed
+358

No files matched your search

+3
View File
@@ -336,6 +336,9 @@ AC_CONFIG_FILES([
Makefile
doc/Makefile
examples/Makefile
examples/coap-client.txt
examples/coap-server.txt
examples/coap-rd.txt
include/coap/coap.h
tests/Makefile
libcoap-$LIBCOAP_API_VERSION.pc:libcoap-$LIBCOAP_API_VERSION.pc.in
+14
View File
@@ -23,4 +23,18 @@ coap_server_LDADD = @top_builddir@/.libs/libcoap-$(LIBCOAP_API_VERSION).la
coap_rd_SOURCES = coap-rd.c
coap_rd_LDADD = @top_builddir@/.libs/libcoap-$(LIBCOAP_API_VERSION).la
# building the manpages
TXT5 = coap-client.txt \
coap-rd.txt \
coap-server.txt
MAN5 = $(TXT5:%.txt=%.5)
man5_MANS = $(MAN5)
.txt.5:
a2x --doctype manpage --format manpage $<
CLEANFILES = *.5
endif # BUILD_EXAMPLES
+165
View File
@@ -0,0 +1,165 @@
// -*- mode:doc; -*-
// vim: set syntax=asciidoc,tw=0:
coap-client(5)
==============
:doctype: manpage
:man source: coap-client
:man version: @PACKAGE_VERSION@
:man manual: coap-client Manual
NAME
-----
coap-client - CoAP Client based on libcoap
SYNOPSIS
--------
*coap-client* [*-A* type1, _type2_ ,...] [*-t* type] [*-b* [num,]size]
[*-B* seconds] [*-e* text] [*-f* file] [*-m* method] [*-N*]
[*-o* file] [*-P* addr[:port]] [*-p* port] [*-s* duration]
[*-O* num,text] [*-T* token] [*-v* num] [*-a* addr] URI
DESCRIPTION
-----------
*coap-client* is a CoAP client to communicate with 6LoWPAN devices via
the protocol CoAP (RFC 7252) using the URI given as argument on the
command line. The URI must have the scheme 'coap' (or 'coaps' when
coap-client was built with support for secure communication). The URI's
host part may be a DNS name or a literal IP address. Note that, for
IPv6 address references, angle brackets are required (c.f. EXAMPLES).
OPTIONS
-------
*-a* addr::
The local address of the interface that has to be used.
*-b* [num,]size::
The block size to be used in GET/PUT/POST requests (value must be a
multiple of 16 not larger than 1024 as libcoap uses a fixed maximum
PDU size of 1400 bytes). If 'num' is present, the request
chain will start at block 'num'. When the server includes a Block2
option in its response to a GET request, coap-client will automatically
retrieve the subsequent block from the server until there are no more
outstanding blocks for the requested content.
*-e* text::
Include text as payload (use percent-encoding for non-ASCII characters).
*-f* file::
File to send with PUT/POST (use '-' for STDIN).
*-m* method::
The request method for action (get|put|post|delete), default is 'get'.
(Note that the string passed to *-m* is compared case-insensitive.)
*-o* file::
A filename to store data retrieved with GET.
*-p* port::
The port to listen on.
*-s* duration::
Subscribe to the resource specified by URI for the given 'duration' in
seconds.
*-t* type::
Content format for given resource for PUT/POST. 'type' must be either
a numeric value reflecting a valid CoAP content format or a string
describing a registered format. The following registered content format
descriptors are supported, with alternative shortcuts given in
parentheses:
text/plain (plain)
application/link-format (link, link-format)
application/xml (xml)
application/octet-stream (binary, octet-stream)
application/exi (exi)
application/json (json)
application/cbor (cbor)
*-v* num::
The verbosity level to use (default: 3, maximum is 9).
*-A* type::
Accepted media types as comma-separated list of symbolic or numeric
values, there are multiple arguments as comma separated list
possible. 'type' must be either a numeric value reflecting a valid
CoAP content format or a string that specifies a registered format as
described for option *-t*.
*-B* seconds::
Break operation after waiting given seconds (default is 90).
*-N* ::
Send NON-confirmable message. If option *-N* is not specified, a
confirmable message will be sent.
*-O* num,text::
Add option 'num' with contents of 'text' to the request.
*-P* addr[:port]::
Address (and port) for proxy to use (automatically adds Proxy-Uri option
to request).
*-T* token::
Include the 'token' to the request.
EXAMPLES
--------
* Example
----
coap-client coap://coap.me
----
Query resource '/' from server 'coap.me' (via the GET method).
* Example
----
coap-client -m get coap://[::1]/
----
Query on localhost via the 'GET' method.
* Example
----
coap-client -m get coap://[::1]/.well-known/core
----
Quite the same, except on the resource '.well-known/core' on localhost.
* Example
----
echo -n "mode=on" | coap-client -m put \
coap://[2001:db8:c001:f00d:221:2eff:ff00:2704]:5683/actuators/leds?color=r -f-
----
Send text 'mode=on' to resource 'actuators/leds?color=r' on the endpoint with
address '2001:db8:c001:f00d:221:2eff:ff00:2704' and port '5683'. Note that the
port '5683' is the default port and isn't really needed to append.
* Example
----
coap-client -m put coap://[fec0::3]/ck -T 3a -t binary -f to_upload
----
Put the contents of file 'to_upload' with content type 'binary' (i.e.
application/octet-stream) into resource 'ck' on 'fec0::3' by usage of a token
'3a' via the 'PUT' method.
FILES
------
There are no configuration files.
EXIT STATUS
-----------
*0*::
Success
*1*::
Failure (syntax or usage error; configuration error; document
processing failure; unexpected error)
BUGS
-----
Please report bugs on the mailing list for libcoap:
libcoap-developers@lists.sourceforge.net
AUTHORS
-------
The libcoap project <libcoap-developers@lists.sourceforge.net>
+88
View File
@@ -0,0 +1,88 @@
// -*- mode:doc; -*-
// vim: set syntax=asciidoc,tw=0:
coap-rd(5)
==========
:doctype: manpage
:man source: coap-rd
:man version: @PACKAGE_VERSION@
:man manual: coap-rd Manual
NAME
-----
coap-rd - A CoAP Resource Directory based on libcoap
SYNOPSIS
--------
*coap-rd* [*-A* addr] [*-g* group] [*-p* port] [*-v* num]
DESCRIPTION
-----------
*coap-rd* is a simple CoAP Resource Directory server that can handle resource
registrations using the protocol CoAP (RFC 7252).
OPTIONS
-------
*-A* addr::
The local address of the interface which the server has to listen.
*-g* group::
Join specified multicast 'group' on startup.
*-p* port::
The 'port' on the given address the server will be waitung for connections.
The default port is 5683 if not given any other value.
*-v* num::
The verbosity level to use (default: 3, maximum is 9).
EXAMPLES
--------
* Example
----
coap-rd -A ::1
----
Let the server listen on localhost (port 5683).
* Example
----
coap-rd -A ::1 -p 13011
----
Quite the same, except listening port is '13011' (and not the default port
5683).
* Example
----
coap-rd -A 2001:db8:81a8:0:6ef0:dead:feed:beef -v 5
----
The listening address is set to '2001:db8:81a8:0:6ef0:dead:feed:beef' and the
verbosity level is set to '5'.
* Example
----
coap-rd -A 2001:db8:81a8:0:6ef0:dead:feed:beef -g FF02:FD
----
Set listening address to '2001:db8:81a8:0:6ef0:dead:feed:beef' and join the
All CoAP Nodes multicast group 'FF02:FD'.
FILES
------
There are no configuration files.
EXIT STATUS
-----------
*0*::
Success
*1*::
Failure (syntax or usage error; configuration error; document
processing failure; unexpected error)
BUGS
-----
Please report bugs on the mailing list for libcoap:
libcoap-developers@lists.sourceforge.net
AUTHORS
-------
The libcoap project <libcoap-developers@lists.sourceforge.net>
+88
View File
@@ -0,0 +1,88 @@
// -*- mode:doc; -*-
// vim: set syntax=asciidoc,tw=0:
coap-server(5)
==============
:doctype: manpage
:man source: coap-server
:man version: @PACKAGE_VERSION@
:man manual: coap-server Manual
NAME
-----
coap-server - CoAP Server based on libcoap
SYNOPSIS
--------
*coap-server* [*-A* addr] [*-g* group] [*-p* port] [*-v* num]
DESCRIPTION
-----------
*coap-server* is a CoAP server which simulate 6LoWPAN devices which can be
addressed via the CoAP protocol.
OPTIONS
-------
*-A* addr::
The local address of the interface which the server has to listen.
*-g* group::
Join specified multicast 'group' on startup.
*-p* port::
The 'port' on the given address the server will be waitung for connections.
The default port is 5683 if not given any other value.
*-v* num::
The verbosity level to use (default: 3, maximum is 9).
EXAMPLES
--------
* Example
----
coap-server -A ::1
----
Let the server listen on localhost (port 5683).
* Example
----
coap-server -A ::1 -p 13011
----
Quite the same, except listening port is '13011' (and not the default port
5683).
* Example
----
coap-server -A 2001:db8:81a8:0:6ef0:dead:feed:beef -v 5
----
The listening address is set to '2001:db8:81a8:0:6ef0:dead:feed:beef' and the
verbosity level is set to '5'.
* Example
----
coap-server -A 2001:db8:81a8:0:6ef0:dead:feed:beef -g FF02:FD
----
Set listening address to '2001:db8:81a8:0:6ef0:dead:feed:beef' and join the
All CoAP Nodes multicast group 'FF02:FD'.
FILES
------
There are no configuration files.
EXIT STATUS
-----------
*0*::
Success
*1*::
Failure (syntax or usage error; configuration error; document
processing failure; unexpected error)
BUGS
-----
Please report bugs on the mailing list for libcoap:
libcoap-developers@lists.sourceforge.net
AUTHORS
-------
The libcoap project <libcoap-developers@lists.sourceforge.net>