From 3e8734dbd5614359b3de8e950c4f07d4802704db Mon Sep 17 00:00:00 2001 From: tastytea Date: Wed, 22 Dec 2021 22:34:07 +0100 Subject: [PATCH] Add man page (#851) This adds a man page which lists command line options, key bindings and commands. A new CMake option `MAN` is added, enabled by default on `UNIX` but not `APPLE`. The man pages are generated with either `a2x` (from asciidoc) or `asciidoctor`. If both are not found, a fatal error is signaled. --- .gitlab-ci.yml | 2 +- CMakeLists.txt | 9 ++ io.github.NhekoReborn.Nheko.yaml | 1 + man/CMakeLists.txt | 48 ++++++++ man/nheko.1.adoc.in | 196 +++++++++++++++++++++++++++++++ 5 files changed, 255 insertions(+), 1 deletion(-) create mode 100644 man/CMakeLists.txt create mode 100644 man/nheko.1.adoc.in diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 36253e1c..ea8d41c9 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -16,7 +16,7 @@ build-gcc9: - apt-get install -y software-properties-common - add-apt-repository ppa:ubuntu-toolchain-r/test -y - add-apt-repository ppa:beineri/opt-qt-5.15.2-focal -y - - apt-get update && apt-get -y install --no-install-recommends build-essential ninja-build qt${QT_PKG}{base,declarative,tools,multimedia,script,quickcontrols2,svg} liblmdb-dev libgl1-mesa-dev libssl-dev git ccache pkg-config libsecret-1-dev cmake + - apt-get update && apt-get -y install --no-install-recommends build-essential ninja-build qt${QT_PKG}{base,declarative,tools,multimedia,script,quickcontrols2,svg} liblmdb-dev libgl1-mesa-dev libssl-dev git ccache pkg-config libsecret-1-dev cmake asciidoc xsltproc # need recommended deps for wget - apt-get -y install wget - /usr/sbin/update-ccache-symlinks diff --git a/CMakeLists.txt b/CMakeLists.txt index 3fd8beb0..c945d094 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -5,6 +5,11 @@ option(CI_BUILD "Set when building in CI. Enables -Werror where possible" OFF) option(ASAN "Compile with address sanitizers" OFF) option(QML_DEBUGGING "Enable qml debugging" OFF) option(COMPILE_QML "Compile Qml. It will make Nheko faster, but you will need to recompile it, when you update Qt." OFF) +if(UNIX AND NOT APPLE) + option(MAN "Build man page" ON) +else() + option(MAN "Build man page" OFF) +endif() set( CMAKE_TOOLCHAIN_FILE "${CMAKE_CURRENT_LIST_DIR}/toolchain.cmake" @@ -739,6 +744,10 @@ if(NOT MSVC AND NOT HAIKU) endif() endif() +if(MAN) + add_subdirectory(man) +endif() + set_target_properties(nheko PROPERTIES CMAKE_SKIP_INSTALL_RPATH TRUE) if(UNIX AND NOT APPLE) diff --git a/io.github.NhekoReborn.Nheko.yaml b/io.github.NhekoReborn.Nheko.yaml index e61d7ec7..253ca1ed 100644 --- a/io.github.NhekoReborn.Nheko.yaml +++ b/io.github.NhekoReborn.Nheko.yaml @@ -199,6 +199,7 @@ modules: - -DCMAKE_BUILD_TYPE=Release - -DLMDBXX_INCLUDE_DIR=.deps/lmdbxx - -DCOMPILE_QML=ON + - -DMAN=OFF buildsystem: cmake-ninja name: nheko sources: diff --git a/man/CMakeLists.txt b/man/CMakeLists.txt new file mode 100644 index 00000000..aadeb15b --- /dev/null +++ b/man/CMakeLists.txt @@ -0,0 +1,48 @@ +# Uses either a2x from asciidoc or asciidoctor to compile the man page. + +include(GNUInstallDirs) + +configure_file("${PROJECT_NAME}.1.adoc.in" "${PROJECT_NAME}.1.adoc" @ONLY) + +find_program (ASCIIDOC_COMPILER a2x) +if (NOT ASCIIDOC_COMPILER) + find_program (ASCIIDOCTOR_COMPILER asciidoctor) + if(NOT ASCIIDOCTOR_COMPILER) + message(FATAL_ERROR + "Could not find asciidoc (a2x) or asciidoctor. " + "Man page generation not possible.") + endif() +endif() + +if(ASCIIDOC_COMPILER) + message(STATUS "Using asciidoc compiler at ${ASCIIDOC_COMPILER}") + + add_custom_command( + OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}.1" + WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}" + DEPENDS "${PROJECT_NAME}.1.adoc" + COMMAND "${ASCIIDOC_COMPILER}" + ARGS + "--doctype=manpage" + "--format=manpage" + "--no-xmllint" + "${PROJECT_NAME}.1.adoc") +endif() + +if(ASCIIDOCTOR_COMPILER) + message(STATUS "Using asciidoctor compiler at ${ASCIIDOCTOR_COMPILER}") + + add_custom_command( + OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}.1" + WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}" + DEPENDS "${PROJECT_NAME}.1.adoc" + COMMAND "${ASCIIDOCTOR_COMPILER}" + ARGS "--backend=manpage" "--doctype=manpage" "${PROJECT_NAME}.1.adoc") +endif() + +if(ASCIIDOC_COMPILER OR ASCIIDOCTOR_COMPILER) + add_custom_target(man ALL DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}.1") + + install(FILES ${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}.1 + DESTINATION ${CMAKE_INSTALL_MANDIR}/man1) +endif() diff --git a/man/nheko.1.adoc.in b/man/nheko.1.adoc.in new file mode 100644 index 00000000..399908a4 --- /dev/null +++ b/man/nheko.1.adoc.in @@ -0,0 +1,196 @@ += nheko(1) +:doctype: manpage +:Date: 2021-12-22 +:Revision: @PROJECT_VERSION@ +:man source: nheko +:man manual: General Commands Manual + +== NAME + +nheko - Desktop client for Matrix using Qt and C++17 + +== SYNOPSIS + +*nheko* [_OPTIONS_] + +== DESCRIPTION + +The motivation behind the project is to provide a native desktop app for Matrix +that feels more like a mainstream chat app (Element, Telegram etc) and less like +an IRC client. + +== OPTIONS + +*-h*, *--help*:: +Displays help on commandline options. + +*--help-all*:: +Displays help including Qt specific options. + +*-v*, *--version*:: +Displays version information. + +*--debug*:: +Enables debug output. + +*-p*, *--profile*:: +Creates a unique profile, which allows you to log into several accounts at the +same time and start multiple instances of nheko. + +== Keyboard shortcuts + +=== Room list + +*Ctrl-Up/Ctrl-Down*:: +Navigate within the room list. + +*Ctrl-K*:: +Search and select rooms from the room list. + +*Alt-A*, *Ctrl-Shift-A*:: +Select next room with activity. + +=== Timeline/Messaging + +*PgUp/PgDn*:: +Scroll timeline per page. + +*Alt-Up/Alt-Down*:: +Reply to a message. + +*Up/Down*:: +Edit a message. + +*Ctrl-E*:: +Edit message currently selected as reply. + +*Alt-F*:: +Forward message currently selected as reply. + +*Ctrl-P/Ctrl-N*:: +Reenter previous/next message. + +*Ctrl-U*:: +Delete everything in the input line. + +*Ctrl-Left/Ctrl-Right*:: +Jump one word left/right in the input line. + +*Shift-Enter*:: +Insert line break. + +*Enter*:: +Submit message. + +== Commands + +=== Custom messages + +*/me* __:: +Send a message as an emote, where your username is prefixed. + +*/react* __:: +Send a message as a reaction when you’re replying to a message. + +*/md* __:: +Force Markdown when sending the current message. + +*/plain* __:: +Force plain text when sending the current message. + +*/rainbow* __:: +Send a message in rainbow colors. + +*/rainbowme* __:: +Send a message as a rainbow-colored emote, where your username is prefixed. + +*/notice* __:: +Send a message as a notice. + +*/rainbownotice* __:: +Send a message as a rainbow-colored notice. + +=== Room management + +*/join* __:: +Join a room. + +*/part*, */leave*:: +Leave the current room. + +*/invite* __:: +Invite a user into the current room. + +*/kick* __:: +Kick a user from the current room. + +*/ban* __:: +Ban a user from the current room. + +*/unban* __:: +Unban a user. + +*/roomnick* __:: +Change your nickname in a single room. + +=== Emoticons + +*/shrug*:: +Inserts `¯\_(ツ)_/¯` + +*/fliptable*:: +Inserts `(╯°□°)╯︵ ┻━┻` + +*/unfliptable*:: +Inserts `┯━┯╭( º _ º╭)` + +*/sovietflip*:: +Inserts `ノ┬─┬ノ ︵ ( \\o°o)\\` + +=== Advanced + +*/clear-timeline*:: +Removes all but the most recent messages from the currently rendered timeline +and then refetches it from the server; can be used to fix some cache issues. + +*/rotate-megolm-session*:: +Rotates the encryption key used to send encrypted messages in a room. + +*/goto* _
_:: + +_address_ can be one of: + + __;; + Jumpd to event with the specified ID and highlights it. + + __;; + Jumpd to the message with the specified index and highlights it. + + __;; + Handles Matrix URI as if you clicked on it. + +*/converttodm*:: +Converts a room to a direct conversation. + +*/converttoroom*:: +Converts a direct conversation to a normal room. + +== FILES + +*Configuration file*:: +`${XDG_CONFIG_HOME:-~/.config}/nheko/nheko.conf` + +*Log file*:: +`${XDG_CACHE_HOME:-~/.cache}/nheko/nheko/nheko.log` + +*Database*:: +`${XDG_DATA_HOME:-~/.local/share}/nheko/nheko/*/data.mdb` + +*Media cache*:: +`${XDG_CACHE_HOME:-~/.cache}/nheko/nheko/media_cache` + + +== REPORTING BUGS + +Please report issues on our bug tracker at +.