From e3746e49a117ebf8d1f43715554c5a1cf8d4a116 Mon Sep 17 00:00:00 2001 From: Christian Duerr Date: Sun, 28 May 2023 12:13:09 +0200 Subject: [PATCH] Move manpages to scdoc This rewrites the existing manpages to use the `scdoc` format, making it simpler to read and edit the manpages without intricate roff knowledge. Some minor changes to the manpages were made in the process, mostly focusing on correcting some of the wording. The list of maintainers has also changed to ensure people not involved in the project anymore aren't unnecessarily contacted for support. --- .editorconfig | 4 ++ .github/workflows/release.yml | 8 +-- CHANGELOG.md | 1 + INSTALL.md | 6 +-- extra/alacritty-msg.man | 64 ------------------------ extra/alacritty.man | 93 ----------------------------------- extra/man/alacritty-msg.1.scd | 59 ++++++++++++++++++++++ extra/man/alacritty.1.scd | 92 ++++++++++++++++++++++++++++++++++ 8 files changed, 163 insertions(+), 164 deletions(-) delete mode 100644 extra/alacritty-msg.man delete mode 100644 extra/alacritty.man create mode 100644 extra/man/alacritty-msg.1.scd create mode 100644 extra/man/alacritty.1.scd diff --git a/.editorconfig b/.editorconfig index 877f8a2e..d68a9a4d 100644 --- a/.editorconfig +++ b/.editorconfig @@ -16,3 +16,7 @@ indent_size = 2 [Makefile] indent_style = tab + +[*.scd] +indent_style = tab +tab_width = 4 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 1b911d96..ed417a65 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -67,13 +67,13 @@ jobs: - name: Install dependencies run: | sudo apt-get install cmake pkg-config libfreetype6-dev libfontconfig1-dev \ - libxcb-xfixes0-dev libxkbcommon-dev python3 + libxcb-xfixes0-dev libxkbcommon-dev python3 scdoc - name: Test run: cargo test --release - - name: Gzip manpage + - name: Generate manpages run: | - gzip -c "./extra/alacritty.man" > "./alacritty.1.gz" - gzip -c "./extra/alacritty-msg.man" > "./alacritty-msg.1.gz" + scdoc < extra/man/alacritty.1.scd | gzip -c > "./alacritty.1.gz" + scdoc < extra/man/alacritty-msg.1.scd | gzip -c > "./alacritty-msg.1.gz" - name: Upload Assets run: | mv ./extra/logo/alacritty-term.svg ./Alacritty.svg diff --git a/CHANGELOG.md b/CHANGELOG.md index 597334d9..52dbb9fc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). ### Packaging - Minimum Rust version has been bumped to 1.65.0 +- Manpages are now generated using `scdoc` (see `INSTALL.md`) ### Changed diff --git a/INSTALL.md b/INSTALL.md index 51bc4762..debe3f81 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -327,12 +327,12 @@ directory. ### Manual Page -Installing the manual page requires the additional dependency `gzip`. +Installing the manual page requires the additional dependencies `gzip` and `scdoc`. ```sh sudo mkdir -p /usr/local/share/man/man1 -gzip -c extra/alacritty.man | sudo tee /usr/local/share/man/man1/alacritty.1.gz > /dev/null -gzip -c extra/alacritty-msg.man | sudo tee /usr/local/share/man/man1/alacritty-msg.1.gz > /dev/null +scdoc < extra/man/alacritty.1.scd | gzip -c | sudo tee /usr/local/share/man/man1/alacritty.1.gz > /dev/null +scdoc < extra/man/alacritty-msg.1.scd | gzip -c | sudo tee /usr/local/share/man/man1/alacritty-msg.1.gz > /dev/null ``` ### Shell completions diff --git a/extra/alacritty-msg.man b/extra/alacritty-msg.man deleted file mode 100644 index 4c843899..00000000 --- a/extra/alacritty-msg.man +++ /dev/null @@ -1,64 +0,0 @@ -.TH ALACRITTY-MSG "1" "October 2021" "alacritty 0.13.0-dev" "User Commands" -.SH NAME -alacritty-msg \- Send messages to Alacritty -.SH "SYNOPSIS" -alacritty msg [OPTIONS] [MESSAGE_OPTIONS] -.SH DESCRIPTION -This command communicates with running Alacritty instances through a socket, -making it possible to control Alacritty without directly accessing it. -.SH "OPTIONS" -\fB\-s\fR, \fB\-\-socket\fR -Path for IPC socket creation -.SH "MESSAGES" -.TP -\fBcreate-window\fR -Create a new window in the same Alacritty process -.TP -.SH "\tOPTIONS" -.RS 12 -.TP -\fB\-\-hold\fR -Remain open after child process exits -.TP -\fB\-\-working\-directory\fR -Start the shell in the specified working directory -.TP -\fB\-e\fR, \fB\-\-command\fR ... -Command and args to execute (must be last argument) -.RE -.TP -\fBconfig\fR -Update the Alacritty configuration -.TP -.SH "\tARGS" -.RS 12 -.TP -\fB...\fR -Configuration file options [example: cursor.style=Beam] -.RE -.TP -.SH "\tOPTIONS" -.RS 12 -.TP -\fB\-w\fR, \fB\-\-window\-id\fR -Window ID for the new config. - -Use `-1` to apply this change to all windows. - -[default: \fB$ALACRITTY_WINDOW_ID\fR] -.RE -.SH "SEE ALSO" -See the alacritty github repository at https://github.com/alacritty/alacritty for the full documentation. -.SH "BUGS" -Found a bug? Please report it at https://github.com/alacritty/alacritty/issues. -.SH "MAINTAINERS" -.sp -.RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -.sp -1 -.IP \(bu 2.3 -.\} -Christian Duerr diff --git a/extra/alacritty.man b/extra/alacritty.man deleted file mode 100644 index d1472bfd..00000000 --- a/extra/alacritty.man +++ /dev/null @@ -1,93 +0,0 @@ -.TH ALACRITTY "1" "August 2018" "alacritty 0.13.0-dev" "User Commands" -.SH NAME -Alacritty \- A fast, cross-platform, OpenGL terminal emulator -.SH "SYNOPSIS" -alacritty [SUBCOMMANDS] [FLAGS] [OPTIONS] -.SH DESCRIPTION -Alacritty is a modern terminal emulator that comes with sensible defaults, but -allows for extensive configuration. By integrating with other applications, -rather than reimplementing their functionality, it manages to provide a flexible -set of features with high performance. -.SH "FLAGS" -.TP -\fB\-h\fR, \fB\-\-help\fR -Prints help information -.TP -\fB\-\-hold\fR -Remain open after child process exits -.TP -\fB\-\-print\-events\fR -Print all events to stdout -.TP -\fB\-q\fR -Reduces the level of verbosity (the min level is \fB\-qq\fR) -.TP -\fB\-\-ref\-test\fR -Generates ref test -.TP -\fB\-v\fR -Increases the level of verbosity (the max level is \fB\-vvv\fR) -.TP -\fB\-V\fR, \fB\-\-version\fR -Prints version information -.SH "OPTIONS" -.TP -\fB\-\-class\fR | , -Defines the window class hint on Linux [default: Alacritty,Alacritty] - -When only the general class is passed, instance will be set to the same value. - -On Wayland the general class sets the `app_id`, while the instance class is ignored. -.TP -\fB\-e\fR, \fB\-\-command\fR ... -Command and args to execute (must be last argument) -.TP -\fB\-\-config\-file\fR -Specify alternative configuration file - -Alacritty looks for the configuration file at the following paths: - 1. $XDG_CONFIG_HOME/alacritty/alacritty.yml - 2. $XDG_CONFIG_HOME/alacritty.yml - 3. $HOME/.config/alacritty/alacritty.yml - 4. $HOME/.alacritty.yml - -On Windows, the configuration file is located at %APPDATA%\\alacritty\\alacritty.yml. -.TP -\fB\-\-embed\fR -X11 window ID to embed Alacritty within (decimal or hexadecimal with "0x" prefix) -.TP -\fB\-o\fR, \fB\-\-option\fR