mdoc(7) markup for accumulating options with arguments - manpage

is there a "proper" or "canonical" markup for a command (section 1) "accumulating" option with argument? (or without for that matter)
an accumulating option can be given multiple times and the effects add up: think gcc's -I or -W.
let's say i'm documenting ssh(1). i want the SYNOPSIS to give away that -v and -o accumulate, this is usually done with ellipses:
ssh [-o option]... [-v]...
i'd like to tack the ellipsis to the idiomatic
.Op Fl o Ar option
the closest i can get is
.Oo
. Fl o Ar option
.Oc Ns \&...
as the shorthand Op coopts it.
what do other people do?

I'm a novice at man pages, but aside from your workaround, the closest I can get is:
.Op [ Fl o Ar option ] No ...
However, this results in:
[[-o option ] ...]
It's not exactly canonical or precisely what you're hoping for, but it seems unambiguous. (See http://docopt.org for other examples of how this can be expressed.)

Related

Always open a txt file using specified app in fish shell

I use fish shell. I always open *.txt files in atom, so I need to type atom filename.txt. I know, that in zsh, there's an option to always open files with some extension in the specific app using alias -s option. Is there a way to achieve the same behavior in fish shell?
Sorry, fish does not support this. Your best bet is to define an ordinary function/alias that calls into atom.
Two solutions come to mind. First, use an abbreviation or function to reduce the number of characters you have to type:
abbr a atom
Now you can just type "a *.txt". The advantage of doing function a; atom $argv; end is that it allows for more complicated steps than just replacing a short command with a longer command. As another example, I have abbr gcm "git checkout master" in my config because that's something I do frequently.
Second, use a key binding. For example, arrange for pressing [meta-a] to insert "atom" at the start of the command and execute it:
function edit_with_atom
set -l line (commandline -b)
commandline -r "atom $line"
commandline -f execute
end
bind \ea edit_with_atom
The key binding allows for more complicated operations than what I've shown above since you can execute arbitrary code.
These solutions don't scale but if there's just a couple of commands you run frequently that you want to invoke with fewer keystrokes they might help.

auto completion in zsh on 3rd parameter

I have a shell script it's usage is:
foo.sh <name> <type> <*.tar.gz>
I want to setup a complete on 3rd parameter only.
If I press on 1st parameter, just show the usage.
Could I use zsh's zshcomp to do this job?
for example:
foo.sh <tab> # display usage
foo.sh a b <tab> # show files match with *.tar.gz
Is there similar script which I could follow?
Things to read.
Here is a blog post discussing the Z-Shell Completion System.
For a slightly more in-depth discussion, read this unix.stackexchange answer.
And, as always, read the man pages!.
Edit: Forgot to add: echo $fpath will show you the function path that zsh uses. On OSX, I have: /usr/local/share/zsh/4.3.17/functions, (location may vary for you), which contains all the ZSH completion functions. Have a look at _ssh, _ls, _tar etc - they're all there, and they all have lots of nifty features you can learn from.
Addressing the question: the direction you should go.
What you're asking is achievable, though. There are several steps.
You need to write a z-shell completion function. It needs to be located on the fpath; the function-path that zsh uses for it's completion system functions. (If it's a small function, putting it into ~/.zshrc will also work, but isn't recommended).
You want completion on the 3rd parameter. To do that, your function would look something like the following:
_arguments "3:<MENU>:<COMPLETION>"
<MENU> is the menu description, which you'll see if you've enabled the menu descriptions. (That's done using zstyle; read the man pages, or the linked pages, for more information).
<COMPLETION> is the things that you can complete with. For example, if you used:
_arguments "3::(Foo Bar)"
when you ran your script and pressed <TAB>, you'd have the option of either Foo or Bar.
[NOTE: There is no <MENU> in that example. If you don't want a menu descriptor, you can omit it as shown].
You want completion on *.tar files. You can call _files to do that:
_files -g \*.tar
Show usage on first parameter: that'd be a completion with no arguments (ie, argument 1). I'm not sure why you'd want completion on only the third option but not the first two (typical usage descriptions), so I don't know how to answer this. If your script is supposed to be used like this: script foo bar FILE.tar, wouldn't you want to complete the foo and bar arguments as well?
Perhaps a better solution would be displaying the usage when the script is run without parameters.
Full script would look something like the following:
#compdef myscript
_arguments "3:tar files:_files -g \*.tar"

What is a good method for inventing a command name?

We're struggling to come up with a command name for our all purpose "developer helper" tool, which we are using on our project. It's like a wrapper for our existing tools like cmake and hg. The purpose of the command is really just to make our lives easier by combining multiple commands into one (for example, publishing packages). For example, we have commands like:
do conf
do build
do install
do publish
We've considered a few ambiguous names like do (as above) and run, but obviously, do is a Linux bash command and run is pretty ambiguous.
We'd like our command to be 2 chars short, preferably - but who thinks we're asking the impossible? Is there a practical way to check the availability of command names (other than just typing them into your terminal), or is it just a case of choose one and hope nobody else will use it? Are we worrying about nothing?
Since it's a "developer helper" tool why not use hm [run|build|port|deploy|test], Help Me ...
Give it a verbose name, then let everyone alias it to whatever they want. Make sure you use the verbose name in other scripts so that it removes ambiguity.
This way, each user gets to use whatever makes sense to him/her, and the scripts are more readable and more easily searchable (for example, grepping four "our_cool_tool" will usually yield better results than grepping for "run").
How many 2-character words are useful in this context? I think you need four. With that in mind, here are some suggestions.
omni
torq
fluf
mega
spif
crnk
splt
argh
quat
drul
scud
prun
sqat
zoom
sizl
I have more if you need them.
Pick one: http://en.wikipedia.org/wiki/List_of_all_two-letter_combinations
To check the availability of command names, I suggest looking for all two-letter filenames that are in the directories in your path. You can use a script like this
for item in `echo $PATH | sed 's/:/ /g'` ; do
ls -1d $item/??
done
It won't show builtins in your shell (like "do" as you mentioned) but it's a good start.
Change ?? to ??? for three-letter files, etc.
I'm going to vote for qp (quick package?) since it's easy to pronounce, easy to type, and easy to remember where the keys are on the keyboard.
I use "asd". it's short and most developers type it without thinking
(oh, and you can always claim later that it stands for some "Advanced Script for Developers" if you need to justify yourself a few years from now)
How about fu? As in Kung Fu. It's a special purpose tool. And it's really easy to type.
I think that run is a good name, at least anybody that will download your project will know what to do. Calling it without parameters should reveal your options.
Even 'do' will do, I think you can use backquotes to run it from bash scripts.
Also remember that running the tools without parameters will tell you what options you have.
Use makefiles to do everything for you.
How about calling it something descriptive, like 'build_runner', and then just aliasing it to 'br' (or preferred acronym) in your .bashrc?
There is a really crappy tool called cleartool (part of clearcase), and people will alias it on their machine to "ct". Perhaps you can have a longer command and suggest users alias it.
It would probably be best to do something like ire_and_curses suggested, name it descriptively then alias it to a 2 letter command. If I was choosing, I would name it dev_help and alias it to dh.
I think you're worrying about nothing. Install the program as 'the-command-to-do-evertyhing-and-if-you-dont-make-your-own-alias-for-it-you-should'. I don't think that will be too long for any modern filesystems, but you might need to shorten it to 'tctdeaiydmyoafiys'. See what common aliases are used, and then change the program's name to that. In other words: don't decide, let natural selection decide for you. If you are working with a team of < 10, this should not even remotely cause any problems.
Call it devtool alias to dt
Custom tools like that I like to start with the prefix 'jj-'. I can type (with big index-finger power) 'jj ' and see all my personal commands. Also, they group together in alphabetical lists. 'J' is not a very common character for built-inc commands, but you can pick your own.
Since you want two characters, you can use just 'zz', or something starting with 'z'.
Are you sure you want to put all your functionality in one command? That might be simultaneously over-constraining and over-loading the interface a little.
do conf
do build
do install
do publish

Can grep (from command line) be set up to highlight the part of the line that matches?

I'm using grep from the command line via cygwin. I'm wondering if there's any way to get it to highlight the part of each line that matches the regex. The closest thing I'm seeing is the -o option, but that only outputs the matching area, and I'd like to see the entire line.
Take a look at the --color (or --colour) option, e.g.
grep --color POST access_log
By default, this uses the "auto" mode which only includes the color codes when output to a terminal, but not when you pipe the output elsewhere. If you want the colors piped out to something other than stdout, then use --color=always
See the linked article for ways you can change the colour and make grep use this option by default.
Try the --color switch.
You might want to try the ack tool. It does the highlighting by default, iirc.
Actually, it does many usefull things by default. Some people like it and I hope You will too.

Boustrophedon Text Editing?

I would like to edit text in boustrophedon in emacs. For those of you who don't know boustrophedon text direction goes "like an ox turns" in a field or like a printer inkjet. For the same reasons this is efficient on a farm or in a printer this text is very efficient to read once you get used to it (which doesn't take too long).
more on boustrophedon typesetting/layout:
http://www.ntg.nl/pipermail/aleph/2004-March/000094.html
To my knowledge there are no implementations of this typesetting style and I am stumped on how to implement it.
Any ideas as to how this could be done?
Thanks,
Andreas
I assume that advising self-insert-command, intercepting the events, and modifying the buffer accordingly is what you want to do. You will then need to rebind the directional commands (forward-char and friends are reversed on opposite lines), and so on.
A lot of work, but definitely possible.
Before you write anything too complicated, ask on emacs-devel. As the comments suggest, it might be useful to have generic support for something like this... although arbitrary snippets of text with different directions won't word-wrap (when inserting) the same way your text will.
Edit: Apparently advising self-insert-command doesn't quite work for this, so you will need to setup a keymap (and bind ?a to (my-new-insert-command ?a) and so on...).
You could write it in sed I hacked the rev script from the sed1liners text to skip a line and then rev every other line:
alias boustrophedon='sed -n "1{p;b a};{/\n/!G;s/\(.\)\(.*\n\)/&\2\1/;//D;s/.//;p};n;p;:a"'
$> echo -en "This\nis\nBoustrou...\ntext\non\ndisplay\nhere.\n" | boustrophedon
This
si
Boustrou...
txet
on
yalpsid
here.
Or, if you want to process a whole file:
$> boustrophedon <filename>