9.7. Imagens

Importante:

O suporte de imagem na documentação é um pouco experimental. Os mecanismos descritos aqui provavelmente não mudarão, mas isso não é garantido.

Para fornecer conversão entre diferentes formatos de imagem, o port graphics/ImageMagick deve estar instalado. Esse port não está incluído no meta port textproc/docproj e deve ser instalado separadamente.

Um bom exemplo do uso de imagens é o documento graphics/ImageMagick. Examine os arquivos nesse diretório para ver como esses elementos são usados ​​juntos. Crie formatos de saída diferentes para ver como o formato determina quais imagens são mostradas no documento renderizado.

9.7.1. Formatos de Imagem

Os seguintes formatos de imagem são suportados atualmente. Um arquivo de imagem será automaticamente convertido em bitmap ou imagem vetorial, dependendo do formato do documento de saída.

Estes são os formatos somente nos quais as imagens devem ser enviadas para o repositório de documentação.

EPS (Encapsulated Postscript)

Imagens com base principalmente em vetores, como diagramas de rede, linhas de tempo e similares, devem estar nesse formato. Estas imagens têm uma extensão .eps.

PNG (Portable Network Graphic)

Para bitmaps, como capturas de tela, use este formato. Essas imagens têm a extensão .png.

PIC (PIC graphics language)

PIC é uma linguagem para desenhar figuras baseadas em vetor simples usadas no utilitário pic(1). Essas imagens têm a extensão .pic.

SCR (SCReen capture)

Este formato é específico para capturas de tela da saída do console. O seguinte comando gera um arquivo SCR shot.scr do buffer de vídeo /dev/ttyv0:

# vidcontrol -p < /dev/ttyv0 > shot.scr

É preferível o formato PNG para capturas de tela porque o arquivo SCR contém texto sem formatação das linhas de comando para que possa ser convertido em uma imagem PNG ou um texto simples, dependendo do formato do documento de saída.

Use o formato apropriado para cada imagem. A documentação geralmente tem uma mistura de imagens EPS e PNG. O Makefile assegura que a imagem de formato correta seja escolhida dependendo do formato de saída usado. Não envie a mesma imagem ao repositório em dois formatos diferentes.

Importante:

O Projeto de Documentação pode eventualmente mudar para o formato SVG (Scalable Vector Graphic) para imagens vetoriais. No entanto, o estado atual das ferramentas de edição compatíveis com SVG torna isso inviável.

9.7.2. Localizações das Imagens

As imagens podem ser armazenados em um dos diversos locais abaixo, dependendo do documento e da imagem:

  • No mesmo diretório do documento em si, geralmente feito para artigos e pequenos livros que mantêm todos os arquivos em um único diretório.

  • Em um subdiretório do documento principal. Geralmente feito quando um livro grande usa subdiretórios separados para organizar capítulos individuais.

    Quando as imagens são armazenadas em um subdiretório do diretório do documento principal, o nome do subdiretório deve ser incluído em seus caminhos no Makefile e no elemento imagedata.

  • Em um subdiretório de doc/share/images nomeado após o documento. Por exemplo, as imagens do Handbook estão armazenadas em doc/share/images/books/handbook. Imagens que funcionam para várias traduções são armazenadas neste nível superior da árvore de arquivos da documentação. Geralmente, estas são imagens que podem ser usadas inalteradas em traduções não inglesas do documento.

9.7.3. Marcação em Imagem

As imagens são incluídas como parte de um mediaobject. O mediaobject pode conter outros objetos mais específicos. Estamos preocupados com dois, o imageobject e o textobject.

Inclua um imageobject e dois elementos textobject. O imageobject apontará para o nome do arquivo de imagem sem a extensão. Os elementos textobject contêm informações que serão apresentadas ao usuário, bem como, ou em vez da própria imagem.

Elementos de texto são mostrados ao leitor em várias situações. Quando o documento é exibido em HTML, elementos de texto são mostrados enquanto a imagem está sendo carregada ou se o ponteiro do mouse estiver sobre a imagem ou se um navegador somente texto estiver sendo usado. Em formatos como texto simples, onde os gráficos não são possíveis, os elementos de texto são mostrados em vez dos gráficos.

Este exemplo mostra como incluir uma imagem chamada fig1.png em um documento. A imagem é um retângulo com um A dentro dela:

<mediaobject>
  <imageobject>
    <imagedata fileref="fig1"/> 1
  </imageobject>

  <textobject>
    <literallayout class="monospaced">+---------------+ 2
|       A       |
+---------------+</literallayout>
  </textobject>

  <textobject>
    <phrase>A picture</phrase> 3
  </textobject>
</mediaobject>

1

Inclua um elemento imagedata dentro do elemento imageobject. O atributo fileref deve conter o nome do arquivo da imagem a ser incluída, sem a extensão. As folhas de estilo irão descobrir qual extensão deve ser adicionada ao nome do arquivo automaticamente.

2

O primeiro textobject contém um elemento literallayout, onde o atributo class é definido como monospaced. Esta é uma oportunidade para demonstrar habilidades artísticas em ASCII. Este conteúdo será usado se o documento for convertido em texto simples.

Observe como a primeira e a última linha do conteúdo do elemento literallayout aparecem ao lado das tags do elemento. Isso garante que nenhum espaço em branco seja incluído.

3

O segundo textobject contém um único elemento phrase. O conteúdo desta frase se tornará o atributo alt para a imagem quando este documento for convertido para HTML.

9.7.4. Entradas de Imagem no Makefile

As imagens devem estar listadas no Makefile na variável IMAGES. Esta variável deve conter os nomes de todas as imagens source. Por exemplo, se houver três figuras, fig1.eps, fig2.png, fig3.png, então o Makefile deve ter linhas como esta.

…
IMAGES= fig1.eps fig2.png fig3.png
…

ou

…
IMAGES=  fig1.eps
IMAGES+= fig2.png
IMAGES+= fig3.png
…

Novamente, o Makefile irá elaborar a lista completa de imagens necessárias para compilar o documento, você só precisa listar os arquivos de imagem que você forneceu.

9.7.5. Imagens e Capítulos em Subdiretórios

Tenha cuidado ao separar a documentação em arquivos menores em diretórios diferentes (consulte Seção 7.7.1, “Usando Entidades Gerais para Incluir Arquivos”).

Imagine que haja um livro com três capítulos e os capítulos sejam armazenados em seus próprios diretórios, chamados chapter1/chapter.xml, chapter2/chapter.xml e chapter3/chapter.xml. Se cada capítulo tiver imagens associadas, coloque essas imagens no subdiretório de cada capítulo (chapter1/, chapter2/, e chapter3/).

No entanto, fazer isso requer a inclusão dos nomes de diretório na variável IMAGES no Makefile, e a inclusão do nome do diretório no elemento imagedata no documento.

Por exemplo, se o livro tiver chapter1/fig1.png, então chapter1/chapter.xml deve conter:

<mediaobject>
  <imageobject>
    <imagedata fileref="chapter1/fig1"/> 1
  </imageobject></mediaobject>

1

O nome do diretório deve ser incluído no atributo fileref.

O Makefile deve conter:

…
IMAGES=  chapter1/fig1.png
…

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>.