[Nix#9015] Manual: render links as textual references on the terminal #111

New issue

Open

opened 2024-03-16 06:44:57 +00:00 by lix-bot · 0 comments

lix-bot commented

2024-03-16 06:44:57 +00:00

Member

Upstream-Issue: NixOS/nix#9015

Problem

Currently links are disabled in terminal output because they are not processed by lowdown. Modern terminals could display interactive links on --help output, but man pages are incapable of that.

It's quite cumbersome and not obvious for contributors to take that into account, and accommodating both web and terminal renderings in a single source is overhead both for editing and reading documentation.

Proposal

Transform links depending on output format. Example:

source:

[nix-store --realise](@docroot@/command-ref/nix-store/realise.md)

man

nix-store --realise (details: `man nix-store-realise`)

help

nix-store --realise (details: `nix-store --help --realise`)

Alternatives

Drop support for man and use info.

Priorities

Add 👍 to issues you find important.

Upstream-Issue: https://git.lix.systems/NixOS/nix/issues/9015 ## Problem Currently links are disabled in terminal output because they are not processed by `lowdown`. Modern terminals could display interactive links on `--help` output, but `man` pages are incapable of that. It's quite cumbersome and not obvious for contributors to take that into account, and accommodating both web and terminal renderings in a single source is overhead both for editing and reading documentation. ## Proposal Transform links depending on output format. Example: - source: ``` [nix-store --realise](@docroot@/command-ref/nix-store/realise.md) ``` - man ``` nix-store --realise (details: `man nix-store-realise`) ``` - help ``` nix-store --realise (details: `nix-store --help --realise`) ## Alternatives Drop support for `man` and use `info`. ## Priorities Add :+1: to [issues you find important](https://github.com/NixOS/nix/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc).

lix-bot added the

imported

label 2024-03-16 06:44:57 +00:00

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: lix-project/lix#111

No description provided.