# Manual documentation pages: man or mdoc?



## nunotex (Oct 30, 2020)

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?


----------



## drhowarddrfine (Oct 30, 2020)

Are you confusing man pages with the mdoc language? I think you want to look at `man mandoc`


----------



## nunotex (Oct 30, 2020)

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


----------



## drhowarddrfine (Oct 30, 2020)

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?


----------



## nunotex (Oct 30, 2020)

For example clang not using mdoc:

```
.\" $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
```


----------



## xtouqh (Oct 30, 2020)

nunotex said:


> Man page generated from reStructuredText.


That's exactly why.

Otherwise, for something that is not converted from another format, please use mdoc.


----------

