he's not talking about the source level mandoc/man macros the subject is about the SYNOPSIS section language for utilities
e.g. in ``grep [ file ]'' the [ ] operator signifies 0 or 1 in ``rm file...'' the ... operator signifies 1 or more On Tue, Aug 13, 2013 at 2:58 AM, Jan Stary <h...@stare.cz> wrote: >> 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'.
