Add in man page support for the different exposed functions with examples #139

mrdeep1 · 2018-02-12T11:53:40Z

./configure now supports --enable-manpages (on by default) where man pages are built and installed as appropriate.

'man coap' provides an overview

coap_attribute, coap_context, coap_handler, coap_recovery, coap_resource and coap_tls_library are in this update

Potentially, coap_logging, coap_session and coap_io have still to be written, and possibly others.

tijuca

Please keep new entries in a alphabetical order to existing entries..

mrdeep1 · 2018-02-19T20:12:38Z

Do you mean new files added to be in an alphabetic order, or something else?

tijuca

Just some remarks, otherwise I'm fine with this PR.

tijuca · 2018-02-19T20:15:10Z

autogen.sh

@@ -27,6 +27,7 @@ depcomp
 doc/Doxyfile doc/doxyfile.stamp doc/doxygen_sqlite3.db doc/Makefile doc/Makefile.in
 examples/*.o  examples/coap-client examples/coap-server examples/coap-rd
 examples/coap-*.5 examples/coap-*.txt examples/Makefile.in
+man/Makefile man/Makefile.in man/coap_*.[37] man/coap_*.txt man/coap_*.xml


Please keep entries here in the alphabetical order.

tijuca · 2018-02-19T20:17:14Z

configure.ac

+man/coap_handler.txt
+man/coap_recovery.txt
+man/coap_resource.txt
+man/coap_tls_library.txt


Also here please keep a alphabetical order of AC_CONFIG_FILES.

tijuca · 2018-02-19T20:18:11Z

man/Makefile.am

@@ -0,0 +1,42 @@
+# examples/Makefile.am
+#
+# Copyright (C)      2015 Carsten Schoenert <c.schoenert@t-online.de>


I'd suggest you use your name for the copyright holder as you the author of the new file.

tijuca · 2018-02-19T20:20:58Z

I hate this webgui ...
So, now with some comments on some changes.

mrdeep1 · 2018-02-19T20:23:54Z

Understood - I will make changes and push shortly.

mrdeep1 · 2018-02-19T20:47:13Z

Changes made and pushed. There was some other legacy out of order which I left alone.
Any other comments?

tijuca · 2018-02-19T21:03:44Z

If ever possible avoid merge commits in pull requests, just rebase your changes on top of the devel branch instead and do a force push into your PR branch.

mrdeep1 · 2018-02-19T22:13:29Z

OK - apologies for not getting it right. So in principal I should do something like - correct?
(in fork mrdeep1, which gave me the original develop)
git checkout develop
(pull in latest obgm/develop)
git pull upstream/develop
git checkout man-pages
git rebase develop
(fix things as appropriate)
git push -f origin man-pages

tijuca · 2018-02-20T10:34:30Z

Yes. :-)
Just try is out. Git is smart enough to drop the merge commit(s) while doing the rebasing.

But I would also suggest here you do some more rebasing on your fixups and squash the fixups commits into the original commits.

mrdeep1 · 2018-02-20T12:30:34Z

I have done some rebasing and squash fixups, so that there is now only the original log entry for autogen.sh, configure.ac and man/Makefile.am. How does it look now?

tijuca · 2018-02-23T14:10:35Z

Then you have done something different than me. You should only see your patches on top of the devel branch an not any patches that are already exists on the branch devel.

mrdeep1 · 2018-02-23T14:33:40Z

I am pretty sure I did the following (upstream is obgm/libcoap/develop):

git checkout develop
git pull upstream develop
git checkout man-pages
git rebase develop
.. then a series of rebasing, squashing 2 commits into 1
git push origin man-pages.

I think that as there were other commits on obgm/develop between my initial commit and updated commit - when I squashed the 2 together all the interim commits were rebuilt and hence became a part of my "git push origin manpages".

Other than my local repository says the only 'git diff' are what I expect from my changes, I so far have not found out how to do this through this GUI.

Is it worth me trashing this pull request and take some time re-doing it from scratch?

tijuca · 2018-02-23T15:09:34Z

I've no idea what you have done as I've done exactly the same as you have written and I only had finally your patches in this branch in the end.
But any way, you don't need to do all from scratch you now can do again a rebasing and keep out all external commits that are not from you. That's one possibility, a second option would be to rename your branch (git branch -m man-pages-old), and create a new branch man-pages from the current head of the branch develop and do cherry-picking of the related commits afterwards.

mrdeep1 · 2018-02-23T17:19:04Z

I think that what is now pushed from my end looks better. I did a "github rebase -i develop" and removed the unwanted commits.

tijuca · 2018-02-24T08:29:01Z

Looks better now.
I haven't down own tests based (due lack of free time) on this PR but as this change set isn't interacting with the build of the binary stuff it should be o.k. if Olaf would merge this and we fix possible small side effects later. Thanks for adding the man pages!

mrdeep1 · 2018-02-24T11:10:22Z

Thanks. My only comment is that it describes some call backs / functions that have pull requests outstanding. If I get some more spare cycles, I will try to do some of theother missing man pages.

obgm · 2018-02-26T09:55:04Z

Thanks, @mrdeep1 and @tijuca, I will merge after the other outstanding PRs.

mrdeep1 · 2018-03-02T18:00:38Z

Updated for COAP_UNKNOWN_RESOURCE change in pull request #133

obgm · 2018-03-07T12:21:19Z

Can we move the subfolder man into doc? Manuals are documentation, after all.

obgm · 2018-03-07T12:23:13Z

man/coap_attribute.txt.in

+
+static void
+init_resources(coap_context_t *ctx)
+{ 


I would like the examples to follow the coding guidelines of libcoap. Here, this means that the block-opening parenthesis is at the end of the previous line.

As it happens, a2x does that anyway, but I will make the change. However, there have to be some blank lines to make things format, asthe a2x ' + ' fails tor work for me to start a new line.

mrdeep1 · 2018-03-07T12:34:15Z

I have seen man files being in the doc directory, man being in a separate directory from doc, but not man as a sub-directory of doc so far in other products.

I did not want to clutter the doc directory with the actual man pages, but can do this if you want.

obgm · 2018-03-07T12:50:30Z

Ok, not sure. @tijuca do you have any preference?

mrdeep1 · 2018-03-07T15:49:49Z

Updated with uri -> uri_path. Directory not changed.

obgm · 2018-04-05T09:12:52Z

Hm, it seems that the manual pages in man/ are built only if both, --enable-manpages and --enable-documentation are passed to configure (i.e., they are not built if any of these two is disabled). But although no manuals are build with configure --enable-manpages --disable-documentation, the configure script complains when a2x is not present. With configure --disable-manpages --enable-documentation, the manual pages in examples/ are built (which was the old behavior before --enable-manpages).

Maybe, we can make this a bit more consistent?
And we should probably move the manual pages from examples/ to man/?

mrdeep1 · 2018-04-05T09:53:53Z

Hi Olaf,

I will try to dis-entangle the documentation building requirements. Would you have any objection to --enable-documentation to being both --enable-manpages + (new) --enable-doxygen ?
--disable-documentation would then override any --enable-manpages / --enable-doxygen definitions - OK?

Sure - happy to move examples man pages to man. I will leave the names with a - seperator, instead of _ separator as I have had to do the the functions man pages.

obgm · 2018-04-05T10:03:26Z

Sounds good to me, thanks!

mrdeep1 · 2018-04-05T13:33:41Z

I believe that I have got this working as expected, and fixed a couple of typos along the way in the man pages

obgm · 2018-04-06T08:50:45Z

man/coap_attribute.txt.in

+*coap_attr_t *coap_find_attr(coap_resource_t *_resource_, const unsigned 
+char *_name_, size_t _nlen_);*
+
+Link with -lcoap-1.


We will run into trouble with burying the API number deep in the manual pages. How about something like

Link with -lcoap-@LIBCOAP_API_VERSION@.

in the respective .in files?

I had held off changing the -l entry as there is the potential that it could be -llibcoap-2-openssl, etc. as a set of alternatives if the library renaming patch goes ahead.

Easy enough to change it to -lcoap-@LIBCOAP_API_VERSION@ for now.

Oh, you are right. Usually pkg-config solves this but, of course, there are many platforms that do not have pkg-config.

Now -lcoap-@LIBCOAP_API_VERSION@in latest push

…setup

Also add in examples/Makefile

Create a new --enable-doxygen Make --enable-documentation include both --enable-manpages and --enable-doxygen and --disable-documentation include --disable-manpages and --disable-doxygen

…be ingored

Delete building man pages as they are now a part of the man directory

tijuca suggested changes Feb 19, 2018

View reviewed changes

tijuca reviewed Feb 19, 2018

View reviewed changes

mrdeep1 force-pushed the man-pages branch from c7b6b1a to 64773bd Compare February 20, 2018 12:21

mrdeep1 force-pushed the man-pages branch from 64773bd to a598796 Compare February 23, 2018 17:16

mrdeep1 force-pushed the man-pages branch from a598796 to 7005f1f Compare March 2, 2018 17:56

mrdeep1 force-pushed the man-pages branch 3 times, most recently from f96cc6f to 477bd84 Compare March 7, 2018 12:19

obgm reviewed Mar 7, 2018

View reviewed changes

mrdeep1 force-pushed the man-pages branch from 477bd84 to d90e531 Compare March 7, 2018 15:47

mrdeep1 force-pushed the man-pages branch 2 times, most recently from 55d8311 to 3b89f76 Compare April 4, 2018 10:21

mrdeep1 force-pushed the man-pages branch from 3b89f76 to f3e2f89 Compare April 5, 2018 13:32

obgm reviewed Apr 6, 2018

View reviewed changes

mrdeep1 added 4 commits April 6, 2018 10:49

man/coap.txt.in: New overview man page

ea30850

man/coap_attribute.txt.in: New man page covering attributes

ee6ede8

man/coap_context.txt.in: New man page convering contexts and session …

e15f881

…setup

man/coap_handler.txt.in: New man page covering handlers

3b9b5d2

mrdeep1 force-pushed the man-pages branch 2 times, most recently from 2a47888 to e6941cd Compare April 7, 2018 10:19

mrdeep1 added 11 commits April 7, 2018 11:34

man/coap_recovery.txt.in: New man page covering transmission recovery

4a655b9

man/coap_resource.txt.in: New man page covering resources

8b1fe26

man/coap_tls_library.txt.in: New man page covering TLS library support

c335c1e

Makefile.am: Add in man pages directory if man pages are being built

050833f

autogen.sh: add in built man files to AUTOGEN_FILES=

d766924

Also add in examples/Makefile

configure.ac: Add in man page building with --enable-manpages

d21e053

Create a new --enable-doxygen Make --enable-documentation include both --enable-manpages and --enable-doxygen and --disable-documentation include --disable-manpages and --disable-doxygen

man/Makefile.am: New Makefile for building and installing man pages

ebcf8dd

.gitignore: Add in man page temp files as well as src/ temp files to …

3f94f70

…be ingored

examples/Makefile.am: Remove building man pages

20cd610

Delete building man pages as they are now a part of the man directory

man/coap_observe.txt.in: New man page covering Observe usage

747205f

coap-{client|rd|server}.txt.in: Move from examples to man directory

d015c50

mrdeep1 force-pushed the man-pages branch from e6941cd to d015c50 Compare April 7, 2018 10:34

mrdeep1 mentioned this pull request Apr 7, 2018

How to make client retransmit its message #163

Closed

obgm mentioned this pull request Apr 9, 2018

configure: error: ==> Install the package containg a2x #164

Closed

obgm merged commit f889c29 into obgm:develop Apr 9, 2018

mrdeep1 deleted the man-pages branch April 9, 2018 12:06

Add in man page support for the different exposed functions with examples #139

Add in man page support for the different exposed functions with examples #139

Conversation

mrdeep1 commented Feb 12, 2018

tijuca left a comment

Choose a reason for hiding this comment

mrdeep1 commented Feb 19, 2018

tijuca left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tijuca commented Feb 19, 2018

mrdeep1 commented Feb 19, 2018

mrdeep1 commented Feb 19, 2018

tijuca commented Feb 19, 2018

mrdeep1 commented Feb 19, 2018

tijuca commented Feb 20, 2018

mrdeep1 commented Feb 20, 2018

tijuca commented Feb 23, 2018

mrdeep1 commented Feb 23, 2018

tijuca commented Feb 23, 2018

mrdeep1 commented Feb 23, 2018

tijuca commented Feb 24, 2018

mrdeep1 commented Feb 24, 2018

obgm commented Feb 26, 2018

mrdeep1 commented Mar 2, 2018

obgm commented Mar 7, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mrdeep1 commented Mar 7, 2018

obgm commented Mar 7, 2018

mrdeep1 commented Mar 7, 2018

obgm commented Apr 5, 2018

mrdeep1 commented Apr 5, 2018

obgm commented Apr 5, 2018

mrdeep1 commented Apr 5, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment