Man page viewer built with web standards

[mathiasbynens]

Writing man pages by hand is pretty horrible. For this reason, most people auto-generate man pages based on Markdown or something else, nowadays.

But it doesn’t have to be that way.

Imagine having a JavaScript library that takes a man page as a string (e.g. https://github.com/mathiasbynens/luamin/blob/master/man/luamin.1) and renders it as HTML. It would be immensely useful.

Currently the workflow for editing a man page by hand goes something like this:

1. Edit man page source file.
2. Run man ./man-page-source-file.1.
3. Confirm the resulting man page looks alright. If it doesn’t, GOTO 1.

Having such a library would make it possible to edit man pages right in the browser, complete with a live preview and everything — the workflow would then be much easier and more efficient. Hipsters around the world would rejoice.

[mathiasbynens]

Ah, I just found Mandrake.app, which kind of does this: http://sveinbjorn.org/mandrake Except it’s a native OS X app, so it can’t be used on Linux.

[SeriousM]

I like the idea! Do you think this should be a kind of service (website) or more a standalone application?
In case of the second one we could use https://github.com/atom/atom-shell/ as the shell. The good thing is that it uses a nodejs/chrome combination inside and it's cross-platform compatible for osx, linux and windows.

[mathiasbynens]

Ideally it would just be a web app. But something based on Atom shell would be nice too.

[SeriousM]

Do you have a documentation about the man-format? I would start implementing a parser then.

[mathiasbynens]

Some useful resources:

• http://unix.stackexchange.com/a/3587/6040
• http://www.cyberciti.biz/faq/linux-unix-creating-a-manpage/
• Also: man mdoc and /usr/share/misc/mdoc.template.

[d0ugal]

Great idea. I actually started doing something like this, I was inspired by an interview with @joestump. The bit that caught my attention...

If you choose UNIX read one man page a day until you’ve read all of the GNU utilities’ man pages.

I wanted to make this easier and better for everyone to do. It would be mobile friendly, provide a reading list and random pages to read. Then as you go you could check them off etc.

However, unfortunately I didn't get very far. I did however start reading more man pages :) I would still love to see this happen, so I'd be happy to help. I can dig out the code I started and see if any of it doesn't make my eyes bleed.

[SeriousM]

I can dig out the code I started and see if any of it doesn't make my eyes bleed.

hahaha, sounds good! what of the code is already done? parsing?

[d0ugal]

Yeah, I think so. I'm not sure I actually have it tho' - this was several years ago. I can check tonight, but don't let that stop you. It's probably only useful for reference.

[d0ugal]

I totally forgot about this until now, I can't find the code I started for it. I'd like to have a go at writing it tho' - have you managed to find time to give it a go?

[roperzh]

Hello, everyone!

This issue inspired me to build two projects:

• Jroff: a man page parser written in JavaScript, featuring basic support for groff commands and support for an and doc macros.
• Grapse: a web application that uses Jroff to parse man pages in real time ( very similar to dillinger, but for man pages ).

Both projects are still in beta, but everyone is more than welcome to contribute / criticize / help in any way :).

cc: @mathiasbynens @d0ugal @SeriousM

[mathiasbynens]

@roperzh Woah, nice work! 👍