Comandos personalizados

Introdução

Uma das maiores vantagens do LaTeX é permitir que seus usuários definam seus próprios comandos. Esse recurso é muito usado por usuários que zelam pela consistência dos seus documentos.

Nesse tutorial, você verá como criar seus próprios comandos, com ou sem argumentos.

Exemplos

Suponha que você esteja escrevendo um livro de Biologia no LaTeX. Você decidiu colocar os nomes das espécies em itálico, que é a convenção usada para escrever nomes de espécies. Uma das formas de fazer isso é usando o comando \textit:

\documentclass[a4paper,10pt]{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}

\begin{document}
  A espécie \textit{Polypodium hydriforme} é um gênero monoespecífico de cnidários parasitas.
  \footnote{Fonte: pt.wikipedia.org/wiki/Polypodium\_hydriforme}
\end{document}

Isso funciona bem se você tem apenas uma espécie. Mas um livro de Biologia certamente teria muitas espécies. Nesse caso, o melhor é criar um comando personalizado usando \newcommand:

\documentclass[a4paper,10pt]{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\newcommand{\especie}[1]{\textit{#1}}

\begin{document}
  A espécie \especie{Polypodium hydriforme} é um gênero monoespecífico de cnidários parasitas.
  \footnote{Fonte: pt.wikipedia.org/wiki/Polypodium\_hydriforme}
\end{document}

A saída é a mesma do documento anterior. A diferença é que agora a marcação ficou mais fácil de manter. O comando \especie criado no exemplo recebe apenas um argumento, que é o nome da espécie. A espécie é colocada em itálico com o comando \textit, mas isso é feito apenas uma vez, na definição do comando.

Além dessa abordagem ser muito mais semântica, você ganha outra excelente vantagem: se você decidir mudar a formatação da espécie, você só vai fazer isso uma vez, na definição do comando. Usando o \texit, você precisaria fazer a mudança em todo lugar em que você escreveu o nome de uma espécie. Um pesadelo, não é mesmo?

Note também que foi introduzido um novo conceito, que é a nota de rodapé, usando o comando \footnote.

Sintaxe

Note que foi usado um comando para criar outro comando. Estranho, né? Mas é assim que funciona. Para criar um novo comando, é preciso usar o comando \newcommand informando o nome do comando e a definição dele, que nada mais é do que o que é feito quando o comando é usado.

O número de argumentos que o comando aceitará é um argumento opcional. Há comandos que não precisam de argumentos. Veja a sintaxe para criação de comandos abaixo:

\newcommand{\nomecomando}[numeroArgumentos][padraoArgumentoOpcional]{Definição}

O número máximo de argumentos que podem ser definidos é 9. Perceba que também há outro argumento opcional, que define um valor padrão para um argumento opcional. Se ele não for usado, é porque todos os argumentos do comando são obrigatórios. Com esse método, só é possível definir um argumento opcional.

Ainda nesse tutorial, será mostrado como definir múltiplos argumentos opcionais usando outro método, e os argumentos opcionais serão discutidos em maiores detalhes.

Talvez você esteja lendo esses tutoriais e seja um desenvolvedor. Se for esse o caso, talvez você associe um comando com o conceito de função em linguagens de programação. Não faça isso. Enquanto as funções estabelecem nomes para seus parâmetros, os comandos do LaTeX não definem parâmetros. Eles apenas definem quantos argumentos eles aceitam.

Os argumentos são acessados por seus índices. Para acessar os argumentos fornecidos ao comando, use #x, sendo x o índice do argumento. Exemplo:

\documentclass[a4paper,10pt]{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\newcommand{\horaformatada}[3]{\textbf{#1} horas, \textbf{#2} minutos e \textbf{#3} segundos}

\begin{document}
  Hora formatada: \horaformatada{07}{30}{25}
\end{document}

Os comandos definidos no preâmbulo tem um nome especial. Eles são chamados de macros. Então, no exemplo acima, a macro horaformatada foi criada.

Comando sem argumentos

Veja abaixo um exemplo de um comando sem argumentos:

\documentclass{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\newcommand{\capitalba}{Salvador}

\begin{document}
  \capitalba\ é a maior cidade e capital da Bahia, com quase 3 milhões de habitantes.
\end{document}

Note que foi colocada uma barra invertida depois do comando \capitalba. Se isso não fosse feito, o LaTeX entenderia que não há nenhum espaço entre o comando e a palavra seguinte. É necessário fazer isso em todos os comandos que geram uma saída e não pedem nenhum argumento, sejam eles personalizados ou não. Veja que é necessário fazer a mesma coisa no comando nativo \LaTeX:

\documentclass{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}

\begin{document}
  Todo mundo gosta de documentos organizados e consistentes, mas poucos se dedicam pra isso.
  Por isso, o \LaTeX\ é bem menos popular que o Word.
\end{document}

Argumentos opcionais

Como já foi dito nesse tutorial, é possível definir comandos com um argumento opcional. O exemplo da hora formatada pode ser alterado para ficar mais flexível. A formatação aplicada aos elementos do horário pode ser passada como argumento, opcionalmente:

\documentclass[a4paper,10pt]{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\newcommand{\horaformatada}[4][\textbf]{#1{#2} horas, #1{#3} minutos e #1{#4} segundos}

\begin{document}
  Hora formatada: \horaformatada{07}{30}{25}

  Hora formatada (itálico): \horaformatada[\textit]{07}{30}{25}
\end{document}

Agora, o comando passou a ter quatro argumentos, sendo um deles opcional. Sempre que um comando tiver um argumento opcional, ele sempre será acessado pelo índice 1, e os argumentos obrigatórios serão acessados pelos índices subsequentes.

O argumento opcional sempre tem um valor padrão, usado no caso do usuário não fornecer um valor para ele. No caso, o valor padrão foi \textbf.

Redefinindo comandos

Você pode redefinir um comando do LaTeX usando o comando \renewcommand. A sintaxe é a mesma do \newcommand. Você pode redefinir tanto comandos definidos pelo LaTeX ou por pacotes de terceiros, como também comandos personalizados:

\documentclass[a4paper,10pt]{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\newcommand{\especie}[1]{\textit{#1}}
\renewcommand{\especie}[1]{\textbf{#1}} % Redefinindo um comando personalizado
\renewcommand{\LaTeX}{Latex} % Redefinindo um comando do LaTeX

\begin{document}
  A espécie \especie{Polypodium hydriforme} é um gênero monoespecífico de cnidários parasitas.
  \footnote{Fonte: pt.wikipedia.org/wiki/Polypodium\_hydriforme}

  Todo mundo gosta de documentos organizados e consistentes, mas poucos se dedicam pra isso.
  Por isso, o \LaTeX\ é bem menos popular que o Word.
\end{document}

Múltiplos argumentos opcionais

Apesar do LaTeX não permitir que você defina comandos com mais de um argumento opcional usando seus recursos nativos, é possível fazer isso usando um pacote chamado xparse:

O exemplo abaixo redefine o comando \capitalba, definindo anteriormente:

\documentclass{article}
\usepackage[utf8]{inputenc}
\usepackage{xparse}
\NewDocumentCommand{\capitalba}{}{Salvador}

\begin{document}
  \capitalba\ é a maior cidade e capital da Bahia, com quase 3 milhões de habitantes.
\end{document}

O comando \NewDocumentCommand é usado para definir novos comandos. Ele aceita três argumentos: o nome do comando, a especificação dos argumentos e a definição do comando.

Agora, veja um exemplo mais complexo, que é o comando da hora formatada reescrito com dois argumentos opcionais e dois obrigatórios:

\documentclass{article}
\usepackage[utf8]{inputenc}
\usepackage{xparse}
\NewDocumentCommand{\horaformatada}{O{\textbf}O{07}mm}{#1{#2} horas, #1{#3} minutos e #1{#4} segundos}

\begin{document}
  Hora formatada: \horaformatada{30}{25}

  Hora formatada (itálico): \horaformatada[\textit][10]{30}{25}
\end{document}

Ao contrário do \newcommand, nativo do LaTeX, aqui não é preciso informar quantos argumentos o comando terá. Isso já fica implícito no segundo argumento, que serve para especificar os argumentos do comando. A mágica está toda nele.

Argumentos opcionais são especificados usando a sintaxe abaixo:

O{valor padrão}

O valor padrão é opcional. Se ele não for definido e o argumento opcional não for passado ao comando, o argumento terá um valor vazio. No comando acima, foram definidos dois argumentos opcionais: o primeiro para a formatação e o segundo para as horas. Os dois tem valores padrões: \textbf e 07, respectivamente.

Se você quiser especificar um argumento obrigatório, escreva m. No último exemplo, como o comando precisa de dois argumentos obrigatórios, o m foi colocado duas vezes.

Os argumentos devem ser acessados na ordem em que eles foram definidos no segundo argumento do \NewDocumentCommand. No exemplo, os dois primeiros argumentos são os opcionais, e os dois últimos são os obrigatórios.