1# doc/Makefile.am 2# 3# Copyright (C) 2015-2018 Carsten Schoenert <c.schoenert@t-online.de> 4# 2018-2023 Jon Shallow <supjps-libcoap@jpshallow.com> 5# 6# SPDX-License-Identifier: BSD-2-Clause 7# 8# This file is part of the CoAP C library libcoap. Please see README and 9# COPYING for terms of use. 10 11 12# We can only perfom the targets in this directory if doxygen is present. 13 14CLEANFILES = \ 15 doxygen_sqlite3.db 16 17EXTRA_DIST = \ 18 docbook.local.css \ 19 upgrade_4.2.1_4.3.0.txt \ 20 upgrade_4.3.0_4.3.1.txt \ 21 upgrade_4.3.1_4.3.2.txt \ 22 upgrade_4.3.2_4.3.3.txt \ 23 upgrade_4.3.3_4.3.4.txt \ 24 main.md \ 25 module_api_wrap.h 26 27if HAVE_DOXYGEN 28 29man-page-cleanup: 30 @rm -f $(top_builddir)/doc/DoxygenLayout.xml 31 @rm -rf $(top_builddir)/doc/man_tmp 32 @rm -rf $(top_builddir)/doc/man_html 33 34man-page-prepare: man-page-cleanup 35 @$(MKDIR_P) $(top_builddir)/doc/man_tmp 36 @$(MKDIR_P) $(top_builddir)/doc/man_html 37 38man-page-start: man-page-prepare 39 ## Setup the man page tab 40 @echo '' > $(top_builddir)/doc/scratch_insert_file 41 @echo ' <tab type="usergroup" visible="yes" url="@ref manpage" title="Manual Pages">' > $(top_builddir)/doc/insert_file 42 @echo ' <tab type="usergroup" visible="yes" url="@ref man_summary" title="Man Pages Summary">' >> $(top_builddir)/doc/insert_file 43 ## 44 @echo '/** @page manpage Manual Pages' > $(top_builddir)/doc/man_tmp/manpage.dox 45 @echo ' Here are the libcoap API and Example manual pages:' >> $(top_builddir)/doc/man_tmp/manpage.dox 46 @echo ' <table class="directory">' >> $(top_builddir)/doc/man_tmp/manpage.dox 47 @echo " <tr>" >> $(top_builddir)/doc/man_tmp/manpage.dox 48 @echo " <td class=\"entry\" align=\"left\"> @ref man_summary </td><td class=\"desc\" align=\"left\">Man Pages Summary</td>" >> $(top_builddir)/doc/man_tmp/manpage.dox 49 @echo " </tr>" >> $(top_builddir)/doc/man_tmp/manpage.dox 50 @echo " <tr class=\"even\">" >> $(top_builddir)/doc/man_tmp/manpage.dox 51 @echo " <td class=\"entry\" align=\"left\"> @ref man_individual </td><td class=\"desc\" align=\"left\">Individual Man Pages</td>" >> $(top_builddir)/doc/man_tmp/manpage.dox 52 @echo " </tr>" >> $(top_builddir)/doc/man_tmp/manpage.dox 53 @echo " </table>" >> $(top_builddir)/doc/man_tmp/manpage.dox 54 @echo ' */' >> $(top_builddir)/doc/man_tmp/manpage.dox 55 ## 56 @echo '/** @page man_summary Manual Pages Summary' > $(top_builddir)/doc/man_tmp/man_summary.dox 57 @echo ' Here are a list of libcoap API summary man pages, some of which have code examples, and Examples:' >> $(top_builddir)/doc/man_tmp/man_summary.dox 58 @echo ' <table class="directory">' >> $(top_builddir)/doc/man_tmp/man_summary.dox 59 ## 60 @echo '/** @page man_individual Individual Manual Pages' > $(top_builddir)/doc/man_tmp/man_individual.dox 61 @echo ' Here are a list of libcoap API individual man pages, some of which have code examples:' >> $(top_builddir)/doc/man_tmp/man_individual.dox 62 @echo ' <table class="directory">' >> $(top_builddir)/doc/man_tmp/man_individual.dox 63 ## 64 ## Setup the upgrading tab 65 @echo '/** @page upgrading Upgrading' > $(top_builddir)/doc/man_tmp/upgrading.dox 66 @echo ' Upgrading between libcoap versions:' >> $(top_builddir)/doc/man_tmp/upgrading.dox 67 @echo ' <table class="directory">' >> $(top_builddir)/doc/man_tmp/upgrading.dox 68 69man-page-build: upg-page-build man-page-start 70 @MAN_FILES=`find $(top_srcdir)/man/ -type f -name "coap.txt.in" ; find $(top_srcdir)/man/ -type f -name "coap_*.in" | LC_ALL=C sort ; find $(top_srcdir)/man/ -type f -name "coap-*.in" | LC_ALL=C sort` ;\ 71 MAN3_FILES=`find $(top_srcdir)/man/ -type f -name "coap_*.in" | LC_ALL=C sort` ;\ 72 UPG_FILES=`find $(top_srcdir)/doc/ -type f -name "upgrade_*.txt" | LC_ALL=C sort` ;\ 73 HTML_FILES=`find $(top_builddir)/man/ -type f -name "*.html"` ;\ 74 COUNT_MAN_FILES=`echo $${MAN_FILES} | wc -w` ;\ 75 COUNT_HTML_FILES=`echo $${HTML_FILES} | wc -w` ;\ 76 ## We need the HTML files from the Asciidoc source files, check if they around, otherwise build them. 77 if [ "$${COUNT_MAN_FILES}" != "$${COUNT_HTML_FILES}" ]; then \ 78 $(MAKE) -C ../man ;\ 79 fi ;\ 80 ## 81 ## Build the summary man pages 82 ## 83 for FILE in $${MAN_FILES} ; do \ 84 BASE=`basename $${FILE} | cut -d. -f 1` ;\ 85 MANUAL=`egrep -B 1 "^====" $${FILE} | head -1` ;\ 86 SUMMARY=`egrep -B 2 "^SYNOPSIS" $${FILE} | ${SED} 's/coap-//g' | cut -d\- -f2 | cut -c2- | head -1` ;\ 87 if [ -z "$${SUMMARY}" ] ; then \ 88 SUMMARY=`egrep -B 2 "^DESCRIPTION" $${FILE} | ${SED} 's/coap-//g' | cut -d\- -f2 | cut -c2- | head -1` ;\ 89 fi ;\ 90 ## 91 ## Fix and copy .html file across 92 ## 93 if [ -f $(top_builddir)/man/$${BASE}.html ]; then \ 94 ## Correct case sensitive Name and Synopsis on master (used later) 95 $(SED) -i 's^<h2>Name</h2>^<h2>NAME</h2>^g' $(top_builddir)/man/$${BASE}.html ;\ 96 $(SED) -i 's^<h2>Synopsis</h2>^<h2>SYNOPSIS</h2>^g' $(top_builddir)/man/$${BASE}.html ;\ 97 cp -f $(top_builddir)/man/$${BASE}.html $(top_builddir)/doc/man_html/$${BASE}.html ;\ 98 else \ 99 echo "ERROR: $(top_builddir)/man/$${BASE}.html not found!";\ 100 exit 1 ;\ 101 fi ;\ 102 ## Build the manual insert page 103 echo "/// @page man_$${BASE} $${MANUAL}" > $(top_builddir)/doc/man_tmp/$${MANUAL}.dox ;\ 104 echo "/// @htmlinclude $${BASE}.html $${MANUAL}" >> $(top_builddir)/doc/man_tmp/$${MANUAL}.dox ;\ 105 ## Update insert_file (the list is sorted appropriately) 106 echo " <tab type=\"user\" visible=\"yes\" url=\"@ref man_$${BASE}\" title=\"$${MANUAL} - $${SUMMARY}\" intro=\"\"/>" >> $(top_builddir)/doc/insert_file ;\ 107 ## Update the summary man page 108 echo " <tr$${ROW_EVEN}>" >> $(top_builddir)/doc/man_tmp/man_summary.dox ;\ 109 echo " <td class=\"entry\" align=\"left\"> @ref man_$${BASE} </td><td class=\"desc\" align=\"left\">$${SUMMARY}</td>" >> $(top_builddir)/doc/man_tmp/man_summary.dox ;\ 110 echo " </tr>" >> $(top_builddir)/doc/man_tmp/man_summary.dox ;\ 111 if [ -z "$${ROW_EVEN}" ] ; then \ 112 ROW_EVEN=" class=\"even\"" ;\ 113 else \ 114 ROW_EVEN= ;\ 115 fi \ 116 done ;\ 117 ## 118 ## Close off the man page summary file 119 ## 120 echo ' </table>' >> $(top_builddir)/doc/man_tmp/man_summary.dox ;\ 121 echo ' */' >> $(top_builddir)/doc/man_tmp/man_summary.dox ;\ 122 echo ' </tab>' >> $(top_builddir)/doc/insert_file ;\ 123 ## 124 ## Build the individual man pages 125 ## 126 echo ' <tab type="usergroup" visible="yes" url="@ref man_individual" title="Individual Man Pages">' >> $(top_builddir)/doc/insert_file ;\ 127 for FILE in $${MAN3_FILES} ; do \ 128 BASE=`basename $${FILE} | cut -d. -f 1` ;\ 129 LIST=`${SED} -ne '/^NAME/,/^SYNOPSIS/p;/^SYNOPSIS/q' $${FILE} | ${SED} -ne '/coap_/{ s/ *, *//g ; p }' | egrep -v "^$${BASE}$$"` ;\ 130 for ENTRY in $${LIST} ; do \ 131 MANUAL="$${ENTRY}(3)" ;\ 132 ## Build the manual insert page 133 echo "/// @page man_$${ENTRY} $${MANUAL}" > $(top_builddir)/doc/man_tmp/$${MANUAL}.dox ;\ 134 echo "/// @htmlinclude $${ENTRY}.html $${MANUAL}" >> $(top_builddir)/doc/man_tmp/$${MANUAL}.dox ;\ 135 ## Create html file 136 cat $(top_builddir)/man/$${BASE}.html | ${SED} "s/Function: $${ENTRY}(/<a class=\"anchor\" id=\"$${ENTRY}\"><\/a>\0/" > $(top_builddir)/doc/man_html/$${ENTRY}.html ;\ 137 ## Update scratch_insert_file for sorting later 138 echo "$${ENTRY}" >> $(top_builddir)/doc/scratch_insert_file ;\ 139 done ;\ 140 done ;\ 141 ## 142 ## Process the (sorted) list of individual man pages 143 ## 144 for ENTRY in `cat $(top_builddir)/doc/scratch_insert_file | LC_ALL=C sort -u` ; do \ 145 ## Update the individual man page 146 MANUAL="$${ENTRY}(3)" ;\ 147 echo " <tab type=\"user\" visible=\"yes\" url=\"@ref man_$${ENTRY}\" title=\"$${MANUAL}\" intro=\"\"/>" >> $(top_builddir)/doc/insert_file ;\ 148 echo " <tr$${ROW_EVEN}>" >> $(top_builddir)/doc/man_tmp/man_individual.dox ;\ 149 echo " <td class=\"entry\" align=\"left\"> @ref man_$${ENTRY} </td><td class=\"desc\" align=\"left\"></td>" >> $(top_builddir)/doc/man_tmp/man_individual.dox ;\ 150 echo " </tr>" >> $(top_builddir)/doc/man_tmp/man_individual.dox ;\ 151 if [ -z "$${ROW_EVEN}" ] ; then \ 152 ROW_EVEN=" class=\"even\"" ;\ 153 else \ 154 ROW_EVEN= ;\ 155 fi \ 156 done ;\ 157 ## 158 ## Close off the individual man pages 159 ## 160 echo ' </table>' >> $(top_builddir)/doc/man_tmp/man_individual.dox ;\ 161 echo ' */' >> $(top_builddir)/doc/man_tmp/man_individual.dox ;\ 162 echo ' </tab>' >> $(top_builddir)/doc/insert_file ;\ 163 ## 164 ## Close off the man page top level 165 ## 166 echo ' </tab>' >> $(top_builddir)/doc/insert_file ;\ 167 ## 168 ## Add in the deprecated tab 169 ## 170 echo ' <tab type="user" visible="yes" url="@ref deprecated" title="Deprecated Items" intro=""/>' >> $(top_builddir)/doc/insert_file ;\ 171 ## 172 ## Start the upgrade tab 173 ## 174 echo ' <tab type="usergroup" visible="yes" url="@ref upgrading" title="Upgrading">' >> $(top_builddir)/doc/insert_file ;\ 175 for FILE in $${UPG_FILES} ; do \ 176 BASE=`basename $${FILE} | $(SED) "s/\.txt$$//g"`; \ 177 UPGRADE=`echo $${BASE} | $(SED) "s/^upgrade_//g"`; \ 178 CUPGRADE=`echo $${UPGRADE} | $(SED) "s/\./-/g"`; \ 179 SUMMARY=`head -1 $${FILE} | ${SED} 's/^= //g'` ;\ 180 ## Build the upgrade insert page 181 echo "/// @page upg_$${CUPGRADE} $${UPGRADE}" > $(top_builddir)/doc/man_tmp/$${UPGRADE}.dox ;\ 182 echo "/// @htmlinclude $${BASE}.html $${UPGRADE}" >> $(top_builddir)/doc/man_tmp/$${UPGRADE}.dox ;\ 183 ## Update insert_file 184 echo " <tab type=\"user\" visible=\"yes\" url=\"@ref upg_$${CUPGRADE}\" title=\"$${SUMMARY}\" intro=\"\"/>" >> $(top_builddir)/doc/insert_file ;\ 185 ## Update the upgrading page 186 echo " <tr$${ROW_EVEN}>" >> $(top_builddir)/doc/man_tmp/upgrading.dox ;\ 187 echo " <td class=\"entry\" align=\"left\"> @ref upg_$${CUPGRADE} </td><td class=\"desc\" align=\"left\">$${SUMMARY}</td>" >> $(top_builddir)/doc/man_tmp/upgrading.dox ;\ 188 echo " </tr>" >> $(top_builddir)/doc/man_tmp/upgrading.dox ;\ 189 if [ -z "$${ROW_EVEN}" ] ; then \ 190 ROW_EVEN=" class=\"even\"" ;\ 191 else \ 192 ROW_EVEN= ;\ 193 fi ;\ 194 if [ -f $(top_builddir)/doc/$${BASE}.html ]; then \ 195 cp -f $(top_builddir)/doc/$${BASE}.html $(top_builddir)/doc/man_html/$${BASE}.html ;\ 196 ## Correct case sensitive Name and Synopsis 197 $(SED) -i 's^<div class="toc"><p><strong>^<div class="section"><p><strong>^' $(top_builddir)/doc/man_html/$${BASE}.html ;\ 198 else \ 199 echo "ERROR: $(top_builddir)/doc/$${BASE}.html not found!";\ 200 exit 1 ;\ 201 fi \ 202 done ;\ 203 ## 204 ## Close off the upgrading tab 205 ## 206 echo ' </table>' >> $(top_builddir)/doc/man_tmp/upgrading.dox ;\ 207 echo ' */' >> $(top_builddir)/doc/man_tmp/upgrading.dox ;\ 208 ## 209 ## Close off the insert file list 210 ## 211 echo ' </tab>' >> $(top_builddir)/doc/insert_file ;\ 212 ## 213 ## Create and Update the DoxygenLayout.xml file 214 ## 215 $(DOXYGEN) -u > /dev/null 2>&1 ;\ 216 $(DOXYGEN) -l ;\ 217 $(SED) -i 's/<tab type="pages" visible="yes" /<tab type="pages" visible="no" /g' $(top_builddir)/doc/DoxygenLayout.xml ;\ 218 $(SED) -i '/<tab type="examples" visible=.*/r insert_file' $(top_builddir)/doc/DoxygenLayout.xml ;\ 219 ## 220 ## Fix up man html files, adding links 221 ## 222 for FILE in $${MAN_FILES} `cat $(top_builddir)/doc/scratch_insert_file` ; do \ 223 ENTRY=`basename $${FILE} | cut -d . -f1` ;\ 224 ## Functions defined in the body 225 $(SED) -i "s^\(<span class=\"strong\"><strong>\)\(coap[_-][0-9a-z_]*\)\(</strong></span>(\|(\)^\1<a class=\"st-desc\" href=\"man_\2.html#\2\" target=\"_self\">\2</a>\3^g" $(top_builddir)/doc/man_html/$${ENTRY}.html ;\ 226 ## Function definitions 227 $(SED) -i "s^\(<span class=\"strong\"><strong>Function: \)\(coap_[0-9a-z_]*\)\(</strong></span>(\|(\)^\1<a class=\"st-desc\" href=\"man_\2.html#\2\" target=\"_self\">\2</a>\3^g" $(top_builddir)/doc/man_html/$${ENTRY}.html ;\ 228 ## The SYNOPSIS entries 229 $(SED) -i "s^\(<p><span class=\"strong\"><strong>[a-z0-9_ \*]*\)\(coap_[0-9a-z_]*\)\([(;]\)^\1<a class=\"st-synopsis\" href=\"man_\2.html#\2\" target=\"_self\">\2</a>\3^g" $(top_builddir)/doc/man_html/$${ENTRY}.html ;\ 230 ## Function in NAME and Examples 231 $(SED) -i "s^\([ =,]\|[(!>]\|\^\)\(coap_[0-9a-z_]*\)\([(,]\| \-\| \xe2\x80\x94\)^\1<a href=\"man_\2.html#\2\" target=\"_self\">\2</a>\3^g" $(top_builddir)/doc/man_html/$${ENTRY}.html ;\ 232 ## Do for a second time in case of overlaps 233 $(SED) -i "s^\([ =,]\|[(!>]\|\^\)\(coap_[0-9a-z_]*\)\([(,]\| \-\| \xe2\x80\x94\)^\1<a href=\"man_\2.html#\2\" target=\"_self\">\2</a>\3^g" $(top_builddir)/doc/man_html/$${ENTRY}.html ;\ 234 done ;\ 235 ## 236 ## Do the highlighting 237 ## 238 for ENTRY in `cat $(top_builddir)/doc/scratch_insert_file` ; do \ 239 ${SED} -i "s/\($${ENTRY}\)\([<(\*, ]\)/<span class=\"man-highlight\">\1<\/span>\2/g" $(top_builddir)/doc/man_html/$${ENTRY}.html ;\ 240 done 241 242if BUILD_MANPAGES 243UPG_LIST = upgrade_4.2.1_4.3.0.txt upgrade_4.3.0_4.3.1.txt upgrade_4.3.1_4.3.2.txt upgrade_4.3.2_4.3.3.txt upgrade_4.3.3_4.3.4.txt 244 245upg-page-build: 246 @for FILE in $(UPG_LIST) ; do \ 247 $(A2X) -d article --format xhtml -D $(top_builddir)/doc/ $(top_srcdir)/doc/$${FILE} ;\ 248 done 249 250all: man-page-build 251 $(DOXYGEN) Doxyfile 252 @$(RM) $(top_builddir)/doc/insert_file $(top_builddir)/doc/scratch_insert_file 253 @cp -f $(top_srcdir)/doc/docbook.local.css $(top_builddir)/doc/html/docbook-xsl.css 254 255else 256# 257# Need to make sure the man directories are in place, but empty 258all: man-page-prepare 259 $(DOXYGEN) Doxyfile 260endif # BUILD_MANPAGES 261 262clean-local: 263 -rm -rf $(top_builddir)/doc/html $(top_builddir)/doc/man_tmp $(top_builddir)/doc/man_html $(top_builddir)/doc/DoxygenLayout.xml $(top_builddir)/doc/docbook-xsl.css $(top_builddir)/doc/*.html 264 265distclean-local: clean-local 266 267endif # HAVE_DOXYGEN 268 269install-data-hook: 270if HAVE_DOXYGEN 271 @if [ ! -d $(top_builddir)/doc/html ]; then \ 272 echo ;\ 273 echo " No install data in '$(top_builddir)/doc/html' found! Please run 'make all' first." ;\ 274 echo ;\ 275 exit 1 ;\ 276 fi 277 $(MKDIR_P) $(DESTDIR)$(htmldir)/html || exit 1 278 cp -a -f $(top_builddir)/doc/html $(DESTDIR)$(htmldir) 279 find $(DESTDIR)$(htmldir) -type f -name "*.md5" -delete 280endif # HAVE_DOXYGEN 281if BUILD_LICENSE_INSTALL 282 $(MKDIR_P) $(DESTDIR)$(docdir) || exit 1 283 $(INSTALL_DATA) $(top_srcdir)/LICENSE $(DESTDIR)$(docdir) 284 $(INSTALL_DATA) $(top_srcdir)/COPYING $(DESTDIR)$(docdir) 285 $(INSTALL_DATA) $(top_srcdir)/README $(DESTDIR)$(docdir) 286endif # BUILD_LICENSE_INSTALL 287 288uninstall-hook: 289if BUILD_LICENSE_INSTALL 290 @if [ -d $(DESTDIR)$(docdir) ] ; then \ 291 (cd $(DESTDIR)$(docdir) ; rm -f LICENSE README COPYING) ; \ 292 fi 293endif # BUILD_LICENSE_INSTALL 294if HAVE_DOXYGEN 295 -rm -rf $(DESTDIR)$(htmldir)/html 296endif # HAVE_DOXYGEN 297 298.PHONY: man-page-cleanup man-page-prepare man-page-start man-page-build 299