New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Man page viewer built with web standards #114

Closed
mathiasbynens opened this Issue Apr 22, 2013 · 11 comments

Comments

Projects
None yet
4 participants
@mathiasbynens
Member

mathiasbynens commented Apr 22, 2013

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

This comment has been minimized.

Member

mathiasbynens commented May 19, 2013

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

This comment has been minimized.

SeriousM commented May 23, 2014

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

This comment has been minimized.

Member

mathiasbynens commented May 24, 2014

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

@SeriousM

This comment has been minimized.

SeriousM commented May 24, 2014

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

@mathiasbynens

This comment has been minimized.

Member

mathiasbynens commented May 24, 2014

Some useful resources:

@d0ugal

This comment has been minimized.

d0ugal commented May 27, 2014

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

This comment has been minimized.

SeriousM commented May 27, 2014

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

This comment has been minimized.

d0ugal commented May 27, 2014

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

This comment has been minimized.

d0ugal commented Jun 14, 2014

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

This comment has been minimized.

roperzh commented Jan 17, 2016

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

This comment has been minimized.

Member

mathiasbynens commented Jan 17, 2016

@roperzh Woah, nice work! 👍

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment