News for hackers. Stuff that matters.
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.

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

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.

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.

Re:History of Unix Manpages (2011) by vngzs on Friday May 29, 2020 @10:00AM (#23350036)
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

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 tyingq on Thursday May 28, 2020 @07:01PM (#23344063)
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.

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 tyingq on Friday May 29, 2020 @07:58AM (#23348906)
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...

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 dredmorbius on Friday May 29, 2020 @01:59AM (#23346696)

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

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

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

Re:History of Unix Manpages (2011) by vletrmx on Thursday May 28, 2020 @06:53PM (#23343963)
mdoc[1] is a significant improvement on the 'man' formatting language, and is already well supported.

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

Re:History of Unix Manpages (2011) by smabie on Thursday May 28, 2020 @07:56PM (#23344602)
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.

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 itomato on Thursday May 28, 2020 @11:25PM (#23345990)
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.

Re:History of Unix Manpages (2011) by tmpfs on Friday May 29, 2020 @02:32AM (#23346867)
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!

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]

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

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

Re:History of Unix Manpages (2011) by smabie on Thursday May 28, 2020 @07:55PM (#23344585)
You can already convert any format to man pages with pandoc if you so desire.
Re:History of Unix Manpages (2011) by arminiusreturns on Thursday May 28, 2020 @07:55PM (#23344594)
I find gnu info, bropages, tldr, and cheatsheet to be much more accessible alternatives to manpages these days, even though rtfm still applies.
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.

Re:History of Unix Manpages (2011) by v3gas on Friday May 29, 2020 @01:06AM (#23346441)