From d2fa9f315132bdb3134323c7d453a62a2681b136 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C5=99emysl=20Eric=20Janouch?= Date: Mon, 26 Oct 2020 17:01:43 +0100 Subject: [PATCH] Convert the manpage to AsciiDoc Writing DocBook XML by hand is an awful experience and the tools aren't much better. Asciidoctor does it well. There's no need to worry about semantics, man(1) just needs to be able to show something at all. This project's manpage is sadly almost useless right now. --- CMakeLists.txt | 31 ++++++++++------------- README.adoc | 2 +- docs/sdtui.1.adoc | 45 +++++++++++++++++++++++++++++++++ docs/sdtui.1.xml | 64 ----------------------------------------------- 4 files changed, 59 insertions(+), 83 deletions(-) create mode 100644 docs/sdtui.1.adoc delete mode 100644 docs/sdtui.1.xml diff --git a/CMakeLists.txt b/CMakeLists.txt index 8f011b7..0eddb7c 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -96,29 +96,24 @@ GETTEXT_CREATE_TRANSLATIONS ( ALL ${project_PO_FILES}) # Documentation -find_program (XSLTPROC_EXECUTABLE xsltproc) -if (NOT XSLTPROC_EXECUTABLE) - message (FATAL_ERROR "xsltproc not found") -endif (NOT XSLTPROC_EXECUTABLE) +find_program (ASCIIDOCTOR_EXECUTABLE asciidoctor) +if (NOT ASCIIDOCTOR_EXECUTABLE) + message (FATAL_ERROR "asciidoctor not found") +endif (NOT ASCIIDOCTOR_EXECUTABLE) -set (project_MAN_PAGES "${PROJECT_NAME}.1") -foreach (page ${project_MAN_PAGES}) +foreach (page "${PROJECT_NAME}.1") set (page_output "${PROJECT_BINARY_DIR}/${page}") - list (APPEND project_MAN_PAGES_OUTPUT "${page_output}") + list (APPEND project_MAN_PAGES "${page_output}") add_custom_command (OUTPUT ${page_output} - COMMAND ${XSLTPROC_EXECUTABLE} - --nonet - --param make.year.ranges 1 - --param make.single.year.ranges 1 - --param man.charmap.use.subset 0 - --param man.authors.section.enabled 0 - http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl - "${PROJECT_SOURCE_DIR}/docs/${page}.xml" - DEPENDS "docs/${page}.xml" + COMMAND ${ASCIIDOCTOR_EXECUTABLE} -b manpage + -a release-version=${PROJECT_VERSION} + "${PROJECT_SOURCE_DIR}/docs/${page}.adoc" + -o "${page_output}" + DEPENDS "docs/${page}.adoc" COMMENT "Generating man page for ${page}" VERBATIM) endforeach (page) -add_custom_target (docs ALL DEPENDS ${project_MAN_PAGES_OUTPUT}) +add_custom_target (docs ALL DEPENDS ${project_MAN_PAGES}) # Project libraries set (project_common_libraries ${ZLIB_LIBRARIES} ${icu_LIBRARIES} @@ -182,7 +177,7 @@ include (GNUInstallDirs) install (TARGETS ${PROJECT_NAME} DESTINATION ${CMAKE_INSTALL_BINDIR}) install (FILES LICENSE DESTINATION ${CMAKE_INSTALL_DOCDIR}) -foreach (page ${project_MAN_PAGES_OUTPUT}) +foreach (page ${project_MAN_PAGES}) string (REGEX MATCH "\\.([0-9])$" manpage_suffix "${page}") install (FILES "${page}" DESTINATION "${CMAKE_INSTALL_MANDIR}/man${CMAKE_MATCH_1}") diff --git a/README.adoc b/README.adoc index 81d72cb..476d1b5 100644 --- a/README.adoc +++ b/README.adoc @@ -30,7 +30,7 @@ a package with the latest development version from Archlinux's AUR. Building and Running -------------------- -Build dependencies: CMake, pkg-config, xsltproc, docbook-xsl + +Build dependencies: CMake, pkg-config, asciidoctor + Runtime dependencies: ncursesw, zlib, ICU, termo (included), glib-2.0, pango, xcb and xcb-xfixes (optional) diff --git a/docs/sdtui.1.adoc b/docs/sdtui.1.adoc new file mode 100644 index 0000000..af5e62d --- /dev/null +++ b/docs/sdtui.1.adoc @@ -0,0 +1,45 @@ +sdtui(1) +======== +:doctype: manpage +:manmanual: sdtui Manual +:mansource: sdtui {release-version} + +Name +---- +sdtui - StarDict terminal UI + +Synopsis +-------- +*sdtui* [_OPTION_]... [_DICTIONARY_.ifo]... + +Description +----------- +*sdtui* is a StarDict dictionary viewer custom tailored for viewing translation +dictionaries, using a simple curses-based terminal UI. + +The program expects to find on its command line the path to a dictionary's +_.ifo_ file, which contains further information required to load the dictionary. + +Some options as well as dictionaries to load on start-up by default can be +specified in a configuration file. See the README for an example. + +// FIXME: the README isn't even installed, so this manual isn't very useful + +Options +------- +*-h*, *--help*:: + Display a help message and exit. + +*-V*, *--version*:: + Output version information and exit. + +Files +----- +_~/.config/sdtui/sdtui.conf_:: + The configuration file, in which you can configure some settings, terminal + colours and the set of dictionaries to be loaded automatically on start-up. + +Reporting bugs +-------------- +Use https://git.janouch.name/p/sdtui to report bugs, request features, +or submit pull requests. diff --git a/docs/sdtui.1.xml b/docs/sdtui.1.xml deleted file mode 100644 index 393c95c..0000000 --- a/docs/sdtui.1.xml +++ /dev/null @@ -1,64 +0,0 @@ - - - - sdtui - sdtui - - Přemysl - Janouch - - - - - sdtui - 1 - User Commands - - - - sdtui - StarDict terminal UI - - - - - sdtui - - - - - dictionary.ifo - - - - -Description -sdtui is a StarDict dictionary viewer custom tailored -for viewing translation dictionaries, using a simple curses-based terminal UI. - -The program expects to find on its command line the path to a dictionary's -.ifo file, which contains further information required for loading the -dictionary. -Some options as well as dictionaries to load on start by default can be -specified in a configuration file. See the README for an example. - - -Options - - - , - - show help options - - - - - , - - output version information and exit - - - - - -