Linux - NewbieThis Linux forum is for members that are new to Linux.
Just starting out and have a question?
If it is not in the man pages or the how-to's this is the place!
Notices
Welcome to LinuxQuestions.org, a friendly and active Linux Community.
You are currently viewing LQ as a guest. By joining our community you will have the ability to post topics, receive our newsletter, use the advanced search, subscribe to threads and access many other special features. Registration is quick, simple and absolutely free. Join our community today!
Note that registered members see fewer ads, and ContentLink is completely disabled once you log in.
If you have any problems with the registration process or your account login, please contact us. If you need to reset your password, click here.
Having a problem logging in? Please visit this page to clear all LQ-related cookies.
Get a virtual cloud desktop with the Linux distro that you want in less than five minutes with Shells! With over 10 pre-installed distros to choose from, the worry-free installation life is here! Whether you are a digital nomad or just looking for flexibility, Shells can put your Linux machine on the device that you want to use.
Exclusive for LQ members, get up to 45% off per month. Click here for more info.
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
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?
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.
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?
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.
LinuxQuestions.org is looking for people interested in writing
Editorials, Articles, Reviews, and more. If you'd like to contribute
content, let us know.
[SOLVED] Conventions for synopsis in man pages
