9.6. Elementos In-line

9.6.1. Realçando Informação

Para enfatizar uma palavra ou frase em particular, use emphasis. Isso pode ser apresentado em itálico ou negrito, ou pode ser falado diferentemente com um sistema de conversão de texto em fala.

Não há uma maneira de mudar a apresentação da ênfase no documento, não existe um equivalente a b e i do HTML . Se as informações apresentadas forem importantes, considere apresentá-las em important em vez de emphasis.

Exemplo 9.19. Exemplo de emphasis

Uso:

<para>&os; is without doubt <emphasis>the</emphasis>
  premiere &unix;-like operating system for the Intel
  architecture.</para>

Aparência:

FreeBSD is without doubt the premiere UNIX®-like operating system for the Intel architecture.


9.6.2. Siglas

Muitos termos de computador são siglas, palavras formadas a partir da primeira letra de cada palavra em uma frase. Os acrônimos são marcados com elementos acronym. É útil para o leitor quando um acrônimo é definido no primeiro uso, como mostrado no exemplo abaixo.

Exemplo 9.20. Exemplo acronym

Uso:

<para>Request For Comments (<acronym>RFC</acronym>) 1149
  defined the use of avian carriers for transmission of
  Internet Protocol (<acronym>IP</acronym>) data.  The
  quantity of <acronym>IP</acronym> data currently
  transmitted in that manner is unknown.</para>

Aparência:

Request For Comments (RFC) 1149 defined the use of avian carriers for transmission of Internet Protocol (IP) data. The quantity of IP data currently transmitted in that manner is unknown.


9.6.3. Citações

Para citar texto de outro documento ou fonte, ou para denotar uma frase que é usada de forma figurada, use quote. A maioria das tags de marcação disponíveis para texto normal também está disponível em quote.

Exemplo 9.21. Exemplo quote

Uso:

<para>However, make sure that the search does not go beyond the
  <quote>boundary between local and public administration</quote>,
  as <acronym>RFC</acronym> 1535 calls it.</para>

Aparência:

However, make sure that the search does not go beyond the boundary between local and public administration, as RFC 1535 calls it.


9.6.4. Teclas, Botões do Mouse e Combinações

Para se referir a uma tecla específica no teclado, use keycap. Para se referir a um botão do mouse, use mousebutton. E para se referir a combinações de pressionamentos de teclas ou cliques do mouse, coloque todos eles em keycombo.

keycombo tem um atributo chamado action, que pode ser um dos click, double-click, other, press, seq, ou simul. Os dois últimos valores indicam se as teclas ou botões devem ser pressionados em sequência ou simultaneamente.

As folhas de estilo adicionam automaticamente quaisquer símbolos de conexão, como +, entre os nomes das chaves, quando agrupados em keycombo.

Exemplo 9.22. Exemplos de Teclas, Botões do Mouse e Combinações

Uso:

<para>To switch to the second virtual terminal, press
  <keycombo action="simul"><keycap>Alt</keycap>
    <keycap>F1</keycap></keycombo>.</para>

<para>To exit <command>vi</command> without saving changes, type
  <keycombo action="seq"><keycap>Esc</keycap><keycap>:</keycap>
    <keycap>q</keycap><keycap>!</keycap></keycombo>.</para>

<para>My window manager is configured so that
  <keycombo action="simul"><keycap>Alt</keycap>
    <mousebutton>right</mousebutton>
  </keycombo> mouse button is used to move windows.</para>

Aparência:

To switch to the second virtual terminal, press Alt+F1.

To exit vi without saving changes, type Esc : q !.

My window manager is configured so that Alt+right mouse button is used to move windows.


9.6.5. Aplicativos, Comandos, Opções e Citações

Ambos os aplicativos e comandos são frequentemente utiilzados ao escrever uma documentação. A distinção entre eles é que um aplicativo é o nome de um programa ou conjunto de programas que preenche uma tarefa específica. Um comando é o nome do arquivo de um programa que o usuário pode digitar e executar em uma linha de comando.

Muitas vezes é necessário mostrar algumas das opções que um comando pode ter.

Finalmente, muitas vezes é útil listar um comando com seu número de seção do manual, no formato command(number) que é comum em manuais Unix.

Marque nomes de aplicações com application.

Para listar um comando com seu número de seção do manual (que deve ser utilizado com maior frequência), o elemento DocBook é citerefentry. Isto irá conter mais dois elementos, refentrytitle e manvolnum. O conteúdo de refentrytitle é o nome do comando, e o conteúdo do manvolnum é a seção da página de manual.

Isso pode ser trabalhoso para escrever e assim uma série de entidades gerais foram criadas para tornar esse processo mais fácil. Cada entidade assume o formato &man.manual-page.manual-section;.

O arquivo que contém essas entidades está em doc/share/xml/man-refs.ent e pode ser referenciado usando este FPI:

PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"

Portanto, a introdução à documentação do FreeBSD geralmente incluirá isto:

<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [

<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
%man;

…

]>

Use command para incluir um nome de comando in-line, mas mostre como algo que o usuário deve digitar.

Use option para marcar as opções que serão passadas para um comando.

Ao se referir ao mesmo comando várias vezes nas proximidades, é preferível usar a notação &man.command.section; para marcação a primeira referência e use command para marcar as referências subsequentes. Isso faz com que a saída gerada, especialmente HTML, apareça visualmente melhor.

Exemplo 9.23. Exemplo de Aplicações, Comandos e Opções

Uso:

<para><application>Sendmail</application> is the most
  widely used Unix mail application.<para>

<para><application>Sendmail</application> includes the
  <citerefentry>
    <refentrytitle>sendmail</refentrytitle>
    <manvolnum>8</manvolnum>
  </citerefentry>, &man.mailq.1;, and &man.newaliases.1;
  programs.</para>

<para>One of the command line parameters to <citerefentry>
    <refentrytitle>sendmail</refentrytitle>
    <manvolnum>8</manvolnum>
  </citerefentry>, <option>-bp</option>, will display the current
  status of messages in the mail queue.  Check this on the command
  line by running <command>sendmail -bp</command>.</para>

Aparência:

Sendmail é o aplicativo de email Unix mais utilizado.

O Sendmail inclui o os programas sendmail(8), mailq(1), e o newaliases(1).

Um dos parâmetros da linha de comando para o sendmail(8), -bp, exibirá o status atual das mensagens no fila de email. Verifique isso na linha de comando executando sendmail -bp.


Nota:

Observe como a notação &man..section; é mais fácil de ser seguida.

9.6.6. Arquivos, Diretórios, Extensões, Nomes de Dispositivo

Para se referir ao nome de um arquivo, um diretório, uma extensão de arquivo ou um nome de dispositivo, use filename.

Exemplo 9.24. Exemplo filename

Uso:

<para> O código fonte do Handbook em inglês é encontrada em
  <filename>/usr/doc/en_US.ISO8859-1/books/handbook/</filename>.
  O arquivo principal é chamado <filename>book.xml</filename>.
  Há também um <filename>Makefile</filename> e vários arquivos com a extensão <filename>.ent</filename>.</para>

<para><filename>kbd0</filename> é o primeiro teclado detectado
  pelo sistema e aparece em
  <filename>/dev</filename>. </para>

Aparência:

O código fonte do Handbook em inglês é encontrada em /usr/doc/en_US.ISO8859-1/books/handbook/. O arquivo principal é chamado book.xml. Há também um Makefile e vários arquivos com a extensão .ent.

kbd0 é o primeiro teclado detectado pelo sistema e aparece em /dev.


9.6.7. Nome dos Ports

Extensão FreeBSD:

Estes elementos fazem parte da extensão do FreeBSD ao DocBook, e não existem no DocBook DTD original.

Para incluir o nome de um programa da Coleção de Ports do FreeBSD no documento, use a tag package. Como a Coleção de Ports pode ser instalada em qualquer local, inclua apenas a categoria e o nome do port; não inclua /usr/ports.

Por padrão, package refere-se a um pacote binário. Para se referir a um port que será compilado a partir do código fonte, configure o atributo role para port.

Exemplo 9.25. Exemplo de package

Uso:

<para>Instale o pacote binário <package>net/wireshark</package> para
  visualizar o tráfego de rede.</para>

<para><package role="port">net/wireshark</package> também pode ser
  compilado e instalado pela Coleção de Ports.</para>

Aparência:

Instale o pacote binário net/wireshark para visualizar o tráfego de rede.

O net/wireshark também pode ser compilado e instalado pela Coleção de Ports.


9.6.8. Hosts, Domínios, Endereços IP, Usuário, Grupo e Outros Itens do Sistema

Extensão FreeBSD:

Estes elementos fazem parte da extensão do FreeBSD ao DocBook, e não existem no DocBook DTD original.

Informações para itens do sistema estão marcadas com systemitem. O atributo class é usado para identificar o tipo específico de informação mostrada.

class="domainname"

O texto é um nome de domínio, como FreeBSD.org ou ngo.org.uk. Não há nenhum componente de nome de host.

class="etheraddress"

O texto é um endereço Ethernet MAC, expresso como uma série de números hexadecimais de 2 dígitos separados por dois pontos.

class="fqdomainname"

O texto é um nome de domínio FQDM, com ambos nome de domínio e hostname.

class="ipaddress"

O texto é um endereço de IP.

class="netmask"

O texto é uma máscara de rede, que pode ser expressa igual a um IP, uma sequência hexadecimal ou como um / seguido por um número (notação CIDR).

class="systemname"

Com class="systemname", as informações marcadas são o nome do host simples, como freefall ou wcarchive.

class="username"

O texto é um nome de usuário, como root.

class="groupname"

O texto é um grupo, como wheel.

Exemplo 9.26. Exemplos systemitem

Uso:

<para>The local machine can always be referred to by the
  name <systemitem class="systemname">localhost</systemitem>, which will have the IP
  address <systemitem class="ipaddress">127.0.0.1</systemitem>.</para>

<para>The <systemitem class="domainname">FreeBSD.org</systemitem>
  domain contains a number of different hosts, including
  <systemitem class="fqdomainname">freefall.FreeBSD.org</systemitem> and
  <systemitem class="fqdomainname">bento.FreeBSD.org</systemitem>.</para>

<para>When adding an <acronym>IP</acronym> alias to an
  interface (using <command>ifconfig</command>)
  <emphasis>always</emphasis> use a netmask of
  <systemitem class="netmask">255.255.255.255</systemitem> (which can
  also be expressed as
  <systemitem class="netmask">0xffffffff</systemitem>).</para>

<para>The <acronym>MAC</acronym> address uniquely identifies
  every network card in existence.  A typical
  <acronym>MAC</acronym> address looks like
  <systemitem class="etheraddress">08:00:20:87:ef:d0</systemitem>.</para>

<para>To carry out most system administration functions
  requires logging in as <systemitem class="username">root</systemitem>.</para>

Aparência:

A máquina local sempre pode ser referenciada pelo nome localhost, que terá o endereço IP 127.0.0.1.

O domínio FreeBSD.org contém vários hosts diferentes, incluindo freefall.FreeBSD.org e bento.FreeBSD.org.

Ao adicionar um alias de IP a uma interface (usando ifconfig) sempre use uma máscara de rede de 255.255.255.255 (que também pode ser expressa como 0xffffffff).

O endereço MAC identifica exclusivamente todas as placas de rede existentes. Um endereço MAC típico se parece com 08:00:20:87:ef:d0.

Para executar a maioria das funções de administração do sistema, é necessário efetuar login como root.


9.6.9. Identificadores Uniformes de Recursos (URIs)

Ocasionalmente, é útil mostrar um Identificador de Recurso Uniforme (URI) sem torná-lo um hiperlink ativo. O elemento uri torna isso possível:

Exemplo 9.27. Exemplo uri

Uso:

<para>Esta URL é mostrada apenas como texto:
  <uri>https://www.FreeBSD.org</uri>. Não é criado um link.</para>

Aparência:

Esta URL é mostrada apenas como texto: https://www.FreeBSD.org. Não é criado um link.


Para criar links, consulte Seção 9.8, “Links”.

9.6.10. Endereços de Email

Os endereços de email são marcados como elementos email. No formato de saída HTML, o texto marcado se torna um hiperlink para o endereço de email. Outros formatos de saída que suportam hiperlinks também podem tornar o endereço de email em um link.

Exemplo 9.28. Exemplo de Hiperlink com email

Uso:

<para> Um endereço de email que não existe, como
  <email>notreal@example.com</email>, pode ser usado como um
  exemplo </para>

Aparência:

Um endereço de email que não existe, como , pode ser usado como exemplo.


Uma extensão específica do FreeBSD permite configurar o atributo role para nolink para evitar a criação do hiperlink para o endereço de email.

Exemplo 9.29. Exemplo de email Sem Hiperlink

Uso:

<para> Às vezes, o link para um endereço de email como
  <email role="nolink">notreal@example.com</email> não é
  desejado.</para>

Aparência:

Às vezes, o link para um endereço de email como não é desejado.


9.6.11. Descrevendo Makefiles

Extensão FreeBSD:

Estes elementos fazem parte da extensão do FreeBSD ao DocBook, e não existem no DocBook DTD original.

Existem dois elementos para descrever partes de Makefiles, buildtarget e varname.

buildtarget identifica um destino de compilação exportado por um Makefile que pode ser fornecido como um parâmetro para o make. varname identifica uma variável que pode ser definida (no ambiente, na linha de comando com o make, ou dentro do Makefile) para influenciar o processo.

Exemplo 9.30. Exemplo de buildtarget e varname

Uso:

<para>Two common targets in a <filename>Makefile</filename>
  are <buildtarget>all</buildtarget> and
  <buildtarget>clean</buildtarget>.</para>

<para>Typically, invoking <buildtarget>all</buildtarget> will
  rebuild the application, and invoking
  <buildtarget>clean</buildtarget> will remove the temporary
  files (<filename>.o</filename> for example) created by the
  build process.</para>

<para><buildtarget>clean</buildtarget> may be controlled by a
  number of variables, including <varname>CLOBBER</varname>
  and <varname>RECURSE</varname>.</para>

Aparência:

Dois targets comuns em um Makefile são all e clean.

Normalmente, invocar all irá reconstruir o aplicativo, e invocar clean removerá os arquivos temporários (.o por exemplo) criados pelo processo de compilação.

clean pode ser controlado por várias de variáveis, incluindo CLOBBER e RECURSE.


9.6.12. Texto Literal

O texto literal, ou texto que deve ser inserido na íntegra, é frequentemente necessário na documentação. Este é um texto extraído de outro arquivo ou que deve ser copiado exatamente como mostrado na documentação em um outro arquivo.

Na maioria das vezes, programlisting será suficiente para denotar este texto. Mas programlisting nem sempre é apropriado, particularmente quando você quer incluir uma parte de um arquivo in-line com o resto do parágrafo.

Nestes casos, use literal.

Exemplo 9.31. Exemplo literal

Uso:

<para>The <literal>maxusers 10</literal> line in the kernel
  configuration file determines the size of many system tables, and is
  a rough guide to how many simultaneous logins the system will
  support.</para>

Aparência:

A linha maxusers 10 no arquivo de configuração do kernel determina o tamanho de muitas tabelas do sistema e é um guia aproximado de quantos logins simultâneos o sistema suportará.


9.6.13. Mostrando Itens que o Usuário Deve Preencher

Haverá diversos momentos em que o usuário irá ver o que fazer, ou será referenciado a um arquivo ou linha de comando, mas não poderá simplesmente copiar o exemplo fornecido. Em vez disso, eles precisam fornecer algumas informações.

replaceable é projetado para essa eventualidade. Use isso dentro de outros elementos para indicar partes do conteúdo desse elemento que o usuário deve substituir.

Exemplo 9.32. Exemplo de replaceable

Uso:

<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>

Aparência:

% man command

replaceable pode ser usado em diversos elementos, incluindo literal. Este exemplo também mostra que o replaceable deve estar apenas em torno do conteúdo que o usuário está destinado a fornecer. O outro conteúdo deve ser deixado de lado.

Uso:

<para>The <literal>maxusers <replaceable>n</replaceable></literal>
  line in the kernel configuration file determines the size of many system
  tables, and is a rough guide to how many simultaneous logins the system will
  support.</para>

<para>For a desktop workstation, <literal>32</literal> is a good value
  for <replaceable>n</replaceable>.</para>

Aparência:

A linha maxusers n no arquivo de configuração do kernel determina o tamanho de muitas tabelas do sistema e é um guia aproximado de quantos logins simultâneos o sistema suportará.

Para uma estação de trabalho, 32 é um bom valor para n.


9.6.14. Mostrando Botões GUI

Os botões apresentados por uma interface gráfica do usuário são marcados com guibutton. Para tornar o texto mais parecido com um botão gráfico, colchetes e espaços não separáveis ​​são adicionados em volta do texto.

Exemplo 9.33. Exemplo guibutton

Uso:

<para>Edit the file, then click
  <guibutton>[&nbsp;Save&nbsp;]</guibutton> to save the
  changes.</para>

Aparência:

Edite o arquivo e clique em [ Salvar ] para salvar as alterações.


9.6.15. Citações de Erros do Sistema

Erros de sistema gerados pelo FreeBSD são marcados com errorname. Isso indica o erro exato que aparece.

Exemplo 9.34. Exemplo errorname

Uso:

<screen><errorname>Panic: cannot mount root</errorname></screen>

Aparência:

Panic: cannot mount root

All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.