annotation

Question

When reading the manual pages, in my experience, there has always been a synopsis section. eg.

 MV(1) BSD General Commands Manual MV(1) NAME mv -- move files SYNOPSIS mv [-f | -i | -n] [-v] source target mv [-f | -i | -n] [-v] source ... directory 

I'm interested in the notation used in the synopsis section. What is called, and where can I find more information about this?

In general, it looks pretty straightforward, and I usually can understand what it means, but I would like to start using it for my own documentation, so I think I need to figure out what I can say about the syntax before I start writing own man pages.

Answer 1

This is qoute from man man :

  The following conventions apply to the SYNOPSIS section and can be used as a guide in other sections. bold text type exactly as shown. italic text replace with appropriate argument. [-abc] any or all arguments within [ ] are optional. -a|-b options delimited by | cannot be used together. argument ... argument is repeatable. [expression] ... entire expression within [ ] is repeatable. Exact rendering may vary depending on the output device. For instance, man will usually not be able to render italics when running in a terminal, and will typically use underlined or coloured text instead. 

So, I think that this synopsis notation was formed historically.