On Fri, 23 Apr 2021 02:57:25 +0200 JM Marcastel <d...@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
