Manual documentation pages: man or mdoc?

nunotex

nunotex

Hello,

Don't know why but I see a lot of recent projects still using legacy man pages.

man(7)() says:
"The man language was the standard formatting language for AT&T UNIX man-
ual pages from 1979 to 1989. Do not use it to write new manual pages: it
is a purely presentational language and lacks support for semantic
markup. Use the mdoc(7) language, instead."

My question is: should a legacy man be re-writed to mdoc?

I'm asking this because I'm about to contribute to a project with a more complete manual but it is legacy man. I don't know if project authors will like a change to mdoc.

What do you think?
 
No, I think not. man and mdoc are both markup languages:

man 7 man: man – legacy formatting language for manual pages
man 7 mdoc: mdoc – semantic markup language for formatting manual pages
 
Well, your post said "using legacy man pages". But your quote comes from man 7 man which expressly states to use mandoc. Why other people aren't using that is a question for them.
What projects are you talking about?
 
For example clang not using mdoc:
Code: 
.\" $FreeBSD: releng/12.2/usr.bin/clang/clang/clang.1 363494 2020-07-24 20:48:06Z dim $
.\" Man page generated from reStructuredText.
.
.TH "CLANG" "1" "2020-06-26" "10" "Clang"
.SH NAME
clang \- the Clang C, C++, and Objective-C compiler
 
Last edited by a moderator:
You must log in or register to reply here.
Back
Top