mirror of
https://github.com/xoofx/markdig.git
synced 2026-02-03 21:36:36 +00:00
Manpage renderer #208
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Originally created by @ghost on GitHub (Jun 1, 2018).
Based on: https://github.com/dotnet/docfx/issues/2648#issuecomment-393918553
@xoofx, do you know of a good spec of manpage that would work on BSD, OSX, Linux and Solaris?
Pandoc's man writer is
d32e866449/src/Text/Pandoc/Writers/Man.hs. We probably need some specs to validate output.@ghost commented on GitHub (Jun 5, 2018):
@omajid, do you know of any place where we can find spec suite for manpages that would work across the board of Unix-like operating systems?
For example, i don't get the difference between
https://linux.die.net/man/1/man and
https://linux.die.net/man/7/man
and apparently NET-2 BSD uses mdoc compatible macros, which doesn't work on Linux without providing
-mdocswitch to man(7). In order to validate the implementation, it would be great to have some markdown and corresponding manpage.@omajid commented on GitHub (Jun 5, 2018):
Sorry, not off the top of my head. I will look into it.
As I understand it,
man(1)is about themancommand and how to use it.man(7)is about how to write those man pages - their syntax and other implementation details.Does the other way around work? If we use the non-mdoc macros, do docs render correctly on NetBSD and other BSDs?
@ghost commented on GitHub (Jun 6, 2018):
maybe @krytarowski or @jsonn would be able to answer it?
@krytarowski commented on GitHub (Jun 6, 2018):
non-mdoc macros, what in particular?
@ghost commented on GitHub (Jun 6, 2018):
nothing in particular, we are just trying to figure out if there is a neutral spec for manpage document format, that would work across Linux, BSD, OSX and Solaris. Pandoc uses groff
d32e866449/src/Text/Pandoc/Writers/Man.hs (L30), is this something which is considered portable in unix world?@krytarowski commented on GitHub (Jun 6, 2018):
For man pages just use mdoc.
@jsonn commented on GitHub (Jun 6, 2018):
For Solaris, it depends on what exactly you mean. Newer Illumos certainly supports mdoc. Old Solaris only man. Man as macro set has many restrictions, i.e. it gives much worse results for web pages. That said, you can use mandoc to create man(7) output from mdoc as well.
@ghost commented on GitHub (Jun 6, 2018):
Thanks! This tool (markdig) converts CommonMark markdown or HTML markup to intermediate representation, then renders the IR to CommonMark or HTML.
We want to introduce a new manpage renderer and parser from/to that IR. For this matter, we needed some well defined manpage specs and the flavor to chose from. There is a good article https://monades.roperzh.com/memories-writing-parser-man-pages/ by @roperzh, which also acknowledges the lack of formal specification as a drawback of manpage
Maybe a spec can be proposed to w3/ecma etc. in effort to formalize.
@cjwatson commented on GitHub (Sep 13, 2019):
I'm pretty confused about why you say that mdoc macros don't work on Linux without passing
-mdoc. This may have been true once, but hasn't been true for many years; they work fine without the need for a special option.(I suspect this is moot for the purposes of this issue, but wanted to clarify it in case the idea takes root elsewhere.)