xoofx
Manpage renderer
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 https://github.com/jgm/pandoc/blob/d32e8664498d799932927d9865ce71e014472ef3/src/Text/Pandoc/Writers/Man.hs. We probably need some specs to validate output.
@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 -mdoc switch to man(7). In order to validate the implementation, it would be great to have some markdown and corresponding manpage.
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?
Sorry, not off the top of my head. I will look into it.
https://linux.die.net/man/1/man https://linux.die.net/man/7/man
As I understand it, man(1) is about the man command and how to use it. man(7) is about how to write those man pages - their syntax and other implementation details.
apparently NET-2 BSD uses mdoc compatible macros, which doesn't work on Linux
Does the other way around work? If we use the non-mdoc macros, do docs render correctly on NetBSD and other BSDs?
apparently NET-2 BSD uses mdoc compatible macros, which doesn't work on Linux
Does the other way around work? If we use the non-mdoc macros, do docs render correctly on NetBSD and other BSDs?
maybe @krytarowski or @jsonn would be able to answer it?
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 https://github.com/jgm/pandoc/blob/d32e8664498d799932927d9865ce71e014472ef3/src/Text/Pandoc/Writers/Man.hs#L30, is this something which is considered portable in unix world?
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.
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
Lack of beginner-friendly resources
Something that really confused me was the lack of a canonical, well defined and clear source to look at, there’s a lot of information in the web which assumes a lot about the reader that it takes time to grasp.
Maybe a spec can be proposed to w3/ecma etc. in effort to formalize.
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.)
