Feature request: add manpage (troff) support

[ngie-eign]

It would be nice if there was a way to render manpages in GitHub so one could look at documentation checked in.

It seems that some Ruby asciidoc renders allow manpage backends to be enabled ( http://asciidoctor.org/docs/render-documents/ ), but that support doesn't seem to be enabled/present on GitHub (see this example for more details: https://github.com/yaneurabeya/scratch/blob/master/testing/intro.1 ). Could this support be added to github/markup?

[mojavelinux]

The manpage support in Asciidoctor requires that you write the manpage in AsciiDoc. It will then display it similar to how it looks in the man pager. There's also a converter on the way to generate the groff output, so the AsciiDoc becomes the single source of truth. However, Asciidoctor itself does not read or process groff.

There are gems available that read groff and generate HTML, though.

[ngie-eign]

Hi Dan!

On Aug 4, 2014, at 12:45 PM, Dan Allen notifications@github.com wrote:

The manpage support in Asciidoctor requires that you write the manpage in AsciiDoc. It will then display it similar to how it looks in the man pager. There's also a converter on the way to generate the groff output, so the AsciiDoc becomes the single source of truth. However, Asciidoctor itself does not read or process groff.

Hmm…

There are gems available that read groff and generate HTML, though.

That would be nice! The one thing that I could think of that would cause problems is man pages which use custom macros to denote OS, release, etc, where it could mislead readers (do other formats have non-self-contained custom directives?). This seems like an edge case and not the norm though.

Thanks :)!
-Garrett

[rodrigc]

@mojavelinux: What ruby gems do you recommend using for taking a troff document and rendering
HTML?

I've been looking for something, but mostly what I have found are Perl scripts
such as the scripts at:

• http://manned.org/
• https://svnweb.freebsd.org/doc/head/en_US.ISO8859-1/htdocs/cgi/man.cgi
• http://users.softlab.ece.ntua.gr/~christia/man-cgi.html

This utility can render HTML directly from troff:

• http://mdocml.bsd.lv/

but without a nice stylesheet, the output looks boring.

I agree with @yaneurabeya that having Github be able to render man pages directly from checked in sources would be very nice. Large projects like FreeBSD which have code checked into github are not going to redo all their man pages in asciidoctor or other markup languages.

[mojavelinux]

Honestly, I wouldn't know more than just poking around the 'net. I looked a
few times and dabbled, but can't recall anymore what I used.

[bkeepers]

Thanks for the feature request. We are actively adding new markup formats at this time, but you are welcome to submit a pull request to add support for it and we will consider it.