O pacote
Um documento SGML consiste em um texto entre tags marcando o início e final de elementos.
Tags têm a forma <elemento> para iniciar o elemento e </elemento> para finalizá-la.
Existem alguns atalhos que se pode usar: <elemento/conteúdo/ especifica um elemento elemento com conteúdo conteúdo, mas o conteúdo não pode conter uma barra /. </> fecha o elemento atualmente aberto.
Muitos tipos de elementos iniciais de tags podem conter atributos; estes aparecem dentro do parêntese, e são separados do elemento por um espaço em branco. Os atributos permitidos em um elemento particular de inicio de tag são descritos ao longo do elemento.
Se você deseja incluir caracteres de marcação SGML (sinais <, > e &) como texto você deve se referir a eles pelo nome (isto é chamado uma referência a entidade na linguagem SGML). &nome; produz o caracter cujo nome é nome.
Alguns caracteres úteis são:
sinal de menor (esquerdo) <
sinal de maior (direito) >
&
símbolo de copyright ©
Você pode também usar &#número; para se referir ao caracter cujo número é número (em /usr/lib/mpage/ISO-Latin.1). número deve estar em valor decimal.
Cada capítulo inicia com a tag <chapt>, seguida do título do capítulo. O título pode conter texto marcado inline, mas sem referências cruzadas (veja ). O mesmo se aplica para um apêndice, exceto que ele inica com uma tag <appendix>.
O corpo de um capítulo ou um apêndice contém zero ou mais parágrafos, o primeiro deve ser indicado por uma tag <p> para distingui-lo do título, e então zero ou mais seções.
Uma seção inicia com <sect>, e tem uma estrutura parecida: título, opcionalmente mais parágrafos, e então opcionalmente subseções.
Subseções são <sect1>; existem também pequenas divisões <sect2>, <sect3> e <sect4>.
Parágrafos são incluídos com <p>. Algumas vezes a tag de início de parágrafo pode ser omitida, mas é obrigatória após <chapt>, <sect> e assim por diante. Não é necessário marcar o final de um parágrafo com </p>.
Parágrafos podem conter texto marcados inline (veja ) e também listas e exemplos ().
Há três tipos de listas:
<list> - lista ordinária (bola)
<enumlist> - lista numerada
<taglist> - lista com tags
Cada entrada em uma lista ordinária ou numerada é um item introduzido por <item>. Cada entrada em uma lista é uma ou mais tags <tag>s seguida de um <item>.
Não é necessário marcar o final de <tag> ou elementos <item>.
Todos os três tipos de lista vem em dois tipos, dependendo se você especificar o atributo compact (eg, <taglist compact>) ou não (eg, <enumlist>). A <tag> pode conter apenas texto marcado inline.
As versões compactas são usadas dentro de parágrafos. O
formatador não colocará "buracos" em torno da lista ou entre os
itens. Existe um problema com isto em HTML. O
formatador HTML não tenta, usando listas HTML com atributo
compact que gerou, mas nem todos os navegadores o
entendem corretamente.
As versões não compactas são entendidas como parágrafos. Cada entrada em tal lista pode conter mais que um parágrafo (denovo, o início do primeiro parágrafo não precisa ser marcado). A lista é separada do texto ao redor, e as entradas umas das outras por linhas em branco como é esperado que ocorra em quebra de parágrafo.
Exemplos - fragmentos de código multi linhas, scripts, e fragmentos similares de texto de computador são incluídos com <example> e finalizados com </example>.
O exemplo será formatado exatamente como ele é digitado, com espaços e novas linhas reproduzidas. Ele será mostrado em uma fonte fixa, normalmente a usada pelo estilo de caracteres <tt>, até mesmo se o formatador usa uma fonte proporcional. Qualquer identação necessária será incluída pelo formatador; o exemplo deve ser incluído iniciando na coluna da esquerda.
Exemplos podem conter texto com caracteres marcados mas não referências cruzadas ou elementos de estilo de caracteres <em>, <strong>, <package>, <prgn>, <file>, and <tt>. Veja .
Um exemplo não produz uma quebra de parágrafo; exemplos são considerados partes do parágrafo. Se um exemplo será um parágrafo então seu próprio parágrafo inicia tags que devem ser adicionadas como apropriadas.
Qualquer caracter de marcação SGML no exemplo deve ser referenciado pelo nome na forma usual de referência a entidade - veja . <example> não funciona como o ambiente TeX verbatim.
Texto ordinário (chamado "texto inline" neste documento) pode conter elementos para formação especial e referência cruzada. Texto inline aparece em capítulo, apêndice e títulos de seções, em aviso de copyright, dentro de parágrafos e em outros lugares parecidos.
Há vários elementos para determinar um significado especial de certas partes do texto. Para todos eles o fim do texto especial deve ser marcado explicitamente, usando uma tag final <element>, a tag final para fechamento de elementos </> ou barra / que finaliza a forma mais abreviada de marcação de elementos (veja ).
Indica que o texto contido é mais importante ou mais
significante que o resto.
Normalmente isto será representado por itálicos se
disponível, ou texto em negrito ou sublinhado, ou em
formato de texto puro colocando o texto entre
asteriscos como *este*.
Indica que o texto contido é ainda mais importante ou
ainda mais significante que o resto.
Tipicamente isto será representado por negrito se
disponível ou em formato texto plano com texto entre
asterisco como *este*.
Indica que o texto contido é uma variável metasintática.
Ou seja, ele é uma peça de objeto da sintaxe que é usado
para ter um valor real substituido.
Normalmente isto será representado por itálicos, em
formato texto plano com sinais de maior e menor como
<este>. Se muitas variáveis metasintáticas são
mostradas uma após as outras elas devem ser, cada uma,
seguida de seu próprio elemento <var>.
Indica que o texto contido é o nome de um pacote Debian.
Isto é normalmente feito usando uma fonte com largura
fixa; em formato texto plano, aspas são usadas em torno
do elemento.
Indica que o texto contido é o nome de um programa,
um arquivo conhecido (normalmente sem o caminho),
uma função ou alguma coisa parecida que tem um nome
no computador.
Em formatos de saída onde o sublinhado de caracter
e vários estilos de fontes estão disponíveis este é
normalmente representado com uma fonte de largura
fixa. Em texto plano, estes nomes não são especialmente
marcados, ocorre a introdução de aspas no fluxo do texto.
Indica que o texto contido é o caminho completo de um
arquivo, buffer, diretório, etc.
Isto é normalmente feito usando uma fonte com largura
fixa; em formato texto plano, aspas podem ser usadas
em torno do elemento.
Indica que o texto contido é um string geral que
vem de fora do computador. Ele deve ser usado para
comandos ou fragmentos de código que devem ser
mostrados na linha de comando ou palavras (veja
para uma alternativa), e assim
por diante. Ele é frequentemente necessário para
introduzir variáveis metasintáticas nestas strings,
em que elas devem fazer parte do elemento <tt>
ao invés de elementos dentro dela.
Isto é normalmente feito usando uma fonte com largura
fixa; em formatos texto plano aspas podem ser usadas
ao redor do elemento.
Produz uma "referência discreta" para identificação de
referência nomeada (see ). Isto deve ser
usada onde uma referência cruzada pode ser útil mas não
intrusiva, mas onde não é essencial.
Em formatos onde referências cruzadas podem ser feitas
não intrusivamente fazendo uma região do texto um
hyperlink sem introduzir textos inline este elemento
causará seu texto contido se tornar um hyperlink para
o alvo da referência cruzada. Em outros formatos
este elemento não tem nenhum efeito.
Há vários elementos para se introduzir referências cruzadas para outras partes do mesmo documento ou para outros documentos.
As referências cruzadas para documentos internos são baseadas no esquema de identificação de referências. Cada capítulo, apêndice, seção, subseção etc. Pode ter um atributo id passando sua referência de identificação - por exemplo <chapt id="spong"> especifica que o capítulo ou apêndice iniciado tem a referência de identificação spong. Esta referência de identificação pode então ser referida em outras partes do documento usando elementos especiais de referência cruzada.
O identificador de referência poderá também ser usado para gerar nomes de arquivos e referências para formatos tal como HTML que produzem diversos arquivos de saída; se nenhuma identificação de referência é especificada então o capítulo, apêndice ou números das seções serão usados. É uma boa idéia identificar no mínimo suas referências de apêndice ou capítulos assim aqueles nomes de arquivos não serão alterados se você alterar a ordem daqueles capítulos, seções ou apêndices em seu documento.
Isto gera uma referência cruzada dentro do mesmo documento
para o capítulo, apêndice ou seção com id refid.
O elemento <ref> não tem nenhum conteúdo;
o capítulo, apêndice ou número de seção e titulo e seu
número de página ou tudo que é apropriado para o formato
de saída será inserido no texto no ponto onde a tag
aparece.
Sintaticamente a referência cruzada é um substantivo de frase,
satisfatório para usuários como (veja <ref
id="...">) ou informações mais
adiante em <ref id="...">..
Gera uma referência cruzada para uma manpage para
name na seção seção. Esta tag
não possui nenhum conteúdo; texto descrevendo a página,
tipicamente name(section),
será inserido no ponto onde <manref>
aparece.
Indica que o texto contido é um endereço de email.
O conteúdo da tag deve ser simplesmente o texto do
endereço de email; marcação de estilo de caracteres e
referências cruzadas são proibidas. Normalmente a tag
final </email> não pode ser omitida, mas
ele pode ser deixado fora quando aparece em uma
<author> como o final de
<author>, implicado pelo inicio do próximo
elemento, implicando no final do endereço de email.
Em muitos formatos isto gerará uma referência cruzada
que pode (por exemplo) ser usada para enviar
endereço de e-mail para o endereço citado. Em outros
será simplesmente uma marcação para um texto especial,
incluindo sinais de maior e menor <
> em torno dele.
<ftpsite> indica que o conteúdo do
elemento é um nome DNS de uma site FTP anônimo, e
<ftppath> que é um caminho no site.
Ambos elementos não podem conter qualquer marcação
de estilo de caracteres ou referência cruzada.
Tipicamente ambos elementos serão feitos em fonte fixa;
se possível, o <ftppath> será feito em um
hyperlink funcional para o site <ftpsite>.
<ftppath> deve sempre ser
precedido por um <ftpsite> no mesmo capítulo,
ou apêndice, mas uma vez que um site foi nomeado
vários caminhos podem ser definidos.
<httpsite> indica que o conteúdo
do elemento é um nome DNS de um site HTTP, e
<httppath> que é o caminho naquele
site. Ambos elementos não podem conter qualquer
estilo de caracter ou referência cruzada.
Normalmente ambos elementos serão feitos em fonte fixa;
Se possível, <httppath> será feita em
um hyperlink funcional para os arquivos nomeados
no diretório mais recente.
<httpsite>.
<httppath> deve sempre ser procedida
de um <httpsite> no mesmo capítulo
ou apêndice, mas uma vez que o site foi nomeado
varios caminhos podem aparecer.
Gera uma referência cruzada para a URL com a
identificação id e usa o name
para ser mostrado no documento ao invés da id.
Esta tag não contém qualquer conteúdo.
Normalmente este elemento será criado em fonte fixa;
Se possível, id será feito em um hyperlink
funcional usando name como identificação.
Footnotes pode aparecer em muitos textos inline, e são indicados por <footnote>... </footnote>. O texto de footnote será removido e colocado em outro lugar (onde depende do formato), e troca com uma referência ou hyperlink para footnote.
O conteúdo do footnote deve conter um ou mais parágrafos; o início do primeiro parágrafo não precisa ser marcado explicitamente. Elementos de marcação inline como um estilo de caracter não fazem efeito no conteúdo do footnotes definido dentro dele - o footnote é um trecho limpo.
Footnote pode ser aninhado, mas é raramente uma boa idéia.
A primeira linha do documento deve ser
O documento deve iniciar com a tag <book> e finalizar com </book>.
Isto pode ser seguido de <title>, um ou mais tags <author>-<email>, e opcionalmente <version>. Cada uma destas é uma peça da marcação de texto inline - veja . A <version> pode também conter <date> que mostra a data e hora em que o documento foi gerado.
Então pode vir uma <abstract>, um aviso de <copyright>, e um marcador <toc>.
<abstract> contém um parágrafo simples que contém um resumo do documento.
A tag <copyright> contém um aviso de copyright (isto é usado, por exemplo, no rodapé de cada página HTML) seguida de um ou mais parágrafos, o primeiro deve ser indicado pela tag <p> para distingui-lo do sumário.
O marcador <toc> especifica que a tabela de conteúdo será produzida. A tag <toc> não contém nada no fonte SGML - seu conteúdo é gerado pelo sistema de processamento. A tag <toc> pode conter um atributo dizendo em detalhes como ele pode ser, por exemplo, <toc sect1> diz que as subseções devem ser incluídas, considerando que a tag <toc chapt> diz que somente capítulos e apêndices devem ser incluídos. Os valores permitidos são chapt, sect, sect1 e sect2.
Seguinte a estas partes vem o corpo do documento - um ou mais capítulos <chapt>, opcionalmente seguido de um ou mais apêndices <appendix>.
Não é necessário marcar o final dos elementos <title>, <author>, <version>, <abstract> e <copyright> - eles são automaticamente fechados no início do próximo elemento.
Debiandoc-SGML, incluindo este manual, é software livre; você pode redistribui-lo e/ou modifica-lo dentro dos termos da GNU General Public Licence como publicada pela Free Software Foundation; versão 2, ou qualquer outra versão futura (à sua escolha).
É distribuido com a intenção de que seja útil, mas sem nenhuma garantia; nem mesmo garantia implícita de comercialização ou adequação a um propósito particular. Veja a GNU General Public License para mais detalhes.
Uma cópia da GNU General Public License está disponível no seu sistema
Debian GNU/Linux, em