% Created 2020-03-25 qua 17:21
\documentclass[11pt]{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{fixltx2e}
\usepackage{graphicx}
\usepackage{longtable}
\usepackage{float}
\usepackage{wrapfig}
\usepackage{rotating}
\usepackage[normalem]{ulem}
\usepackage{amsmath}
\usepackage{textcomp}
\usepackage{marvosym}
\usepackage{wasysym}
\usepackage{amssymb}
\usepackage{hyperref}
\tolerance=1000
\usepackage{color}
\usepackage{listings}
\author{Marco Dimas Gubitoso}
\date{\today}
\title{Guia Rápido para o uso do \texttt{org-mode}}
\hypersetup{
  pdfkeywords={},
  pdfsubject={},
  pdfcreator={Emacs 25.2.2 (Org mode 8.2.10)}}
\begin{document}

\maketitle
\tableofcontents


\section{Introdução}
\label{sec-1}
\label{come-o}
Este é um guia rápido para começara usar p \texttt{org-mode} do \emph{Emacs}.  Não
é completo, nem daria para ser, pois há um número enorme de opções e
modos de configuração.  No entanto, deve bastar para a maior partes
das tarefas do dia a dia.

Vou me focar na produção de \emph{slides} e de páginas \emph{web}.  Neste
tutorial,  o objetivo são páginas e documentos \LaTeX.  Farei um outro
tutorial específico para \emph{slides} usando \emph{Beamer}.

Uma vez domindo o básico, será fácil estender para outras atividades.
Entre os recursos adicionais estão:

\begin{itemize}
\item Lista de tarefas (\emph{Todo lists}, \emph{checklists} etc)
\item Agenda
\item Planilhas (é bom conhecer \emph{lisp})
\item Geração de \emph{sites}
\item Anotações de ideias para planejamento
\end{itemize}

Talvez a melhor forma de começar a aprender seja olhando o fonte deste
prórpio documento.

\section{Organização do documento}
\label{sec-2}

As seções são definidas por uma série de *s no começo da linha.  O
número de *s indica o nível, da forma natural:

\begin{description}
\item[{\texttt{*}}] Seção
\item[{\texttt{**}}] Subseção
\item[{\texttt{***}}] Subsubseção
\end{description}

e assim por diante.

O início do documento pode conter um cabeçalho de configurações.  Eu
pessoalmente gosto de colocar esta linha
\begin{verbatim}
#+STARTUP: hidestars
\end{verbatim}
para ocultar asteriscos repetidos.

\section{Opções gerais de configuração}
\label{sec-3}
\subsection{Por documento}
\label{sec-3-1}
Cada documento pode conter suas próprias configurações, que aparecem
como comentários especiais.  

Os comentários seguem o formato das linguagens de \emph{script}, isto é,
tudo que segue um \texttt{\#} é ignorado.   Para as opções, o início da linha
deve conter \texttt{\#+} seguido do nome da configuração, seguido pr \texttt{:}, sem
espaços.  Depois disso, na mesma linha, seguem os valores.  Veja o
exemplo acima.

São muitas opções que podem ser vistas na documentação. As mais
comuns eu citarei ao longo do documento.   Farei uma outra página com
um resumo geral.
\subsection{Universais}
\label{sec-3-2}
Há configurações que afetam o comportamento do \texttt{org-mode} como um
todo.  Normalmente não é preciso mexer nelas, a menos que você
queira adaptações muito particulares.

No entanto, existe pelo menos uma que vale a pena olhar:
\texttt{org-babel-load-languages}.  Esta variável é uma lista das linguagens
que recebem formatação especial e que podem ser executadas dentro de
um documento.  As opções disponíveis dependem dos modos instalados,
eis algumas:

\begin{center}
\begin{tabular}{lll}
Linguagem & Módulo necessário & Comentário\\
\hline
Awk & awk & \\
C & nenhum & \\
C++ & nenhum & \\
Calc & nenhum & Calculadora do Emacs\\
CSS & nenhum & Estilos para HTML\\
Ditaa & ditaa & Desenhos simples (veja abaixo)\\
Dot (Graphviz) & dot & \\
Emacs Lisp & nenhum & \\
Fortran & fortran & \\
Gnuplot & gnuplot, gnuplot-mode & \\
Java & java & \\
Javascript & node.js & \\
\LaTeX{} & latex, auctex, reftex & \\
Lisp & lisp, slime & \\
Make & nenhum & \\
Matlab & matlab, matlab.el & \\
Octave & octave & \\
Org & nenhum & \\
Perl & perl, cperl-mode (opcional) & \\
Python & python, python-mode (opcional) & \\
R & R, ess-mode, tikzDevice & \\
Ruby & ruby, irb, ruby-mode, inf-ruby mode & \\
Sass & sass, sass-mode & \\
Scala & scala & \\
Scheme & nenhum & \\
shell & algum \emph{shell} & \\
SQLite & SQLite, sqlite3, SQL mode & Banco de dados simples\\
\end{tabular}
\end{center}

Há muitas outras. Pessoalmente eu habilitei
\begin{itemize}
\item \emph{emacs-lisp}
\item \emph{fortran}
\item \emph{gnuplot}
\item \emph{latex}
\item \emph{perl}
\item \emph{python}
\item \emph{ruby}
\item \emph{sh}
\item \emph{sqlite}
\item \emph{ditaa}
\item \emph{C}
\end{itemize}

\section{Escrevendo o documento}
\label{sec-4}
\subsection{Linguagem de marcação}
\label{sec-4-1}

O texto usa uma linguagem de marcação bem simples e intuitiva.

\begin{center}
\begin{tabular}{ll}
\hline
\texttt{/itálico/} & \emph{itálico}\\
\texttt{*negrito*} & \textbf{negrito}\\
\texttt{\_sublinhado\_} & \uline{sublinhado}\\
\texttt{+cancelado+} & \sout{cancelado}\\
= \texttt{verbatim} = & \texttt{verbatim}\\
\texttt{\textasciitilde{}código\textasciitilde{}} & \verb~código~\\
\texttt{expoente\textasciicircum{}2} & expoente$^{\text{2}}$\\
\texttt{índice\_ijk} & índice$_{\text{ijk}}$\\
\hline
\end{tabular}
\end{center}


Além disso, símbolos comuns do Latex podem ser usados diretamente
como $\alpha$, $\beta$, $\gamma$ ou $\Gamma$  --- veja \texttt{org-entities-help}

\begin{verbatim}
Além disso, símbolos comuns do Latex podem ser usados diretamente
como \alpha, \beta, \gamma ou \Gamma  --- veja =org-entities-help=
\end{verbatim}

Para textos mais complexos, \emph{environments} do Latex podem ser usados
normalmente, se necessários

\begin{equation}
x = \sqrt{x^2}
\end{equation}

Os trechos em Latex podem ser visualizados no próprio Emacs com \verb~C-c    C-x C-l~. \verb~C-c C-c~ faz retornar ao normal.
\subsection{Listas}
\label{sec-4-2}

São três tipos, seguindo o padrão do \LaTeX{}.

\begin{enumerate}
\item Enumeradas ou ordenadas, como essa aqui.
\begin{enumerate}
\item Começam com um número seguido de \texttt{.} ou \texttt{)}
\setcounter{enumii}{2}
\item A numeração pode ser alterada se colocar um \texttt{[@} \emph{número} 
         \texttt{]} antes do \textbf{texto}.
\item Para letras, é preciso mudar a variável
\texttt{org-list-allow-alphabetical}. Há algumas formas de fazer isso.

\begin{enumerate}
\item Use \verb~C-h v~. para mudar
\item Use um bloco de código (veja mais à frente).
\item Mude seu \texttt{.emacs}
\end{enumerate}
\end{enumerate}
\item Normais (não ordenadas), podem ser marcadas com \texttt{*}, \texttt{+} ou \texttt{-}.
\begin{itemize}
\item O uso de \texttt{*} não é recomendado pois pode ser confundido com
marcador de seção, embora não haja ambiguidade.
\item Fora isso, não há segredo.
\end{itemize}
\item Descritivas.  São como as não ordenadas, mas cada item recebe um
nome seguido de \texttt{::}.
\begin{description}
\item[{simples}] Basta usar o \texttt{::} como separador

\item[{fácil}] é edição normal de texto. Em todas as listas
\texttt{M-<enter>} inicia o próximo item.

\item[{rápido}] não precisa de muita formatação manual.
\end{description}
Este é o código:
\end{enumerate}

\rule{\linewidth}{0.5pt}
\begin{verbatim}
 1. Enumeradas ou ordenadas, como essa aqui.
     1. Começam com um número seguido de =.= ou =)=
     3. [@3] A numeração pode ser alterada se colocar um =[@= /número/ 
      =]= antes do *texto*.
     4. Para letras, é preciso mudar a variável
      =org-list-allow-alphabetical=. Há algumas formas de fazer isso.

        a) Use ~C-h v~. para mudar 
        b) Use um bloco de código (veja mais à frente).
        c) Mude seu =.emacs=
2. Normais (não ordenadas), podem ser marcadas com =*=, =+= ou =-=.
     + O uso de =*= não é recomendado pois pode ser confundido com
     marcador de seção, embora não haja ambiguidade.
     + Fora isso, não há segredo.
3. Descritivas.  São como as não ordenadas, mas cada item recebe um
  nome seguido de =::=.
     + simples :: Basta usar o =::= como separador

     + fácil :: é edição normal de texto. Em todas as listas
              =M-<enter>= inicia o próximo item.

     + rápido :: não precisa de muita formatação manual.
\end{verbatim}

\rule{\linewidth}{0.5pt}


\subsection{Tabelas}
\label{sec-4-3}

Este é um dos pontos altos do \texttt{org-mode} e merece um tutorial à
parte.  Não pela dificuldade, mas pela enorme quantidade de recursos
oferecidos.  Aqui eu novamente vou mostar o básico e, se houver
interesse, monto uma explicação mais profunda depois.

As tabelas são construídas simplesmente separando as colunas por \texttt{|};
A tecla \texttt{TAB} faz todo o alinhamento automaticamente.  Para colocar
uma linha horizontal, basta começá-la com \texttt{|-{}-{}-} e pressionar \texttt{TAB}.
Há  exemplos acima, vou destacar um deles:

\begin{verbatim}
|----------------+--------------|
| =/itálico/=    | /itálico/    |
| =*negrito*=    | *negrito*    |
| =_sublinhado_= | _sublinhado_ |
| =+cancelado+=  | +cancelado+  |
| = =verbatim= = | =verbatim=   |
| =~código~=     | ~código~     |
| =expoente^2=   | expoente^2   |
| =índice_ijk=   | índice_ijk   |
|----------------+--------------|
\end{verbatim}

Para inserir ou remover uma coluna, pode-se usar \verb~M-S-<right>~ ou
\verb~M-S-<left>~, respectivamente.

\subsubsection{Conversão automática}
\label{sec-4-3-1}

A função \texttt{org-table-convert-region} transforma uma região de texto
em uma tabela.  Para definir as colunas, a função usa TABs, vírgulas
ou sequências de espaços, dependendo da estrutura das linhas. Um
prefixo 4 (\verb~C-u~) força vírgulas, um prefixo 16 (\verb~C-u C-u~) força
TAB e outro prefixo numérico força uma quantidade fixa de espaços.

Esta possibilidade é muito útil para imprtar arquivos CSV
facilmente. 

\subsection{Imagens}
\label{sec-4-4}

As imagens podem ser inseridas diretamente, colocando o nome do
arquivo entre colchetes duplos:
\begin{verbatim}
[[file:algo.jpg]] ou [[./algo.jpg]]
\end{verbatim}

É possível ainda colocar uma legenda com um comentário \emph{antes} da
imagem (ou tabela):
\begin{verbatim}
#+CAPTION: Legenda da imagem ou tabela
\end{verbatim}

Para dar um nome de referência, para \emph{links}, por exemplo, usa-se o
mesmo método:
\begin{verbatim}
#+NAME: fig:exemplo
\end{verbatim}

\begin{figure}[htb]
\centering
\includegraphics[width=.9\linewidth]{./algo.jpg}
\caption{\label{42}Tudo em paz}
\end{figure}


\subsection{\emph{Links}}
\label{sec-4-5}

Funcionam do mesmo modo que as imagens, entre colchetes duplos, com
uma URL (ou URI) no meio.  No caso dos links, é possível colocar uma
descrição.  Por exemplo, \hyperref[come-o]{para voltar para o começo}

\begin{verbatim}
Por exemplo, [[começo][para voltar para o começo]]
\end{verbatim}

Neste exemplo, temos uma âncora local, definida assim:
\begin{verbatim}
<<começo>>
\end{verbatim}
bem no início, veja o fonte.
\subsubsection{Notas de rodapé}
\label{sec-4-5-1}
São casos particulares, marcadas entre colchetes simples e começando
com \texttt{fn:}.  Se estão no meio do texto, formam uma referência, se a
marcação estiver no início da linha, é a nota \footnote{Fácil, não é mesmo?}
propriamente dita.

\begin{verbatim}
São casos particulares, marcadas entre colchetes simples e começando
com =fn:=.  Se estão no meio do texto, formam uma referência, se a
marcação estiver no início da linha, é a nota [fn:simples]
propriamente dita.
\end{verbatim}
\newpage
No final do documento coloquei

\begin{verbatim}
[fn:simples] Fácil, não é mesmo
\end{verbatim}
\section{Blocos}
\label{sec-5}

Embora tecnicamente seja parte do documento, resolvi deixar em uma
seção à parte, pois é outro ponto bem versátil do \texttt{org-mode}.

Os blocos são delimitados com duas diretivas especiais:
\begin{verbatim}
#+BEGIN_...
...
#END
\end{verbatim}
A sequência \texttt{...} deve ser trocada pelo tipo de bloco desejado.
Existem vários, em particular os das linguagens especificadas em
\texttt{org-babel-load-languages} e os descritos abaixo.

Na versão que uso, os blocos podem ser rapidamente inseridos com \texttt{<}
seguido de uma letra e um TAB no início da linha, a letra sendo a
primeira de cada tipo (\texttt{<c} insere \texttt{CENTER}, \texttt{<s} insere \texttt{SRC} etc).


\subsection{Gerais}
\label{sec-5-1}
\begin{itemize}
\item \texttt{CENTER}
\end{itemize}
\begin{center}
Texto centralizado, \emph{com marcações}.
\textbf{Bem} conveniente.  $\alpha$$^{\text{2}}$ = $\beta$+$\zeta$$^{\text{3}}$
\end{center}

\begin{verbatim}
#+BEGIN_CENTER
Texto centralizado, /com marcações/.
*Bem* conveniente.  \alpha^2 = \beta+\zeta^3
#+END_CENTER
\end{verbatim}

\begin{itemize}
\item \texttt{EXAMPLE}   Também pode ser gerado iniciando a linha com \texttt{:}.
\end{itemize}
\begin{verbatim}
Para exemplos, isto é, verbatim.
O está dentro do bloco é copiado literalmente para a saída.
\end{verbatim}

\begin{verbatim}
#+BEGIN_EXAMPLE
Para exemplos, isto é, verbatim.
O está dentro do bloco é copiado literalmente para a saída.
#+END_EXAMPLE
\end{verbatim}

\begin{itemize}
\item \texttt{QUOTE}  Para citações.
\end{itemize}
\begin{quote}
I love quotations because it is a joy to find thoughts one might have,
beautifull  expressed with much authority by someone recognized wiser 
than oneself.

\textasciitilde{}Marlene Dietrich
\end{quote}
\begin{verbatim}
#+BEGIN_QUOTE
I love quotations because it is a joy to find thoughts one might have,
beautifull  expressed with much authority by someone recognized wiser 
than oneself.

~Marlene Dietrich
#+END_QUOTE
\end{verbatim}

\begin{itemize}
\item \texttt{VERSE}  Para versos
\end{itemize}
\begin{verse}
Por vezes à noite há um rosto \\
Que nos olha do fundo de um espelho \\
E a arte deve ser como esse espelho \\
Que nos mostra o nosso próprio rosto. \\
\vspace*{1em}
Jorge Luis Borges \\
\end{verse}

\begin{verbatim}
#+BEGIN_VERSE
Por vezes à noite há um rosto
Que nos olha do fundo de um espelho
E a arte deve ser como esse espelho
Que nos mostra o nosso próprio rosto.

Jorge Luis Borges
#+END_VERSE
\end{verbatim}

\newpage
\subsection{Saídas específicas}
\label{sec-5-2}
São blocos que são usados apenas em formatos específicos e ignorados
nos outros.  Os formatos possíveis são vários, incluindo
\emph{LibreOffice} (odt).  Os blocos pré-definidos são estes

\begin{itemize}
\item \texttt{ASCII} Para saída em texto normal
\end{itemize}
\begin{verbatim}
#+BEGIN_ASCII
Este conteúdo  só aparecerá se for selecionado o formato ASCII
#+END_ASCII
\end{verbatim}

\begin{itemize}
\item HTML
\end{itemize}
\begin{verbatim}
#+BEGIN_HTML
Este conteúdo  só aparecerá se for selecionado o formato <i>HTML</i>.
#+END_HTML
\end{verbatim}
\begin{itemize}
\item LATEX
\end{itemize}
Este conteúdo  só aparecerá se for selecionado o formato \LaTeX.
\begin{verbatim}
#+BEGIN_LaTeX
Este conteúdo  só aparecerá se for selecionado o formato \LaTeX.
#+END_LaTeX
\end{verbatim}

\subsection{Código fonte}
\label{sec-5-3}
Os blocos com \texttt{SRC} recebem um parâmetro adicional com a linguagem
desejada.  Os blocos são formatados de acordo com a sintaxe, além de
permitir que os programas sejam executados.

Tanto o código fonte como o resultado podem ser incluídos no
documento final, para isso coloque \texttt{:exports} na linha inicial,
depois da linguagem.  \texttt{:exports} recebe um destes valores:

\begin{itemize}
\item \texttt{code} : apenas o código é exportado, esse é o \emph{default}
\item \texttt{results} : apenas os resultados
\item \texttt{both} : código e resultado são exportados
\item \texttt{none} : nenhum dos dois
\end{itemize}

Aqui colocarei apenas alguns exemplos, se houver interesse eu faço um
outro tutorial específico, com mais informação e detalhes.

Dentro de um bloco, pode-se editar no modo específico da linguagem
com \texttt{M-x org-edit-special}, normalmente associada a \texttt{C-c} '.  Seguem
alguns exemplos:

\begin{description}
\item[{C}] Note o uso de C maiúsculo
\end{description}
\lstset{language=C,label= ,caption= ,numbers=none}
\begin{lstlisting}
#include <stdio.h>

int main()
{
  puts("Hello world!");
  return 0;
}
\end{lstlisting}

\begin{verbatim}
Hello world!
\end{verbatim}

No fonte está escrito assim:
\begin{verbatim}
 #+BEGIN_SRC C :exports both
#include <stdio.h>

int main()
{
  puts("Hello world!");
  return 0;
}
 #+END_SRC
\end{verbatim}

\begin{description}
\item[{elisp}] útil para configurações locais no emacs

Neste exemplo, eu simplesmente autorizei a execução de blocos sem
perguntas.
\end{description}
\lstset{language=elisp,label= ,caption= ,numbers=none}
\begin{lstlisting}
(setq org-confirm-babel-evaluate nil)
\end{lstlisting}
\newpage
\begin{description}
\item[{ruby}] 
\end{description}
\lstset{language=Ruby,label= ,caption= ,numbers=none}
\begin{lstlisting}
require 'date'

$av = "avaliado em #{Date.today}"
\end{lstlisting}

\begin{verbatim}
avaliado em 2020-03-25
\end{verbatim}

\begin{description}
\item[{python}] 
\end{description}
\lstset{language=Python,label= ,caption= ,numbers=none}
\begin{lstlisting}
return 6*7
\end{lstlisting}

\begin{verbatim}
42
\end{verbatim}

\begin{description}
\item[{ditaa}] Para desenhos simples.  Precisa ter \texttt{ditaa.jar} instalado
e atualizar a variável \texttt{org-ditaa-jar-path} com sua
atualização.  O pacote \texttt{ditaa} está incluído no Ubuntu.
\end{description}

\includegraphics[width=.9\linewidth]{eniac.png}

\newpage
Este é o pedaço do documento que gera esta imagem:

\begin{verbatim}
#+BEGIN_SRC elisp :exports none
(setq org-ditaa-jar-path "/usr/share/ditaa/ditaa.jar")
#+END_SRC

#+RESULTS:
: /usr/share/ditaa/ditaa.jar


#+BEGIN_SRC ditaa :file eniac.png  :exports results  
             
            +------------------------------------------+
            |                                          |
            |           +----------------+             |
            |           |  Programa      |             |
            |           +----------------+             |
   Entrada  |                                          | Saída       
  --------->|           +----------------+             +-------->
            |           | Controlador/SO |             |
            |           +----------------+             |
            |                                          |
            |                                          |
            |   /--------\            /---------\      |
            |   |  CPU   |            | Memória |      |
            |   \--------/            \---------/      |
            |                                          |
            +------------------------------------------+

#+END_SRC

#+RESULTS:
\end{verbatim}
\texttt{: file:eniac.png}
\newpage
\section{Geração das saídas}
\label{sec-6}

A geração das saídas é muito simples.  Basta usar \texttt{C-c e} e um menu
aparecerá com as opções de geração. O menu é auto-explicatório, mas
coloco aqui as opções mais comuns:

\begin{description}
\item[{\texttt{C-c e l p}}] Gera \LaTeX{} e o PDF correspondente.
\item[{\texttt{C-c h o}}] Gera HTML e abre o \emph{browser} padrão.
\item[{\texttt{C-c t u}}] Grava um arquivo texto formatado e em UTF-8
\end{description}

O processamento é muito rápido, a possibilidade de abrir imediatamente
o documento final ajuda nos ajustes.

Para o \LaTeX{} formatar corretamente código fonte é preciso incluir um
\texttt{package} adequado.  O mais direto é o \texttt{listings}.  A linha abaixo
pode ser colocada no início do documento e será incluída no cabeçalho
do arquivo \texttt{.tex}, outras inclusões podem ser feitas do mesmo modo:

\begin{verbatim}
#+LATEX_HEADER: \usepackage{listings}
\end{verbatim}

O bloco com \texttt{elisp} gera um erro inofensivo, pois \texttt{listings} não
conhece a linguagem.  Há outras opções, como \texttt{minted}, mas é preciso
configurar mais coisas e ficará para um eventual tutorial no futuro.

Ainda para saídas específicas, pode-se incluir linhas como estas:

\begin{verbatim}
#+latex: \newline
#+html: <br>
\end{verbatim}


Isso é tudo por enquanto.  A ideia foi mostrar o suficiente para
produzir páginas e PDFs.  Se houver interesse eu mostro como preparar
outros tipos de material.
% Emacs 25.2.2 (Org mode 8.2.10)
\end{document}