> On Mon, Aug 12, 2013 at 9:21 PM, Anthony J. Bentley <anth...@cathet.us>wrote: > > Evan Root writes: > > > Hello Misc, > > > I tried man 5 man for an explanation of the synopsis section of the man > > > page and it says there isn't a manual for the file format conventions of > > > manual pages. Sometimes I have difficulty with the syntax of the synopsis > > > sections, is there a document I can refer to? > > > > OpenBSD manuals are written in the mdoc macro language. There is a page > > describing it, in section 7 (not 5). It is mentioned in the "SEE ALSO" > > section of man(1). > > > > man 7 mdoc > > > > There is also a man(7) page, describing the older "man" macros, but these > > are not used for new manuals in OpenBSD. mdoc has the advantage of being > > a semantic format, unlike the old man language where the commands mostly > > change only the presentation.
On Aug 12 22:19:58, cellarr...@gmail.com wrote: > I don't think you understood. I am not looking to write a man page. I was > just wondering if the system came with an explanation of the manual page > synopsis section language syntax. Which is exactly what Anthony pointed you to: The mdoc(7) describes the language syntax in great detail. > Sometimes I get confused by the language > and am not sure if I understand the synopsis sections of the man pages. > Also I am concerned that people who I might recommend OpenBSD to will find > that an undocumented part of the system is the man pages. The mandoc people could probably take this as an offence. The manual system, as other parts of OpenBSD, is thoroughly documented. > Even the welcome message from Theo says "This message attempts to describe > the most basic initial questions that a > system administrator of an OpenBSD box might have..... If you are not > familiar with how to read man pages, type > "man man" at a shell prompt and read the entire thing." Well have you? That points you to mdoc(7) in SEE ALSO. "How to read man pages" in the welcome message refers to the the rendered manpages - as presented to the user with man(1). You are asking about the language syntax - how the manpages are written. > I think that this post on stack exchange presents my question better.. the > answers are all pretty short and non-committal though. > http://stackoverflow.com/questions/8716047/is-there-a-specification-for-a-man-pages-synopsis-section So you _are_ looking to write a manpage; mdoc(7) has a section called "MANUAL STRUCTURE" with a subsection called "SYNOPIS". Have you missed it? After you write it, don't forget to 'mandoc -Tlint'.
