LinuxQuestions.org - [SOLVED] Conventions for synopsis in man pages

- Linux - Newbie (https://www.linuxquestions.org/questions/linux-newbie-8/)

- - Conventions for synopsis in man pages (https://www.linuxquestions.org/questions/linux-newbie-8/conventions-for-synopsis-in-man-pages-4175581497/)

Conventions for synopsis in man pages

I looked at man page for man, and the following are conventions for the synopsis:

Quote:

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.

Then I looked at man page for lvcreate:

Quote:

LVCREATE(8) System Manager's Manual LVCREATE(8)

NAME lvcreate - create a logical volume in an existing volume group

SYNOPSIS
lvcreate [--addtag Tag] [--alloc AllocationPolicy] [-a|--activate [a|e|l]{y|n}] [-A|--autobackup {y|n}]
[-C|--contiguous {y|n}] [-d|--debug] [-h|-?|--help] [--noudevsync] [--ignoremonitoring] [--monitor {y|n}]
[-i|--stripes Stripes [-I|--stripesize StripeSize]] {[-l|--extents LogicalExtentsNumber[%{VG|PVS|FREE}] | -L|--size LogicalVolumeSize[bBsSkKmMgGtTpPeE]] | -V|--virtualsize VirtualSize[bBsSkKmMgGtTpPeE]}
.... ....

In above bolded texts, {} and % are in the texts.
There are no descriptions of conventions for {} and % in "mam man" page.

What are the descriptions for {} and %?

Where else can I find full descriptions for conventions?

I have difficulty reading the synopsis due to cluttering.

Is there a better utility that separates each item (argument)
in a synopsis command into a more readable format
(may be even put each item into single line)?

Another possible solution is to copy into an editor, e.g nano or gedit,
and then manually separate the argument into new line.
But I loose the bold and italics in the synopsis after pasting....

How do I retain bold and italics properties in the texts at pasting time?

Thank you.

I am not sure I really follow you? The synopsis simply gives a listing of all the possible switches and options, whilst the individual information for each is then contained in the 'options' section,
so for part of your bolded example:

Code:

      -l|--extents LogicalExtentsNumber[%{VG|PVS|FREE|ORIGIN}]

              Gives the number of logical extents to allocate for the new logical volume.  The total number of physical extents allocated will be greater than this, for example, if the volume is  mirrored.

              The  number  can  also be expressed as a percentage of the total space in the Volume Group with the suffix %VG, as a percentage of the remaining free space in the Volume Group with the suffix

              %FREE, as a percentage of the remaining free space for the specified PhysicalVolume(s) with the suffix %PVS, or (for a snapshot) as a percentage of the total space in the Origin Logical  Vol‐

              ume with the suffix %ORIGIN (i.e. 100%ORIGIN provides space for the whole origin).  When expressed as a percentage, the number is treated as an approximate upper limit for the number of phys‐

              ical extents to be allocated (including extents used by any mirrors, for example).

Which to me would seem to answer nicely what the percent symbol is for and that the bracketed items are the options to choose from.

As for retaining the text properties of things like bold or italics, I am not familiar with any system that would specifically allow you to retain such things from program to program.

You're right - there is a paucity of info on the use of curly brackets { } in usage text. Basically, they mean that you must use one of the alternative terms within the brackets.

In the case you quote, % is a literal character, it does not have any special meaning.

The curly brackets enclose sets of alternatives, one of which must be present. That is in contrast with the square brackets that enclose alternatives that are entirely optional. In the lvcreate manpage that you quoted, the "%" character is just a literal character with no special meaning, so some of the alternatives that could appear there would be "--extents 50%FREE", "--extents 2500", or "-l 25%VG".

The two levels of curly brackets do make that a bit confusing. The outer set means that some size specification must be present. The inner set means that if a "%" sign is present it must be followed by one of "VG", "PVS", or "FREE".

The SYNOPSIS section really isn't intended to tell the whole story, but is just a convenient reminder for someone already familiar with the command. There are much more complete descriptions in the OPTIONS section of the manpage.

Quote:

brackets { }

{} should be called braces,
not brackets, as in [] or a.k.a. "square" brackets.

No?

I guess it can be called CURLY brackets, {}, too....

[SOLVED] Conventions for synopsis in man pages

[SOLVED] Conventions for synopsis in man pages

Thank you.

Please mark as SOLVED using the thread tools

Well, I got more questions .... on SYPNOSIS.

Quote:

How do I find description on "FILE_SPEC" from local machine?
In above synopsis, it look like parenthesis, (), imply required option.
But this is not described in "man man" page.

Where in documentation on Linux machine (or somewhere else?) can I find better descriptions of syntax / symbols used in man pages than from man man page?

Thank you.

As your issue seems to be more with specific commands and their usage, why not go to the web site for the command and look at the documentation there

Quote:

Originally Posted by grail (Post 5559182)

As your issue seems to be more with specific commands and their usage, why not go to the web site for the command and look at the documentation there

Further to this comment, there doesn't appear to be a solid standard on the format of command synopses, just commonly accepted guidelines which may differ. Sometimes, as in this case, the synopsis is trying to represent a complicated situation in reality and often can't do it justice. Synopses are written by many different people with different approaches, and can be wrong too (for example, in the synopsis above, note the extraneous closing parentheses).

So, I agree with grail: if there are ambiguities in a synopsis then look further into the documentation and search for examples on the web. Failing that, contact the manual author (their email is almost always given on the man page) or, if you're feeling up to it, check the source code to see how the command really works.