Re:History of Unix Manpages (2011)
by vngzs on Thursday May 28, 2020 @05:42PM
(#23343085)
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.
Re:History of Unix Manpages (2011)
by jolmg on Thursday May 28, 2020 @07:42PM
(#23344482)
> 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.
Re:History of Unix Manpages (2011)
by einpoklum on Thursday May 28, 2020 @06:39PM
(#23343800)
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/
Re:History of Unix Manpages (2011)
by einpoklum on Friday May 29, 2020 @05:12AM
(#23347893)
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.
Re:History of Unix Manpages (2011)
by microtherion on Thursday May 28, 2020 @07:50PM
(#23344541)
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.
Re:History of Unix Manpages (2011)
by dmckeon on Thursday May 28, 2020 @06:40PM
(#23343803)
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.
Re:History of Unix Manpages (2011)
by enriquto on Friday May 29, 2020 @03:33AM
(#23347211)
> (...) 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.
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.
Re:History of Unix Manpages (2011)
by badsectoracula on Friday May 29, 2020 @05:02AM
(#23347848)
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.
Re:History of Unix Manpages (2011)
by LadyCailin on Monday June 01, 2020 @02:45PM
(#23382146)
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.
Re:History of Unix Manpages (2011)
by _jal on Thursday May 28, 2020 @06:21PM
(#23343560)
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.
Re:History of Unix Manpages (2011)
by mprovost on Friday May 29, 2020 @05:01AM
(#23347843)
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]
Re:History of Unix Manpages (2011)
by badsectoracula on Friday May 29, 2020 @04:58AM
(#23347824)
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.
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
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.
It seems like ronn[0] does roughly what I want, as mentioned below.
[0]: https://github.com/apjanke/ronn-ng
Anyway, you should probably ask the author/maintainer of groff about these matters: James Clark, whose homepage is http://www.jclark.com/
Perl's POD is also a pretty natural starting point that generates md and man pages from a reasonable source format.
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.
Also, for Windows, Microsoft made something similar: https://docs.microsoft.com/en-us/powershell/module/microsoft...
A tool or family of tools that convert various other formats to the groff format might be a more accessible project.
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/
[1]: https://manpages.bsd.lv/mdoc.html
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.
Terminal emulators don't handle markdown natively, but *roff is alive and well.
Plan 9 even uses roff.
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!
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.
[0] http://rtomayko.github.io/ronn/ronn.1 [1] https://github.com/apjanke/ronn-ng
https://github.com/apjanke/ronn-ng
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.