From 3e9afb146043a94da25e0e8fc4bc6c03ebc7a2f1 Mon Sep 17 00:00:00 2001 From: Carsten Schoenert Date: Thu, 18 Jun 2015 20:30:03 +0200 Subject: [PATCH] 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. --- configure.ac | 3 + examples/Makefile.am | 14 +++ examples/coap-client.txt.in | 165 ++++++++++++++++++++++++++++++++++++ examples/coap-rd.txt.in | 88 +++++++++++++++++++ examples/coap-server.txt.in | 88 +++++++++++++++++++ 5 files changed, 358 insertions(+) create mode 100644 examples/coap-client.txt.in create mode 100644 examples/coap-rd.txt.in create mode 100644 examples/coap-server.txt.in diff --git a/configure.ac b/configure.ac index ca2af11f..cbb2cf88 100644 --- a/configure.ac +++ b/configure.ac @@ -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 diff --git a/examples/Makefile.am b/examples/Makefile.am index 535f752b..3df63f17 100644 --- a/examples/Makefile.am +++ b/examples/Makefile.am @@ -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 diff --git a/examples/coap-client.txt.in b/examples/coap-client.txt.in new file mode 100644 index 00000000..88117bda --- /dev/null +++ b/examples/coap-client.txt.in @@ -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 diff --git a/examples/coap-rd.txt.in b/examples/coap-rd.txt.in new file mode 100644 index 00000000..762609cf --- /dev/null +++ b/examples/coap-rd.txt.in @@ -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 diff --git a/examples/coap-server.txt.in b/examples/coap-server.txt.in new file mode 100644 index 00000000..c15741ef --- /dev/null +++ b/examples/coap-server.txt.in @@ -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