How to write a command that includes a figure?

Question

I would like a shorthand command to include a figure.

• Description and filename are mandatory
• Short caption is optional
• Optional arguments can be passed to \includegraphics

Here's the snippet I am trying to write:

    \newcommand\figH[4][]{
    \begin{figure}[H]
        \begin{center}
            \caption[#4]{\label{#2}#3}
            \includegraphics[#1]{#2}
        \end{center}
    \end{figure}%
    }
    
    \figH[width=\linewidth]{filename}{description}{short-description}
    \figH{filename}{description}{short-description}
    \figH{filename}{description}

I am still confused with the optional arguments in commands.

Answer 1

Instead of defining many arguments you could also define a key=value interface that sets the label, short-caption, or place for the float's placement. With expkv-cs you can use the ... handler to get all the unknown key=value pairs (and the keys without values) in a single argument to forward them to \includegraphics (resulting in a single optional key=value argument and two mandatory arguments).

\documentclass{article}

\usepackage{graphicx}
\usepackage{float}
\usepackage{expkv-cs}

\makeatletter
\newcommand\fig[2][]{\fig@kv{short={#2},#1}{#2}}
\ekvcSplitAndForward\fig@kv\fig@out
  {
    % defaults here
     short = {}% will get set for each call to match the caption argument
    ,internal-label = {} % empty, not for direct use (easier that way)
    ,place = tbp
    ,...
  }
\ekvcSecondaryKeys\fig@kv
  {
     nmeta H = place=H % shortcut
    ,meta label = internal-label=\label{#1} % wraps \label around the value
    % add more keys you want to be handled special here
  }
\newcommand\fig@out[6]
  {%
    \begin{figure}[#3]
      \centering
      \caption[{#1}]{#5#2}%
      \includegraphics[{#4}]{#6}%
    \end{figure}%
  }
\makeatother

\usepackage{duckuments}

\begin{document}
\listoffigures
\blindduck
\fig[H]{A lovely duck}{example-image-duck}

\fig[width=3cm, short=Ducky]{A frightening duck!}{example-image-duck-portrait}
\end{document}

Answer 2

Don't. You lose in flexibility while not gaining much in input speed, because you always have to remember the order of the arguments.

Also, the option [H] should be avoided, because it leads to several pagination problems, which the standard optional arguments to figure try to overcome. Also center is not the best and the \centering declaration is best.

Let's see how you might do. You need

1. an optional argument for the float placement
2. an optional argument for the “short” caption
3. a mandatory argument for the caption
4. a mandatory argument for the label
5. an optional argument for the figure parameters
6. a mandatory argument for the image file.

Placing two consecutive optional arguments that deal with different aspects is bad; so we could insert the label in the second position. Thus we need

\NewDocumentCommand{\addfigure}{
  O{htp} % the suggested default
  m      % the label
  O{#4}  % the short caption (defaults to the long one)
  m      % the caption
  O{}    % the options to \includegraphics
  m      % the file name
}{%
  \begin{figure}[#1]
  \centering
  \caption[#3]{\label{#2}#4}
  \includegraphics[#5]{#6}
  \end{figure}
}

Let's see possible calls:

\addfigure{fig:A}[short desc]{long caption}[width=\columnwidth]{filename}

\addfigure{fig:B}[short desc]{long caption}{filename}

\addfigure[!htbp]{fig:C}{long caption}[width=6cm]{filename}

Compare the last with

\begin{figure}[!htpb]
\centering

\caption{long caption\label{fig:C}}

\includegraphics[width=6cm]{filename}

\end{figure}

and decide which is clearer.

Answer 3

The \figH defined has below, using \NewDocumentCommand, has five arguments, as noted in the comment. Here, \NewDocumentCommand is better than \newcommand in that you can easily have multiple optional arguments.

This can be served as a starting point for you, feel free to edit and expand it for your need.

\documentclass{article}

\usepackage{graphicx,float}
\usepackage{geometry}

\NewDocumentCommand \figH { O{} m O{} m o }
% #1 = options for \includegraphics (optional, initial to be empty)
% #2 = figure name
% #3 = short caption (optional, initial to be empty)
% #4 = caption
% #5 = label (optional, initial to be NoValue)
  {%
    \begin{figure}[H]%
      \begin{center}%
        \caption[#3]{\IfValueT{#5}{\label{#5}}#4}%
        \includegraphics[#1]{#2}%
      \end{center}%
    \end{figure}%
  }

\begin{document}

\figH[width=\linewidth]{example-image-a}{description}[fig:A]
\figH{example-image-b}[short-description]{description}[fig:B]
\figH{example-image-c}{description}

\end{document}