Hacker News Reader

Comment by vngzs | Hacker News Reader

I've always wondered: are there any efforts to bring manpages into a modern, easy-to-write text format such as Markdown? I'm sure there are people who would like to write manpages, but are intimidated by the relatively arcane file format & folder structure [0].

We wouldn't want to break existing pages, and surely it would have to be a cross-distro effort, and maybe Markdown isn't the perfect format without modifications. But it's always felt like a natural evolution to me. I suspect some developers (like: most Go program authors) would gladly supply a manual if the workflow were more familiar to people.

[0]: http://www.iitk.ac.in/LDP/HOWTO/Man-Page/index.html

View on HN

> surely it would have to be a cross-distro effort

No. Each person that wants to write a manpage just needs to decide on their own what format they want to write it in and use a tool that converts that format to nroff. There's no need for coordination amongst anyone, and this way there's no risk of breaking existing manpages.

There's multiple such tools. Here's one:

https://github.com/mvertes/txt2man

It's in the main repos of at least Archlinux and Debian.

> maybe Markdown isn't the perfect format without modifications. But it's always felt like a natural evolution to me

I don't think Markdown supports the indentation conventions of manpages.

Thanks for the critique. A conversion tool like that is a much better approach.

It seems like ronn[0] does roughly what I want, as mentioned below.

[0]: https://github.com/apjanke/ronn-ng

Do we have a terminal "renderer" for Markdown? That doesn't make too many assumptions? The could be a start. Or perhaps a utility which renders Markdown as troff.

Anyway, you should probably ask the author/maintainer of groff about these matters: James Clark, whose homepage is http://www.jclark.com/

Pandoc is a fairly popular package that can convert between md and man page formats (many other formats also).

Perl's POD is also a pretty natural starting point that generates md and man pages from a reasonable source format.

That's not what I was asking, actually. I meant rendering markdown directly on a terminal, not going through troff.

But this is not so bad as a temporary measure - instead of having man render the troff and pipe it into pager, pandoc will render the markdown into troff, pipe it to man (I guess), then to pager. Shouldn't be terribly difficult to set up.

Ah, okay. There's mdless: https://github.com/ttscoff/mdless

Also, for Windows, Microsoft made something similar: https://docs.microsoft.com/en-us/powershell/module/microsoft...

I used POD for several years to write my manpages. Recently i bit the bullet and started writing in mdoc. Still not sure this was the right choice: It's a terrible formatting language, but it is a bit richer in what formatting it can express.

    mktotext ()
    {
        pandoc --standalone --from markdown --to html -o - $1 | /usr/bin/w3m -dump -T text/html | ${PAGER:-less}
    }

Tune to preferred utilities. Invoking a console browser directly on the HTML rather than dumping ASCII is another option.

Changing all existing man pages (in all distorts, languages, etc.) seems like a “boil the ocean” solution - perhaps easy on the technical side to automate conversion of 1000s of pages, but harder on the social side of persuading most distros to use a new format.

A tool or family of tools that convert various other formats to the groff format might be a more accessible project.

> (...) intimidated by the relatively arcane file format & folder structure

Notice that there's also mdoc [0], which is a saner format, specifical for manpages. I'm not sure that writing manpages in markdown would be a good idea (or make too much of a difference for the author). A fundamental point of man pages is their very strict format, which is enforced by the markup.

A good way to produce manpages is not to write them, but produce them automatically from your code. One of the best tools for that is GNU's help2man [1], where you only have to write the "--help" and "--version" options on your program, and help2man creates a manpage from that.

[0] https://man.openbsd.org/mdoc.7

[1] https://www.gnu.org/software/help2man/

mdoc[1] is a significant improvement on the 'man' formatting language, and is already well supported.

[1]: https://manpages.bsd.lv/mdoc.html

Yeah, it's better. But still sucks. Check out this man page I wrote using mdoc: https://github.com/smabie/stag/blob/master/stag.1

I don't even have any idea what it says or means anymore.. There's no reason (anymore) for macros to only be at the beginning of the line. But will this requirement ever go away? I doubt it.

One thing i do not understand, why bother writing this format directly instead of using some WYSIWYG editor (none exists - that i know of - for manpages specifically, but... why?)? All you need is to have some autoformatting for the output so that diffs in source control (if you care for that) are readable, but beyond that you shouldn't need to care at all about how the source looks for something that is essentially a rich text document - and rich text editors existed since the dawn of personal computing.

My experience with most *nix environments is that it’s mostly written for machines by programmers. Doesn’t seem like there’s much in the way of user researchers figuring out how to make it useable by non-programmer humans. Apple products excepted.

Pandoc can handle groff, but what does Markdown offer?

Terminal emulators don't handle markdown natively, but *roff is alive and well.

Plan 9 even uses roff.

I wrote some tooling around this for creating man pages from markdown for CLI apps:

https://github.com/mkdoc/mkcli

And a generic man page output is here:

https://github.com/mkdoc/mkout/blob/master/README.md#mkman

It does make the experience much nicer than writing TROFF!

groff really isn't difficult to write. The main problem with it is that it is terrible to edit after you've been away from it for a while.

That said, a markdown front end is probably not a bad idea. It would address editability and approachability for people who get anxious around old formats.

ronn is a useful tool for writing manpages in Markdown and produces great output [0]. The original project is unmaintained but there's a current fork. [1]

[0] http://rtomayko.github.io/ronn/ronn.1 [1] https://github.com/apjanke/ronn-ng

https://github.com/apjanke/ronn-ng

You can already convert any format to man pages with pandoc if you so desire.

I find gnu info, bropages, tldr, and cheatsheet to be much more accessible alternatives to manpages these days, even though rtfm still applies.

Texinfo in general is also better for something longer than a few "pages" since it is meant for actual manuals, with content lists, indexes, search, hyperlinks, chapters, etc instead of the text vomit you get with with a manpage.

Similar to Windows CHM (for which there are cross platform tools to create and view - e.g. Free Pascal and Lazarus have their own CHM generator and viewer) and other similar documentation formats that provide some form of organization and metadata.

Reply on news.ycombinator.com