Re: Man page that explains the file format of man pages?
Extended Backus-Naur Form! That is exactly what I was looking for Andreas. Thank you. I really didn't know what this was called or if there was a formal definition or not. Lol, the wikipedia page says that it does not have a single dialect. The IEEE standard is a good reference for quirks of the unix usage of EBNF. I think that if one starts with the wikipedia page and gets the basics and then can use the IEEE 1003.1 ch. 12 Errata page it's actually pretty clear. Thank you again! Evan Root, CCNA 505.226.1319 On Tue, Aug 13, 2013 at 1:40 AM, Andres Perera wrote: > 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 wrote: > >> On Mon, Aug 12, 2013 at 9:21 PM, Anthony J. Bentley >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'.
Re: Man page that explains the file format of man pages?
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 wrote: >> On Mon, Aug 12, 2013 at 9:21 PM, Anthony J. Bentley 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'.
Re: Man page that explains the file format of man pages?
> On Mon, Aug 12, 2013 at 9:21 PM, Anthony J. Bentley 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'.
Re: Man page that explains the file format of man pages?
On Mon, Aug 12, 2013 at 11:49 PM, Evan Root wrote: > 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 the best answer is included in that stack exchange submission POSIX.1-2008 Chapter 12 "Utility Conventions" describes the syntax of the SYNOPSIS sections for utilities, which is what you're looking for
Re: Man page that explains the file format of man pages?
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. 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. 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." 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 Evan Root, CCNA 505.226.1319 On Mon, Aug 12, 2013 at 9:21 PM, Anthony J. Bentley 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. > > -- > Anthony J. Bentley
Re: Man page that explains the file format of man pages?
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. -- Anthony J. Bentley
Man page that explains the file format of man pages?
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? I also looked up the Unix version 1 man pages just for history's sake and found that they are reaaallly simple and easy to understand. Is this just something that has gotten out of hand over time? Evan Root, CCNA
