Skip to content
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

Add support for mdoc (e.g. manpages) markup #942

Closed
FireyFly opened this issue Oct 12, 2016 · 2 comments
Closed

Add support for mdoc (e.g. manpages) markup #942

FireyFly opened this issue Oct 12, 2016 · 2 comments

Comments

@FireyFly
Copy link

FireyFly commented Oct 12, 2016

Manpages are the canonical source of documentation on *NIX systems, for both C/system libraries as well as programs (especially command-line tools). As such, many repositories are bound to include manpages next to the souce code, to be installed together with the program/library. Such manual pages are written using the mdoc macro package for troff.

Now, Github already identifies troff files (as groff), but simply renders them as source code. It would be nice if they could be rendered to HTML as well, much like other markup formats, and to make matters simpler both the GNU groff and the mandoc implementations support doing precisely that. So, what would need to be done is to process the generated HTML output and turn it into something presentable on Github, ideally with nice anchor links and everything.

When I searched existing issues, I came across #11 "Support ronn format" which does mention that support for new markup types aren't accepted anymore... however, I do feel the mdoc case is a bit different, considering how prevalent manpages are. Another point is that README files sometimes document options and environment variables for programs as well, which is exactly the kind of documentation that would go in a manpage. Having to maintain the same documentation in two markup formats seems a bit annoying and counterproductive.

I'm not really familiar with Ruby myself, so I don't think I'll look into implementing this myself in the near future, but I figured I could pitch the idea and see whether others think it would be useful with mdoc rendering support for Github. Thoughts?

@FireyFly FireyFly changed the title Add support for troff -mdoc (e.g. manpages) markup Add support for troff mdoc (e.g. manpages) markup Oct 12, 2016
@FireyFly FireyFly changed the title Add support for troff mdoc (e.g. manpages) markup Add support for mdoc (e.g. manpages) markup Oct 12, 2016
@pali
Copy link
Contributor

pali commented Jun 27, 2018

Duplicate of #478

@FireyFly
Copy link
Author

FireyFly commented Jul 3, 2018

Closing since duplicate, per @pali (thanks!)

@FireyFly FireyFly closed this as completed Jul 3, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants