G.4. Criação da documentação

G.4.1. Emacs/PSGML

O PSGML é o modo de editar documentos SGML mais comum e mais poderoso. Quando configurado de forma apropriada, permite utilizar o Emacs para inserir marcas e verificar a consistência da marcação. Também pode ser utilizado para HTML. Visite o página na Web do PSGML para baixar os arquivos, obter as instruções de instalação, e ver a documentação detalhada.

Existe um ponto importante a ser observado com relação ao PSGML: o autor assume que o diretório principal da DTD do SGML na máquina utilizada é /usr/local/lib/sgml. Se for utilizado /usr/local/share/sgml, como acontece nos exemplos deste capítulo, isto deve ser compensado, seja definindo a variável de ambiente SGML_CATALOG_FILES, ou personalizando a instalação do PSGML (o manual explica como fazer).

O que vem a seguir deve ser adicionado ao arquivo de ambiente ~/.emacs (ajustando os nomes dos caminhos conforme apropriado para o sistema utilizado):

; ********** for SGML mode (psgml)

(setq sgml-omittag t)
(setq sgml-shorttag t)
(setq sgml-minimize-attributes nil)
(setq sgml-always-quote-attributes t)
(setq sgml-indent-step 1)
(setq sgml-indent-data t)
(setq sgml-parent-document nil)
(setq sgml-default-dtd-file "./reference.ced")
(setq sgml-exposed-tags nil)
(setq sgml-catalog-files '("/usr/local/share/sgml/catalog"))
(setq sgml-ecat-files nil)

(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )

e no mesmo arquivo deve ser adicionada uma entrada para SGML na definição (existente) de auto-mode-alist:

(setq
  auto-mode-alist
  '(("\\.sgml$" . sgml-mode)
   ))

Atualmente, cada arquivo fonte SGML possui o seguinte bloco no final:

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->

Isto define vários parâmetros do modo de edição, mesmo que o arquivo ~/.emacs não esteja definido mas, por azar, se forem seguidas as instruções de instalação acima, então o caminho do catálogo não corresponde a este local na máquina utilizada. Por isso pode ser necessário desativar as variáveis locais:

(setq inhibit-local-variables t)

A distribuição do PostgreSQL inclui o arquivo de definições DTD analisado reference.ced. Ao utilizar o PSGML, acaba-se descobrindo que uma maneira confortável de trabalhar com os arquivos separados das partes do livro é inserindo uma declaração DOCTYPE apropriada ao editar. Por exemplo, ao se trabalhar com o fonte deste arquivo, que é um capítulo do apêndice, o documento pode ser especificado como uma instância do "appendix" do documento DocBook fazendo a primeira linha se parecer com:

<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.2//EN">

Isto permite que tudo que leia SGML o faça direito, e que o documento possa ser verificado pelo comando nsgmls -s docguide.sgml; mas esta linha precisa ser removida antes de ser gerado o conjunto completo da documentação.

G.4.2. Outros modos do Emacs

O GNU Emacs vem com um modo SGML diferente, que não é tão poderoso quanto o PSGML, mas que é menos confuso e mais leve. Oferece, também, realce da sintaxe (bloqueio de fonte), que pode ser muito útil.

Norm Walsh disponibiliza um modo principal do GNU Emacs para editar documentos DocBook, que também possui bloqueio de fonte e várias funcionalidades para reduzir a digitação.