You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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?
The text was updated successfully, but these errors were encountered:
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
changed the title
Add support for troff mdoc (e.g. manpages) markup
Add support for mdoc (e.g. manpages) markup
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?
The text was updated successfully, but these errors were encountered: