Re: Modernising UNIX manpages.

[James K. Lowden]

On Fri, 23 Apr 2021 02:57:25 +0200
JM Marcastel <don@marcastel.com> wrote:

I think you're confusing two things: the capability of mdoc and groff,
and the user's experience. Don't worry; you're not the first!  

> If all that can be done in mdoc, then fine, I am willing to give a
> try? even if a little frustrated by an antiquated markup syntax.

I have argued that mdoc syntax (and troff's in general) has never been
improved on. There is no documentation system as powerful as troff with
fewer imperatives or less markup overhead.  

> A great achievement, in my view, would be to bring into UNIX manpages
> some of the achievements of Texinfo. Unsorted:
> - Content structure (not simply outlining)
> - Efficient cross-referencing
> - Lists and tables
> - Special displays (floats, images, footnotes)

All of that can be done in troff today, including anchors and links in
PDFs. mdoc itself has no hyperlink support in groff, but it does in
mandoc (https://mandoc.bsd.lv/man/mdoc.7.html#Lk), so the trail is
already blazed.  

> We are not simply piping a man page through a pager, we are
> navigating the documents.

Exactly!  Users experience man pages as text documents in a pager in a
terminal.  For most users -- even for many programmers today -- the
terminal is an alien device, a leftover from the Time Before the Web.
And, really, monospaced fonts in 2021?  

troff is not limiting the user's experience.  Channel any documentation
system you like into less(1), and the experience will be the same.
Channel troff output to a better display, however, and the experience
improves.  That, by the way, is the basic idea behind the mandoc
project.  

As I have argued in this forum and elsewhere, what Linux needs is a
dedicated documentation viewer that takes advantage of the user's
bitmapped display, and -- unlike a web browser or simple PDF viewer --
is specialized for displaying and searching documentation.  

The nearest thing we have to that also has a terrible UI: info(1).  Its
only merit is that in some ways it's better than less(1).  Notably, for
navigation by named links (e.g. indices). 

Allow me to describe something better.  It could use man pages as they
exist today, provide for richer graphical content, and improve the user
experience.  

[snip]
The tool I designed starts not with mdoc, but with ditroff(7), which
IMO is the most succinct description of a bitmapped display there is,
bar none. By working at that level, the tool automatically supports
text and bitmapped graphics, including of course graphs and pictures. 

Besides mechanisms to describe fonts, lines, and motion,
ditroff has "device escapes", which is how it supports PDF links.  

Contrary to most Human Interface Guidelines, decades of GUI experience
prove the *centrality* of the keyboard. The most popular text editors
can be used without a mouse, and all "superuser" tools support
extensive keyboard interaction (which they, tellingly, term
"shortcuts"). A dedicated documentation viewer should build on that
knowledge, and support configurable keyboard input with defaults based
on less(1) and info(1).  For example:

  /     to search by regex
  nN    to repeat a regex search forward/back 
  E     to jump to a new document (with tab-completion)
  I     to jump to an indexed term reference (with completion)
  L     to go back to the last page
  K     for a system-wide keyword search
  H     to display a history of documents
  :b    to return to previous document
  :f    to go to the next document the document stack

Arrow keys scroll the document.  Why info moves the cursor, I'll never
know.  Keyboards since ever had a tab key to move from link to link. 

Like many websites do, I would devote one line near the top of the
screen to a document stack, so the user can see his own breadcrumbs.
Another nice feature of many websites is support for the clipboard, so
sample code can be copied and pasted with perfect fidelity. 

The single feature I would borrow from PDF viewers is the document ToC
on the left (usually) as an expandable outline. For a man page, the
outline hardly matters.  For 300-page document, it's invaluable.  
[pins]

Everything described above can be done using troff ditroff output
with appropriate escapes, most of which exist now.  

The documentation viewers that exist today (as opposed to document
viewers) are amateurish toys.  The worst is xman(1), which stops well
short of what was possible when it was written. The documentation
viewers I used in Qt and Gnome were clumsy and (IIRC) suffered from
being tied to HTML. IMO that is why real users use less(1).  

In short if your goal is to make authoring documentation easier, I
put it to you that's a lost cause.  Experience shows many have tried
and all failed.  But, if your goal is a better experience for the user
trying to read and navigate the documentation we have, and to create a
platform that utilizes the full capability of the user's graphical
interface, then I agree 100%.  

The problem is, the solution to a better tool lies not in the etheral
domain of language design, but in the grotty domain of GUI
programming.  And no one will pay for it.  Other than that, it's easy.  

--jkl