Documentação com Markdown: Textos acadêmicos conforme as regras ABNT com o Limarka

Limarka é uma ferramenta que possibilita a produção documentos acadêmicos em conformidades com as Normas da ABNT a partir a partir de texto em Markdown

Este é o terceiro artigo da série sobre produção de documentos com Markdown, uma linguagem de marcação simples bastante útil para qualquer um que precise produzir praticamente qualquer tipo de documento técnico, acadêmico, para a Web, etc.

No primeiro artigo da série fizemos uma pequena introdução sobre linguagens de marcação, apresentamos as características principais do Markdown e sua sintaxe básica.

No segundo artigo da série apresentamos o Pandoc, que é um software gratuito e open-source conversor entre diversos tipos de linguagens de marcação e arquivos de texto, e que também possui a sua própria implementação Markdown.

Neste texto apresentaremos o Limarka, que é uma ferramenta capaz de gerar arquivos PDF de documentos acadêmicos, como artigos, dissertações e teses, em conformidade com as Normas da ABNT a partir de textos escritos em Markdown.

Este artigo se concentrará em apresentar o Limarka, sua instalação e seu funcionamento básico.

Documentação com Markdown: Textos acadêmicos conforme as regras ABNT com o Limarka

Sumário do artigo

Introdução

O Limarka é uma ferramenta de linha de comando - sem interface gráfica - que gera arquivos PDF em conformidade com as Normas da ABNT para documentos acadêmicos a partir de arquivos arquivos somente texto - plain text - escritos uma linguagem de marcação de sintaxe simples, o Markdown.

O Limarka foi criado em 2016 por Eduardo de Santana Medeiros Alexandre, que desenvolveu a ferramenta de linha de comando a partir de sua dissertação de mestrado do Programa de Pós-Graduação em Informática do Centro de Informática da Universidade Federal da Paraíba - PPGI/CI/UFPB, com o objetivo de ajudar na elaboração de trabalhos acadêmicos.

Com a utilização do Limarka, os capítulos e seções são criados com a numeração apropriada; o sumário é criado e atualizado automaticamente; a numeração das páginas, figuras e tabelas é configurada corretamente, as referência bibliográficas e notas de rodapé são gerenciadas, dentre outras funcionalidades.

De forma bastante resumida, o Limarka funciona assim:

As configurações gerais são definidas em um arquivo de configuração YAML;
O texto do trabalho acadêmico é escrito em uma arquivo utilizando a sintaxe Markdwon (podem ser produzidos outros arquivos para anexos e apêndices);
As referências bibliográficas são cadastradas em um arquivo BibTex;
O Limarka gera um PDF do trabalho.

O software possui licença de Software Livre, qualquer um pode baixar, utilizar ou alterar a ferramenta.

abnTeX2

O Limarka permite a escrita de documentos acadêmicos em Markdown, mas utiliza modelos abnTeX2, que é uma evolução do abnTeX (ABsurd Norms for TeX), que é uma suíte para LaTeX que atende os requisitos das normas da Associação Brasileira de Normas Técnicas - ABNT para elaboração de documentos técnicos e científicos brasileiros, como artigos científicos, relatórios técnicos e trabalhos acadêmicos como teses, dissertações, projetos de pesquisa e outros documentos do gênero.

A ferramenta foi inserida na comunidade dos desenvolvedores do abnTeX, que são comprometidos em produzir documentos e estilos LaTeX para produção de documentos em conformidade com as Normas da ABNT. O Limarka utiliza internamente os modelos criados e mantidos por essa comunidade.

A vantagem da utilização do Limarka é que o Markdown é uma linguagem de marcação muito mais leve e menos verbosa que o LaTeX, como já vimos nos primeiros artigos desta série, que possui uma curva de aprendizado - muito - menor e mantém a maior parte das vantagens da utilização do LaTeX para documentação acadêmica em relação a ferramentas WYSYWYG (como Microsoft Word ou LibreOffice Writer), qual seja a separação entre a formatação e o conteúdo, a manutenção de um arquivo somente texto independente de plataforma, o gerenciamento automatizado de bibliografia e outros elementos e, mais especificamente, a não necessidade de preocupação com as Nomas da ABNT durante o processo de escrita.

A ideia central de produzir documentos a partir de uma linguagem de marcação é distanciar o autor o máximo possível da apresentação visual da informação, pois a constante preocupação com a formatação tende a desviar o pensamento do conteúdo escrito.

Pandoc

O Pandoc, conversor universal de documentos e formatos que apresentamos em nosso segundo artigo desta serie, é o coração do Limarka (e é uma das dependências que precisam estar instaladas para que o Limarka funcione). É ele que permite a transformação do Markdown em LaTeX e então a sua conversão em PDF (utilizando os modelos abnTeX2, como mencionado). O próprio desenvolvedor do Limarka afirma que sua ferramenta é uma parte minúscula do Pandoc.

O Limarka é, em certo sentido, um conjunto de filtros, modelos e outros componentes que estendem as funcionalidades do Pandoc, organizando e automatizando a conversão de arquivos escritos em Markdown em arquivos PDF já formatados conforme as normas da ABNT.

Instalação do Limarka

Na apresentação da documentação do Limarka menciona-se que:

“O público alvo da ferramenta são alunos com afinidade com tecnologias, e que estão necessitando escrever relatórios para disciplinas ou um trabalho de conclusão de curso”

Isto porque o Limarka não é exatamente um software “pronto”, mas um projeto aberto, aparentemente mantido pelo próprio criador e por uma comunidade relativamente pequena.

É uma ferramente de linha de comando, sem interface gráfica, assim como o Pandoc, o que por si só já pode afastar usuários um pouco menos acostumados. Além disso, por ser uma espécie de “projeto em desenvolvimento”, a utilização requer um mínimo de familiaridade com tecnologia e algumas configurações, a começar por sua instalação, que têm uma série de dependências (softwares que também precisam estar instalados para que o Limarka funcione).

Não é nada tão complicado que não possa ser aprendido seguindo algumas instruções simples, e em comparação com a curva de aprendizado do LaTeX ou com a complexidade, inconsistência e dificuldade de se escrever um documento acadêmico em Word ou Writer o Limarka pode até ser considerado simples.

O Limarka possui as seguintes dependências:

Pandoc;
MikTeX;
Perl;
Pdftk;
Ruby (versão de desenvolvimento).

A seguir, vamos resumir os passos para instalação de todo o conjunto no Windows, para maiores detalhes ou para instalação em outros sistemas operacionais pode ser consultada a documentação do Limarka.

Instalação do Pandoc e do MikTeX

Já apresentamos a instalação do Pandoc e do MikTeX em nosso segundo artigo desta série, que é importante que seja lido antes deste, bem como o primeiro artigo, no qual apresentamos a sintaxe básica do Markdown e trouxemos uma introdução a respeito de linguagens de marcação.

O abnTeX2, cujos modelos são utilizados internamente pelo Limarka será instalado automaticamente na primeira utilização do MikTeX.

Instalação do Perl

Perl é uma linguagem de programação. Não será necessário entender ou sequer utilizar a linguagem de fato para utilizar o Limarka, basta instalá-la. Sua instalação é necessária para a execução do latexmk, uma das dependências internas do Limarka.

A maneira mais simples de instalar a linguagem no Windows é através do Prompt de Comando (no Windows 10 é só digitar cmd na caixa de pesquisa ao lado do botão iniciar) e, já no prompt, digitar o seguinte comando:

powershell -Command "& $([scriptblock]::Create((New-Object Net.WebClient).DownloadString('https://platform.activestate.com/dl/cli/install.ps1'))) -activate-default ActiveState/Perl-5.32"

Basta então seguir as orientações no próprio Prompt de Comando, serão necessárias duas ou três confirmações e em poucos minutos o Perl estará instalado.

Instalação do PDFtk

O PDFtk Server é uma ferramenta de linha de comando para trabalhar com arquivos PDF, é utilizada para dar ao software a capacidade de manipular PDF.

Basta fazer o download do instalador adequado conforme o sistema operacional no site oficial do PDFtk e instalar como qualquer outro software.

Instalação do Ruby

O aplicativo Limarka é desenvolvido na linguagem Ruby e distribuído para instalação através de um Gem.

Ruby é uma linguagem de programação. Também não será necessário entender ou sequer utilizar a linguagem de fato para utilizar o Limarka, basta instalá-la.

A maneira mais simples de instalar a linguagem no Windows é através do RubyInstaller, que é um instalador independente baseado em Windows que inclui a linguagem Ruby e um ambiente de execução. Basta fazer o download e instalar como qualquer outro software.

Para instalar o Ruby em outros sistemas operacionais é só seguir as instruções no site do Ruby.

Com o Ruby instalado, para finalmente instalar o Limarka, no Windows, é só abrir o Prompt de Comando (no Windows 10 é só digitar cmd na caixa de pesquisa ao lado do botão iniciar) e, já no prompt, digitar o seguinte comando:

gem install limarka

A instalação correrá normalmente. Não aparecerá nenhum ícone novo na área de trabalho ou menu iniciar, uma vez que o Limarka não possui interface, é um programa de linha de comando, as instruções para o conversor serão feitas através do próprio Prompt de Comando do Windows.

Configuração do PANDOC_ABNT_BAT

o pandoc_abnt é um filtro Pandoc, instalado junto com o Limarka. Para executar o Limarka no Windows, todavia, é necessário configurar a variável de ambiente PANDOC_ABNT_BAT apontando para o local do arquivo pandoc_abnt.bat, uma vez que sem essa configuração o Pandoc não encontrará este filtro.

Para fazer esta configuração é só abrir o Prompt de Comando (no Windows 10 é só digitar cmd na caixa de pesquisa ao lado do botão iniciar) e, já no prompt, digitar o seguinte comando:

setx PANDOC_ABNT_BAT C:\Ruby27-x64\bin\pandoc_abnt.bat

Se por acaso estiver utilizando um sistema de 32 bits o comando a será digitado é o seguinte:

setx PANDOC_ABNT_BAT C:\Ruby27\bin\pandoc_abnt.bat

Caso esteja lendo isso no futuro e tenha instalado uma versão posterior do Ruby, o trecho Ruby27-x64 ou Ruby27 deve ser substituído pela versão do Ruby instalada, Ruby28-x64 ou Ruby29, por exemplo. É só verificar o nome da pasta Ruby no diretório C: (na imensa maioria dos casos será o diretório C:) de seu computador através do Windows Explorer. Qualquer mudança que venha a ocorrer no futuro também pode ser conferida no site da documentação do Limarka.

Instalação de softwares editores

Como já dissemos, um documento Markdown pode ser escrito em qualquer editor de texto simples, pode ser escrito no bloco de notas do Windows, por exemplo. O que, todavia, não seria a forma mais inteligente de fazê-lo. O mesmo pode ser dito de um documento Bibtex, no qual serão cadastradas as referência bibliográficas.

Neste sentido, é altamente recomendada a utilização de softwares editores específicos. Existem inúmeras alternativas simples e gratuitas.

Editor de textos

O ideal é que os editores possuam as seguintes funcionalidades:

Corretor ortográfico;
Realce da sintaxe da linguagem Markdown;
Possibilite navegação rápida no arquivo;

Existem diferentes opções que possuem estas características nativamente ou através de plugins. Duas opções que recomendamos são o notepad++ e o vscode, ambas gratuitas.

Basta fazer o download do instalador nos respectivos sites oficiais e instalar como qualquer outro software.

Editor de referências

Também existem diferentes opções adequadas de softwares editores de referências, muitas das quais gratuitas. Basta que o software seja capaz de editar um arquivo BibTeX.

A alternativa recomendada pela própria documentação do Limarka é o JabRef.

Basta fazer o download do instalador adequado conforme o sistema operacional no site oficial do JabRef e instalar como qualquer outro software.

Modelo de projeto

O primeiro passo para a utilização do Limarka é baixar um modelo de trabalho acadêmico limarka.

O “modelo” é um arquivo .zip com um conjunto de pastas e arquivos.

Os modelos de projeto contém:

Arquivos para edição do texto;
Arquivo para cadastro de referências bibliográficas;
Arquivo de configuração;
Templates para geração do PDF.

Os modelos de projeto são disponibilizados através de uma pasta .zip que precisará ser descompactada para utilização.

Download do modelo

O modelo padrão é compatível com as normas da ABNT. É possível que instituições específicas criem modelos customizado com padrões de formatação que vão além das exigências das ABNT. Este modelos serão disponibilizados nesta pasta do repositório do Limarka no Github.

Já o arquivo com o modelo padrão oficial do projeto pode ser baixado neste link.

O arquivo trabalho-academico-limarka-master deve ser movido para o local onde serão salvos os arquivos do trabalho acadêmico a ser desenvolvido e descompactado. Após a descompactação o arquivo .zip deve ser excluído.

Estrutura de arquivos

O modelo de projeto do limarka possui diversos arquivos, alguns são templates e outros tipos de arquivos que não necessariamente precisam ser utilizados. A seguir apresentamos sucintamente os arquivos que devem ser editados.

trabalho-academico.md
O arquivo trabalho-academico.md é o principal arquivo do projeto, onde deve ser digitado o corpo do trabalho acadêmico, utilizando a sintaxe Markdown.
apendices.md e anexos.md
O propósito dos arquivos apendices.md e anexos.md é bastante intuitivo, o primeiro serve para a escrita dos apêndices e o segundo para a escrita dos anexos. Em ambos deve-se utilizar a sintaxe de Markdown.
errata.md
Caso seja necessário a criação de uma errata esta deve ser feita no arquivo errata.md.
configuracao.yaml
A configuração do limarka é realizada através da edição do arquivo configuracao.yaml.
Neste arquivo serão inseridos o título do trabalho, nomes do autor e orientador, datas, etc., além de configurações para utilização dos apêndices, anexos e errata.
referencias.bib
O arquivo referencias.bib é o banco de referências do trabalho. Todas as referências que poderão ser utilizadas no trabalho devem ser cadastradas nesse arquivo.
imagens/ficha-catalografica.pdf e imagens/folha-de-aprovacao-escaneada.pdf
O arquivo imagens/ficha-catalografica.pdf deve ser substituído pelo arquivo fornecido pela equipe especializada da instituição para a qual o trabalho acadêmico está sendo feito. Caso a instituição forneça um arquivo .docx ou em outro formato este deve ser exportado ou convertido em PDF, sobrescrevendo esse arquivo.

O arquivo imagens/folha-de-aprovacao-escaneada.pdf também deve ser substituído pela folha fornecida pelo curso ou programa.

Esses arquivos poderão ser utilizados na versão final do trabalho. Sua utilização ou não utilização é definida no arquivo configuracao.yaml.

PDF gerado

O nome do arquivo de saída, o PDF gerado pelo Limarka, depende do tipo de trabalho definido em configuracao.yaml, e pode ser um dos seguintes:

xxx-Monografia-projeto.pdf
xxx-Monografia.pdf
xxx-TCC-projeto.pdf
xxx-TCC.pdf
xxx-Dissertacao-projeto.pdf
xxx-Dissertacao.pdf
xxx-Tese-projeto.pdf
xxx-Tese.pdf

Configuração inicial

A configuração inicial consiste em inserir os dados para capa do trabalho, folha de rosto e o tipo do trabalho, dentre outras definições.

Deve-se abrir arquivo configuracao.yaml, inserir e alterar os respectivos dados e então salvar com o mesmo nome.

No segundo artigo desta série apresentamos - sucintamente - a sintaxe da linguagem YAML que, como pode ser conferido, é extremamente simples.

Produção do documento

O corpo do texto do trabalho deve ser digitado no arquivo trabalho-academico.md, a maioria dos elementos deverão ser escritos utilizando a sintaxe Markdown. Já apresentamos a sintaxe Markdown em nosso primeiro artigo desta série e sua versão estendida, Pandoc’s Markdown no segundo artigo da mesma série, que é importante que sejam lidos antes deste.

O Limarka utiliza o Pandoc’s Markdown, com a extensão raw_tex, para possibilitar inclusão de código latex no texto, além do filtro pandoc_abnt para a produção de alguns elementos específicos. Na sequência apresentamos a sintaxe para a criação de elementos específicos que não são cobertos pela sintaxe Markdown e Pandoc’s Markdown já apresentada nos artigos anteriores.

Código LaTeX

O código LaTeX pode ser livremente inserido ao longo do texto em meio ao Markdown:

\begin{array}{c|c}
  1 & 2 \\ 
  \hline
  3 & 4
\end{array}

Inclusive dentro de parágrafos, assim por exemplo: \sqrt{81}.

Figuras e tabelas

As normas ABNT exigem que as Figuras e Tabelas obrigatoriamente possuam legenda, fonte e sejam referenciadas o mais próximo possível de sua localização.

A sintaxe do Markdown não é expressiva o suficiente para atender essas exigências para imagens e tabelas. O filtro pandoc_abnt, que faz parte do Limarka, soluciona isso através de uma sintaxe específica que mescla Markdown com LaTeX e atente às normas ABNT.

Figuras

As Figuras deverão ser salvas no diretório imagens, que faz parte do modelo do projeto, e incluídas, referenciadas e descritas com código LaTeX.

A imagem em si é inserida utilizando a mesma sintaxe do Pandoc’s Markdown, um sinal ! (exclamação) seguido pelo texto âncora entre colchetes [], que nesta caso será a legenda da imagem, seguido pelo caminho - ou path - para o arquivo entre parêntesis () e seguido pelos atributos entre chaves {}. O atributo identificador, precedido pelo caracter # (hash) é obrigatório, através dele a imagem poderá ser referenciada no texto. Também pode ser adicionado o atributo largura, em porcentagem, que define a largura da imagem em relação à largura total do documento.

Para inserir a fonte da imagem, no parágrafo seguinte (parágrafos, em Markdown, como já vimos, são trechos de texto separados entre si por uma linha em branco) à inserção da imagem deve ser inserido texto começando com Fonte:, seguido, evidentemente, pela fonte.

Para referenciar a imagem no texto deve ser utilizado o comando LaTeX \autoref ou \ref, seguido pelo identificador definido para a imagem entre chaves {}, sem o # (hash), conforme trecho a seguir.

![Legenda da imagem](imagens/imagem.png){#identificador largura=100%}

Fonte: Autor.

A imagem pode ser referenciada no texto, assim \autoref{identificador}. Ou então, ver Figura \ref{identificador}.

Tabelas

Uma tabela pode ser inserida utilizando a mesma sintaxe Pandoc’s Markdown para tabelas apresentada no nosso segundo artigo desta série, com uma pequena diferença: a legenda da tabela deve ser necessariamente inserida no parágrafo anterior à tabela em si, em uma linha começando com : (dois pontos). Na sequência da legenda deve ser utilizado o comando LaTeX \label para adicionar o identificador da tabela.

A fonte e a forma de referenciar a tabela no texto segue o mesmo padrão das imagens, conforme trecho a seguir.

: Bairros de capitais brasileiras \label{tabcidades}

| São Paulo   | Rio de Janeiro | Belo Horizonte |
|:------------|:--------------:|---------------:|
| Sé          | Lapa           | Savassi        |
| República   | Glória         | Lourdes        |
| Pinheiros   | Flamengo       | Pampulha       |
| Barra Funda | Botafogo       | Barreiro       |

Fonte: Autor.

A tabela pode ser referenciada no texto, assim \autoref{tabcidades}.

Quadros

Um quadro utiliza quase exatamente a mesma sintaxe de uma tabela (uma vez que um quadro é, de fato, um tipo de tabela). A única diferença é que a legenda do quadro, também inserida no parágrafo que antecede a tabela/quadro em si, deve começar com a palavra Quadro, seguido do nome do quadro, seguido de : (dois pontos), seguido da legenda. O nome do quadro funcionará como identificador para referenciar o quadro ao longo do texto, de modo que não será necessário utilizar o comando \label. Conforme exemplo a seguir.

Quadro perfil: Perfil dos voluntários do experimento

| Vol. | Formação acadêmica              | Experiência c/ Latex | Experiência c/ Markdown |
|:----:|:-------------------------------:|:--------------------:|:-----------------------:|
|  1   | Ciência da Computação           | ShareLatex           | Readme/Github           |
|  2   | Engenharia da Computação        | Viu prof. utilizando | -                       |
|  3   | Engenheiro elétrico (mestrando) | Utiliza para tudo    | -                       |

Fonte: Autor.

O quadro pode ser referenciado no texto, assim \autoref{perfil}.

Referências

O Limarka utiliza o mesmo sistema do LaTeX para elaborar as referências e citá-las no texto. As referências deverão ser cadastradas no arquivo referencias.bib, que faz parte do modelo do projeto. As referências podem ser editadas “manualmente” no arquivo referencias.bib, utilizando um editor de textos ou mesmo o bloco de notas, ou então pode-se utilizar um editor de referências, como o JabRef, recomendado.

Sistema de referências

A norma ABNT NBR 10.520, em seu item 6, determina que o sistema de citações/referências pode ser de duas formas: Autor-Data ou Numérico. Essa escolha também determinará como a seção de referências será organizada (por ordem alfabética ou por ordem de citação). Deve-se escolher qual dessas fomas será seguida no trabalho.

No arquivo configuracao.yaml, na linha com a chave referencias_sistema, deve ser digitado o valor num se a escolha for pelo Sistema Numérico ou o valor alf se a escolha for pelo Sistema Autor-Data.

Na figura 1 a seguir pode ser observada a diferença entre o Sistema Autor-Data, à esquerda, e o Sistema Numérico, à direita.

Sistemas de referência — Sistemas de Referências. Autor-Data à esquerda e Numérico à direita.

Cadastro de referências

As referências devem ser cadastradas no arquivo referencias.bib, como já foi dito. Na sequência apresentamos exemplos dos principais tipos de entrada de referência no padrão Bibtex. Não é exatamente necessário conhecer a sintaxe Bibtex caso opte-se por utilizar um editor de referências, como o JabRef.

Livro

A adição de um livro é feita através de uma entrada @book no arquivo referencias.bib. Conforme este modelo:

@book{sobrenomeANO,
 author  ={Sobrenome, N. and Sobrenome2, N2.},
 title   ={Título da Obra},
 organization={Revista Brasileira de Geografia},
 address ={Cidade da Editora},
 publisher={Nome da editora},
 pages   =137,
 series  ={Série do livro},
 number  =15,
 note    ={Bibliografia: p. 131--132},
 isbn ={XX-XXX-XXXX-X},
 issn ={XXXX-XXXX},
 year ={1998}
}

Para citar essa referência basta utilizar, no texto, \cite{sobrenomeANO}.

Capítulo de livro

A adição de um capítulo de livro é feita através de uma entrada @inbook no arquivo referencias.bib. Conforme este exemplo:

@inbook{secretaria1999,
 abnt-6023-2000-section = {7.3.2-3},
 organization={São Paulo {(Estado). Secretaria do Meio Ambiente}},
 title   ={Tratados e organizações ambientais em matéria de meio ambiente},
 booktitle={Entendendo o meio ambiente},
 address ={São Paulo},
 volume  =1,
 url     ={http://www.bdt.org.br/sma/entendendo/atual.htm},
 urlaccessdate={8 mar. 2017},
 year =1999
}

Para citar essa referência basta utilizar, no texto, \cite{secretaria1999}.

Artigo

A adição de um artigo é feita através de uma entrada @article no arquivo referencias.bib. Conforme este exemplo:

@article{costa1998,
 author  ={V. R. Costa},
 title   ={À Margem da lei: o Programa Comunidade Solidária},
 journal ={Em Pauta},
 section ={Revista da Faculdade de Serviço Social da UERJ},
 address ={Rio de Janeiro},
 pages   ={131-148},
 number  =12,
 volume  =3,
 pages   ={15-21},
 issn    ={0034-723X},
 url     ={http://www.brazilnet.com.br/contexts/brasilrevistas.htm},
 urlaccessdate={28 nov. 2017},
 year    =1998
}

Para citar essa referência basta utilizar, no texto, \cite{costa1998}.

Site

A adição de um site é feita através de uma entrada @misc no arquivo referencias.bib. Conforme este exemplo

@misc{alves2021,
 title   ={Operação Urbana Porto Maravilha: Engenharia Financeira e Institucional},
 url     ={https://www.inteligenciaurbana.org/2021/05/porto-maravilha-engenharia-financeira.html},
 author  ={Alves, E. F.},
 urlaccessdate={25 mai. 2021}
}

Para citar essa referência basta utilizar, no texto, \cite{alves2021}.

Citação de Referências

Para a citação de uma referência esta deve estar, evidentemente, cadastrada no arquivo referencias.bib.

A citação de referências utiliza o mecanismo do LaTeX. O primeiro elemento (a chave) deve ser utilizado com o comando \cite.

O número da página que está sendo citada, bem como outros indicadores, também pode ser adicionado à citação, entre colchetes [], logo após o comando \cite e antes da chave da referência que está sendo citada, conforme exemplos a seguir.

> Para realizar uma citação direta (com mais de três linhas), basta iniciar a linha com o símbolo '>'. Este parágrafo seria apresentado com o espaçamento à esquerda \cite[p. 7]{chave_da_referencia}.

Para realizar uma citação direta (com três ou menos linhas), "basta colocar o texto entre aspas dentro do texto, mas é necessário indicar a página ou seção de onde o texto foi retirado no documento" \cite[p. 7]{chave_da_referencia}.

Uma citação indireta pode ser realizada apenas indicado a referência, \cite{chave_da_referencia}.

Anexos e apêndices

Os anexos e apêndices devem ser digitados nos arquivos anexos.md e apendices.md, respectivamente, que fazem parte do modelo do projeto. Deve-se utilizar a mesma sintaxe do arquivo trabalho-academico.md, a diferença é que nesses arquivos os capítulos tornam-se Anexos ou Apêndices.

Para utilização desses elementos é necessário habilitar sua utilização no arquivo configuracao.yaml. Nas linhas com as chaves apendices e anexos, deve ser digitado o valor true para habilitar o elemento ou false para desabilitá-lo.

Inclusão de PDFs

Uma funcionalidade bastante útil nas seções de Anexos e Apêndices é a inclusão de arquivos PDF. Para isso, pode ser utilizado o comando LaTeX \includepdf. O documento PDF a ser inserido deve ser salvo, preferencialmente, na pasta imagens do modelo do projeto. O caminho e o nome do arquivo PDF a ser inserido deve estar no parâmetro - entre chaves {} - do comando \includepdf.

O seguinte comando irá inserir a primeira página do documento PDF:

\includepdf{imagens/nome-do-arquivo.pdf}

O seguinte comando insere todas as páginas do documento PDF:

\includepdf[pages=-]{imagens/nome-do-arquivo.pdf}

O seguinte comando insere todas as páginas do documento PDF em ordem reversa:

\includepdf[pages=last-1]{imagens/nome-do-arquivo.pdf}

O seguinte comando insere todas as páginas do documento PDF e adiciona cabeçalho com paginação:

\includepdf[pages=-,pagecommand={\thispagestyle{abntheadings}}]{imagens/nome-do-arquivo.pdf}

O comando \includepdf faz parte do pacote PDFpages, sua documentação com mais detalhes sobre a utilização do comando, caso seja necessário, pode ser encontrada neste link.

Geração do PDF

A geração do PDF consiste em invocar o Limarka no diretório do projeto, e então o conteúdo do arquivo trabalho-academico.md, em conjunto com os dados do arquivo referencias.bib, além das imagens e PDFs incluídos, e eventualmente dos arquivos auxiliares anexos.md, apendices.md e errata.md será utilizado para gerar o PDF final.

Isto pode ser feito diretamente através do Prompt de comando do Windows, de forma muito parecida com a utilização do Pandoc (que, de fato, é a suíte de conversores utilizada pelo Limarka).

Para invocar o Limarka desta maneira, ou seja, abrir o Prompt de Comando ou o PowerShell em uma pasta específica - a pasta do projeto, neste caso - basta navegar até esta pasta através do Windows Explorer e, com a tecla shift pressionada, clicar com o botão direito do mouse em uma área em branco da pasta em questão. Será aberto um menu suspenso e, neste menu, devemos clicar na opção “abrir janela do PowerShell aqui” ou “abrir janela do Prompt de comando aqui” (pode estar disponível uma ou outra opção, conforme a versão do Windows que estiver sendo utilizada).

Então uma janela do interpretador de linha de comando será aberta já na pasta em que está nosso arquivo que será convertido. A janela aberta se parece com esta figura 2.

prompt-win — Prompt de comando do Windows

A lógica consiste em digitar os comandos no interpretador de linha de comando e pressionar enter para executá-los.

Deve-se digitar o seguinte comando para executar o Limarka e gerar o PDF:

limarka exec

E caso queira obter ajuda com os demais comandos do Limarka, basta digitar o seguinte:

limarka help exec

Todavia, existe uma opção que pode ser mais simples, através de um menu interativo (que, na verdade, é um arquivo .bat que também roda do prompt).

Um dos arquivos que estão na pasta deste modelo oficial é justamente este menu interativo, o arquivo se chama menu-interativo.bat, basta abri-lo. O Prompt será aberto e apresentará um “menu” semelhante a este:

+------------+---------------------------------------------+
|             Menu interativo - limarka v0.6.0             |
|      /home/eduardo/w/abnt/trabalho-academico-modelo      |
+------------+---------------------------------------------+
| Comando    | Descrição                                   |
+------------+---------------------------------------------+
| exec       | Executa o limarka.                          |
| figura     | Imprime código para adição de Figura.       |
| tabela     | Imprime código para adição de Tabela.       |
| cronograma | Imprime código para inclusão de Cronograma. |
| rascunho   | Executa o limarka lendo de rascunho.md      |
| web        | Imprime o endereço da documentação online.  |
| menu       | Imprime esse menu.                          |
| sair       | Termina o menu interativo.                  |
+------------+---------------------------------------------+
? [exec, figura, tabela, cronograma, rascunho, web, menu, sair] 

O menu apresenta ao usuário os comandos disponíveis e suas descrições, e fica aguardando que o usuário digite qual comando deseja executar. Digite exec para executar o Limarka.

Conclusão

Neste artigo apresentamos a instalação e o funcionamento básico do Limarka, que é uma ferramenta capaz de gerar arquivos PDF de documentos acadêmicos, como artigos dissertações e teses, em conformidade com as Normas da ABNT a partir de textos escritos em Markdown. Outros detalhes, bem como configurações e comandos avançados podem ser encontradas no site da documentação do Limarka.

Além do blog, a plataforma Inteligência Urbana disponibiliza páginas com referências para livros, cursos e leis e normas relacionadas aos temas que tratamos aqui. Caso você tenha interesse pode conferir nossos serviços oferecidos e entrar em contato quando quiser. Se quiser ser alertado da publicação de material novo pode assinar a nossa newsletter, e muito obrigado pela atenção até aqui!

Principais referências