Re: Man pages are great, man readers are the problem

Re: Man pages are great, man readers are the problem

[Matěj Cepl]

[-- Attachment #1.1.1: Type: text/plain, Size: 1579 bytes --]

(reaction to the blog post “Man pages are great, man readers are
the problem” [1] and the email reaction to it [2])

On Thu Apr 24, 2025 at 2:31 PM CEST, Andrew Thorp wrote:
> I appreciated your post regarding man pages as I like to read man pages
> for documentation but had no idea they're so richly linked. Today I
> discovered that the Chawan text-based web browser can also read the man
> formats, and in fact comes with a utility `mancha` which one uses just
> like `man` but which renders the man page using chawan [1].

Please, not yet another small and irrelevant programming langauge
for something which could (and probably should) be a shell script.

While the current man(1) is mostly just `nroff -T utf8
<manpage>|less` I would like if we can finally upgrade to 1990s
and use `roff -T html <manpage>|w3m -T text/html` instead?

Do we need yet another dependency on a weird programming language
for it? (yes, author can write a program in any language they
want, but do I have to use it?)

Best,

Matěj

[1] https://whynothugo.nl/journal/2025/04/09/man-pages-are-great-man-readers-are-the-problem/
[2] https://lists.sr.ht/~whynothugo/public-inbox/%3CD9EVCM0CFDB8.NSOLZ6J86B0W@redhat.com%3E
-- 
http://matej.ceplovi.cz/blog/, @mcepl@en.osm.town
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8
 
Because dwm is customized through editing its source code, it’s
pointless to make binary packages of it. This keeps its userbase
small and elitist. No novices asking stupid questions.
  -- http://dwm.suckless.org/


[-- Attachment #1.2: E09FEF25D96484AC.asc --]
[-- Type: application/pgp-keys, Size: 3102 bytes --]

-----BEGIN PGP PUBLIC KEY BLOCK-----

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
wwCdEnRlCGlvnO78R0FgKXlt3RyzGuE=
=sxoW
-----END PGP PUBLIC KEY BLOCK-----

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 216 bytes --]

Re: Man pages are great, man readers are the problem

[Ingo Schwarze]

Hello,

Matej Cepl wrote on Thu, Apr 24, 2025 at 04:47:40PM +0200:

> reaction to the blog post
> "Man pages are great, man readers are the problem"
> https://whynothugo.nl/journal/2025/04/09/man-pages-are-great-man-readers-are-the-problem/

I agree with everything said in that block post, with two exceptions:

>> we need a pager which understands man pages natively.

That's an extremely bad idea.

Correctly parsing manual pages is a rather complicated task.
The mandoc(1) toolkit is not yet feature complete and already has
over forty thousand lines of code in C files.  That's more than
double the code size of less(1) in OpenBSD.

Conversely, i'm not convinced mandoc(1) should grow its own
pager.  If i were to write a pager, it would be *much* less bloated
than less(1) and only have a tiny fraction of its features.
But then no doubt lots of people would be very unhappy because
no doubt many people use more features in less(1) than i do.

Integration of man(1) into mandoc(1) was a natural step for three
reasons:
 (1) finding a manual page in the file system, which is the main
     task of man(1), is closely enough related to parsing it
 (2) the amount of code required for the integration was rather
     small
 (3) the integration enabled some unification and simplification
     of the command line options

Integratio of less(1) into mandoc(1) would not have any such advantages
and would require massive amounts of code.  So in this case, the
traditional UNIX approach - let every tool do one task, and do it well -
seems preferable.

>> we could also re-flow text when the terminal window is made narrower.

This has been discussed before and i shot it down as pointless,
intrusive complication.  In the rare case that you make a window narrower,
what's wrong with typing q arrow-up enter ?  Note that full reformatting
is required in the narrower window anyway, so you couldn't reasonably
hope to remain at the same place in the manual page either way.

> and the email reaction to it
> https://lists.sr.ht/~whynothugo/public-inbox/%3CD9EVCM0CFDB8.NSOLZ6J86B0W@redhat.com%3E

>> Today I discovered that the Chawan text-based web browser can
>> also read the man formats

This is wildly inaccurate.  In the file adapter/protocol/man.nim
you can see that all chawan does with manual pages is

  execl("/bin/sh", "sh", "-c", "/some/path/to/man", more arguments

which means calling whatever is installed on the system as the
native man(1) program, and then some naive postprocessing.
All this looks extremely naive and pedestrian.  
I most definitely wouldn't trust it at all for my manual page
reading.  Layers on top of layers of abstraction on top of other
tools, and all those layers are likely full of bugs, considering
how naive it all looks.

I think dismissing chawan as rubbish is a safe bet.

> On Thu Apr 24, 2025 at 2:31 PM CEST, Andrew Thorp wrote:

>> I appreciated your post regarding man pages as I like to read man pages
>> for documentation but had no idea they're so richly linked. Today I
>> discovered that the Chawan text-based web browser can also read the man
>> formats, and in fact comes with a utility `mancha` which one uses just
>> like `man` but which renders the man page using chawan [1].

> Please, not yet another small and irrelevant programming langauge
> for something which could (and probably should) be a shell script.
> 
> While the current man(1) is mostly just `nroff -T utf8
> <manpage>|less` I would like if we can finally upgrade to 1990s
> and use `roff -T html <manpage>|w3m -T text/html` instead?

I disagree.  For terminal display, HTML is not better than -T utf8
display.  The terminal formatter provides lots of fine formatting
details that HTML cannot express, so on the terminal, terminal
output is more readable than HTML output.

Also, in terminal output, following liks isn't all that important.
When i want to follow a link, i usually want to contonue reading where
i was afterwards, so i typically paste the manual page name that is
linked to to a separate man(1) command in another terminal window
and look at both windows side by side.  Maybe following links would
occasionally be nice to have, but not really important.

Needless to say, on the web, the tradeoff is completely different -
but there, the problem is already completely solved with HTML
output and CSS, see e.g. man.openbsd.org .

All that said, improving support for users who actively opt into
using HTML for manual page display would make sense.
For example, we need sensible defaults for the -O style and
-O man options - but achieving that is not trivial.  But let's
not force HTML down everyone's throat.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: Man pages are great, man readers are the problem

[Matěj Cepl]

[-- Attachment #1.1.1: Type: text/plain, Size: 1408 bytes --]

On Thu Apr 24, 2025 at 7:50 PM CEST, Ingo Schwarze wrote:
>> While the current man(1) is mostly just `nroff -T utf8
>> <manpage>|less` I would like if we can finally upgrade to 1990s
>> and use `roff -T html <manpage>|w3m -T text/html` instead?
>
> I disagree.  For terminal display, HTML is not better than -T utf8
> display.  The terminal formatter provides lots of fine formatting
> details that HTML cannot express, so on the terminal, terminal
> output is more readable than HTML output.

What I meant is that since 1990s when I see a link I would like
to be able to activate it (and actually I am not talking about
HTML only, I have been a happy user of early pre-HTML hypertext
programs like Houdini, MaxThink, and HyperRez, not mentioning
Plan 9 and plumber [1]). Copying text of the link to command line
as an argument of the command line feels distinctly pre-1990s.

Best,

Matěj

[1] When I asked last week Gemini about equivalents of Plan9
    plumber on Linux, it went distinctly melancholic,
    https://paste.sr.ht/~mcepl/03bcccc7243e7cb56e40dfabc7f208d200e10ea0
-- 
http://matej.ceplovi.cz/blog/, @mcepl@en.osm.town
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8
 
SCSI is *not* magic. There are *fundamental* *technical*
reasons why you have to sacrifice a young goat to your SCSI
chain every now and then.
    -- John F. Woods, SCSI HowTo


[-- Attachment #1.2: E09FEF25D96484AC.asc --]
[-- Type: application/pgp-keys, Size: 3102 bytes --]

-----BEGIN PGP PUBLIC KEY BLOCK-----

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
wwCdEnRlCGlvnO78R0FgKXlt3RyzGuE=
=sxoW
-----END PGP PUBLIC KEY BLOCK-----

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 216 bytes --]

Re: Man pages are great, man readers are the problem

[Steffen Nurpmeso]

Matěj Cepl wrote in
 <D9F4H0KQCSY6.3N5DFVYMD20SU@cepl.eu>:
 |On Thu Apr 24, 2025 at 7:50 PM CEST, Ingo Schwarze wrote:
 |>> While the current man(1) is mostly just `nroff -T utf8
 |>> <manpage>|less` I would like if we can finally upgrade to 1990s
 |>> and use `roff -T html <manpage>|w3m -T text/html` instead?
 |>
 |> I disagree.  For terminal display, HTML is not better than -T utf8
 |> display.  The terminal formatter provides lots of fine formatting
 |> details that HTML cannot express, so on the terminal, terminal
 |> output is more readable than HTML output.
 |
 |What I meant is that since 1990s when I see a link I would like
 |to be able to activate it (and actually I am not talking about
 |HTML only, I have been a happy user of early pre-HTML hypertext
 |programs like Houdini, MaxThink, and HyperRez, not mentioning
 |Plan 9 and plumber [1]). Copying text of the link to command line
 |as an argument of the command line feels distinctly pre-1990s.

With less(1) version 650 and above, best with brand-new 676 (fixes
some bugs) and above, there you get OSC-8 links.  This is pretty
fancy, and i would only wish more people would make use of it:

 ^O^O
    Run a shell command to open the URI in the current OSC  8  hyper‐
    link,  selected  by a previous ^O^N or ^O^P command.  To find the
    shell command, the environment variable named "LESS_OSC8_xxx"  is
    read, where "xxx" is the scheme from the URI (the part before the
    first  colon),  or is empty if there is no colon in the URI.  The
    value of the environment variable is then expanded  in  the  same
    way as prompt strings (in particular, any instance of "%o" is re‐
    placed with the URI) to produce an OSC 8 "handler" shell command.
    The standard output from the handler is an "opener" shell command
    which is then executed to open the URI.

    There are two special cases:

           1.     If  the  URI  begins with "#", the remainder of the
                  URI is taken to be the value of the id parameter in
                  another OSC 8 link in the same file, and ^O^O  will
                  simply jump to that link.

^ That he did that is so fine i got grazy!  (It drives my mdocmx.)

           2.     If  the opener begins with the characters ":e" fol‐
                  lowed by whitespace and a filename, then instead of
                  running the opener as a shell command,  the  speci‐
                  fied  filename is opened in the current instance of
                  less.

    In a simple case where the opener accepts the complete URI  as  a
    command line parameter, the handler may be as simple as

    echo mybrowser ’%o’

    In  other  cases, the URI may need to be modified, so the handler
    may have to do some manipulation of the %o value.

    If  the  LESS_OSC8_xxx  variable  is  not   set,   the   variable
    LESS_OSC8_ANY   is   tried.    If   neither   LESS_OSC8_xxx   nor
    LESS_OSC8_ANY is set, links using  the  "xxx"  scheme  cannot  be
    opened.   However,  there  are  default  handlers for the schemes
    "man" (used when LESS_OSC8_man is not set) and "file" (used  when

^ And that.

    LESS_OSC8_file  is  not  set), which should work on systems which
    provide the sed(1) command and a  shell  with  syntax  compatible
    with  the  Bourne shell sh(1).  If you use LESS_OSC8_ANY to over‐
    ride LESS_OSC8_file, you must set LESS_OSC8_file to "‐" to  indi‐
    cate  that the default value should not be used, and likewise for
    LESS_OSC8_man.

    The URI passed to an OSC8 handler via %o  is  guaranteed  not  to
    contain  any  single quote or double quote characters, but it may
    contain any other shell metacharacters such as semicolons, dollar
    signs, ampersands, etc.  The handler should take care  to  appro‐
    priately  quote parameters in the opener command, to prevent exe‐
    cution of unintended shell commands in the case of opening a  URI
    which  contains  shell  metacharacters.   Also, since the handler
    command is expanded like a command prompt, any metacharacters in‐
    terpreted by prompt expansion (such as percent, dot, colon, back‐
    slash, etc.) must be escaped with a backslash  (see  the  PROMPTS
    section for details).

Ie, you get browser like behavior on a text terminal within
a manual page.  I hope for a better and interactive UNIX manual
future.

--steffen
|
|Der Kragenbaer,                The moon bear,
|der holt sich munter           he cheerfully and one by one
|einen nach dem anderen runter  wa.ks himself off
|(By Robert Gernhardt)
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: Man pages are great, man readers are the problem

[Matěj Cepl]

[-- Attachment #1.1.1: Type: text/plain, Size: 803 bytes --]

On Fri Apr 25, 2025 at 11:13 AM CEST, Steffen Nurpmeso wrote:
> With less(1) version 650 and above, best with brand-new 676 (fixes
> some bugs) and above, there you get OSC-8 links.  This is pretty
> fancy, and i would only wish more people would make use of it:

Hmm, so I have created package for less 676 [1] (I understand
our maintainer he doesn’t want to upgrade the distro until it is
officially released), but now how to persuade mandoc to actually
generate the links?

Thank you for the hint,

Matěj

[1] https://build.opensuse.org/package/show/home:mcepl/less
-- 
http://matej.ceplovi.cz/blog/, @mcepl@en.osm.town
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8
 
To the well-organized mind, death is but the next great adventure.
  -- Albus Dumbledore


[-- Attachment #1.2: E09FEF25D96484AC.asc --]
[-- Type: application/pgp-keys, Size: 3102 bytes --]

-----BEGIN PGP PUBLIC KEY BLOCK-----

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
wwCdEnRlCGlvnO78R0FgKXlt3RyzGuE=
=sxoW
-----END PGP PUBLIC KEY BLOCK-----

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 216 bytes --]

Re: Man pages are great, man readers are the problem

[Ingo Schwarze]

Hello Matej,

Matej Cepl wrote on Fri, Apr 25, 2025 at 03:42:40PM +0200:

> but now how to persuade mandoc to actually generate the links?

You won't.

NOT generating any ANSI escape codes is among the most fundamental
design descisions of mandoc(1), and the reason for that decision
is security / defense in depth.

Keep in mind that mandoc(1) is supposed to be secure to run
 - as root
 - on untrusted input
 - even if run in the only terminal+shell you have on a system.
For example, a user might stop sshd(8) on a remote system,
intending to edit the configuration, then restart sshd(8).
Amid the editing process, the user might look at manual pages.
If the man(1) program then makes the terminal window unusable,
the user may have shut themselves out of the remote system.

The ANSI X3.64 (ISO/IEC 6429) standard supports a very large number
of different escape sequences.  Nobody doubts that several of these
sequences are very dangerous no matter the context.  Few people, if
any, doubt that many more of these sequences can be dangerous
depending on the context and use case.  A few people think that it
is possible to pick and choose which of these sequences to honour
and which to ignore, such that their use becomes secure.  For example,
many people think that the sequnces changing the text colour pose a
relatively small danger.  Then again, even those can easily cause
harm by making output unreadable - and not only within one file
that is printed to the terminal, but affecting all subsequent
iutput, even if completely unrelated.

In any case, keeping a system secure requires keeping each layer of
the system secure, even under the assumption that all other layers
may be broken, such that you have multiple layers of cheese protecting
your security.  Generating any kind of ANSI X3.64 would be akin to
using a slice of Swiss cheese for one of the layers, arguing "let's
make sure that none of the holes aligns with any hole i other layers,
and we are secure".  Allowing the pager (e.g. less(1)) to honour
any kind of ANSI X3.64 would already poke holes into a second of the
protective layers.

Thinking such Swiss cheese protection is secure is utterly foolish.
Experience shows that sooner or later, something *will* go wrong,
holes will align, and security will be compromised,   That is
especially true when a misfeature is as sprawling, with as many
moving parts that have to be controlled, as ANSI X3.64.  With so
many different escape codes, it's particularly likely that *some*
dangers will be overlooked.  For that reason, mandoc(1) will
never produce ANSI X3.64.

Also note that OSC is among the most dangerous ANSI escape codes
because it is not even standardized.  All the standard says about
it (in paragrph 8.3.89) is

  OSC is used as the opening delimiter of a control string for
  operating system use.  The command string following may consist
  of a sequence of bit combinations in the range 00/08 to 00/13
  and 02/00 to 07/14.  The control string is closed by the terminating
  delimiter STRING TERMINATOR (ST).  The interpretation of the command
  string depends on the relevant operating system.

So not only does the standard literally allow OSC to do *anything* to
the terminal with no restrictions - which means it does not only replace
this layer of cheese with Swiss cheese, but removes this layer entirely -
but even worse, using OSC 8 for hyperlinks violates the standard
because the standard defines that *operating systems* can use
OSC for OS-specific purposes.  The mandoc(1) command is designed
to be portable and OS-independent.  So even if it were willing
to use ANSI X3.64 (which it isn't), it couldn't possibly use OSC.
Using OSC 8 for hyperlinks is akin to using variable names starting
with double underscores in C code: it blatantly and directly violates
the relevant standard.

I'm open to other solutions for making links work in terminal output -
but i have to admit so far, no particularly good solution has been
proposed yet, and since the task isn't all that urgent, that
resulted in the feature not being implemented yet, in marked
contrast to HTML, where it is a natural feature that was implemented
many years ago.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: Man pages are great, man readers are the problem

[Ingo Schwarze]

Hello Matej,

Matej Cepl wrote on Thu, Apr 24, 2025 at 09:39:53PM +0200:

> What I meant is that since 1990s when I see a link I would like
> to be able to activate it (and actually I am not talking about
> HTML only, I have been a happy user of early pre-HTML hypertext
> programs like Houdini, MaxThink, and HyperRez, not mentioning
> Plan 9 and plumber [1]). Copying text of the link to command line
> as an argument of the command line feels distinctly pre-1990s.

I agree that being able to follow links would be nice to have in
terminal output, even though less important than in HTML output.

ECMA-48 is a non-starter though, OSC among the worst parts of ECMA-48,
and abusing OSC 8 for hyperlinks is totally out of the question,
as i explained in more detail on the mandoc mailing list:

  https://marc.info/?l=mandoc-discuss&m=174559265520868

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: Man pages are great, man readers are the problem

[Steffen Nurpmeso]

Ingo Schwarze wrote in
 <aAuinu7MveztIfmd@isnote.usta.de>:
 ...
 |because it is not even standardized.  All the standard says about
 |it (in paragrph 8.3.89) is

ECMA-48, 5th Edition.

 |  OSC is used as the opening delimiter of a control string for
 |  operating system use.  The command string following may consist
 |  of a sequence of bit combinations in the range 00/08 to 00/13
 |  and 02/00 to 07/14.  The control string is closed by the terminating
 |  delimiter STRING TERMINATOR (ST).  The interpretation of the command
 |  string depends on the relevant operating system.
 ...
 |because the standard defines that *operating systems* can use
 |OSC for OS-specific purposes.[.]

Yes.  UNIX manual pages among which.  Thank you.

--steffen
|
|Der Kragenbaer,                The moon bear,
|der holt sich munter           he cheerfully and one by one
|einen nach dem anderen runter  wa.ks himself off
|(By Robert Gernhardt)
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: Man pages are great, man readers are the problem

[Matěj Cepl]

[-- Attachment #1.1.1: Type: text/plain, Size: 1105 bytes --]

On Fri Apr 25, 2025 at 4:56 PM CEST, Ingo Schwarze wrote:
> NOT generating any ANSI escape codes is among the most fundamental
> design descisions of mandoc(1), and the reason for that decision
> is security / defense in depth.

Your project, your decision, but let me here suggest, that
this decision is completely and fundamentally wrong. If you
are making a car intended for the general audience your first
thought shouldn’t be “What if somebody used this car to deliver
supplies on the Russia/Ukraine front? Could we make it solid
enough to resist loitering munition? We cannot rely on just one
level of security, but it must be multi-layered, etc.” And that’s
basically what you are doing here. We are not talking about SSH
server (which is truly meant to be used in the battle scenarios),
but a documentation viewer with limited and mostly controlled set
of documents. I don’t want to use APC for my daily shopping!

Best,

Matěj

-- 
http://matej.ceplovi.cz/blog/, @mcepl@en.osm.town
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8
 
<”}}}><


[-- Attachment #1.2: E09FEF25D96484AC.asc --]
[-- Type: application/pgp-keys, Size: 3102 bytes --]

-----BEGIN PGP PUBLIC KEY BLOCK-----

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
wwCdEnRlCGlvnO78R0FgKXlt3RyzGuE=
=sxoW
-----END PGP PUBLIC KEY BLOCK-----

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 216 bytes --]

Re: Man pages are great, man readers are the problem

[Steffen Nurpmeso]

Matěj Cepl wrote in
 <D9FVM4RCAMJ8.EXZ9SFXYZPNN@cepl.eu>:
 |On Fri Apr 25, 2025 at 4:56 PM CEST, Ingo Schwarze wrote:
 |> NOT generating any ANSI escape codes is among the most fundamental
 |> design descisions of mandoc(1), and the reason for that decision
 |> is security / defense in depth.
 |
 |Your project, your decision, but let me here suggest, that
 |this decision is completely and fundamentally wrong.[.]

Nah, it is also about Ingo's threshold.  For example he then
later, after talking almost the same, implemented direct .gz aka
gzip file support.  And .. i do not exaggerate when i say his
"defense in depth" is more like a "Dampfnudel", which can be
verified very easily by renaming whatever to something with a .gz
file extension, and mandoc(1) will happily trash the terminal with
whatever there is, for example

  p$ mandoc x.1.gz | cat -vet
  ()                                                                          ()$
  $
  M-CM-=7zXZ???M-CM-&M-CM-^VM-BM[.....]

It will gobble just any file by the way, and shamelessly hammer
through any control and whatever that it encounters.

You know, that is .. ok.  But it is not "defense in depth",
especially if you take into account what this means for OpenSSH,
where they now parse files before they dlopen(3) them, if i recall
correctly, and similar.

--steffen
|
|Der Kragenbaer,                The moon bear,
|der holt sich munter           he cheerfully and one by one
|einen nach dem anderen runter  wa.ks himself off
|(By Robert Gernhardt)
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: Man pages are great, man readers are the problem

[Mingye Wang]

On Fri, Apr 25, 2025 at 3:39 AM Matěj Cepl <mcepl@cepl.eu> wrote:
> Copying text of the link to command line
> as an argument of the command line feels distinctly pre-1990s.

In a way not quite pre-1990s: you do have windows and clipboards to
make copying easier than manual typing. That was indeed used a bit
earlier in the conversation to make it seem like not having hyperlinks
is actually tolerable :)

Well, being someone who often reads the man page over an ssh link and
somehow still not a power user of tmux or screen (which is my own
fault), I do agree about the usefulness of links.

On Fri, Apr 25, 2025 at 11:03 PM Ingo Schwarze <schwarze@usta.de> wrote:
> NOT generating any ANSI escape codes is among the most fundamental
> design descisions of mandoc(1)...
> [...]
> even those can easily cause
> harm by making output unreadable - and not only within one file
> that is printed to the terminal, but affecting all subsequent
> iutput, even if completely unrelated.

I understand that OpenBSD relies on a very tight security model
brought, in part, by feature minimization. But really how minimal is
the current approach of not emitting ANSI escape codes? Right now
mandoc's terminal driver just puts out overstrike sequences, a format
not understood by most terminal devices [by the admission of man(1) in
OpenBSD-current]. On most terminal devices this then becomes a problem
for the pager [less(1) by default, same man page], which achieves it
by... honoring ANSI escape codes and emitting them.

If ANSI escape codes are truly a toxic misfeature that puts holes into
everything they touch sooner or later, then they must too render the
terminal application that emit them (such as pagers) unacceptably
hole-rich for OpenBSD. But the thing is, they aren't. Formatting is
stateful and goes on and on to affect readability, yes, but that
subset has a clear reset code <ESC>[0m. The pager tries its best to
not mess up the console by doing resets every once in a while and on
SIGTERM, but it can spill if a SIGKILL comes. That people seem to have
accepted, or it would not be in OpenBSD.

mandoc can do the same kind of precautions on generating ANSI
sequences. There is an additional assumption that less(1) will honor a
subset of ANSI escape codes not only on output, but also on intake,
but I still don't see how that becomes a huge leap of faith involving
a lot of additional moving parts.

> using OSC 8 for hyperlinks violates the standard
> because the standard defines that *operating systems* can use
> OSC for OS-specific purposes.  The mandoc(1) command is designed
> to be portable and OS-independent.

The term "operating system" means little different from "vendor". If
an operating system does not use OSC 8 this way, it can choose to not
ship mandoc as part of its standard distribution, or to patch it out.
I believe mandoc(1) still implements .Os with the ability to accept an
argument which changes the emitted OS name: does that violate what the
"operating system" wants too?

Best,
Mingye
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv