% Utilização de Markdown para elaboração de TCCs: experimento da ferramenta Limarka % Eduardo de Santana Medeiros Alexandre % 2017
institute: Universidade Federal da Paraíba
theme: Warsaw lang: pt-BR graphics: true slide-level: 2 titlepage-note: Título menor aqui. header-includes:
- "\usepackage{amsfonts}"
- "\logo{imagens/limarka-logo.png}"
- Escrita de Trabalho de Conclusão de Curso (TCC) como requisito para conclusão de curso;
- Soluções onerosas de formatações extraídos de TCCs reais
{width=50%}
- Erros são mais perceptíveis durante o processo de orientação.
{width=40%}
{width=40%}
- Permite seus usuários se concentrarem na elaboração do conteúdo do texto.
A coexistência de códigos Latex no arquivo fonte do texto diminui a legibilidade do texto.
g
{width=70%}
{width=70%}
- Normas da ABNT
- Normas da Instituição
- Orientador
- Histórico do que foi aceito no curso
- Guias de formatação
\pause
- Contemplar peculiaridades exigidas pelas Normas da ABNT e gerenciar os conflitos.
Estudantes nacionais elaborarem seus TCCs utilizando uma linguagem de marcação leve, despreocupando-se das Normas da ABNT e demais exigências de formatação.
Avaliar o uso de uma linguagem de marcação leve para escrita de TCCs em conformidade com as Normas da ABNT.
-
Analisar requisitos de formatação de TCCs;
-
Identificar linguagem de marcação apropriada para escrita de TCCs
-
Implementar aplicação que possibilite usuários escrever TCCs nacionais utilizando uma linguagem de marcação leve
-
Avaliar o uso de uma linguagem de marcação leve para a escrita de TCCs nacionais por estudantes
- Experimento de utilização da ferramenta
- Observações
- Entrevistas semiestruturadas
- Análise qualitativa
- Somente voluntários que potencialmente precisariam elaborar um TCC.
-
ALEXANDRE, E. de S. M. Limarka: making possible brazilian students writing dissertation and thesis with markdown. The Journal of Open Source Software, v. 2, n. 9, 2017. Disponível em: http://dx.doi.org/10.21105/joss.00169.
-
ALEXANDRE, E. de S. M. One language to rule all writings: why you should be using Markdown. Journal of Universal Computer Science. Qualis B1 - Submetido.
- ABNT NBR 14724, Informação e documentação - Trabalhos acadêmicos - Apresentação;
- ABNT NBR 6023, Informação e documentação - Referências - Elaboração;
- ABNT NBR 6024, Informação e documentação - Numeração progressiva das seções de um documento escrito - Apresentação;
- ABNT NBR 6027, Informação e documentação - Sumário - Apresentação;
- ABNT NBR 6028, Informação e documentação - Resumo - Procedimento;
- ABNT NBR 6034, Informação e documentação - Índice - Apresentação;
- ABNT NBR 10520, Informação e documentação - Citações em documentos - Apresentação;
- ABNT NBR 12225, Informação e documentação - Lombada - Apresentação;
- Código de Catalogação Anglo-Americano. 2. ed. rev. 2002. São Paulo: FEBRA, 2004.
- IBGE. Normas de apresentação tabular. 3. ed. Rio de Janeiro, 1993.
Cada documento possui uma data de início de vigência, tornando o anterior obsoleto.
a) nome da instituição (opcional); b) nome do autor; c) título; d) subtítulo; e) número do volume; f) local (cidade); g) ano de depósito.\pause
- Logotipo
- Curso
- Departamento
-
Obrigatoriamente adicionar na parte superior (a) o tipo da ilustração (Figura, Quadro, Tabela etc.), (b) um travessão como separador, e (c) um título para a ilustração;
-
Obrigatoriamente adicionar na parte inferior, a Fonte da imagem, mesmo que seja do próprio autor;
-
Opcionalmente notas explicativas e legendas também podem ser adicionadas na parte inferior;
-
Obrigatoriamente referenciar a ilustração no texto, o mais próximo possível.\pause
-
Guias ou manuais conflitantes com as Normas da ABNT
- Fonte de ilustrações e tabelas;
- Notas explicativas;
- Diferenciação entre Tabela e Quadro;
- Pré-textuais (Ficha catalográfica, Folha de aprovação).
Alínea:
a) Banana;
b) Côco;
c) Manga.
- formato para produção de livros criado pela editora O’Reilly;
- livros técnicos;
- XML;
- mais de 350 tags (v5.0).
- Agilizar a escrita de livros;
- Exportação para o formato DocBook.
- Inclusão e formatação de códigos;
- Suporta referência de quase todos os elementos de um livro;
- Ótimo suporte para tabelas;
- Sintaxe de comandos em inglês;
- Modularização do texto;
- Extensível através de filtros.
- Conversão de texto para HTML.
- Código fonte deve ser semelhante a apresentação;
- Escrever o texto sem perceber que há marcações nele.
- Bastante simples;
- Não possui palavras chaves.
{width=20cm}
\note[1]{Tipos de recursos: audio, code, image, math, poetry, table and video.}
- Criação de quadros laterais que atravessam páginas
- Criação de quadros tipados (Discussão, Erro, Informação, Dica e Atenção)
- Quizz (marcados), Exercícios e Respostas
~~~
{quiz, id: quiz1}
? Quantas letras existem na palavra Markua?
a) 5
B) 6
c) 7
{/quiz}
~~~
- Software nacional (comercial) -- implementa linguagem de marcação própria.
- Utiliza formulários para gerar gerar/editar conteúdos.
- Inspiração para utilização de formulários no Limarka.
- Normas da ABNT
- Normas e modelos de Instituições
- Configuração da capa;
- Configuração dos pré-textuais obrigatórios: folha de rosto, folha de aprovação, resumo e abstract;
- Criação de Sumário automático;
- Configuração de estilos diferentes para entradas do sumário, para os títulos dos textuais e pré-textuais;
- Configuração de estilos de capítulos, seções e texto;
- Inclusão de Ilustrações, Quadros e Tabelas com título, fonte e possibilidade de referenciação no texto;
- Elaboração da seção de Referências (com formatação diferenciada);
- Elaboração de apêndices, anexos e incluir pdfs;
- Escrita dos principais elementos do trabalho através de uma linguagem de marcação leve.
- Fácil utilização.
- Confiável em relação as mudanças das Normas.
| Objetivos da Pesquisa | Concluído |
|---|---|
| Analisar requisitos de formatação de TCCs | \checkmark |
| Identificar linguagem de marcação apropriada para escrita de TCCs | |
| Implementar aplicação que possibilite usuários escrever TCCs nacionais utilizando uma linguagem de marcação leve | |
| Avaliar o uso de uma linguagem de marcação leve para a escrita de TCCs nacionais por estudantes |
- Primeira alternativa devido a experiência prévia na produção de livros do curso de Licenciatura em Computação a Distância da UFPB.
Análise e projeto de sistemas, Cálculo Diferencial e Integral, Estruturas de Dados, Fundamentos Antropo-Filosóficos da Educação, Fundamentos Psicológicos da Educação, Fundamentos sócio-histórico da educação, Introdução a Arquitetura de Computadores, Introdução a Compiladores, Introdução a Computação, Introdução a Educação a Distância, Introdução a programação, Linguagem de Programação I, Linguagem de programacao II, Matemática Computacional, Metodologia do Trabalho Científico, Objetos Digitais e Educação em Computação, Probabilidade e Estatística.
{width=60%}
Não é possível utilizar o formato DocBook como intermediário para produção de TCCs, pois não há correspondentes para: Errata, Folha de Aprovação e Ficha Catalográfica.
| Solução | Status |
|---|---|
| Asciidoc (original) | Abortada |
\framesubtitle{Solução não descrita na dissertação}
- Possibilitaria geração de PDF sem Latex (desejável).
- Geração de DocBook e formatação de PDF através de XSL Formatting Objects (https://www.w3.org/TR/xsl11/)
- Seria necessário implementar todas as regras da ABNT através de FO;
- Incertezas devido a nunca ter sido utilizado antes com este propósito.
| Solução | Status |
|---|---|
| Asciidoc (original) | Abortada |
| Asciidoc (DocBook com XSL-FO) | Abortada |
- Não utiliza DocBook como intermediário (desejado)
- A geração do PDF ocorre sem utilizar Latex
- As configurações de formatação são realizadas através de arquivo YAML
- A ferramenta ainda encontra-se em estágio alpha
| Solução | Status |
|---|---|
| Asciidoc (original) | Abortada |
| Asciidoc (DocBook com XSL-FO) | Abortada |
| Asciidoc (asciidoctor-pdf) | Abortada |
-
Utilização de abnTeX2 para formatação com as Normas da ABNT;
-
Utilização de Engine de Templates para gerar código Latex;
-
Configuração de pré-textuais utilizando YAML;
- Fácil experimentação;
- Transparência nas orientações e escritas de TCCs para educação a distância;
- Requer conhecimentos da sintaxe de YAML e Latex;
- Exige validação do arquivo fonte com base na sintaxe de Asciidoc;
- Exige familiaridade para escrita de termos básico em inglês;
- Inexiste na sintaxe da linguagem para inserir fontes em figuras e tabelas;
- Submissão de imagens requer saber utilizar o git;
asciidoctor-latexem estágio alfa;
| Solução | Status |
|---|---|
| Asciidoc (original) | Abortada |
| Asciidoc (DocBook com XSL-FO) | Abortada |
| Asciidoc (asciidoctor-pdf) | Abortada |
| Asciidoc (asciidoctor-latex) | Abortada |
Formatos suportados: native Haskell, JSON version of native AST, plain text, pandoc’s extended Markdown, original unextended Markdown, PHP Markdown Extra, GitHub-Flavored Markdown, MultiMarkdown, CommonMark Markdown, reStructuredText, XHTML, HTML5, LaTeX, LaTeX beamer slide show, ConTeXt, groff man, MediaWiki markup, DokuWiki markup, ZimWiki markup, Textile, Emacs Org mode, GNU Texinfo, OPML, DocBook 4, DocBook 5, OpenDocument, OpenOffice text document, Word docx, Haddock markup, rich text format, EPUB v2 book, EPUB v3, FictionBook2 e-book, AsciiDoc, InDesign ICML, TEI Simple, Slidy HTML and JavaScript slide show, Slideous HTML and JavaScript slide show, DZSlides HTML5 + JavaScript slide show, reveal.js HTML5 + JavaScript slide show, S5 HTML and JavaScript slide show.
a. Configuração requer conhecimentos de Estruturas de Dados, sintaxe YAML e Latex
a. Usuário teria dificuldade em obter suporte do código Latex gerado
a. Os pré-textuais precisariam ser criados em Latex pelo usuário
a. A sintaxe de citação da linguagem suporta um único estilo de chamada de citações
a. Inexiste suporte na sintaxe da linguagem para especificação de fonte de ilustrações e tabelas
| Solução | Status |
|---|---|
| Asciidoc (original) | Abortada |
| Asciidoc (DocBook com XSL-FO) | Abortada |
| Asciidoc (asciidoctor-pdf) | Abortada |
| Asciidoc (asciidoctor-latex) | Abortada |
| Markdown (pandoc) | Abortada |
a. Utilização de um template customizado baseado no abnTeX2
a. Utilização de formulário em vez de arquivo YAML
a. As figuras, tabelas e quadros precisariam ser inseridas através de código Latex\pause
- Markdown foi estendido.
- Não é mais necessário utilizar a sintaxe de Latex para inclusão de Figuras, Tabelas e Quadros.
| Solução | Status |
|---|---|
| Asciidoc (original) | Abortada |
| Asciidoc (DocBook com XSL-FO) | Abortada |
| Asciidoc (asciidoctor-pdf) | Abortada |
| Asciidoc (asciidoctor-latex) | Abortada |
| Markdown (pandoc) | Abortada |
| Markdown (pandoc, abntex2, formulário) | Escolhida |
{#fig:arquitetura width=70%}
{#chat width=85%}
a. Adoção do formato PDF para o formulário;
a. Os campos de preenchimento no formulário utilizam a mesma sintaxe do texto;
a. Oferta de alternativas de configuração;
a. Escolhas das configurações são apresentadas seguindo a ordem natural de utilização.
- Baseado no template de trabalho acadêmico do abnTeX2;\pause
- Aposentadoria do abntex2cite;
- Customização dos modelos do abntex2 para uso do biblatex-abnt;
- Verificação de compatibilidade dos modelos de documentos, referências bibliográficas e citação com as normas vigentes da ABNT;
- Produção de novos manuais.
{#teste-bdd width=75%}
Experimentando recursos mínimos da ferramenta:
- Capa, Folha de rosto e Resumo
- Citações direta e indireta
- Figura e Tabela
- Cronograma
- Referências
- Apêndices ou Anexos (opcionais).
| Vol. | Formação acadêmica | Exp. c/ Latex | Exp. c/ Markdown |
|---|---|---|---|
| 1 | C. da Computação | ShareLatex | Readme/Github |
| 2 | Eng. da Computação | Viu prof. utilizando | - |
| 3 | Eng. elétrico (ms) | Utiliza para tudo | - |
| 4 | Eng. da Computação | 3 vezes on-line | - |
| 5 | Eng. da Computação | Mictex no Windows | - |
| 6 | C. da Computação | Viu prof. utilizando | - |
| 7 | Eng. Florestal (ms) | - | - |
| 8 | Eng. de Produção | - | - |
| 9 | Eng. da Computação | Overleaf | Readme/Github |
| 10 | Eng. Ambiental | - | - |
- O processo de instalação da ferramenta foi considerado fácil por usuários com afinidade com informática, que estão habituados a instalar programas e dependências.
-
Gedit, Sublime, Emacs, Vim ou Notepad++ -- "estava no paraíso".
-
Problema: Leitores de PDF que realizam lock no arquivo.
-
Dificuldades no Windows (arquivo Zip).
"Foi bem fácil, já estava tudo bem explicado. Errar não tinha como. É aqui que você faz isso, e já tinha um exemplo preenchido."
- Realizadas manualmente no template Latex.
- Nessa dissertação: evitar hifenização; numeração de linhas.
"Simples com o menu e linha direta"
"Na primeira vez demorou bastante"
"De início pareceu um pouco complicado, mas vai se acostumando com a novidade e vai se tornando prático. (...) não é uma coisa que fazemos no dia a dia."
- Geração automática do PDF quando o arquivo é salvo.
"Zero problema, muito simples, muito explicativo."
"No Word teria que colocar tudo, na ferramenta já está estruturado, amarrado."
"[Comparando com o Latex] aqui foi mais rápido. Lá precisava modificar pouca coisa, mas precisava procurar o que precisava configurar. E tinha algumas paradas obscuras em Latex, e aqui eu não precisava me preocupar com isso".
- Idêntico ao Latex, mas com pré-processamento das referências.
Teve dificuldade porque não sabia o que era e como fazer.
"Foi mediano. Não foi muito fácil, nem difícil"
"A parte mais complicada era em Latex para fazer as referências. Mas já tem pronto [referindo-se aos exemplos disponibilizados no Wiki], mas na hora de usar era bem fácil".
Não tinha entendido a marcação inicialmente.
Colou uma tabela já utilizada proveniente de outro lugar, faltando fonte.
"Foi um pouco mais trabalhoso que a figura, porque precisa saber de acordo com o código qual o número de colunas que vai utilizar e de seções". [Habitualmente faz as tabelas no Excel e cola no Word].
- Curva de aprendizado maior (código Latex).
"Quem não tem contato com programação se assustaria um pouco". Intuitivo e legal.
"Tive dificuldades na escrita do conteúdo"
"É muito bom de utilizar porque se preocupa [mais] com o conteúdo"
"Não tem o trabalho de formatar no Word e não precisaria dos códigos Latex que são gigantes"
"Bem mais simples que Latex"
- Utilizaria o Word, pois tem mais contato no cotidiano.
- Tem dúvidas se utilizaria o Limarka, para evitar o problema em ter que configurar o Latex novamente [utilizou o editor Overleaf on-line na qualificação]
- Se a coordenação do curso aceitasse o modelo produzido pelo Limarka, preferia utilizar ele do que o ShareLatex, mesmo tendo que instalar e utilizar as ferramentas localmente.
- Limarka. Mesmo habituado a fazer no Word, mas esse aqui é mais direto, faz toda a estrutura para mim. No Word eu teria que fazer tudo, passo a passo, todas as coisas.
- Passaria a utilizar o Limarka. Fica mais fácil de utilizar e não precisa lidar com as regras do Latex.
- Planeja convencer colega para utilizar o Limarka e obter o feedback dele.
- Complicado mas prático.
- É complicado no início, mas vale a pena.
- Experiencia inovadora, mas não muito usual.
- Com a ferramenta Limarka, você consome mais tempo se preocupando com o conteúdo do seu trabalho do que com a formatação.
- O que era difícil ficou fácil.
- É simples de utilizar.
- Simples, compacta e cômoda.
- Rápido e intuitivo.
- Agilidade e bem estar no uso da ferramenta.
- É possível utilizar uma linguagem de marcação leve (Markdown) para escrita de TCCs nacionais em conformidade com as Normas da ABNT.
- Solução alternativa aos Offices e Latex.
- Expressivamente equivalente a Latex.
- Possibilita melhorias não presentes no Word e Latex (ex: alíneas).
- Sua utilização pode ser incentiva pois há indícios de que seja mais simples e fácil do que Latex.