diff --git a/Makefile b/Makefile index c7ee98f..8ec61e6 100644 --- a/Makefile +++ b/Makefile @@ -29,8 +29,10 @@ docs: make $(strip $(DOCS)) build/man/%: docs/%.md build/man/ docs/ - pandoc --from markdown --to man \ - $< $@ + pandoc --to man \ + --standalone \ + --output $@ \ + $< %/: @mkdir -p $@ diff --git a/docs/args.1.md b/docs/args.1.md index e69de29..93aea16 100644 --- a/docs/args.1.md +++ b/docs/args.1.md @@ -0,0 +1,56 @@ +--- +title: args +section: 1 +author: Kevin Samuel +--- + +# SYNOPSIS + +args ARGUMENT ... + +# DESCRIPTION + +**args** separately prints to standard output each argument it receives with its position. + +The intended use of this tool is to help understand word splitting and quote removal by the shell. + +Each argument prints one line of output in the following format. + +``` + @[POSITION] [ARGUMENT] +``` + +The two fields are separated by a single tab character. + +In case an empty string is received as an argument, it is represented as follows +for clarity. These quotes are not the actual input. Quotes would normally be removed by +the shell before the command's execution. + +``` + @1 '' +``` + +# EXAMPLE + +```console +$ args one two "" "word with spaces" $(echo substituted command) +@1 one +@2 two +@3 '' +@4 word with spaces +@5 substituted +@6 command +``` + +If @5 and @6 surprised you, finding cases like these and playing around is the exact +reason this tool exists. + +# EXIT CODES + +0 Success + +1 Failed because no arguments were received + +# LICENSE + +This software is distributed under the license specified in `LICENSE.txt`