showme

showme is a bash script to visualize the pdf file of a paper I've got in my collection:

showme delvalle12a

opens the pdf file. It works if the file is in the bibTeX database (i.e., in ~/bib somewhere) and has .pdf extension. There is bash autocompletion, which is welcome for zubi... papers (?!).

One can use another viewer or application (e.g., gimp):

showme delvalle12a --with evince

the --with can be put anywhere.

The option -2 also opens another copy in the right window manager (which I often need to work on two copies simultaneously):

showme delvalle12a -2

Versions

1. v°0.1 on 31 Dec (2023)
2. v°1.5 on 19 August (2025) — --with option
3. v°2.1 on 17 September (2025) — -2 option

Source

The first version that served me well for almost 600 days was a simple hack:

#!/bin/bash
# v°0.1 Sun 31 Dec 2023

okular `locate $1 | grep -i ".pdf$" | grep -i bib`

Last version:

#!/bin/bash

#       #@=----===@%:        
#     :#:::-=---===+=@=-     
#    +=%* :-+=:....   .:@-   ____  _                    
#   @-+#-*%+**+#=+*#@@@@#@  / ___|| |__   _____      _ 
#  @=%.% #      @ .#     %= \___ \| '_ \ / _ \ \ /\ / / 
# #:..   @   @# * @   @# ##  ___) | | | | (_) \ V  V / 
# #.=:% .%.     @-=*     @% |__ __| |_|_|\___/ \_/\_/  
# %@.*@   :#@@@-. @ +%@%- @    |  \/  | ___   
# *@@% #@ ..      =+.. ...@    | |\/| |/ _ \ what
#  @:#-.:-= .:.+#-:  .. : @    | |  | |  __/ you got
#  @.:---::@. ..:-++=:.-%.%    |_|  |_|\___| 
#   @=-:-:@ @++==-:-=++-@%.  
#     @-::. : . . .. . :@    
#      @:--:...........=*    v2.1 Wed Sep 17 2025  
#      **=-=::.......:.@     laussy.org/wiki/showme
#       *=:-=.:::::::: @     F.P. Laussy
#        %@.::.::::::.+#     
#         -@@+=:.....+@      

# Default program
PROGRAM="okular"

# Parse options with getopt
PARSED=$(getopt -o w:2 -l with:,two -n 'showme' -- "$@")
if [ $? -ne 0 ]; then
  echo "Error: Invalid option" >&2
  exit 1
fi
eval set -- "$PARSED"

# Initialize two-files flag
TWO_FILES=false

# Process options
while true; do
  case "$1" in
    -w|--with)
      PROGRAM="$2"
      shift 2
      ;;
    -2|--two)
      TWO_FILES=true
      shift
      ;;
    --)
      shift
      break
      ;;
    *)
      echo "Error: Invalid option" >&2
      exit 1
      ;;
  esac
done

# Check if a search term is provided
if [ -z "$1" ]; then
  echo "Error: No search term provided" >&2
  exit 1
fi

# Get matching PDF files
FILES=($(locate "$1" | grep -i ".pdf$" | grep -i bib))

# Check if at least one file was found
if [ ${#FILES[@]} -eq 0 ]; then
  echo "Error: No matching PDF files found" >&2
  exit 1
fi

if [ "$TWO_FILES" = true ]; then
  # Open the first instance on the current desktop
  $PROGRAM "${FILES[0]}" &>/dev/null &

  # Open the same file again in a second instance
  $PROGRAM "${FILES[0]}" &>/dev/null &

  # Wait briefly for the second window to appear
  sleep 0.5

  # Get the window ID of the second instance
  WINDOW_ID=$(wmctrl -l | grep -i "$PROGRAM" | tail -n 1 | awk '{print $1}')

  # Get the current desktop number
  CURRENT_DESKTOP=$(wmctrl -d | grep '*' | awk '{print $1}')

  # Calculate the next desktop number
  TOTAL_DESKTOPS=$(wmctrl -d | wc -l)
  NEXT_DESKTOP=$(( (CURRENT_DESKTOP + 1) % TOTAL_DESKTOPS ))

  # Move the second window to the next desktop
  wmctrl -i -r "$WINDOW_ID" -t "$NEXT_DESKTOP"
else
  # Original behavior: open the first file
  $PROGRAM "${FILES[0]}" &>/dev/null &
fi

Bash autocompletion is taken care of in showme-completion.bash in /etc/bash_completion.d/. This can work for other similar commands, such as bib2wiki by registering them on the last line.

#!/bin/bash

_showme_completion() {
  local cur prev
  COMPREPLY=()
  cur="${COMP_WORDS[COMP_CWORD]}"
  prev="${COMP_WORDS[COMP_CWORD-1]}"

  # Directories to search for PDFs
  local search_dirs=("$HOME/bib/transit" "$HOME/bib/sci")

  # Handle options
  if [[ "$cur" == -* ]]; then
    COMPREPLY=( $(compgen -W "-w --with" -- "$cur") )
    return 0
  fi

  # If previous word is -w or --with, suggest programs
  if [[ "$prev" == "-w" || "$prev" == "--with" ]]; then
    COMPREPLY=( $(compgen -W "okular evince acroread" -- "$cur") )
    return 0
  fi

  # Complete PDF filenames from both ~/bib/transit and ~/bib/sci
  local files=""
  for dir in "${search_dirs[@]}"; do
    if [ -d "$dir" ]; then
      # Get list of PDFs in the directory, strip .pdf extension
      files+=$(find "$dir" -maxdepth 1 -type f -iname "*.pdf" -printf "%f\n" | sed 's/\.pdf$//' | sed "s|^$dir/||")
      files+=" "
    fi
  done

  # Generate completions if files were found
  if [ -n "$files" ]; then
    COMPREPLY=( $(compgen -W "$files" -- "$cur") )
  fi

  return 0
}

# Register the completion function for multiple commands
complete -F _showme_completion showme
complete -F _showme_completion bib2wiki