diff options
author | Gerald Combs <gerald@wireshark.org> | 2021-06-18 03:20:51 -0700 |
---|---|---|
committer | Wireshark GitLab Utility <gerald+gitlab-utility@wireshark.org> | 2021-10-01 16:42:34 +0000 |
commit | 84ab55cf752f96268dd67f54556e0423b78f979b (patch) | |
tree | 895b1f3b9be0d476a7e78ecce9e603b10a8802c3 /cmake/modules | |
parent | 9f1607ab473c578d714320fa735fb0bc4e1d1e96 (diff) |
Docs+Packaging: Convert our man pages to Asciidoctor.
Convert doc/*.pod to Asciidoctor. This:
* Means we use the same markup for our man pages, the guides, and
release notes.
* Lets us add versions to our man pages.
* Gives us more formatting options, e.g. AsciiDoc supports `commands`,
nested lists and makes it easy to include version information. The
manpage backend doesn't seem to support tables very well,
unfortunately.
Convert our CMake configuration to produce *roff and html man pages
using Asciidoctor. Add a "manarg" block macro which makes our synopses
wrap correctly.
Similar to the release notes, guides, and FAQ, if Asciidoctor isn't
found the man pages won't be generated or installed.
Move Asciidoctor to the list of package build dependencies in various
places.
This commit includes the conversion script (pod2adoc.py), which will be
removed later.
Line count sanity check:
Man page .pod .adoc
androiddump 260 280
asn2deb 93 105
capinfos 401 471
captype 54 55
ciscodump 241 269
dftest 42 42
dpauxmon 153 169
dumpcap 464 534
editcap 528 583
etwdump 136 156
extcap 157 181
idl2deb 91 103
idl2wrs 120 100
mergecap 206 207
mmdbresolve 75 75
randpkt 107 111
randpktdump 158 184
rawshark 558 610
reordercap 76 78
sdjournal 145 157
sshdump 272 302
text2pcap 274 312
tshark 2135 2360
udpdump 133 151
wireshark-filter 486 479
wireshark 2967 3420
Diffstat (limited to 'cmake/modules')
-rw-r--r-- | cmake/modules/FindAsciidoctor.cmake | 35 | ||||
-rw-r--r-- | cmake/modules/FindPOD.cmake | 84 |
2 files changed, 29 insertions, 90 deletions
diff --git a/cmake/modules/FindAsciidoctor.cmake b/cmake/modules/FindAsciidoctor.cmake index 32c610f1b7..3876d04754 100644 --- a/cmake/modules/FindAsciidoctor.cmake +++ b/cmake/modules/FindAsciidoctor.cmake @@ -39,12 +39,14 @@ if(ASCIIDOCTOR_EXECUTABLE) set (_asciidoctor_common_args # Doesn't work with AsciidoctorJ? # --failure-level=WARN + # --trace --attribute build_dir=${CMAKE_CURRENT_BINARY_DIR} - --require ${CMAKE_CURRENT_SOURCE_DIR}/asciidoctor-macros/ws_utils.rb - --require ${CMAKE_CURRENT_SOURCE_DIR}/asciidoctor-macros/commaize-block.rb - --require ${CMAKE_CURRENT_SOURCE_DIR}/asciidoctor-macros/cveidlink-inline-macro.rb - --require ${CMAKE_CURRENT_SOURCE_DIR}/asciidoctor-macros/wsbuglink-inline-macro.rb - --require ${CMAKE_CURRENT_SOURCE_DIR}/asciidoctor-macros/wssalink-inline-macro.rb + --require ${CMAKE_SOURCE_DIR}/docbook/asciidoctor-macros/ws_utils.rb + --require ${CMAKE_SOURCE_DIR}/docbook/asciidoctor-macros/commaize-block.rb + --require ${CMAKE_SOURCE_DIR}/docbook/asciidoctor-macros/cveidlink-inline-macro.rb + --require ${CMAKE_SOURCE_DIR}/docbook/asciidoctor-macros/manarg-block.rb + --require ${CMAKE_SOURCE_DIR}/docbook/asciidoctor-macros/wsbuglink-inline-macro.rb + --require ${CMAKE_SOURCE_DIR}/docbook/asciidoctor-macros/wssalink-inline-macro.rb ) set(_asciidoctor_common_command @@ -83,7 +85,7 @@ if(ASCIIDOCTOR_EXECUTABLE) unset(_output_xml) ENDMACRO() - # Currently single page only. + # Single page only, for the release notes and man pages. MACRO( ASCIIDOCTOR2HTML _asciidocsource ) GET_FILENAME_COMPONENT( _source_base_name ${_asciidocsource} NAME_WE ) set( _output_html ${_source_base_name}.html ) @@ -124,6 +126,27 @@ if(ASCIIDOCTOR_EXECUTABLE) unset(_output_txt) ENDMACRO() + # Single page only, for the release notes and man pages. + MACRO( ASCIIDOCTOR2MAN _asciidocsource _man_section) + GET_FILENAME_COMPONENT( _source_base_name ${_asciidocsource} NAME_WE ) + set( _output_man ${_source_base_name}.${_man_section} ) + + ADD_CUSTOM_COMMAND( + OUTPUT + ${_output_man} + COMMAND ${_asciidoctor_common_command} + --backend manpage + --out-file ${_output_man} + ${CMAKE_CURRENT_SOURCE_DIR}/${_asciidocsource} + DEPENDS + ${CMAKE_CURRENT_SOURCE_DIR}/${_asciidocsource} + ${ARGN} + ) + add_custom_target(generate_${_output_man} DEPENDS ${_output_man}) + set_asciidoctor_target_properties(generate_${_output_man}) + unset(_output_man) + ENDMACRO() + # news: release-notes.txt # ${CMAKE_COMMAND} -E copy_if_different release-notes.txt ../NEWS diff --git a/cmake/modules/FindPOD.cmake b/cmake/modules/FindPOD.cmake deleted file mode 100644 index 0233b5fc98..0000000000 --- a/cmake/modules/FindPOD.cmake +++ /dev/null @@ -1,84 +0,0 @@ -# -# - Find pod2man and pod2html. -# - -find_program(POD2MAN_EXECUTABLE - NAMES - pod2man - pod2man.bat - PATHS - /bin - /usr/bin - /usr/local/bin - /sbin -) - -find_program(POD2HTML_EXECUTABLE - NAMES - pod2html - pod2html.bat - PATHS - /bin - /usr/bin - /usr/local/bin - /sbin -) - -# handle the QUIETLY and REQUIRED arguments and set POD2HTML_FOUND to TRUE if -# all listed variables are TRUE -include(FindPackageHandleStandardArgs) -find_package_handle_standard_args(POD DEFAULT_MSG POD2MAN_EXECUTABLE POD2HTML_EXECUTABLE) - -mark_as_advanced( - POD2MAN_EXECUTABLE - POD2HTML_EXECUTABLE -) - -# run pod2man and pod2html -macro(pod2manhtml _sourcefile _manext) - get_filename_component(_basefile ${_sourcefile} NAME) - set(_outman ${_basefile}.${_manext}) - set(_outhtml ${_basefile}.html) - - add_custom_command( - OUTPUT - ${_outman} - COMMAND - ${PERL_EXECUTABLE} ${POD2MAN_EXECUTABLE} - --section=${_manext} - --center=\"The Wireshark Network Analyzer\" - --release=${PROJECT_VERSION} - ${_sourcefile}.pod - > ${_outman} - DEPENDS - ${_sourcefile}.pod - ) - - add_custom_command( - OUTPUT - ${_outhtml} - COMMAND - ${PERL_EXECUTABLE} ${POD2HTML_EXECUTABLE} - --title=\"${_basefile} - The Wireshark Network Analyzer ${CPACK_PACKAGE_VERSION}\" - --css=ws.css - --noindex - ${_sourcefile}.pod - > ${_outhtml} - DEPENDS - ${_sourcefile}.pod - ${CMAKE_SOURCE_DIR}/docbook/ws.css - ) -endmacro(pod2manhtml) - -# -# Editor modelines - https://www.wireshark.org/tools/modelines.html -# -# Local variables: -# c-basic-offset: 8 -# tab-width: 8 -# indent-tabs-mode: t -# End: -# -# vi: set shiftwidth=8 tabstop=8 noexpandtab: -# :indentSize=8:tabSize=8:noTabs=false: -# |