===============================
   = Indentar source code no Vim =
   ===============================

   = Introdução =
   --------------

   Há duas maneiras de indentar um código fonte:
     1. com tabs reais, também chamado de hard tabs.
     2. com espaços no lugar de tabs (sim, o vim pode ser configurado para
        substituir uma tabulação por um certo número de espaços).

   Há vantagens e desvantagens em cada um dos métodos. Há alguns artigos que
   discutem o assunto na web, embora parece que mais pessoas preferem Espaços
   no lugar de Hard Tabs, mas isso é pura questão de gosto, e cada caso é um
   caso.

   Basicamente temos as opções:
    1.     'tabstop' - altera a largura da tabulação (Tabs reais).
    2.   'expandtab' - causa espaços serem usados/inseridos no lugar de
                       caracteres Tab.
    2. 'softtabstop' - configura detalhadamente a quantidade de espaço a serem
                       inseridos quando a tecla Tab é pressionada.
    3.  'shiftwidth' - afeta o uso de ">>", "<<", modo normal, "Ctrl-t" e
                       "Ctrl-d" no Modo Insert, além de ter influência em como
                       indetação automática funciona.

   Para iniciar , execute isso no vim:
       :set list ~
       :set listchars=tab:T_ ~

   A partir de agora, toda vez que o vim "enxergar" um Tab real, ele vai
   mostrar algo como "T_____" no lugar do tab, para que o Tab fique
   visualmente percebível.

   Pra desabilitar basta fazer:
       :set nolist ~


   = Indentação com Hard Tabs Apenas =
   -----------------------------------

   Por padrão, o vim vem configurado com:
     tabstop = 8 ~
     softtabstop = 0 ~
     shiftwidth = 8 ~
     noexpandtab ~

   Independente da sua configuração, digite esta linha para testar
   (simplesmente coloca os valores default):
       :set tabstop=8 softtabstop=0 shiftwidth=8 noexpandtab ~

   O que acontece então?
    1. Com essa configuração, pressionar a tecla Tab no modo insert insere um
       caractere Tab real, com largura de 8 colunas.
    2. Nesse caso, o <Backspace> deleta o caractere Tab (deleta 8 colunas), o
       que visualmente parece que vários espaços foram deletados ao mesmo tempo.
    3. No modo Normal, usar >> e << insere ou deleta um Tab real. O mesmo
       ocorre ao se pressionar Ctrl-t e Ctrl-d no modo Insert.

   Para ver que todo aquele espaço em branco é um único Tab, posicione o cursor
   sobre o espaço em branco e pressione "x". Você vai notar que deleta uma
   região bem maior do que um único espaço. Pode-se usar 'listchars' também.


   = Espaços - Caso 1 =
   --------------------

   Veja esta outra configuração:
       :set tabstop=8 softtabstop=0 shiftwidth=8 expandtab ~

    1. Agora, pressionar Tab insere espaços em número equivalente ao que está
       configurado em tabstop, que por padrão é 8.
    2. Backspace agora deleta um espaço por vez.
    3. No modo Normal, usar >> e << insere ou deleta 8 espaços. O mesmo
       ocorre ao se pressionar Ctrl-t e Ctrl-d no modo Insert. Isso porque
       'shiftwidth' não foi alterado.

   Para ter certeza que o Tab insere espaços, inicie uma nova linha, pressione
   "Tab" e escreva "hello". Volte para a parte em branco (antes de "hello") e
   delete alguns espaços com "x". Você vai notar que você está realmente
   deletando um único espaço por vez. 'listchars' não pode mais mostrar "T____"
   agora, ou algo está errado.

   = Espaços  - Caso 2 =
   ---------------------

   Deixando 'softtabstop' com o mesmo valor de 'tabstop':
       :set tabstop=8 softtabstop=8 shiftwidth=8 expandtab ~

    1. Pressionar Tab continua inserindo espaços em número equivalente ao
       que está configurado em 'tabstop'.
    2. Backspace agora deleta os 8 espaços de uma vez, como se estivesse
       deletando uma tab real.
    3. No modo Normal, usar >> e << insere ou deleta 8 espaços. O mesmo
       ocorre ao se pressionar Ctrl-t e Ctrl-d no modo Insert. Ou seja, é
       o mesmo comportamento que o da configuração anterior. Normal, pois
       'shiftwidth' não foi alterado.

   Pode fazer o teste anterior para certificar-se de que pressionar Tab ainda
   insere espaços em branco. 'listchars' deve continuar não mostrando "T____".


   = Espaços = Caso 3 =
   --------------------

   Configure desta maneira:
       :set tabstop=8 softtabstop=4 shiftwidth=4 expandtab ~

   O comportamento agora é:
    1. Pressionar Tab continua inserindo espaços em número equivalente ao
       que está configurado em 'tabstop', que agora é 4.
    2. Backspace agora deleta os 4 espaços, por causa do "softtabstop=4".
    3. No modo Normal, usar >> e << insere ou deleta 4 espaços. O mesmo
       occorre ao se pressionar Ctrl-t e Ctrl-d no modo Insert.

   = Espaços = Caso 4 =
   --------------------

   Mas (note o NOexpandtab):
       :set tabstop=8 softtabstop=4 shiftwidth=4 noexpandtab ~

   Agora, 'noexpandtab' não está habilitado, e portanto, pressionar <Tab>
   insere um Tab real (e não espaços no lugar do Tab). Se pressionar Tab, e
   'tab=8', um Tab terá largura de 8 colunas.

   Como você sabe, ">>", "<<", "Ctrl-t" e "Ctrl-d" são controlados por
   'shiftwidth'. Se 'shiftwidth=4', 4 espaços serão inseridos (ou deletados)
   com os comandos mencionados.

   Com a opção "list" e "listchairs" funcionando, pressione ">>" duas vezes.
   Você vai notar que ele se transforma em um Tab real. Isso porque "tabstop=8"
   e "shiftwidth=4", etão, 4 + 4 = 8. Se "tabstop=12", por exemplo, então
   pressionar ">>" 3 vezes se gera uma Tab real, porque 4 + 4 + 4 = 12.

   Isso tudo acontece porque 'softtabstop' tem precedência sobre 'tabstop'.
   Então, quando pressionamos, por exemplo, "Ctrl-t" uma vez, ele insere 4
   espaços, mas quando pressionamos "Ctrl-t" uma segunda vez, ele diz "Hmm,
   isso está igual a "largura" do 'tabstop', e então os 8 espaços são
   deletados e um Tab real é inserido. Quando usamos <Backspace>, "Ctrl-d" ou
   "<<", o processo inverso ocorre.


   = Misturando - Caso 5 =
   -----------------------

   Vamos deixar 'tabstop' igual 4, com 'expandtab' desabilitado:
       :set tabstop=4 softtabstop=4 shiftwidth=4 noexpandtab ~

    1. Agora, como 'tabstop' está igual 'shiftwidth' e 'expandtab', quando
       <Tab>, ">>" ou "Ctrl-t" for pressionado, uma Tab real será inserida
       pois o Vim notou que as configurações estão iguais. Quando as
       configurações estão iguais.

   NOTE que tabs reais e espaços antigos no arquivo continuam sendo o que eram.
   O que pode mudar é o tamanho das Tabs reais, mas não o fato de serem Tabs
   reais ou não. O que já era Tab real continua sendo Tab real, e o que era
   (grupos) de espaços continuam sendo (grupos) de espaços (grupos de espaços
   que por venturam tenham sido inseridos em lugar de Tabs reais).

   = Possíveis Escolhas =
   ======================

   = Hard Tabs (Tabs Reais) =
   --------------------------
   Quem prefere trabalhar com Tabs reais, uma boa escolha é deixar 'tabstop'
   igual 'shiftwidth', pois eles trabalharão de maneira consistente e
   homogênea. Espaços não serão usados.

   = Espaços em vez de Tabs Reais =
   --------------------------------
   Deixar 'softtabstop' igual 'shiftwidth' assegura que ">>", "<<",
   "Ctrl-t" e "Ctrl-d" adicionem e removam Tabs (não reais, pois agora é
   substituída por espaços) com o mesmo comportamento de se adicionar e deletar
   tabs pressionando a tecla <Tab> e <Backspace>. Ou seja, todos eles vão
   adicionar ou remover o mesmo número de espaços - vão funcionar de forma
   homogênea. Pode-se também, nesse caso (e alguns acham aconselhável), deixar
   'tabstop' com o mesmo valor de 'shiftwidth' e 'softtabstop'.

   -------------------------------------------------------------------------------

   = Notas Finais =
   ---------------------

   Saiba que o Vim permite configurar tudo isso de acordo com o 'filetype'. Por
   exemplo, é possível configurar que arquivos "html" utilizem 2 espaços no
   lugar do Tab, um arquivo em "C" utilize 4 espaços no lugar de um Tab, e
   ainda, quando um arquivo "bash" for editado, um Tab real de 6 colunas seja
   usado. Ou seja, quando o arquivo é aberto, o vim usa as configurações
   predefinidas automaticamente.

   Alguns exemplos.

   Vamos criar os diretórios necessários:
       mkdir --parents ~/.vim/after/ftplugin/ ~

   Para HTML:
   Criar o um arquivo chamado "html.vim" dentro do último diretório criado:
       vim ~/.vim/after/ftplugin/html.vim ~

   E coloque o seguinte conteúdo dentro do arquivo:
       set softtabstop=2 expandtab shiftwidth=2 ~


   Para CSS:
   Criar o arquivo css.vim, no mesmo diretório que do exemplo anterior:
       vim ~/.vim/after/ftplugin/css.vim ~

   E cole o seguinte conteúdo:
       set softtabstop=4 expandtab shiftwidth=4 ~


   Para "bash", com Hard Tabs:
       vim ~/.vim/after/ftplugin/bash.vim ~
   E cole:
       set tabstop=6 softtabstop=6 shiftwidth=6 noexpandtab ~


   = Dica final =
   --------------

   Se você optar por usar Espaços no lugar de tabs, há uma maneira de inserir
   Tabs reais sem ter que mudar temporariamente a configuração. Isto é
   conseguido inserindo-se caracteres não imprimíveis literalmente.

   No vim, isso é muito fácil. Basta pressionar "Ctrl-v" no modo Inserte, e
   então pressionar a tecla Tab em seguida. Passo-a-passo:

               vim --> abre o vim no terminal (poderia ser o gvim).
                 i --> entra no modo insert na posição onde está o cursor.
            Ctrl-v --> pressionar a combinação "ctrl-v". Vai aparecer um
                       caractere parecido com um "^". Neste momento, o Vim está
                       esperando você digitar o caractere que termina a
                       sequência, no nosso exemplo, um <Tab>.
             <Tab> --> pressione Tab.
     "hello world" --> escreva "hello world" por que esse é um encantamento que
                       garante que você aprenda o conteúdo. Sempre foi assim em
                       todas as linguagens, e essa é a razão. São palavras
                       mágicas.

   Como mesmo exemplo você poderia inserir um caractere <Enter> ou <Backspace>
   literalmente no texto.

   Referências:
   ------------

     No Vim:
       :help 'softtabstop'
       :help 'tabstop'
       :help 'shiftwidth'
       :help 'expandtab'

       http://vimcasts.org/

       http://vim.wikia.com/wiki/Indenting_source_code