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

@@ -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

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)

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:

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()

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* _<message>_::
+Send a message as an emote, where your username is prefixed.
+
+*/react* _<text>_::
+Send a message as a reaction when you’re replying to a message.
+
+*/md* _<message>_::
+Force Markdown when sending the current message.
+
+*/plain* _<message>_::
+Force plain text when sending the current message.
+
+*/rainbow* _<message>_::
+Send a message in rainbow colors.
+
+*/rainbowme* _<message>_::
+Send a message as a rainbow-colored emote, where your username is prefixed.
+
+*/notice* _<message>_::
+Send a message as a notice.
+
+*/rainbownotice* _<notice>_::
+Send a message as a rainbow-colored notice.
+
+=== Room management
+
+*/join* _<roomname>_::
+Join a room.
+
+*/part*, */leave*::
+Leave the current room.
+
+*/invite* _<username>_::
+Invite a user into the current room.
+
+*/kick* _<username>_::
+Kick a user from the current room.
+
+*/ban* _<username>_::
+Ban a user from the current room.
+
+*/unban* _<username>_::
+Unban a user.
+
+*/roomnick* _<roomname>_::
+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>_::
+
+_address_ can be one of:
+
+    _<event ID>_;;
+    Jumpd to event with the specified ID and highlights it.
+
+    _<message index>_;;
+    Jumpd to the message with the specified index and highlights it.
+
+    _<Matrix URI>_;;
+    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
+<https://github.com/Nheko-Reborn/nheko/issues>.