7 ms·

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 lik

by vngzs 6y ago

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 http://www.iitk.ac.in/LDP/HOWTO/Man-Page/index.html

_jal 6y ago
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.
jolmg 6y ago
> 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 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.
- vngzs 6y ago
  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 https://github.com/apjanke/ronn-ng
einpoklum 6y ago
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/ http://www.jclark.com/
- tyingq 6y ago
  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.
  - microtherion 6y ago
    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.
  - einpoklum 6y ago
    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.
    - tyingq 6y ago
      Ah, okay. There's mdless: https://github.com/ttscoff/mdless https://github.com/ttscoff/mdless Also, for Windows, Microsoft made something similar: https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/show-markdown https://docs.microsoft.com/en-us/powershell/module/microsoft...
- deleted 6y ago
  [deleted]
dmckeon 6y ago
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.
vletrmx 6y ago
mdoc[1] is a significant improvement on the 'man' formatting language, and is already well supported. [1]: https://manpages.bsd.lv/mdoc.html https://manpages.bsd.lv/mdoc.html
- smabie 6y ago
  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 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.
  - badsectoracula 6y ago
    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.
    - LadyCailin 6y ago
      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.
smabie 6y ago
You can already convert any format to man pages with pandoc if you so desire.
arminiusreturns 6y ago
I find gnu info, bropages, tldr, and cheatsheet to be much more accessible alternatives to manpages these days, even though rtfm still applies.
- badsectoracula 6y ago
  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.
itomato 6y ago
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.
tmpfs 6y ago
I wrote some tooling around this for creating man pages from markdown for CLI apps: https://github.com/mkdoc/mkcli https://github.com/mkdoc/mkcli And a generic man page output is here: https://github.com/mkdoc/mkout/blob/master/README.md#mkman https://github.com/mkdoc/mkout/blob/master/README.md#mkman It does make the experience much nicer than writing TROFF!
enriquto 6y ago
> (...) 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 https://man.openbsd.org/mdoc.7 [1] https://www.gnu.org/software/help2man/ https://www.gnu.org/software/help2man/
mprovost 6y ago
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 http://rtomayko.github.io/ronn/ronn.1 [1] https://github.com/apjanke/ronn-ng https://github.com/apjanke/ronn-ng https://github.com/apjanke/ronn-ng https://github.com/apjanke/ronn-ng

by vngzs 6y ago

_jal 6y ago

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.

jolmg 6y ago

> 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 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.

vngzs 6y ago
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 https://github.com/apjanke/ronn-ng

einpoklum 6y ago

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/ http://www.jclark.com/

tyingq 6y ago
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.
- microtherion 6y ago
  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.
- einpoklum 6y ago
  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.
  - tyingq 6y ago
    Ah, okay. There's mdless: https://github.com/ttscoff/mdless https://github.com/ttscoff/mdless Also, for Windows, Microsoft made something similar: https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/show-markdown https://docs.microsoft.com/en-us/powershell/module/microsoft...
deleted 6y ago
[deleted]

dmckeon 6y ago

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.

vletrmx 6y ago

mdoc[1] is a significant improvement on the 'man' formatting language, and is already well supported. [1]: https://manpages.bsd.lv/mdoc.html https://manpages.bsd.lv/mdoc.html

smabie 6y ago
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 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.
- badsectoracula 6y ago
  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.
  - LadyCailin 6y ago
    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.

smabie 6y ago

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

arminiusreturns 6y ago

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

badsectoracula 6y ago
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.

itomato 6y ago

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.

tmpfs 6y ago

I wrote some tooling around this for creating man pages from markdown for CLI apps: https://github.com/mkdoc/mkcli https://github.com/mkdoc/mkcli And a generic man page output is here: https://github.com/mkdoc/mkout/blob/master/README.md#mkman https://github.com/mkdoc/mkout/blob/master/README.md#mkman It does make the experience much nicer than writing TROFF!

enriquto 6y ago

> (...) 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 https://man.openbsd.org/mdoc.7 [1] https://www.gnu.org/software/help2man/ https://www.gnu.org/software/help2man/

mprovost 6y ago

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 http://rtomayko.github.io/ronn/ronn.1 [1] https://github.com/apjanke/ronn-ng https://github.com/apjanke/ronn-ng https://github.com/apjanke/ronn-ng https://github.com/apjanke/ronn-ng