Capítulo 13. Configuração do Editor

Esta tradução pode estar desatualizada. Para ajudar com as traduções, acesse a ferramenta de traduções do FreeBSD.

Ajustar a configuração do editor de texto pode tornar o trabalho nos arquivos da documentação mais rápido e fácil, além de ajudar os documentos a ficarem em conformidade com as diretrizes do projeto.

13.1. Vim

Instale o editors/vim, ou editors/vim-console, em seguida siga as instruções em Configuração. Usuários mais avançados podem usar um linter mais adequado como o Ale que também pode atuar como um Protocolo de Servidor de Idiomas do Vim.

13.1.1. Uso

Os escritores de páginas de manuais podem usar os seguintes atalhos de teclado para reformatar:

  • Pressione P para reformatar parágrafos ou texto selecionado no modo Visual.

  • Pressione T para substituir grupos de oito espaços por um tab.

Um linter chamado Vale foi adicionado para verificar erros gramaticais e cosméticos nos documentos. O Vale possui suporte para diversos editores e IDEs.

O Vale já é instalado como uma dependência do textproc/docproj meta-port. Caso contrário, instale textproc/vale com:

$ pkg install vale

Instale o Ale para intergrar o textproc/vale com o editors/vim.

% mkdir -p ~/.vim/pack/vendor/start
% git clone --depth 1 https://github.com/dense-analysis/ale.git ~/.vim/pack/vendor/start/ale

Os usuários que estão usando gerenciadores de plug-in no editors/vim não precisam dos passos acima e devem seguir as instruções do próprio gerenciador de plug-in para instalar o Ale.

Neste momento devido a um bug no Vale é necessário copiar a configuração do Vale para o diretório home. Considerando que o repositório foi clonado em ~/doc da seguinte forma:

% cp -R ~/doc/.vale* ~/

13.1.2. Configuração

Edite o ~/.vimrc, adicionando estas linhas ao final do arquivo:

~/.vimrc
if has("autocmd")
  au BufNewFile,BufRead *.adoc call Set_ADOC()
  au BufNewFile,BufRead *.[1-9] call Set_MAN()
endif " has(autocmd)

function Set_Highlights()
  "match ExtraWhitespace /^\s* \s*\|\s\+$/
  return 0
endfunction " Set_Highlights_Adoc()

function Set_Highlights_MAN()
  highlight default link OverLength ErrorMsg
  match OverLength /\%71v.\+/
  return 0
endfunction " Set_Highlights_MAN()

function ShowSpecial()
  setlocal list listchars=tab:>>,trail:*,eol:$
  hi def link nontext ErrorMsg
  return 0
endfunction " ShowSpecial()

function Set_COMMON()
  setlocal number
  setlocal shiftwidth=2
  setlocal tabstop=8
  setlocal softtabstop=2
  setlocal formatprg="fmt -p"
  setlocal autoindent
  setlocal smartindent
  call ShowSpecial()
  call Set_Highlights()
  return 0
endfunction " Set_COMMON()

function Set_ADOC()
  setlocal syntax=asciidoc
  setlocal filetype=asciidoc
  call Set_COMMON()
  return 0
endfunction " Set_ADOC()

function Set_MAN()
  setlocal syntax=man
  setlocal filetype=man
  setlocal textwidth=70
  " Rewrap paragraphs
  noremap P gqj
  " Replace spaces with tabs
  noremap T :s/        /\t/<CR>
  call Set_COMMON()
  call Set_Highlights_MAN()
  return 0
endfunction " Set_Man()

let g:ale_fixers = {
\   '*': ['remove_trailing_lines', 'trim_whitespace'],
\}
let g:ale_linters = {
\   'asciidoc': ['vale'],
\}
let g:ale_fix_on_save = 1

A configuração acima removerá automaticamente a linha final, o espaço final e vários espaços que podem exibir alterações indesejadas adicionais na saída do git diff. Nesses casos, mencione isso adequadamente no log de commit.

13.2. Emacs

Instale-o a partir de editors/emacs ou editors/emacs-devel.

13.2.1. Validação

O modo nxml do Emacs usa esquemas NG relax compacto para validar o XML. Um esquema NG relax compacto para a extensão do FreeBSD para DocBook 5.0 está incluído no repositório de documentação. Para configurar o modo nxml para validar usando este esquema, crie ~/.emacs.d/schema/schemas.xml e adicione estas linhas ao arquivo:

~/.emacs.d/schema/schemas.xml
<locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
  <documentElement localName="section" typeId="DocBook" />
  <documentElement localName="chapter" typeId="DocBook" />
  <documentElement localName="article" typeId="DocBook" />
  <documentElement localName="book" typeId="DocBook" />
  <typeId id="DocBook" uri="/usr/local/share/xml/docbook/5.0/rng/docbook.rnc" />
</locatingRules>

13.2.2. Revisão Automatizada com Flycheck e Igor

O pacote Flycheck está disponível no Emacs Lisp Package Archive da Milkypostman (MELPA). Se a MELPA ainda não estiver nos repositórios de pacotes do Emacs, ele pode ser adicionado executando

(add-to-list 'package-archives '("melpa" . "http://stable.melpa.org/packages/") t)

Adicione a linha ao arquivo de inicialização do Emacs (qualquer um deles, ~/.emacs, ~/.emacs.el, ou ~.emacs.d/init.el) para tornar esta alteração permanente.

Para instalar o Flycheck, execute

(package-install 'flycheck)

Crie um verificador Flycheck para textproc/igor executando

(flycheck-define-checker igor
  "FreeBSD Documentation Project sanity checker.

See URLs https://www.freebsd.org/docproj/ and
http://www.freshports.org/textproc/igor/."
  :command ("igor" "-X" source-inplace)
  :error-parser flycheck-parse-checkstyle
  :modes (nxml-mode)
  :standard-input t)

  (add-to-list 'flycheck-checkers 'igor 'append)

Novamente, adicione essas linhas ao arquivo de inicialização do Emacs para tornar as mudanças permanentes.

13.2.3. Configurações Específicas da Documentação do FreeBSD

Para aplicar configurações específicas para o projeto de documentação do FreeBSD, crie o arquivo .dir-locals.el no diretório raiz do repositório de documentação e adicione estas linhas ao arquivo:

;;; Directory Local Variables
;;; For more information see (info "(emacs) Directory Variables")

((nxml-mode
  (eval . (turn-on-auto-fill))
  (fill-column . 70)
  (eval . (require 'flycheck))
  (eval . (flycheck-mode 1))
  (flycheck-checker . igor)
  (eval . (add-to-list 'rng-schema-locating-files "~/.emacs.d/schema/schemas.xml"))))

13.3. nano

Instale o aplicativo partir de editors/nano ou editors/nano-devel.

13.3.1. Configuração

Atualmente não há arquivo de highlight de sintaxe adoc/asciidoc com distribuição nano. Então vamos criar um do zero e usar um editor para criar um novo arquivo ou adicionar linhas no ~/.nanorc com este conteúdo:

~/.nanorc
syntax "asciidoc" "\.(adoc|asc|asciidoc)$"
# main header
color red "^====+$"
# h1
color red "^==[[:space:]].*$"
color red "^----+$"
# h2
color magenta "^===[[:space:]].*$"
color magenta "^~~~~+$"
# h4
color green "^====[[:space:]].*$"
color green "^\^\^\^\^+$"
# h5
color brightblue "^=====[[:space:]].*$"
color brightblue "^\+\+\+\++$"
# attributes
color brightgreen ":.*:"
color brightred "\{[a-z0-9]*\}"
color red "\\\{[a-z0-9]*\}"
color red "\+\+\+\{[a-z0-9]*\}\+\+\+"
# Paragraph Title
color yellow "^\..*$"
# source
color magenta "^\[(source,.+|NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]"
# Other markup
color yellow ".*[[:space:]]\+$"
color yellow "_[^_]+_"
color yellow "\*[^\*]+\*"
color yellow "\+[^\+]+\+"
color yellow "`[^`]+`"
color yellow "\^[^\^]+\^"
color yellow "~[^~]+~"
color yellow "'[^']+'"
color cyan "`{1,2}[^']+'{1,2}"
# bullets
color brightmagenta "^[[:space:]]*[\*\.-]{1,5}[[:space:]]"
# anchors
color brightwhite "\[\[.*\]\]"
color brightwhite "<<.*>>"
# trailing whitespace
color ,blue "[[:space:]]+$"
# multiples of eight spaces at the start a line
# (after zero or more tabs) should be a tab
color ,blue "^([TAB]*[ ]{8})+"
# tabs after spaces
color ,yellow "( )+TAB"
# highlight indents that have an odd number of spaces
color ,red "^(([ ]{2})+|(TAB+))*[ ]{1}[^ ]{1}"

Processe o arquivo para criar guias incorporadas:

% perl -i'' -pe 's/TAB/\t/g' ~/.nanorc

13.3.2. Uso

Especifique opções úteis adicionais ao executar o editor:

% nano -AKipwz -T8 _index.adoc

Usuários do csh(1) podem definir um alias em ~/.cshrc para automatizar estas opções:

alias nano "nano -AKipwz -r 70 -T8"

Depois que o alias é definido, as opções serão adicionadas automaticamente:

% nano _index.adoc

Última alteração em: 9 de março de 2024 por Danilo G. Baio