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 a página na Web do PSGML para baixar os arquivos, obter as instruções de instalação, e ver a documentação detalhada.

Existe uma coisa importante a ser observada 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 desabilitar 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.