Comandos personalizados

  1. Introdução
  2. Exemplos
  3. Sintaxe
  4. Comando sem argumentos
  5. Argumentos opcionais
  6. Redefinindo comandos
  7. Múltiplos argumentos opcionais

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.

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. Você não precisa usar o comando \textit toda vez que escrever o nome de uma espécie para colocá-la em itálico.

É muito melhor criar um comando \especie, que recebe o nome da espécie como argumento e a coloca em itálico internamente. Dessa forma, ao escrever um nome de uma espécie, você só precisa usar esse 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 apenas 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?

Exemplos

Veja a diferença dos dois métodos em exemplos. Primeiro, um documento que usa o \textit para colocar os nomes das espécies em itálico:

\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}

Agora, um exemplo que usa um comando especie para alcançar o mesmo resultado:

\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}

Veja que o nome do comando foi colocado sem acento, porque acentos não podem ser usados em nomes de comandos. Espaços também não podem ser usados. Também foi introduzido um novo conceito, que é a nota de rodapé, usando o comando \footnote. Ele é explicado em maiores detalhes depois.

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}

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. Só é possível definir um argumento opcional. Argumentos opcionais serão discutidos em detalhes mais tarde, nesse tutorial. O número máximo de argumentos que podem ser definidos é 9.

Nomes de comandos não podem ter acentos nem cedilhas ou caracteres do tipo. Também não podem ter hífens nem underlines, e nem espaços. Assim, ao criar comandos de palavras compostas, ou você não usa nada para separar as palavras ou usa camelCase ou StudlyCaps.

Talvez você esteja lendo esses tutoriais e seja um programador. 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.

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}}
\renewcommand{\LaTeX}{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. Para definir um comando, você precisa usar o comando \NewDocumentCommand passando três argumentos para ele: o nome do comando, a especificação dos argumentos deles e a definição do comando.

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}

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. Existem várias especificações que podem ser usadas para definir os argumentos, mas será explicado apenas o básico do pacote, que é o necessário para que você possa usar mais de um argumento opcional e suficiente na maioria dos casos.

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.

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.