Many man pages and --help option use a format for describing the command line options of the documented utilities. For instance, for the cd shell command:
cd [-L | -P] [directory]
cd -
I'd like to parse these descriptions. Is there a model or formal format (even if it is not widely accepted)?
I've seen that at least python's argparse (http://pymotw.com/2/argparse/) can generate something like that.
Some details about the notation used for the SYNOPSIS section can be found in the man manual:
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.
The command or function illustration is a pattern that should match all possible
invocations. In some cases it is advisable to illustrate several exclusive
invocations as is shown in the SYNOPSIS section of this manual page.
There are further details in the the POSIX Utility Syntax Guidelines.
Many libraries to parse the command line options can generate the synopsis section (e.g. take a look at boost::program_options).
Related
I have this POD file:
=head1 Create professional slideshows with Mojolicious::Plugin::RevealJS
=head2 Install and run a Mojolicious server
Santa's elf had a problem. He had to write very fast a presentation and show it to a bunch of new elf's.
The email assigning this to him was sent by Santa himself.
The elf started to look on Metacpan and found this module: L<Mojolicious::Plugin::RevealJS|https://metacpan.org/pod/Mojolicious::Plugin::RevealJS>
He quickly typed the following commands:
C<cpanm Mojolicius Mojolicious::Plugin::RevealJS>
Now he could generate an mojo lite app using:
C<mojo generate lite-app slide_show>
Because the elf was trained in the ancient arts of the elders
he cloud open new file with vim and paste this code in:
=begin perl
use Mojolicious::Lite -signatures;
app->static->paths(['.']);
plugin 'RevealJS';
any '/' => { template => 'presentation', layout => 'revealjs' };
app->start;
=end perl
When I run perldoc t.pod, the code between '=begin perl' and '=end perl' is not visible. I don't understand what I'm doing wrong.
The perlpod documentation says ...
For, begin, and end will let you have regions of text/code/data that are not generally interpreted as normal Pod text, but are passed directly to particular formatters, or are otherwise special. A formatter that can use that format will use the region, otherwise it will be completely ignored.
The formatter in this case is the thing that perldoc uses to render your POD into text. I suspect it doesn't know what to do with the format perl, so it ignores it.
A formatter that produces HTML might know what to do with the perl format, and might replace this with a code block that has syntax highlighting.
If you want your code examples in the POD to always show up as code, use a verbatim paragraph instead. This is done by adding indentation at the front.
=head2 frobnicate($foo)
This function frobnicates the C<$foo>.
my $bar = frobnicate($foo)
=cut
sub frobnicate { ... }
The description of a =begin <format>/=end <format> in perlpod starts by saying this:
=begin formatname
=end formatname
=for formatname text...
For, begin, and end will let you have regions of text/code/data that are not generally interpreted as normal Pod text, but are passed directly to particular formatters, or are otherwise special. A formatter that can use that format will use the region, otherwise it will be completely ignored.
Anything between =begin perl and =end perl is ignored by the standard Pod formatter and will only be processed by a specialised "perl" formatter (and no such formatter exists in the standard Perl toolset - you'd need to write your own).
You don't say what you expect this syntax to achieve, but it seems likely that you're looking for a verbatim paragraph.
Verbatim Paragraph
Verbatim paragraphs are usually used for presenting a codeblock or other text which does not require any special parsing or formatting, and which shouldn't be wrapped.
A verbatim paragraph is distinguished by having its first character be a space or a tab. (And commonly, all its lines begin with spaces and/or tabs.) It should be reproduced exactly, with tabs assumed to be on 8-column boundaries. There are no special formatting codes, so you can't italicize or anything like that. A \ means \, and nothing else.
I've just noticed a pattern (in git and the CommandLineParser lib for .NET) for verb-style command arguments, and wondering if someone can confirm:
myprog dothis -a "someArg"
-a
--arg
What's the difference between the single-dash-prefix and the double-dash-prefix? Is the single dash prefix always for a single-letter argument specifier, where a double dash prefix always for a "long name" of the argument?
Is there a formal convention somewhere that drives this, or is it a generally accepted informal practice? (or am I just making something of nothing?)
Just curious... the I had never noticed the pattern in git and the CommandLineParser docs are pretty thin and some blog post or another implicated the convention.
(for that matter... what's this style of verb/args even called? I can't seem to find much of anything on it)
From the wikipedia: https://en.wikipedia.org/wiki/Command-line_interface
Option conventions in Unix-like systems
In Unix-like systems, the ASCII hyphen-minus begins options; the new
(and GNU) convention is to use two hyphens then a word (e.g. --create)
to identify the option's use while the old convention (and still
available as an option for frequently-used options) is to use one
hyphen then one letter (e.g. -c); if one hyphen is followed by two or
more letters it may mean two options are being specified, or it may
mean the second and subsequent letters are a parameter (such as
filename or date) for the first option.
Two hyphen-minus characters without following letters (--) may
indicate that the remaining arguments should not be treated as
options, which is useful for example if a file name itself begins with
a hyphen, or if further arguments are meant for an inner command (e.g.
sudo). Double hyphen-minuses are also sometimes used to prefix "long
options" where more descriptive option names are used. This is a
common feature of GNU software. The getopt function and program, and
the getopts command are usually used for parsing command-line options.
There is posix convention and getopt
But it's not always the case, e.g. java and find.
See also:
https://golang.org/pkg/flag/
http://docs.oracle.com/javase/8/javafx/api/javafx/application/Application.Parameters.html
I am documenting my code with doxygen and want to introduce a separating line after a short description. What command can I use to include a separator? I have seen a series of separating lines in the doxygen manual but cannot find the appropriate command.
As noted in albert's comment, the syntax is <hr>.
Note that this does not work equally well in all output formats, but it does work in HTML. See albert's comment below.
This question already has answers here:
What does the number in parentheses shown after Unix command names in manpages mean?
(7 answers)
Closed 4 years ago.
I have a simple question I made my self but didn't find any answer and hints.
When I type for the man entries of a command, e.g. "man git", I get the following:
...
DESCRIPTION
...
See gittutorial(7) to get started, then see Everyday Git[1] ...
The Git User's Manual[2] has a more in-depth
introduction.
After you mastered the basic concepts, you can come back to this page to learn what commands Git offers. You can learn more about individual Git
commands with "git help command". gitcli(7) manual page gives you an overview of the command line command syntax.
Formatted and hyperlinked version of the latest Git documentation can be viewed at http://git-htmldocs.googlecode.com/git/git.html.
Could someone explain what are those "See gittutorial(7)...Everyday Git[1]...gitcli(7)" etc.? I mean, I know that they are telling "look at this resource if you want to know the basic concepts, for more info, etc.", but actually how should one interpret it?
What is the meaning of the numbers (like 7, 1, 2, etc..) inside the parenthesis or brackets? And where I can find the resources the manual is telling me to see, do I have to type something in the man prompt, or search on the Internet?
I just would like to ask for an elucidation.
Thank you for your attention!
Man pages are splitted into sections
to access a manual page inside a specific section you prepend the section number before the manpage name, for example try:
man 3 fork
or
man 2 fork
Usually the square braketed numbers are links to additional material in the NOTES section of the manpage (scroll to the bottom)
The parenthesized numbers indicate in which section of the manual the referenced entry appears. Section (1) is commands (programs), section (2) is system call functions, section (3) is general library functions, etc. Some terms have distinct entries in multiple sections. For example, this ...
man 1 printf
... gives a different manual page (from section 1, describing the printf program) than does this ...
man 3 printf
... which gives a page from section 3, describing the printf() function from the C standard library.
It means type man 7 gittutorial for more info. Man page are divided in numbered categories, sometimes overlapping. Use apropos git for instance to see the various possibilities.
The numbers in parentheses, manpage(N), are the manual section, each of the 8 sections covers a different topic.
See man-mages(7) ;) for a list of sections:
man man-pages
And you can open a manpage from a given section by including the number in the command:
man 7 man-pages
The numbers give you a hint of what the manpage will cover, e.g. time(1) is about a command, whereas time(2) is about a system call, and let you specify which section of the manual you're interested in when there's an entry with the same name on different sections.
The numbers between brackets, something[N] are footnotes, usually pointing to places where you can get more information.
A typical format for command line arguments is:
myApp --myArg=myValue
What if I want to pass in a set of key value pairs through the command line? Something like:
myApp --myList={arg1=val1;arg2=val2;arg3=val3...}
Since there seems to be no standard for this sort of thing, can anyone provide examples from well-used utilities that have this sort of command line argument input? I poked around some man pages but didn't find any.
Edit: I'm wondering both how the input should be formatted and what the help text might look like.
I think it largely depends on how you parse the arguments in your program.
Here are some examples that the programs accept multiple key-value pair values.
man php:
--define foo[=bar]
-d foo[=bar] Define INI entry foo with value bar
man git:
-c <name>=<value>
Pass a configuration parameter to the command. The value given will
override values from configuration files. The <name> is expected in
the same format as listed by git config (subkeys separated by
dots).
For both, one can pass multiple -d or -c arguments to the programs which gives you the ability to supply a list of key-value pairs to the programs.
IMO, it's not a big problem having your own style of accepting lists of key-value pairs for your program as long as it works and is well-documented. :)
P.S.: I think this question would be more appropriate be placed on Programmers Stack Exchange rather than on SO. See here and here.
If the app needs so many arguments, I would use a config file instead of passing them in command line:
myApp --config=file.cnf
This approach has the following advantages:
flexibility - you can have a bunch of configs prepared for different invocations, and just use them,
no problems with quoting - it's always painful if command line arguments have spaces, double quotes, <, >, or other special characters,
simplicity - you control the config file format, it can be for example INI, JSON, XML etc. It's easy to create it and as easy to parse as parsing command line -- if not easier,
security - if any argument may be sensitive, it's not visible from tools displaying command line arguments.