Knowledge Bits - Software

Retrieving Logs for a Single Service Run from systemd

2026-05-10T00:00:00-04:00

systemd is the init system and service manager (and a bunch of other things) used by many major Linux distributions. As a service manager, it provides the ability to run programs (called services) in the background with features like restarting failed programs or running programs on a schedule. By default (i.e., unless a service’s unit file says to send it somewhere else), the output from these programs is stored in a journal that can be viewed with the journalctl(1) command. However, basic journalctl(1) invocations have the potential to swamp you with logs; sometimes you just want to see the output from a single run of a service or see a history of when a service was started & stopped. Here’s how you do that.

This article is based on systemd 255 on Ubuntu Noble 24.04. There may be some corner cases I have missed that make what I say here not 100% accurate.

Basic `journalctl(1)` Usage

By default, a given user only has permission to read journal entries for their own per-user systemd service manager. In order to read the system journal or other users’ journals, you must be root (possibly via sudo) or belong to the systemd-journal, adm, or wheel group.

Important

Journal entries do not last forever; you only have so much disk space, after all. Depending on configuration, the journal service will delete old entries if they reach a certain age or if the total size of the journal reaches a certain limit. You therefore might not be able to retrieve information from the journal about things that happened too long ago.

You can get a basic view of all the journal entries for a service by running journalctl -u $service, where $service is the name of the service with or without the “.service” suffix. Add the --user option if the service belongs to your per-user manager. The entries shown can be limited with the -n/--lines, --since, and --until options, among others; see the journalctl(1) manpage for more information.

By default, the output from journalctl is a chronological sequence of both systemd-generated messages (things like “Starting myservice.service”) and service-generated messages (such as standard output from the service commands). Each line consists of a timestamp, a hostname, a command name, a PID, and the actual message. The -o/--output option can be used to adjust the output format, though most formats only differ in how the timestamp is displayed.

Internally, each entry in systemd’s journal consists of a number of key-value pairs called fields that include data on the logged message, when it was emitted, and where it came from. Most of the fields are documented in systemd.journal-fields(7), and you can output all fields of journal entries by passing -o json (or -o json-pretty or another supported JSON format) or -o verbose to journalctl.

journalctl entries can be filtered based on field values by passing the command one or more match arguments of the form FIELDNAME=VALUE. Note that only exact string matches on values are supported; you cannot ask journalctl to filter, say, by a regex or by whether a field is set/unset; for that, postprocessing the output with jq(1) or another program is necessary. Multiple match arguments for the same field name are ORed together, while match arguments for different fields are ANDed. Using + as an argument causes the preceding match arguments to be ORed as a group against the following match arguments.

Systemd vs. Service Entries

When working with a service’s journal logs, there are two main types of entries that we usually want to discern between: entries emitted by systemd itself about the service — usually messages of the form “Starting myservice.service”, “Stopped myservice.service”, etc. — and entries that contain output from the service’s actual command(s).

Entries from systemd itself about a service are distinguished by having the INVOCATION_ID field (or USER_INVOCATION_ID for user services) set but not _SYSTEMD_INVOCATION_ID; the SYSLOG_IDENTIFIER field will also have a value of “systemd”. The UNIT field (or USER_UNIT for user services) will also be set to the name of the service in question (including template arguments and the “.service” suffix).

Caution!

Field names without leading underscores are not “trusted” journal fields, and thus any program that writes directly to the journal can create an entry with INVOCATION_ID, SYSLOG_IDENTIFIER, or UNIT set to whatever it wants. In order to exclude any potential deceptive entries when using journalctl to filter by one or more of these fields, include _PID=1 as a match argument so that you only see entries from systemd itself. Note that this only works when querying the system manager; for user managers, there does not seem to be a foolproof way to say “only show entries generated by the manager.”

Entries for actual output from a service’s commands (including child commands) are distinguished by having the _SYSTEMD_INVOCATION_ID field set, but not INVOCATION_ID or USER_INVOCATION_ID. The _SYSTEMD_UNIT field (or _SYSTEMD_USER_UNIT for user services) will also be set to the name of the service in question (including template arguments and the “.service” suffix).

Note that the latter kind of entries don’t just cover the service’s stdout & stderr; if the service command logged anything via syslog or wrote to the journal directly, that’s in here, too. You can separate out these sources by filtering on the _TRANSPORT field, which has a value of “stdout” for the command’s standard output & standard error (and for input to systemd-cat(1)), “syslog” for syslog messages, and “journal” for messages written directly to the journal with the sd_journal_print(3) APIs.

You may be wondering about the value of the SYSLOG_IDENTIFIER mentioned above when it comes to command output entries. As far as I can determine, when _TRANSPORT is “stdout” or “journal”, SYSLOG_IDENTIFIER is usually the filename of the executable that produced the message, except for messages produced with systemd-cat, which use the identifier specified on the command line with --identifier, leaving the field unset if the option is not given. For _TRANSPORT=syslog, SYSLOG_IDENTIFIER is the program name by default, but programs that write to syslog are free to use any string they want as their identifier.

Invocation IDs

As you may have noticed above, journal entries related to a service run all have an invocation ID associated with them. Each invocation ID is a random 32-character hexadecimal string that identifies a specific runtime cycle of a service (the period between when the service changes from “inactive” to “active”/”activating” and when it becomes inactive again). An invocation ID is the key information needed to get the logs for a single service run from journalctl.

If you want to view the logs for the most-recently started run of a service, begin by getting that run’s invocation ID via:

systemctl show --no-pager -P InvocationID $service

Replace $service with the name of the service in question (with or without the “.service” suffix). If querying a user session unit, add --user to the command. If the service has stopped and not been restarted, this command will nevertheless output the invocation ID for the most recent (stopped) run. If the given service does not exist or was never started, the command will output a blank line.

If the run you want logs for is not the most recent, you’ll need to determine the run’s invocation ID by looking back through the journal for the service. If you just know the approximate time at which the desired run occurred, you can browse the “Starting $service.service” and “Stopped $service.service” systemd messages with their timestamps & corresponding invocation IDs by using jq(1) and the following shell command:

journalctl -o json -t systemd -u $service | jq -r '"[\(.__REALTIME_TIMESTAMP|tonumber / 1000000 | todate)] [\(.INVOCATION_ID)] \(.MESSAGE)"'

Replace $service with the name of the service in question (with or without the “.service” suffix). If querying a user session unit, add --user to the journalctl command and change .INVOCATION_ID in the jq command to .USER_INVOCATION_ID.

This will give you output like the following, letting you map timestamp ranges to invocation IDs:

[2026-04-22T13:41:35Z] [439e459b1db44a97974eae5c133f4543] Starting apache2.service - The Apache HTTP Server...
[2026-04-22T13:41:36Z] [439e459b1db44a97974eae5c133f4543] Started apache2.service - The Apache HTTP Server.
[2026-04-23T00:00:00Z] [439e459b1db44a97974eae5c133f4543] Reloading apache2.service - The Apache HTTP Server...
[2026-04-23T00:00:00Z] [439e459b1db44a97974eae5c133f4543] Reloaded apache2.service - The Apache HTTP Server.
[2026-04-24T00:00:00Z] [439e459b1db44a97974eae5c133f4543] Reloading apache2.service - The Apache HTTP Server...
[2026-04-24T00:00:00Z] [439e459b1db44a97974eae5c133f4543] Reloaded apache2.service - The Apache HTTP Server.
[2026-04-26T00:00:00Z] [439e459b1db44a97974eae5c133f4543] Reloading apache2.service - The Apache HTTP Server...
[2026-04-26T00:00:01Z] [439e459b1db44a97974eae5c133f4543] Reloaded apache2.service - The Apache HTTP Server.
[2026-04-27T00:00:01Z] [439e459b1db44a97974eae5c133f4543] Reloading apache2.service - The Apache HTTP Server...
[2026-04-27T00:00:01Z] [439e459b1db44a97974eae5c133f4543] Reloaded apache2.service - The Apache HTTP Server.
[2026-05-07T16:19:39Z] [439e459b1db44a97974eae5c133f4543] Stopping apache2.service - The Apache HTTP Server...
[2026-05-07T16:19:40Z] [439e459b1db44a97974eae5c133f4543] apache2.service: Deactivated successfully.
[2026-05-07T16:19:40Z] [439e459b1db44a97974eae5c133f4543] Stopped apache2.service - The Apache HTTP Server.
[2026-05-07T16:19:40Z] [439e459b1db44a97974eae5c133f4543] apache2.service: Consumed 8min 45.667s CPU time, 111.8M memory peak, 22.5M memory swap peak.
[2026-05-07T16:19:40Z] [c80c7d5e0453447ea57bf833b3ead2cf] Starting apache2.service - The Apache HTTP Server...
[2026-05-07T16:19:40Z] [c80c7d5e0453447ea57bf833b3ead2cf] Started apache2.service - The Apache HTTP Server.
[2026-05-08T00:00:00Z] [c80c7d5e0453447ea57bf833b3ead2cf] Reloading apache2.service - The Apache HTTP Server...
[2026-05-08T00:00:01Z] [c80c7d5e0453447ea57bf833b3ead2cf] Reloaded apache2.service - The Apache HTTP Server.
[2026-05-09T00:00:01Z] [c80c7d5e0453447ea57bf833b3ead2cf] Reloading apache2.service - The Apache HTTP Server...
[2026-05-09T00:00:01Z] [c80c7d5e0453447ea57bf833b3ead2cf] Reloaded apache2.service - The Apache HTTP Server.
[2026-05-10T00:00:00Z] [c80c7d5e0453447ea57bf833b3ead2cf] Reloading apache2.service - The Apache HTTP Server...
[2026-05-10T00:00:00Z] [c80c7d5e0453447ea57bf833b3ead2cf] Reloaded apache2.service - The Apache HTTP Server.

If you don’t know the run’s timestamp but you can recognize the target run from the command output, you can view all log messages prefixed with their invocation IDs like so:

journalctl -o json -u $service | jq -r '"[\(.INVOCATION_ID // ._SYSTEMD_INVOCATION_ID)] \(.MESSAGE)"'

Getting Logs for an Invocation ID

Once you have the invocation ID for the service run you want to view logs for, you can get the service’s output with:

journalctl _SYSTEMD_INVOCATION_ID=$id

where $id is replaced by the invocation ID. Note that there is no need to specify the service name, nor even to specify --user for user session units.

Note that the output from this command will include fields like timestamp, hostname, command name, and PID in each line. If you just want only the actual output from the service with no “decorations,” add -o cat to the command. If you want custom formatting, your best bet is to output all the journal fields with -o json and process the entries with jq or another program.

If you also want to include systemd’s “Starting”, “Stopped”, etc. messages in the output (say, in order to see the command’s exit status), change the match arguments like so:

journalctl INVOCATION_ID=$id + _SYSTEMD_INVOCATION_ID=$id

If querying a user session unit, change INVOCATION_ID to USER_INVOCATION_ID.

The BitTorrent Encryption Protocol

2023-10-19T00:00:00-04:00

The encryption protocol used by the BitTorrent peer-to-peer file-sharing protocol — known variously as Message Stream Encryption (MSE), Protocol Encryption (PE), or MSE/PE, among other names — is what keeps you secure while you download massive amounts of … Linux ISOs. While some (including the creator of BitTorrent) have been critical of the protocol, comparing it to mere “obfuscation,” it remains highly popular among users distributing perfectly legitimate files over the internet that ISPs shouldn’t concern themselves over.

The de facto specification for the protocol appears to be <https://wiki.vuze.com/w/Message_Stream_Encryption>, but the page has been down whenever I’ve checked recently, and the actual content is not optimally presented. Thus, I’ve written up everything I’ve been able to determine about MSE/PE here.

Contents

Overview
Definitions
Client’s Handshake
Server’s Handshake
After the Handshake
BitTorrent-Specific Aspects
- Detecting Encryption
- Broadcasting Encryption Support
References

Overview

An MSE/PE connection begins with the client and server performing a Diffie–Hellman key exchange handshake, in which each party generates a private key with corresponding public key, the public keys are exchanged, and then — by the power of mathematics — both parties independently calculate the same number (the shared secret), which remains unknown to eavesdroppers. Each party then uses the shared secret to initialize two keystreams: infinite generators of pseudo-random bytes calculated from an initial value; the bytes from one keystream are then used to encrypt & decrypt data sent from the client to the server, and the other keystream is used for data sent from the server to the client.

After the handshake, the parties transmit their data, which is encrypted using a method negotiated during the handshake; the only defined options are to keep using the keystreams or to stop using encryption entirely.

Definitions

MSE/PE encryption uses the following constants and functions:

P is the following 96-byte (768-bit) prime, here rendered in hexadecimal:

ffffffffffffffff c90fdaa22168c234  c4c6628b80dc1cd1 29024e088a67cc74
020bbea63b139b22 514a08798e3404dd  ef9519b3cd3a431b 302b0a6df25f1437
4fe1356d6d51c245 e485b576625e7ec6  f44c42e9a63a3621 0000000000090563

G is 2 (a primitive root modulo P).
SKEY is a shared key — a byte string with a value known or recognizable by both parties. For BitTorrent, this is the 20-byte info hash of the torrent the connection is dedicated to.
len(X) is the length of the byte string X as a two-byte big-endian integer. The length of X cannot exceed 65535.
HASH(X) is the 20-byte SHA1 hash of the byte string X.

Client’s Handshake

The peer initiating an MSE/PE connection performs its side of the handshake as follows as soon as it opens the connection:

The client generates a random integer Xa to use as its private key for this connection only. Xa must be at least 128 bits long; using more than 180 bits is not believed to add further security. 160 bits is recommended.
The client calculates its public key: Ya = pow(G, Xa) mod P.
The client sends packet 1: Ya encoded as a 96-byte (768-bit) big-endian integer, followed by a string of random bytes with a randomly-chosen length from 0 to 512.
The client receives packet 2. Because the length of this packet is not known by the client and there is no means for indicating the end of the packet, the client must identify the end of the packet by waiting for sufficient time (the original spec says 30 seconds) for the entire packet to arrive. If the server sends fewer than 96 bytes in that time (For comparison, the unencrypted BitTorrent handshake message is 68 bytes), or the server sends more than 608 bytes, then the server is not performing a valid MSE/PE handshake.
The client extracts Yb from the first 96 bytes of packet 2 and computes the Diffie-Hellman shared secret: S = pow(Yb, Xa) mod P. Xa is then securely discarded.
- When used as a byte string in later steps, S is encoded as a 96-byte (768-bit) big-endian integer.
The client initializes an outgoing RC4 keystream from the key HASH("keyA" + S + SKEY) and an incoming RC4 keystream from the key HASH("keyB" + S + SKEY). The first 1024 bytes output by each keystream are discarded.
The client sends packet 3, constructed as follows:
```
HASH("req1" + S)
+ (HASH("req2" + SKEY) XOR HASH("req3" + S))
+ RC4(VC + crypto_provide + len(PadC) + PadC + len(IA) + IA)
```
where:
- RC4(X) encrypts the byte string X by XORing it with bytes produced by the outgoing RC4 keystream.
- VC is a verification constant of eight zero-valued bytes that is used to verify whether the other party knows S and SKEY and thus defeat replay attacks of the SKEY hash.
- crypto_provide is a 32-bit big-endian integer in which individual bits are set to indicate the encryption methods supported by the client. The defined methods are plain text (bit 0x01) and RC4 (bit 0x02).
- PadC is arbitrary data with a length of 0 to 512 bytes, reserved for extending the crypto handshake in future versions. Current implementations may choose to set it to the empty string. For padding-only usage in the current version, the bytes should be zeroed.
- IA is the initial (post-handshake) data that the client wishes to send. It may be 0 bytes long, and it cannot be more than 65535 bytes long.
The client receives & verifies packet 4:
- The first eight bytes are received and decrypted by XORing them with bytes from the incoming RC4 keystream. If the resulting bytes are not all zero, the handshake is invalid.
- The next four bytes are received and decrypted in the same manner to obtain crypto_select, a big-endian integer in which a bit corresponding to one of the methods given in crypto_provide has been set in order to indicate which encryption method will be used after the handshake. If crypto_select does not have exactly one bit set, or if the set bit does not correspond to one of the methods in crypto_provide, the handshake is invalid.
- The next two bytes are received and decrypted to obtain len(PadD).
- The next len(PadD) bytes are received and decrypted to obtain PadD. Note that, although the result of the decryption is unused, the decryption must still be performed in order to keep the incoming keystream in sync with the server’s outgoing keystream.

Server’s Handshake

The peer receiving an MSE/PE connection performs its side of the handshake as follows as soon as it accepts the connection:

The server generates a private key Xb following the same rules as for the client’s private key.
The server calculates its public key: Yb = pow(G, Xb) mod P.
The server sends packet 2: Yb encoded as a 96-byte (768-bit) big-endian integer, followed by a string of random bytes with a randomly-chosen length from 0 to 512.
The server receives packet 1. As with the client’s receipt of packet 2, the server must determine the end of packet 1 by waiting for sufficient time (the original spec says 30 seconds) for the entire packet to arrive.
The server extracts Ya from the first 96 bytes of packet 1 and computes the Diffie-Hellman shared secret: S = pow(Ya, Xb) mod P (This is equal to the S computed by the client). Xb is then securely discarded.
- When used as a byte string in later steps, S is encoded as a 96-byte (768-bit) big-endian integer.
The server receives & verifies packet 3:
- The first 20 bytes must equal HASH("req1" + S).
- The next 20 bytes are received and XORed with HASH("req3" + S) to obtain HASH("req2" + SKEY). The server then identifies SKEY by comparing this hash against HASH("req2" + K) for all known/accepted shared keys K. (For BitTorrent, this means comparing against HASH("req2" + info_hash) for all info hashes of torrents managed by the server.)
- The server initializes an outgoing RC4 keystream from the key HASH("keyB" + S + SKEY) and an incoming RC4 keystream from the key HASH("keyA" + S + SKEY). (Note that this is the reverse of the client.) The first 1024 bytes output by each keystream are discarded.
- The next eight bytes are received and decrypted by XORing them with bytes from the incoming RC4 keystream. If the resulting bytes are not all zero, the handshake is invalid.
- The next four bytes are received and decrypted in the same manner to obtain crypto_provide.
- The next two bytes are received and decrypted to obtain len(PadC).
- The next len(PadC) bytes are received and decrypted to obtain PadC. Note that, although the result of the decryption is unused, the decryption must still be performed in order to keep the incoming keystream in sync with the client’s outgoing keystream.
- The next two bytes are received and decrypted to obtain len(IA).
- The next len(IA) bytes are received and decrypted to obtain IA, the beginning of the actual data being transferred.
The server chooses one of the encryption methods given by crypto_provide to use for the rest of the connection. Bits with unknown meanings are ignored. If crypto_provide does not contain any encryption methods that the server supports, the handshake fails.
The server sends packet 4: RC4(VC + crypto_select + len(PadD) + PadD), where:
- RC4(X) encrypts the byte string X by XORing it with bytes produced by the server’s outgoing RC4 keystream.
- VC is eight zero-valued bytes, the same as in packet 3.
- crypto_select is a 32-bit big-endian integer with one bit set to indicate the encryption method chosen by the server. The bits have the same meanings as for crypto_provide.
- PadD is arbitrary data with a length of 0 to 512 bytes, reserved for extending the crypto handshake in future versions. Current implementations may choose to set them to 0-length. For padding-only usage in the current version, they should be zeroed.

After the Handshake

Once all of the above is carried out, the MSE/PE handshake is complete, and the client & server transmit the data they came here to transmit, encrypted using the selected encryption method. If plain text was selected, further data is sent & received as-is without encryption. If RC4 was selected, sent & received data will be encrypted using the sender’s outgoing RC4 keystream and decrypted using the receiver’s incoming RC4 keystream; these are the same keystreams as used during the handshake, i.e., they are not reinitialized.

BitTorrent-Specific Aspects

Detecting Encryption

MSE/PE was introduced into a world where BitTorrent connections were already being made without encryption, and many connections still aren’t encrypted, so peers need a way to determine whether a fresh connection is encrypted or not.

When a BitTorrent peer that supports MSE/PE receives an incoming connection, it can determine whether an MSE/PE handshake is being performed by checking whether the first 20 bytes received equal the BitTorrent handshake header "\x13BitTorrent protocol"; if the bytes match, the connection is (almost certainly) not using MSE/PE, and the peer can choose to either continue the connection unencrypted or else sever the connection.

When a BitTorrent peer that supports MSE/PE makes an outgoing connection, it has the following options, which it chooses among based on its configuration and any broadcasts of encryption support it’s received (see below):

The peer can attempt an MSE/PE handshake; if that fails, it abandons the remote peer.
The peer can attempt an MSE/PE handshake; if that fails, it severs the connection and tries to reconnect without using encryption.
The peer connects without using encryption. If the remote peer sends a BEP 10 extended handshake containing an e value of 1, the local peer severs the connection and reconnects using MSE/PE.
The peer connects without using encryption and does not use MSE/PE with the remote peer.

Broadcasting Encryption Support

BitTorrent peers can broadcast their support of MSE/PE to other peers via HTTP trackers and/or Peer Exchange. (The UDP tracker protocol and DHT do not appear to have any capabilities for broadcasting encryption support.)

When a BitTorrent peer that supports MSE/PE makes an announcement to an HTTP tracker, it can include one or more of the following URL query parameters:

supportcrypto=1 — Indicates that the peer can create & receive MSE/PE connections
requirecrypto=1 — Indicates that the peer only creates & accepts MSE/PE connections. If the tracker supports this parameter, then this peer will not be returned in responses to peers that do not set supportcrypto=1 or requirecrypto=1.
cryptoport=X (used in combination with port=0 and requirecrypto=1) — If the tracker supports the cryptoport parameter, it will provide this peer’s port as X in responses to other peers that also support MSE/PE and will not provide this peer at all to peers that do not support MSE/PE. If the tracker does not support the cryptoport parameter, then this peer’s actual port will not be given out to any peers.

When supportcrypto=1 or requirecrypto=1 is set in an announcement to a supporting HTTP tracker, the response will include a crypto_flags field, the value of which is a sequence of bytes, one for each peer in peers in order; a given byte will be 1 if the peer requires MSE/PE and 0 otherwise.

Preliminary searching on GitHub indicates that, when an HTTP tracker sends a response with “peers”, “peers6”, and “crypto_flags” fields, the “crypto_flags” only applies to the “peers” field and not “peers6”, though I have yet to encounter a tracker that actually sends “crypto_flags” in the wild.

If a peer prefers MSE/PE connections to unencrypted, it can indicate this to connecting peers by including an e field with a value of 1 in the BEP 10 extended handshakes it sends. This e value will then be broadcast to other peers using Peer Exchange (BEP 11).

References

Converting Lists to Simple Tables and Back with rs

2023-05-03T00:00:00-04:00

If you have a file that’s just a list of items, one item per line, and you want to turn it into a simple table — one delimited just by whitespace without any border characters — how would you do that? Follow up question: If you have a simple table, and you want to convert it into a list of items, one per line, how would you do that? The answer to both questions is: with the rs command, and this article will show you how.

rs is a Unix command-line program for reshaping arrays of data. Most Linux users can get it by installing the rs package, and macOS users will find it preinstalled.

Converting a List of Lines to a Simple Table

When rs is invoked without any options, it constructs a table from standard input, treating each line as its own table entry, and fills in columns before rows. Thus, if we have the following file saved in lines.txt:

Dapper Drake
Edgy Eft
Feisty Fawn
Gutsy Gibbon
Hardy Heron
Intrepid Ibex
Jaunty Jackalope
Karmic Koala
Lucid Lynx
Maverick Meerkat
Natty Narwhal
Oneiric Ocelot
Precise Pangolin
Quantal Quetzal
Raring Ringtail
Saucy Salamander
Trusty Tahr
Utopic Unicorn
Vivid Vervet
Wily Werewolf
Xenial Xerus
Yakkety Yak
Zesty Zapus

Then running rs < lines.txt will produce the following output:

Dapper Drake      Jaunty Jackalope  Precise Pangolin  Vivid Vervet
Edgy Eft          Karmic Koala      Quantal Quetzal   Wily Werewolf
Feisty Fawn       Lucid Lynx        Raring Ringtail   Xenial Xerus
Gutsy Gibbon      Maverick Meerkat  Saucy Salamander  Yakkety Yak
Hardy Heron       Natty Narwhal     Trusty Tahr       Zesty Zapus
Intrepid Ibex     Oneiric Ocelot    Utopic Unicorn

Important

When rs is run without any arguments, it acts like it was given the -e (Read one table entry from each line of input) and -t (Fill in columns before rows) options. If you specify any arguments of your own, then -e and -t will not be in effect unless you specify them explicitly.

rs automatically determines the number of table columns based on what will fit in an 80-character line. To change the line length to, say, 60 characters, pass -w60 to the command (No space is allowed between the option and its argument). To ask for a specific number of table rows and let rs figure out the number of columns, supply the desired number of rows as an argument, e.g., rs -e -t 8 < lines.txt. To ask for a specific number of table columns instead, pass a 0 argument (to tell rs “Figure the number of rows out yourself”) followed by the desired number of columns, e.g., rs -e -t 0 3 < lines.txt.

By default, rs will output every column at the same width; in the example above, this results in the first column having more padding on the right than is strictly necessary. The -z option will get rid of that padding; thus, by running rs -e -t -z < lines.txt, we get the following output:

Dapper Drake   Jaunty Jackalope  Precise Pangolin  Vivid Vervet
Edgy Eft       Karmic Koala      Quantal Quetzal   Wily Werewolf
Feisty Fawn    Lucid Lynx        Raring Ringtail   Xenial Xerus
Gutsy Gibbon   Maverick Meerkat  Saucy Salamander  Yakkety Yak
Hardy Heron    Natty Narwhal     Trusty Tahr       Zesty Zapus
Intrepid Ibex  Oneiric Ocelot    Utopic Unicorn

One thing you might not have noticed about the output is that the last line, having fewer columns than the others, ends in several spaces to make the end line up with the start of the last column. rs doesn’t have an option to disable this extra whitespace, but if you really want to get rid of it, you can pipe the output through sed -e 's/ *$//' to strip all trailing spaces.

Lastly, if you want the rows of the table to be filled in before the columns, invoke rs with the -e option and no -t option; thus, rs -e < lines.txt gives us:

Dapper Drake      Edgy Eft          Feisty Fawn       Gutsy Gibbon
Hardy Heron       Intrepid Ibex     Jaunty Jackalope  Karmic Koala
Lucid Lynx        Maverick Meerkat  Natty Narwhal     Oneiric Ocelot
Precise Pangolin  Quantal Quetzal   Raring Ringtail   Saucy Salamander
Trusty Tahr       Utopic Unicorn    Vivid Vervet      Wily Werewolf
Xenial Xerus      Yakkety Yak       Zesty Zapus

Converting a Simple Table to a List of Lines

Say we have the following text saved in table.txt:

Dapper Drake      Jaunty Jackalope  Precise Pangolin  Vivid Vervet
Edgy Eft          Karmic Koala      Quantal Quetzal   Wily Werewolf
Feisty Fawn       Lucid Lynx        Raring Ringtail   Xenial Xerus
Gutsy Gibbon      Maverick Meerkat  Saucy Salamander  Yakkety Yak
Hardy Heron       Natty Narwhal     Trusty Tahr       Zesty Zapus
Intrepid Ibex     Oneiric Ocelot    Utopic Unicorn    Artful Aardvark

and we want to convert this into a list of table entries, one per line, column by column (i.e., we want Intrepid Ibex to come before Jaunty Jackalope in the output). Because the columns are separated by multiple spaces and the table entries also contain spaces, we can’t use rs by itself to accomplish this. Instead, we first use sed -e 's/ \{2,\}/\t/g' to convert runs of two or more spaces to tab characters, and then rs can process the table using tabs as the cell delimiter.

Next, we have to pipe the output of sed through two rs invocations: the first invocation transposes the table so that the second invocation will split its entries apart in the correct order (For whatever reason, rs can’t do all this in a single invocation). The full command line will look like this:

sed -e 's/ \{2,\}/\t/g' table.txt | rs -c -C -T | rs -c 0 1

(The -c and -C options tell rs to use a tab as the input and output column delimiters, respectively.)

This works fine for the table above, but if the last column is short by two or more columns, like so:

Dapper Drake      Jaunty Jackalope  Precise Pangolin  Vivid Vervet
Edgy Eft          Karmic Koala      Quantal Quetzal   Wily Werewolf
Feisty Fawn       Lucid Lynx        Raring Ringtail   Xenial Xerus
Gutsy Gibbon      Maverick Meerkat  Saucy Salamander  Yakkety Yak
Hardy Heron       Natty Narwhal     Trusty Tahr
Intrepid Ibex     Oneiric Ocelot    Utopic Unicorn

then rs will not do what we want by default. When the rs -c -C -T step goes to transpose its input, it finds that a direct transposition would result in the last two columns of the output being short, which rs dislikes, and so it decides to fix things by moving “Intrepid Ibex” (the next cell after “Trusty Tahr”) to the cell below “Trusty Tahr” and right of “Yakkety Yak” in the output, producing this (with tabs converted to aligned spaces to make it easier to read):

Dapper Drake      Edgy Eft          Feisty Fawn       Gutsy Gibbon      Hardy Heron       Oneiric Ocelot
Jaunty Jackalope  Karmic Koala      Lucid Lynx        Maverick Meerkat  Natty Narwhal     Utopic Unicorn
Precise Pangolin  Quantal Quetzal   Raring Ringtail   Saucy Salamander  Trusty Tahr
Vivid Vervet      Wily Werewolf     Xenial Xerus      Yakkety Yak       Intrepid Ibex

and then when this table is flattened with rs -c 0 1, the output will be in the wrong order.

We can tell rs to not do this by passing the -n option to the rs -c -C -T command, which will make it output an all-blank entry below “Trusty” and right of “Yakkety” in the output instead of moving “Intrepid.” However, this blank cell will result in the final rs -c 0 1 command printing blank lines at the end of the output; we can avoid this by stripping trailing tabs before passing the table on. Hence, the final command line, that works regardless of how short the last column happens to be, is:

sed -e 's/ \{2,\}/\t/g' table.txt | rs -c -C -T -n | sed -e 's/\t*$//' | rs -c 0 1

On the other hand, if the table we’re converting to a list that happens to be read by going across the first row, then the second row, etc. — e.g., if it was produced with rs -e without the -t option — instead of being read by going down the first, second, etc. column, then the whole business with rs -c -C -T -n and stripping trailing tabs is unnecessary, and we can turn this table:

Dapper Drake      Edgy Eft          Feisty Fawn       Gutsy Gibbon
Hardy Heron       Intrepid Ibex     Jaunty Jackalope  Karmic Koala
Lucid Lynx        Maverick Meerkat  Natty Narwhal     Oneiric Ocelot
Precise Pangolin  Quantal Quetzal   Raring Ringtail   Saucy Salamander
Trusty Tahr       Utopic Unicorn    Vivid Vervet      Wily Werewolf
Xenial Xerus      Yakkety Yak

into a list by just running:

sed -e 's/ \{2,\}/\t/g' table.txt | rs -c 0 1

Basics of Writing Unix Man Pages

2022-11-24T00:00:00-05:00

On Unix-like systems, the documents that one views with the man command (known as “man pages”) are written in a markup language called “roff” (short for “run off”) that dates back to the pre-Unix days in the 1960’s. roff is technically a full-blown programming language with numerous features, but you only need to know a very small subset in order to produce most man pages. This article will describe that subset so that you can go on to write man pages for your own software.

Man pages, like most roff documents, use a roff macro package that defines a set of high-level commands. The macro package used by most man pages is, unsurprisingly, the man package, and that is what is covered here. Some man pages instead use the mdoc package, which originated in BSD. Modern versions of the man command use the mandoc package for processing man pages, which autodetects whether a file is written using man or mdoc and processes it accordingly.

Contents

roff Syntax
Document Structure Commands
Font Commands
Additional Escape Sequences
Man Page Conventions
Rendering a Man Page
A Sample Man Page
Further References

roff Syntax

A roff file is composed of a mixture of control lines — lines that start with a control character, usually a period or single-quote — and text lines — lines that do not.

Control lines are commands to roff (also known as requests). They consist of a control character & a command name followed by some number of space-separated (not tab-separated!) arguments. To include spaces in an argument, either escape them with a backslash or enclose the entire argument in double-quotes; to use double-quotes inside an argument, write them as \(dq.

For example, the input:

.B Bold
and brash?  More like
.IR Belongs " in the " Trash.

contains the command .B (for making text bold) with the argument “Bold” and the command .IR (for alternating between italic and roman text) with the arguments “Belongs” (which will be italic), “ in the ” (which will be roman), and “Trash” (which will be italic). This is all rendered as:

Bold and brash? More like Belongs in the Trash.

There may be any number of spaces & tabs (or none at all) between the control character and the command name, but the control character must be the first character in the line.
A line with just a period is ignored.

Text lines give the text that will be displayed. They can contain escape sequences, inline commands that start with backslashes.

Whitespace around escape sequences is significant and is not discarded. The syntax of an escape sequence allows roff to automatically determine where it ends; for example, escape sequences starting with \( are always followed by two more characters to complete the sequence, and so an escape sequence like \(em (em-dash) can be embedded in the middle of a word: foo\(embar becomes “foo—bar”.
To start a text line with a period, precede the period with either a backslash or the escape sequence \&.
To render a literal backslash in text, use the escape sequence \\\\, \e, or \(rs.

For example, the input from above can be rewritten using escape sequences like so:

\fBBold\fR and brash?  More like \fIBelongs\fR in the \fITrash.\fR

A comment consists of a backslash and double quote (\") and extends to the end of the line. A full-line comment can be formed by using the command .\".

A single logical line can be broken across multiple physical lines by placing a backslash at the end of each physical line.

Document Structure Commands

.TH title section [footer-middle] [footer-outside] [header-middle]

This must be the first non-comment command in a man page, and it must appear exactly once. It sets the page title (which is conventionally in all-caps) and section number for the man page (see “Manual Sections” below) to the given values, to be displayed in the form title(section) at the left & right sides of the header of the rendered manual page.

The remaining three arguments are optional. To omit an argument but still be able to specify an argument after it, write \& in place of the omitted argument.

If footer-middle is given, it will be rendered in the middle of the footer. This argument is usually set to the date the man page was written.
If footer-outside is given, it will be rendered on the left side of the footer. This is usually set to the version of the software being documented.
If header-middle is given, it will be rendered in the middle of the header. If it is omitted and section is a number from 1 to 9, certain versions of man will supply a default value.

.SH [name]

Start a section with the given name. If no argument is given, the next line will be used as the name.

.SS [name]

Start a subsection with the given name. If no argument is given, the next line will be used as the name.

.LP or .PP or .P

Paragraph break, resetting any indentation caused by the .TP, .IP, or .HP command

.TP [n]

Start a labelled, indented paragraph. The next text line after this command is the paragraph label, and any following text lines up to the next .PP will be indented. If a numeric argument is given, the paragraph will be indented by that many columns.

.IP [text] [n]

Start an indented paragraph. The text argument, if given, will be used as the paragraph’s bullet/“tag”; this is usually the bullet escape sequence (\(bu), the em-dash escape sequence (\(em), or a number followed by a period. If no text argument is supplied, no bullet will be present, but the following paragraph will still be indented; this can be used to start a new indented paragraph after an initial indented paragraph created by .TP, .IP, or .HP.

If a numeric second argument is given, the paragraph will be indented by that many columns.

.HP [n]

Start an indented paragraph in which the first line is not indented. If a numeric second argument is given, the paragraph will be indented by that many columns.

.RS [n]

Increase the amount of indentation until a corresponding .RE. If a numeric second argument is given, the indentation will be increased by that many columns.

.RE

Undo the increase in indentation caused by the last .RS

.br

Insert a line break

.sp

Skip a line

.sp N

Skip N lines

Font Commands

The following escape sequences can be used to change the font within a text line:

\fB: Change the font to bold
\fI: Change the font to italic (on a terminal, underlined)
\fR: Change the font to roman
\fP: Change back to the previous font

The following requests render an argument in a given font:

.B [text]: Renders the given text (or the text of the next line if no argument is given) in bold with a word break before & after.
.I [text]: Renders the given text (or the text of the next line if no argument is given) in italic (on a terminal, underlined) with a word break before & after.

The following commands take multiple arguments and render them in alternating fonts. A word break/whitespace will be inserted before & after the arguments, but there will be no words breaks/whitespace inserted between the arguments. For example, the following:

This is
.BI very styled
text.

will render as:

This is verystyled text.

.RB text ...: Renders the given arguments in alternating roman and bold, roman first.
.BR text ...: Renders the given arguments in alternating bold and roman, bold first.
.RI text ...: Renders the given arguments in alternating roman and italic/underlined, roman first.
.IR text ...: Renders the given arguments in alternating italic/underlined and roman, italic/underlined first.
.BI text ...: Renders the given arguments in alternating bold and italic/underlined, bold first.
.IB text ...: Renders the given arguments in alternating italic/underlined and bold, italic/underlined first.

Tip

While modern groff lets you use these commands with any number of arguments, traditional implementations limit usage to six arguments; keep this in mind if you want to make your man page portable.

Additional Escape Sequences

Select Non-ASCII Characters

See grof_char(7) for the complete set of available character escape sequences.

Escape	Character
`\(bu`	bullet (•)
`\*R`	registration symbol (®)
`\*(Tm`	trademark symbol (™)
`\(co`	copyright (©)
`\(em`	em-dash (—)
`\(en`	en-dash (–)
`\(rq`	right double-quote (“)
`\(lq`	left double-quote (”)
`\(oq`	left single-quote (‘)
`\(cq`	right single-quote (’)

Note

When viewing a man page in the terminal, not all installations will display Unicode characters. On systems that display man pages in ASCII (which include macOS as of Big Sur), non-ASCII characters will be rendered as the visually closest ASCII character where possible.

Special ASCII Characters

Some output devices transform certain ASCII input characters to similar Unicode characters, so the following escape sequences can be used to ensure that the desired ASCII character appears in the rendered man page:

Escape	Character
`\(aq`	Apostrophe (‘)
`\(ga`	Grave accent (`)
`\(ha`	Caret/circumflex accent (^)
`\(ti`	Tilde (~)
`\-`	Hyphen/minus (-)

Other

A backslash followed by a space produces a non-breaking space that remains at a fixed width when text is justified.
\~ produces a non-breaking space that nevertheless stretches like a normal inter-word space when justifying text.
\& produces a non-printable, zero-width character. It can be placed next to a token to deprive it of any special meaning; for example, it can be placed after a period at the end of an abbreviation to prevent it from being treated as the end of a sentence.

Man Page Conventions

Manual Sections

Each man page is traditionally placed into one of nine manual sections (not to be confused with the sections within a man page created by the .SH command; for that, see below). The pages for a given section are stored together, and the section number is also used as the file extension. The sections are:

Commands for use by general users
C system calls
C library functions, libraries, & headers
Devices, special files, and sockets
File formats
Games
Miscellaneous
Commands for use by system administrators (including servers/daemons)
C kernel functions

Sections of a Man Page

The contents of a man page are divided into sections by the .SH command. Different sources give slightly different lists of the “standard” sections, but the most common, in roughly the order they should appear in a man page, are:

NAME

Gives the name of the man page and a short description of what it documents. This is usually considered the only mandatory section.

In order for a man page named “foobar” to be properly indexed by whatis and apropos, NAME must be the first section in the man page, and the .SH NAME line must be followed immediately by a line of the form foobar \- short description of foobar.

SYNOPSIS

Shows the syntax for invoking a command or calling a C function.

The synopsis for a command usually follows the following conventions:

Text that should be entered as-is by the user (e.g., options and the name of the command) should be in bold, while placeholder text that should be replaced with some value by the user (e.g., command arguments) should be in italics/underlined.
Optional syntax elements (e.g., most options) should be enclosed in square brackets.
Alternative forms of a syntax element (e.g., the short and long form of an option) should be separated by whitespace and a vertical bar.
Syntax elements that can be repeated (e.g., arguments that can be given multiple times) are indicated by appending three periods (...).

See A Sample Man Page below for an example of these rules in action.

DESCRIPTION

An explanation of what the command, function, etc. does

OPTIONS

A list of any command-line options a program takes and their meanings. This list is usually created using .TP or .IP to produce paragraphs labeled with the option they describe, with each option in bold and any argument it may take in italics/underlined.

EXIT STATUS

A list of the possible exit statuses for a command and their meanings

ENVIRONMENT

A description of any environment variables that affect the command or function

FILES

A description of any files the command uses (configuration files, startup files, etc.). It is recommended that file paths be styled in italics/underlined.

NOTES

Any miscellaneous notes

BUGS

A list of known shortcomings in the documented software or functionality

EXAMPLES

Examples of how to use the software or functionality

AUTHORS

A list of the authors of the software and/or man page

REPORTING BUGS

Information on how to report any bugs found in the software

COPYRIGHT

SEE ALSO

A comma-separated list of related man pages and/or other documents. References to other man pages should be formatted with the name in bold and the section number in roman enclosed in parentheses.

Other Conventions

Use \- instead of plain - for ASCII hyphens, e.g., in command-line options. Use plain - in hyphenated words.
Blank lines are discouraged, as they may not render correctly in all output formats. Use the .sp command instead to produce a blank line, or use .PP to start a new paragraph.
Each sentence should typically start on a new line.
Use only a single space between words in text; multiple spaces will not be collapsed into one when rendering.

Rendering a Man Page

To render a man page in the terminal the way that man would, run man -l path/to/man/page. (On macOS, you have to instead run mandoc -a path/to/man/page). You may also want to pass the --warnings option (-Wall for mandoc) in order to catch any problematic syntax.

If your version of man does not support the -l option, you can instead run groff (GNU roff, the typical roff implementation on nearly all Unix machines nowadays) directly with groff -man -Tutf8 path/to/man/page | less -is.

Of course, groff can render to more than just terminals by changing the value passed to the -T option in the groff command. Values of interest include pdf, ps (for PostScript), and html; these require the gropdf, grops, and grohtml commands, respectively, to be installed in order to work.

A Sample Man Page

.TH FOOBAR 1 2022-11-24 v1.0
.SH NAME
foobar \- foo all your bars
.SH SYNOPSIS
.B foobar
[\fB\-a\fR \fIarg\fP]
.RB [ \-f | \-\-fu ]
.RB [ \-xyz ]
.IR "bar " ...
.SH DESCRIPTION
.B foobar
takes a list of one or more
.IR bar s
and foos each of them.
.PP
In detail, lorem ipsum dolor sit amet, consectetur adipisicing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi
ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore
eu fugiat nulla pariatur.
Excepteur sint occaecat cupidatat non proident,
sunt in culpa qui officia deserunt mollit anim id est laborum.
.SH OPTIONS
.TP
.BI "\-a " arg
Put the apple at
.IR arg .
.TP
.BR \-f ", " \-\-fu
Do a FUBAR instead.
.IP
Note that this can permanently destroy your computer.
.IP \fB\-x\fR
Be exact about it.
.TP
.B -y
Be yucky about it.
.IP \fB-z\fR
Be zucchini about it.
.SH FILES
.TP
.I ~/.cache/foo
This is where the bars are stored.
.SH "SEE ALSO"
.BR man (1),
.BR groff (7),
.BR groff_man (7)
.PP
.I A Brief History of Foo
by Fabian Oscar Oh
.PP
.RI < https://www.example.com/foo/bar.html >

[Download this file]

Rendered:

[View animation on asciinema.org]

Further References

groff(7) man page: <https://man7.org/linux/man-pages/man7/groff.7.html>
groff_char(7) man page: <https://man7.org/linux/man-pages/man7/groff_char.7.html>
groff_man(7) man page: <https://man7.org/linux/man-pages/man7/groff_man.7.html>
man-pages(7) man page: <https://man7.org/linux/man-pages/man7/man-pages.7.html>

Special Version Control Files

2021-06-22T00:00:00-04:00

The following is a list of VCS-specific files that one may find in the working directories of common version control systems. This list is useful for, say, knowing what files to ignore when traversing a project directory.

Did I leave anything out? Feel free to send a pull request.

VCS	File/Directory	Purpose	Documentation
Git	`.git/`	Repository data	gitrepository-layout(5)
	`.gitattributes`	Defines per-path attributes	gitattributes(5)
	`.gitignore`	Lists files to exclude from version control	gitignore(5)
	`.gitmodules`	Defines submodules	gitmodules(5)
	`.mailmap`	Maps names & e-mails to canonical values	gitmailmap(5)
Mercurial	`.hg/`	Repository data	wiki:FileFormats
	`.hgignore`	Lists files to exclude from version control	hgignore(5)
	`.hgsigs`	Contains changeset signatures from the GPG extension	—
	`.hgtags`	Defines tags	—
Darcs	`_darcs/`	Repository data	—
	`.binaries`	Lists files to treat as binary [1]	Manual
	`.boring`	Lists files to exclude from version control [1]	Manual
Bazaar	`.bzr/`	Repository data	—
Bazaar	`.bzrignore`	Lists files to exclude from version control	bzr ignore
Subversion	`.svn/` or `_svn/` [2]	Local copy of repository data [3]
CVS	`CVS/`	Local copy of repository data (one per directory)	Manual
RCS	filename`,v`	Version history for filename	Manual
RCS	`RCS/`	Conventional directory for storing `*,v` files	—

[1]	(1, 2) Darcs normally stores its binaries file and boring file inside the `_darcs/` directory, but it is possible to use any file under version control in their place; the names listed here are the conventional names for such files.

[2]	For compatibility with ASP.NET, Subversion will use the name `_svn` instead of `.svn` if the `SVN_ASP_DOT_NET_HACK` environment variable is defined.

[3]	Prior to version 1.7, Subversion placed a `.svn`/`_svn` directory in every subdirectory of the working directory under version control.

All About reStructuredText Hyperlinks

2020-07-28T00:00:00-04:00

reStructuredText offers a number of different ways to write hyperlinks, but keeping track of all of them and their gotchas isn’t easy, and the information is scattered around the spec. This document aims to summarize all of the hyperlink-related information from the reStructuredText Markup Specification in one (hopefully) well-organized place.

This document describes reStructuredText hyperlinks as of Docutils version 0.16, the latest version at time of writing.

Contents

Standalone Hyperlinks
Embedded URI Hyperlinks
Embedded Alias Hyperlinks and Hyperlink Targets
Named Hyperlink References
Anonymous Hyperlinks
Embedded URI Hyperlinks and Automatic Reference Names
- Gotcha: Duplicate Link Text
Embedded Alias Hyperlinks and Automatic Reference Names
Intra-Document Links
Chaining Hyperlink Targets
Styling Link Text
Link Text within a Word

Standalone Hyperlinks

Firstly, reStructuredText supports standalone hyperlinks — just a bare URI (including a scheme) or e-mail address without any link text:

Go to http://www.example.com to see something neat!

E-mail me at me@example.com.

The above renders as:

Go to http://www.example.com to see something neat!

E-mail me at me@example.com.

Note that, unlike Markdown, angle brackets are not required around standalone hyperlinks, and if you do include angle brackets, the brackets will be present in the rendered output.

Also note that the scheme is required in order for a URI to be recognized as a standalone hyperlink. The domains names in the following will not be converted to hyperlinks:

Go to www.example.com — or to <www.example.org>!

If you want a hyperlink that links to www.example.com without a scheme and uses the address as the link text, you can either write out the link the long way as an embedded URI hyperlink with link text, or you can use embedded URI syntax without any link text, in which case the URI becomes the link text. For example:

Go to `<www.example.com>`_.

renders as:

Go to www.example.com.

This isn’t very useful for linking to domains, but it can be useful when you want a link to a page in the same directory with the page filename used as the link text:

See `<other_page.html>`_ for other stuff.

Rendered:

See other_page.html for other stuff.

Embedded URI Hyperlinks

If you want to create a hyperlink with link text, the most straightforward way to do so is with the embedded URI syntax:

Here is `a link <http://www.example.com>`_ to somewhere.

This renders as:

Here is a link to somewhere.

The syntax consists of a backtick, the link text (with any embedded backticks escaped with backslashes), whitespace, the target URI or e-mail address inside angle brackets, another backtick, and a single underscore. If the URI ends with an underscore, the underscore must be preceded by a backslash in order to not be parsed as an embedded alias.

Note that link text is treated literally rather than processed for any inline markup. See “Styling Link Text” below for a way around this.

There is a gotcha you may run into when defining two embedded URI hyperlinks with the same link text but different URIs; see below for more information.

Embedded Alias Hyperlinks and Hyperlink Targets

If the URI is lengthy, or if you want to link to the same location more than once, you may want to use an embedded alias. In this form, instead of specifying the URI next to the link text, you specify a hyperlink reference containing a reference name, and then you specify elsewhere (in a hyperlink target) what URI the reference name points to. For example:

Here is `a link <link_target_>`_ to somewhere.

.. _link_target: http://www.example.com

Rendered:

Here is a link to somewhere.

This syntax consists of two parts:

At the location in the text where you want the link to appear, write a backtick, the link text (with embedded backticks escaped), whitespace, a reference name followed by an underscore and encased in angle brackets, another backtick, and another underscore.
- The reference name can be any sequence of characters, though if it contains any backticks or angle brackets, or begins or ends with space characters, the characters in question will need to be escaped with backslashes when using the name in an embedded alias link.
  
  When comparing two reference names for equality, runs of whitespace are normalized to a single space, and alphabetic characters are converted to lowercase.

Elsewhere in the reStructuredText document (either before or after the hyperlink reference), write a (external) hyperlink target on a line of its own: optional whitespace, two periods, a space, an underscore, the same reference name as before (without the trailing underscore from before), a colon, whitespace, and then the URI or e-mail address that the link should point to.
- If the reference name contains any colons or is just a single underscore, you must either escape the characters in question or else enclose the reference name in backticks (in which case any backticks in the reference name need to be escaped). Either way, any leading or trailing space characters or backticks in the reference name need to be escaped as well.
- If the URI contains any space characters or ends with an underscore, the characters in question will need to be escaped with backslashes.
- The reference name and the URI may be on the same line, or you can put them on separate lines, in which case the URI must be indented relative to the two periods and there must be no intervening blank lines. The URI may even span multiple lines, in which case the lines are concatenated and any whitespace in the URI that isn’t escaped is discarded. For example, the following hyperlink targets all map to the same URI:
```
.. _one-liner: http://docutils.sourceforge.net/rst.html

.. _starts-on-this-line: http://
   docutils.sourceforge.net/rst.html

.. _entirely-below:
   http://docutils.
   sourceforge.net/rst.html
```
- If the same reference name is used for two or more hyperlink targets with different URIs, a warning is produced, and the reference name will be unusable.
- Hyperlink reference names, footnote labels, and citation labels share the same namespace. This means you can link to a footnote or citation by its label, but it also means that you can’t define a reference name that is the same as a footnote or citation label.

Once a reference name is defined in a hyperlink target, the same reference name can be used in any number of embedded alias links to create multiple hyperlinks to the same destination.

As with embedded URI hyperlinks, link text is treated literally rather than processed for any inline markup. See “Styling Link Text” below for a way around this.

Named Hyperlink References

We can simplify embedded aliases one step further and use the link text as the reference name. Simply omit the part in angle brackets:

Here is `a link`_ to somewhere.

.. _a link: http://www.example.com

If the link text ends with text inside angle brackets, at least one of the angle brackets needs to be escaped — or an escaped space character should be added to the end of the link text — in order to prevent the link from being parsed as an embedded URI or alias hyperlink.

This gets even simpler if the link text is a simple reference name — a single word (no whitespace) consisting only of letters, numbers, hyphens, underscores, periods, colons, and/or plus signs, with no punctuation at the beginning or end, and with no occurrences of two or more punctuation characters in a row. A simple reference name can be written with just the trailing underscore, no backticks:

This following word_ is a hyperlink.

.. _word: https://www.example.com

The same reference name may be used both as a named hyperlink reference and in an embedded alias link:

`This site`_ links to the same location as `these words <This site_>`_.

.. _This site: https://www.example.com

Anonymous Hyperlinks

What if you want to use the hyperlink reference syntax, but it’s for a URI that will only be linked once, you don’t feel like giving it a reference name, and the link text is too long to use as an efficient reference name? The solution: anonymous hyperlinks.

`This link`__ goes to a dot-com.  `This other link`__ goes to a dot-net.

.. __: https://www.example.com
__ https://www.example.net

Rendered:

This link goes to a dot-com. This other link goes to a dot-net.

Write the link text as a named hyperlink reference, but instead of ending it with one underscore, use two. (As with named hyperlink references, the backticks can be omitted for a simple reference name.) Then, for the hyperlink target, use an underscore in place of the reference name (so that you have two underscores in a row); alternatively, the entire hyperlink target can be written as just two underscores, whitespace, and the URI or e-mail address.

The first anonymous hyperlink in a document will link to the URI given by the first anonymous hyperlink target, the second anonymous hyperlink will link to the second anonymous target, etc.

Embedded URI Hyperlinks and Automatic Reference Names

Here’s an interesting fact about embedded URI hyperlinks: they’re equivalent to a named hyperlink reference using the link text as the reference name. That means this:

`This website <https://www.example.com>`_ is awesome!

is exactly equivalent to:

`This website`_ is awesome!

.. _This website: https://www.example.com

As a consequence of this, you can link to the same location as an embedded URI link by using its link text as the reference name:

I changed my mind; `this website <https://www.example.com>`_ sucks.  Let me
reiterate: The website at `this link <this website_>`_ is nothing special.

Gotcha: Duplicate Link Text

As stated above, if a reference name is associated with two different URIs, rendering the document will produce a warning, and the reference name will be unusable in hyperlinks. So what happens if we define two embedded URI hyperlinks with the same link text but different URIs, like so?

See `here <https://www.example.com>`_ and `here <https://www.example.net>`_
for more information.

With the above input, a warning will be produced, but the hyperlinks will still point where you want them to, and the reference name here will refer to the first URI. This normally isn’t all that bad, but if you’re using a renderer that fails on warnings — e.g., if you’re uploading a project with a reStructuredText README to the Python Package Index — the rendering will fail, and your upload to PyPI will either be rejected or end up with an unrendered project description.

So how do we cleanly write embedded URI links with the same link text but different URIs? Answer: We add an extra underscore to the end of the link, turning it into an anonymous hyperlink.

See `here <https://www.example.com>`__ and `here
<https://www.example.net>`__ for more information.

With two underscores, no hyperlink target is created, and so there is no conflict.

Embedded Alias Hyperlinks and Automatic Reference Names

Similarly to embedded URI hyperlinks, using an embedded alias hyperlink turns the link text into a reference name pointing at the same location as the hyperlink reference. The following markup defines four hyperlinks that all point to <https://www.example.com>:

See `this site <site_>`_ for more information.

.. _site: https://www.example.com

Now that I've written that link, I can write these links: `Click me! <this
site_>`_  I link to `this site`_!  `Click me!`_

If you define multiple embedded alias hyperlinks with the same link text but different hyperlink references, the document will render without any warnings, and the link text will be usable as a reference name pointing to the same location as the first hyperlink reference.

Intra-Document Links

Linking to different parts of the same document is accomplished using embedded alias hyperlinks and named hyperlink references, just like external links; the difference is in how the hyperlink target is defined.

Internal Hyperlink Targets

A hyperlink target without a URI creates an internal hyperlink target that points to the next element in the document after the target.

Click `here <After Lorem_>`_ to skip the next paragraph.

Lorem ipsum dolor sit amet …

.. _After Lorem:

This paragraph can be linked to with the reference name "``After Lorem``."
Aren't you glad you didn't skip the previous paragraph now?

Rendered:

Click here to skip the next paragraph.

Lorem ipsum dolor sit amet …

This paragraph can be linked to with the reference name “After Lorem.” Aren’t you glad you didn’t skip the previous paragraph now?

The target points to the next element even if the target is indented so as to be “nested” at the end of an indented block. This allows us to attach targets to individual elements of a list:

1. Any following lines that line up with "Any" belong to this list item.

   .. _item2:

2. This list item can be linked to with the reference name ``item2``.

If the .. _item2: line above wasn’t indented, it would split the list into two lists, and the target would point to the second list. (A target before a list always points to the list as a whole; a target pointing to just the first item is not possible.)

Named Directives

Most reStructuredText directives support a :name: option that takes a string as an argument. Setting this option allows you to link to the directive using that name, equivalent to preceding the directive with an internal hyperlink target.

.. danger::
    :name: dont-or-whatever

    Don't stick your finger in the— You know what?  Forget it.  I'm not
    your mother.

… Text passes …

Hey, remember `that admonition from earlier <dont-or-whatever_>`_?  I was
serious.

Rendered:

!DANGER!

Don’t stick your finger in the— You know what? Forget it. I’m not your mother.

… Text passes …

Hey, remember that admonition from earlier? I was serious.

As this is the same as using an internal hyperlink target, a warning will be generated if two directives have the same name or if the name of a directive is the same as a reference name of another hyperlink target.

Inline Internal Targets

A phrase within a paragraph of text can be made into a target by preceding the phrase with an underscore and a backtick, escaping any backticks inside the phrase, and appending a backtick to the end of the phrase. (The backticks cannot be omitted, no matter how simple the phrase is.) This defines the phrase itself as a reference name that points to the phrase’s location in the document.

They're called "paragraphs," but I've never seen them _`para`!  Know what I
mean?

(I don't know what I was saying `here <para_>`_.)

Implicit Hyperlink Targets for Section Titles

A section title in a reStructuredText document implicitly defines a hyperlink target pointing to that section with the same reference name as the section title.

Go read "`All About Eels`_" to learn about our wriggly friends!

Didn't you hear me?  Who wouldn't want to click `this link <All About
Eels_>`_?

All About Eels
==============
Did you know?  When you're bit in the heel by a big giant eel, that's a
moray.

If a section has the same name as a hyperlink target or a directive, the hyperlink target or directive takes precedence, and the section cannot be linked to by name. If two or more sections have the same name, none of them can be linked to by name. In order to link to a section that cannot be linked by name, you must precede the section title with an internal hyperlink target and link to that.

Chaining Hyperlink Targets

It’s possible to define multiple hyperlink targets all pointing to the same location by “chaining” the targets together, one after the other:

.. _foo:
.. _bar:
.. _baz: https://www.example.com

Now the reference names foo_, bar_, and baz_ all link to the same place.

Chained hyperlink targets all point to the same location as the last target in the chain. If the last target is an internal hyperlink target, the chained targets will all point to the same document element as that last target:

.. _foo:
.. _bar:
.. _baz:

Now the reference names foo_, bar_, and baz_ all link to this paragraph.

Alternatively, a hyperlink target A can be defined to point to the same location as another target B by defining the hyperlink target with B (as a named hyperlink reference) in place of the URI:

.. _some link: https://www.example.com
.. _foo: `some link`_

Now `some link`_ and foo_ go to the same website.

The .. _foo: definition is called an indirect hyperlink target. As with named hyperlink references, the backticks can be dropped when the hyperlink reference is a simple reference name. As with external hyperlink targets, the hyperlink reference may begin on the same or next line as the target, and it may span multiple lines.

Styling Link Text

As you may have noticed, inline markup in link text is treated literally rather than being processed into emphasis etc. For example, this:

Try this recipe for `pie *à la mode* <https://www.example.com>`_.

renders as:

Try this recipe for pie *à la mode*.

The asterisks are rendered as-is instead of causing the “à la mode” to be emphasized.

Fortunately, there’s a trick to use inline markup in link text: Define the link using a substitution:

Try this recipe for |pie à la mode|_.

.. |pie à la mode| replace:: pie *à la mode*
.. _pie à la mode: https://www.example.com

Rendered:

Try this recipe for pie à la mode.

The steps to do this are as follows:

In our text, we insert a substitution reference where we want the link to be. A substitution reference consists of a vertical bar, some arbitrary substitution text, and another vertical bar. Because we also want this to be a hyperlink, an underscore is added after the closing vertical bar, causing the substitution reference to also be a named hyperlink reference with the substitution text as the reference name.
- The substitution text can be any text that does not begin or end with whitespace. Substitution text is matched case-sensitively, but if that fails, a case-insensitive match is tried.
Elsewhere in the document, a substitution definition is given for the substitution reference: two periods, a space, a vertical bar, the same substitution text as in the substitution reference, another vertical bar, whitespace, a replace:: directive (without leading ..), whitespace, and then finally the inline markup to display in place of the substitution reference in the rendered document.

Elsewhere in the document, a hyperlink target is created that maps the substitution text to the URI or e-mail address that the substituted text should link to. To link to a location in the document rather than to an external URI, either use an indirect hyperlink target:

Try this recipe for |pie à la mode|_.

.. |pie à la mode| replace:: pie *à la mode*
.. _pie à la mode: `pie recipe`_

Some intervening text

.. _pie recipe:

So here's how you make pie *à la mode*: …

or else make the substitution text the same as the reference name of the internal target:

Try this recipe for |pie recipe|_.

.. |pie recipe| replace:: pie *à la mode*

Some intervening text

.. _pie recipe:

So here's how you make pie *à la mode*: …

If desired, the substitution reference can be made into an anonymous hyperlink instead by placing two underscores instead of one after the closing vertical bar, in which case the hyperlink target must follow the anonymous hyperlink target syntax.

Link Text within a Word

Normally, a hyperlink spans one or more full words, but what if we want to only link part of a word? To do so, we must insert a backslash (optionally followed by a whitespace character) between the link and the rest of the word:

These `link <https://www.example.com>`_\s are getting out of control!  Now
they're in the in\ test_\ ines of our words.

.. _test: https://www.example.net

This renders as:

These links are getting out of control! Now they’re in the intestines of our words.

Unicode and LaTeX

2020-07-27T00:00:00-04:00

LaTeX is a powerful document typesetting system, but (especially if you’re using a version even a few years old), getting it to accept and display non-ASCII characters natively requires knowledge squirreled away in scattered documents. Here we cover how to get LaTeX to work with UTF-8 input characters in hopes of thwarting the squirrels of obscurity.

Or you could just skip all that and use XeLaTeX or LuaLaTeX instead.

pdfTeX Engine (pdfLaTeX)

When using “basic” LaTeX with the pdfTeX engine, enabling UTF-8 input requires simply placing the following commands at the top of your document preamble:

\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}

The exact effects of these commands are as follows:

\usepackage[T1]{fontenc} sets the output font encoding to T1. A font encoding is a mapping between character codes and glyphs in a font; the font encodings defined by LaTeX are described in [4].

By default, LaTeX uses the OT1 font encoding, a 7-bit encoding in which accented characters like “ö” are formed by adding an accent glyph to the base letter. T1, by contrast, is an 8-bit encoding supporting widespread European languages in which many letter+accent combinations exist as single glyphs. [3] [14]

Without this command, characters will be represented using what’s available in OT1, and, as a result, words containing accented characters won’t be correctly hyphenated, copying-and-pasting accented characters from a built PDF won’t work correctly, and inputting a |, <, or > will produce a completely different character in the resulting PDF. [14]

If one passes a comma-separated list of font encodings to the fontenc package, the last encoding in the list becomes the document’s default encoding, and switching to the other encodings (e.g., in order to enter characters only defined by those encodings) becomes possible using the command sequence \fontencoding{INSERT ENCODING NAME HERE} \selectfont. [6] [13] [9]
\usepackage[utf8]{inputenc} sets the input encoding for the document source to UTF-8, allowing UTF-8 characters to appear in the input document. Additionally, for each font encoding used in the document, inputenc loads a mapping of UTF-8 characters to commands usable in that font encoding. [1] When paired with the fontenc command above, on recent LaTeX versions, inputenc loads mappings from the files omsenc.dfu, ot1enc.dfu, t1enc.dfu, and ts1enc.dfu [13], located in $TEXDIR/texmf-dist/tex/latex/base in an installed TeX Live distribution; this in turn allows the user to input any of the characters mapped by those files into a document and have the characters be typeset appropriately.

Without this command, older versions of LaTeX will use a “raw” input encoding in which each input byte is typeset as the glyph in the same position in the current font. [8]

Beginning with the 2018-04-01 release, LaTeX uses UTF-8 as the default encoding for source files, making \usepackage[utf8]{inputenc} redundant. [8]

Once the above commands are added to your document preamble, you will be able to enter a number of UTF-8 characters directly into your document and have them show up in the built PDF without having to type out their commands. You’ll even be able to write smart quotes (“ and ”) directly instead of typing quotes out as `` and ''.

So instead of writing this:

``My na\"\i{}ve r\'esum\'e is attached.''  --- Se\~nor \TH{}or

you can write this:

“My naïve résumé is attached.”  — Señor Þor

and LaTeX will handle the input correctly.

Note that LaTeX does not support combining characters; input must be in a composed form.

If LaTeX encounters a Unicode character that it doesn’t have a definition for, typesetting will stop with an error message of the form:

! Package inputenc Error: Unicode char ☃ (U+2603)
(inputenc)                not set up for use with LaTeX.

If you want to use a certain character in your document that LaTeX doesn’t recognize, you can use the \DeclareUnicodeCharacter{hexcode}{cmd} command provided by inputenc. Its first argument is the hexadecimal code point of the Unicode character to define, and the second argument is the LaTeX command to execute when the character is encountered. [1] For example:

\usepackage{tikzsymbols}  % provides \Snowman
\DeclareUnicodeCharacter{2603}{\Snowman}
% Now you can put ☃ in your document!

If you don’t want to have to enter characters as codepoints, the \newunicodechar command provided by the newunicodechar package lets you use the character itself instead, [2] allowing us to rewrite the example above as:

\usepackage{newunicodechar}
\usepackage{tikzsymbols}  % provides \Snowman
\newunicodechar{☃}{\Snowman}
% Now you can put ☃ in your document!

As a special case, loading the textcomp package lets you input all of the Unicode characters that can be output with textcomp’s commands; for example, textcomp defines a \textmusicalnote command that produces ♪ (U+266A, EIGHTH NOTE), and so including textcomp in your preamble allows you to write “♪” in your document and have it be treated as the \textmusicalnote command, producing a “♪” in the output.

Non-Latin Alphabets

The commands described so far only provide meaningful support for text in Latin-derived alphabets. In order to enter text in other alphabets, more elaborate steps are required.

Cyrillic Alphabet

The most direct way to enable Cyrillic input is to specify a Cyrillic font encoding in the fontenc command. Due to the large number of Cyrillic characters in existence, the script is split up into three font encodings (T2A, T2B, and T2C) that each match up with the T1 encoding in the lower 7-bit range, plus a fourth encoding, X2, that contains all of the Cyrillic characters but is not compatible with T1. [4] [11]

A purely-Cyrillic document can be written with the X2 font encoding as follows:

\documentclass{article}
\usepackage[X2]{fontenc}
\usepackage[utf8]{inputenc}
\begin{document}
Пролетарии всех стран, соединяйтесь!
\end{document}

If you want to use both Cyrillic and Latin characters in your document, you need to pass both T1 and X2 to fontenc. Whichever one is listed last in the fontenc command becomes the default font encoding for the document; the other font encoding can be switched to by writing \fontencoding{INSERT ENCODING NAME HERE} \selectfont. [6] [13] [9] For example:

\documentclass{article}
\usepackage[X2,T1]{fontenc}
\usepackage[utf8]{inputenc}
\begin{document}
“{\fontencoding{X2}\selectfont Пролетарии всех стран, соединяйтесь!}” said
Señor Þor.
\end{document}

Managing encodings this way can get annoying; fortunately, the babel package provides a better way. Add a \usepackage[LANGUAGES]{babel} command to your preamble, where LANGUAGES is replaced by a comma-separated list of the languages that will be used in your document; the last language in the list will become the document’s default language. Within the document, the language can be changed with \selectlanguage{LANGUAGE} (though, for short passages, it’s better to use \foreignlanguage{LANGUAGE}{TEXT}), and when it’s set to a Cyrillic-using language, you can write in Cyrillic. [7] [11] For example:

\documentclass{article}
% If we don't explicitly load a Cyrillic font encoding, babel emits a
% warning and defaults to loading T2A.
\usepackage[T2A,T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage[russian,english]{babel}
\begin{document}
“\foreignlanguage{russian}{Пролетарии всех стран, соединяйтесь!}” said
Señor Þor.
\end{document}

Greek Alphabet

As with Cyrillic, entering Greek in LaTeX requires setting the font encoding, in this case to LGR: [4]

\documentclass{article}
\usepackage[LGR,T1]{fontenc}
\usepackage[utf8]{inputenc}
\begin{document}
“{\fontencoding{LGR}\selectfont Ἄνδρα μοι ἔννεπε, Μοῦσα, πολύτροπον, ὃς
μάλα πολλὰ}” said Homer.

“Is he talking about me?” wondered Señor Þor.
\end{document}

As before, we can let also choose to let babel take care of the encodings for us:

\documentclass{article}
% No need to explicitly load LGR!
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage[greek,english]{babel}
\begin{document}
“\foreignlanguage{greek}{Ἄνδρα μοι ἔννεπε, Μοῦσα, πολύτροπον, ὃς μάλα
πολλὰ}” said Homer.

“Is he talking about me?” wondered Señor Þor.
\end{document}

As another alternative, the greek-fontenc package provides a textalpha package that allows one to write Greek directly without the need for babel or language-switching: [5]

\documentclass{article}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{textalpha}
\begin{document}
“Ἄνδρα μοι ἔννεπε, Μοῦσα, πολύτροπον, ὃς μάλα πολλὰ” said Homer.

“Is he talking about me?” wondered Señor Þor.
\end{document}

greek-fontenc also provides an alphabeta package that lets one use Greek characters directly in math mode. [5]

Other Alphabets

LaTeX’s built-in font encodings only cover Latin, Cyrillic, and Greek. Enabling input in other alphabets is a separate topic for each alphabet with no easy one-size-fits-all answer.

XeTeX Engine (XeLaTeX) and LuaTeX Engine (LuaLaTeX)

Besides pdfTeX, LaTeX can also run on two major alternative engines:

The XeTeX engine, on which LaTeX runs as XeLaTeX
The LuaTeX engine, on which LaTeX runs as LuaLaTeX. This is a TeX engine with an embedded interpreter for the Lua programming language that allows developers to extend the engine by coding in Lua. [12] [15]

Both engines fully support Unicode input and support modern font technologies, including being able to use fonts from the operating system. [16] [12] When it comes to Unicode support, the major differences between pdfLaTeX and XeLaTeX/LuaLaTeX are:

XeLaTeX and LuaLaTeX documents must always be written in UTF-8, while pdfLaTeX accepts document in various input encodings. [10] [13]
The fontenc and inputenc commands used in pdfLaTeX should be omitted when working with XeLaTeX/LuaLaTeX; the Unicode engines ignore (and give a warning about) inputenc, while setting fontenc can actually cause some characters (like smart quotes) to not be recognized. Instead, you can just start entering Unicode characters directly into your document without having to include any packages.
The set of available Unicode characters in XeLaTeX/LuaLaTeX is determined by what characters are defined in the current font. [13] The default font in both XeLaTeX and LuaLaTeX is Latin Modern, a derivative of TeX’s Computer Modern default font that adds many more characters.
If XeLaTeX encounters a Unicode character that does not exist in the current font, the resulting PDF will show the font’s placeholder character if it has one; if the font has no placeholder character, nothing will be shown. Either way, the .log file will contain a line of the form:
```
Missing character: There is no ☃ in font [lmroman10-regular]:mapping=tex-text;!
```
If LuaLaTeX encounters a Unicode character that does not exist in the current font, the character will be omitted in the resulting PDF. No warning will be emitted or logged.
\DeclareUnicodeCharacter is not a valid command in XeLaTeX or LuaLaTeX; one must instead write something like:
```
\usepackage{tikzsymbols}  % provides \Snowman
\catcode`☃=\active
\protected\def ☃{\Snowman}
```
\newunicodechar can still be used in place of this method, though. [2]
Being able to write in another alphabet is largely a matter of switching to a font that supports that alphabet. See the fontspec package for how to change fonts in XeLaTeX and LuaLaTeX.
While neither XeLaTeX nor LuaLaTeX natively supports combining characters, the Lua scripting capabilities in the latter can be used to give combining characters in your source code the desired effect; see <https://tex.stackexchange.com/a/149197> for an example.

References

[1]	(1, 2) Alan Jeffrey and Frank Mittelbach, inputenc.sty. Version 1.3c. Last modified 2018 August 11, <http://mirrors.ctan.org/macros/latex/base/inputenc.pdf> (accessed 2020 July 27).

[2]	(1, 2) Enrico Gregorio, The newunicodechar package. Last modified 2018 April 8, <http://mirrors.ctan.org/macros/latex/contrib/newunicodechar/newunicodechar.pdf> (accessed 2020 July 27).

[3]	“fontenc vs inputenc”, TeX - LaTeX Stack Exchange. Last modified 2018 April 3, <https://tex.stackexchange.com/q/44694> (accessed 2020 July 27).

[4]	(1, 2, 3) Frank Mittelbach, Robin Fairbairns, Werner Lemberg, and LaTeX3 Project Team, LaTeX font encodings. Last modified 2016 February 18, <https://www.latex-project.org/help/documentation/encguide.pdf> (accessed 2020 July 27).

[5]	(1, 2) Günter Milde, Greek Unicode with 8-bit TeX and inputenc. Last modified 2019 July 11, <http://mirrors.ctan.org/language/greek/greek-inputenc/greek-utf8.pdf> (accessed 2020 July 27).

[6]	(1, 2) Johannes Braams, David Carlisle, Alan Jeffrey, Leslie Lamport, Frank Mittelbach, Chris Rowley, and Rainer Schöpf, The LaTeX2e Sources. Last modified 2020 February 2, <http://mirrors.ibiblio.org/CTAN/macros/latex/base/source2e.pdf> (accessed 2020 July 27).

[7]	Johannes L. Braams and Javier Bezos, Babel: Localization and internationalization. Version 3.47. Last modified 2020 July 13, <http://mirrors.ctan.org/macros/latex/required/babel/base/babel.pdf> (accessed 2020 July 27).

[8]	(1, 2) LaTeX News, issue 28, 2018 April. <https://www.latex-project.org/news/latex2e-news/ltnews28.pdf> (accessed 2020 July 27).

[9]	(1, 2) LaTeX2e unofficial reference manual. Last modified 2018 October, <http://tug.org/texinfohtml/latex2e.html> (accessed 2020 July 27).

[10]	Tobias Oetiker, Hubert Partl, Irene Hyna, and Elisabeth Schlegl, The Not So Short Introduction to LaTeX2ε. Version 6.2. Last modified 2018 February 28, <http://tug.ctan.org/info/lshort/english/lshort.pdf> (accessed 2020 July 27).

[11]	(1, 2) Vladimir Volovich, Werner Lemberg, and LaTeX3 Project Team, Cyrillic languages support in LaTeX. Last modified 1999 March 12, <https://www.latex-project.org/help/documentation/cyrguide.pdf> (accessed 2020 July 27).

[12]	(1, 2) “What are XeTeX and LuaTeX?”, The TeX Frequently Asked Question List. <https://www.texfaq.org/FAQ-xetex-luatex> (accessed 2020 July 27).

[13]	(1, 2, 3, 4, 5) “What Unicode characters does pdfLaTeX support with a minimal preamble?”, TeX - LaTeX Stack Exchange. Last modified 2020 July 27, <https://tex.stackexchange.com/q/555199> (accessed 2020 July 27).

[14]	(1, 2) “Why should I use \usepackage[T1]{fontenc}?”, TeX - LaTeX Stack Exchange. Last modified 2017 April 13, <https://tex.stackexchange.com/a/677> (accessed 2020 July 27).

[15]	Wikipedia contributors, “LuaTeX,” Wikipedia, The Free Encyclopedia. <https://en.wikipedia.org/w/index.php?title=LuaTeX&oldid=965669811> (accessed 2020 July 27).

[16]	XeTeX - Unicode-based TeX. <http://xetex.sourceforge.net> (accessed 2020 July 27).

Knowledge Bits - Software

Retrieving Logs for a Single Service Run from systemd

Basic journalctl(1) Usage

Systemd vs. Service Entries

Invocation IDs

Getting Logs for an Invocation ID

The BitTorrent Encryption Protocol

Converting Lists to Simple Tables and Back with rs

Converting a List of Lines to a Simple Table

Converting a Simple Table to a List of Lines

Basics of Writing Unix Man Pages

Special Version Control Files

All About reStructuredText Hyperlinks

Unicode and LaTeX

pdfTeX Engine (pdfLaTeX)

Non-Latin Alphabets

Cyrillic Alphabet

Greek Alphabet

Other Alphabets

XeTeX Engine (XeLaTeX) and LuaTeX Engine (LuaLaTeX)

References

Basic `journalctl(1)` Usage