Páginas compostas: figuras com rótulos

Esta página trata das figuras de uma página composta, ou do texto corrido, que põem palavras sobre a sua imagem. Como se escreve uma página composta está em Páginas compostas; os estilos de rótulo e os campos de rótulo de uma âncora, em Configuração › Páginas compostas.

#Figuras com rótulos

:::figure{resource="mapa-europa" slot="mapa"}
::label[OCÉANO ATLÁNTICO]{at="atlantico" style="mar"}
::label[**Madrid**]{at="madrid"}
::label[Mar Negro]{at="62% 48%"}
:::

:::figure{resource="…"} coloca um recurso, com a legenda e o número dele, como faz ::resource, e lista os rótulos que vão sobre a imagem: uma linha ::label[TEXTO]{…} por rótulo, com linhas em branco permitidas entre elas.

• at indica uma âncora do recurso (um ponto definido uma única vez sobre a imagem e compartilhado por todos os idiomas), ou dá um ponto em porcentagens da imagem, at="x% y%", para um rótulo sem âncora.
• style indica um estilo de rótulo e prevalece sobre o estilo da âncora.
• leader traça uma linha do rótulo até o ponto da âncora, e leader="none" a retira (veja Linhas de chamada, legendas de mapa e símbolos).
• O texto entre colchetes é Markdown em linha: negrito, itálico, chips e símbolos escritos com :icon.

Uma figura funciona tanto no texto corrido quanto dentro de um bloco. Os rótulos dela são desenhados sobre a imagem como texto e vão aonde a figura for: uma coluna, um flutuante, um bloco girado ou reduzido pela escada de ajuste (os passos que fazem o conteúdo caber), uma página dupla. Quando falta o ::: de fechamento de uma figura, a primeira linha que não é um rótulo nem está em branco encerra a figura, e o Postext a aponta como contêiner não fechado.

#As palavras próprias de uma figura

Um recurso guarda uma imagem, as âncoras dela e um único conjunto de palavras, mas cada edição de um livro precisa das próprias palavras. Uma figura pode definir o próprio alt, a própria caption e a própria note, na linha de abertura ou em linhas próprias, e eles substituem os do recurso nas páginas desse arquivo:

:::figure{resource="relieve" alt="Mapa de relieve de Varenia"}
::caption[Relieve de **Varenia**, con sus tres cordilleras]
::note[Fuente: levantamiento de 1932]
::label[Mar de Sal]{at="mar"}
:::

• Como atributos da linha de abertura, alt, caption e note recebem um texto curto entre aspas. As linhas ::alt[…], ::caption[…] e ::note[…] recebem o texto entre colchetes, que pode conter Markdown em linha e \\ para uma quebra de linha, como a legenda e a nota de um recurso. Uma linha prevalece sobre o atributo de mesmo nome; as linhas ficam entre os rótulos, com linhas em branco se quiser.
• O que a figura não define continua sendo o do recurso. Um valor vazio não diz nada: caption="" tira a legenda, alt="" marca a imagem como decorativa.
• As palavras substituem as do recurso no capítulo em que estão escritas: a diagramação, o texto alternativo de todas as saídas e o PDF marcado as usam, e o próprio recurso não muda. Num capítulo, um recurso tem um só conjunto de palavras, o da primeira figura: se uma figura posterior do mesmo recurso trouxer outros textos, eles não aparecem, e o Postext gera o aviso figureWordsShared. Uma cópia reduzida que precise de legenda própria usa um segundo recurso que aponte para o mesmo arquivo de imagem. Ao contrário de um rótulo, a legenda não é associada caractere a caractere ao Markdown; sourceAt responde a um clique nela como faz com a legenda de um recurso.

#Como um rótulo é composto

• Onde. Um rótulo fica no ponto da âncora, dado como fração da imagem inteira; se a imagem for recortada na área segura ou composta menor, o rótulo acompanha o desenho. O align da âncora indica que lado do rótulo fica no ponto, e verticalAlign, que borda fica na altura dele. start e end seguem a direção do próprio rótulo: em árabe, start é a borda direita. rotate gira o rótulo em torno do ponto, no sentido horário e em qualquer ângulo: um rio ao longo do curso, uma serra na diagonal.
• Aparência. O style do rótulo, ou então o da âncora, indica um estilo de rótulo (veja Configuração › Páginas compostas); sem estilo, o rótulo usa a fonte do texto do corpo. O halo traça o contorno das letras por baixo do preenchimento; a placa (background) preenche a caixa em volta do texto, alargada por padding.
• Ajuste. Se a âncora tem width, o rótulo quebra entre palavras dentro dessa medida, nunca no meio de uma palavra. Quando uma palavra é mais larga que a medida, o rótulo inteiro é composto menor, até o minScale do estilo; um rótulo que ainda assim não cabe é desenhado com a palavra mais larga cortada. Sem width, o rótulo fica numa só linha, exceto onde quebra com \\, como numa legenda.
• Texto. O texto entre colchetes é Markdown em linha, composto como uma legenda: negrito, itálico, chips, marcações de destaque, referências, fórmulas em linha. Um nome de várias palavras é um único rótulo, qualquer que seja a ordem das palavras em cada idioma: ::label[OCEANO ATLÂNTICO] e ::label[ATLANTIC OCEAN] ficam na mesma âncora. Rótulos da direita para a esquerda são compostos da direita para a esquerda; os chineses e japoneses quebram entre caracteres.
• Saídas. O canvas, o PDF, o visualizador HTML, o EPUB de layout fixo e o Folio desenham os rótulos. Numa página da direita para a esquerda, o rótulo fica onde a imagem o mostra.
• Vertical. Com writingMode: 'vertical-rl' na âncora (ou no estilo de rótulo dela), o rótulo é composto como uma página vertical: os caracteres em pé, em células uma sob a outra, as colunas da direita para a esquerda, as palavras latinas e os números longos virados de lado e os números curtos numa só célula. Então width é uma parte da altura da imagem, o comprimento de uma coluna, e um rótulo chinês ou japonês se reparte em mais colunas. align corre ao longo da coluna (start é a ponta de cima), verticalAlign através das colunas (top é a primeira, a da direita), e rotate continua girando o rótulo. Na página espelhada de um livro da direita para a esquerda, o rótulo se lê do mesmo jeito, de cima para baixo nas colunas e em pé, no mesmo ponto da imagem (desde o postext 1.40).
• Verificações. Um rótulo que continua mais largo do que a medida no minScale do estilo gera labelOverflow; dois rótulos cujas linhas se tocam geram labelOverlap no posterior. As duas coisas são verificadas em cada edição; assim, uma tradução com palavras mais longas mostra onde precisa de espaço. A paleta de uma parte (:::part{palette="…"}) recolore os rótulos das páginas dela como faz com as legendas. A verificação de contraste mede um rótulo sobre a placa ou, se não houver, sobre o halo; um rótulo posto diretamente sobre a imagem é ignorado, porque o fundo dele é a imagem. O preflight de impressão também verifica os rótulos: letra pequena em cores de processo, tintas e distância ao refile.
• Numa página dupla. Uma figura que atravessa a lombada de uma página dupla (um bloco com crossGutter: true) pinta uma metade em cada página; um rótulo que entrasse na faixa da medianiz seria cortado pela dobra e não se leria em nenhuma das duas. Esse rótulo desliza na horizontal até a borda da faixa, do lado em que fica o ponto da âncora, e mantém a altura; um ponto exatamente sobre a lombada fica na primeira página, como um bloco. Uma âncora com gutter: 'cross' mantém o lugar, para um título posto nas duas páginas. As bordas externas da folha não são tocadas: um rótulo que passa do refile é cortado como a imagem. Desde o postext 1.43.

#Linhas de chamada, legendas de mapa e símbolos

Desde o postext 1.48, um rótulo pode ficar afastado do que nomeia, um rótulo pode ser a legenda de um mapa, e um rótulo, uma legenda ou uma célula de tabela pode trazer símbolos.

Linhas de chamada. O labelAt de uma âncora afasta o rótulo do seu ponto (um nome no mar, uma nota na margem de um esquema), e uma linha de chamada liga o rótulo de volta ao ponto. A aparência é o leader do estilo de rótulo (veja Configuração › Estilos de rótulo); o Markdown só a liga ou desliga para um rótulo:

:::figure{resource="relieve" slot="mapa"}
::label[Sierra Alta]{at="peaks" leader}
::label[Lago Verde]{at="lake" leader="none"}
:::

leader com qualquer valor que não seja none, false ou off liga a linha; sem o atributo, decide o leader da âncora e, sem nenhum dos dois, um rótulo afastado do seu ponto recebe uma linha quando o estilo dele tem leader. A nota de um bloco também pode apontar para um lugar da imagem: um conector cuja ponta indica uma âncora da imagem (anchor: 'lake').

Rótulos de várias linhas. :::label{at="…" style="…"} … :::, dentro de um :::figure, escreve um rótulo linha por linha: cada linha não vazia da origem é uma linha do rótulo; assim, uma legenda de mapa ou um endereço não precisa de \\ no fim de cada linha. O primeiro ::: fecha o rótulo, e o seguinte, a figura. ::label[…] continua sendo um rótulo de uma linha, quebrado só onde diz \\.

Legendas de mapa. Um rótulo num estilo com kind: 'legend' é a legenda de um mapa: cada linha é uma fila, e o símbolo que abre uma fila fica numa coluna da largura do símbolo mais largo; assim, as palavras das filas começam numa mesma borda. Escreva o símbolo no começo de cada linha:

:::figure{resource="mapa-politico" slot="mapa"}
:::label{at="key" style="key"}
:icon[País]{glyph="■" color="country"} País
:icon[Capital]{glyph="⊙" font="Noto Sans Math"} Capital
:icon[Cidade]{resource="town-mark" size="0.55"} Cidade
:icon[Fronteira]{line="dashed" color="border"} Fronteira
:::
::label[:icon[Capital]{glyph="⊙" font="Noto Sans Math"} Varena]{at="capital"}
:::

Símbolos. :icon[alt]{…} põe um pequeno símbolo na linha, apoiado na linha de base:

O primeiro de resource, glyph e line que estiver escrito decide o tipo; sem nenhum deles, a diretiva continua sendo texto. O texto entre colchetes é o texto alternativo do símbolo: os leitores de tela, o PDF marcado e o texto alternativo da imagem o leem no lugar do símbolo, e um símbolo com colchetes vazios é decoração. Os símbolos são lidos nos rótulos de figura e em todos os trechos de um recurso: legendas, notas e células de tabela. Nesta versão, não são lidos no texto corrido, nos títulos nem nos textos de design.

#labelAnchorUnknown

O at de um ::label indica uma âncora que o recurso da figura não tem. O rótulo não é desenhado; o EPUB refluível continua listando-o, e o texto alternativo da imagem o menciona. O aviso traz o recurso, a âncora, as âncoras que o recurso tem (known), o idioma, a página e o intervalo de origem do texto do rótulo. Corrija o id da âncora, adicione a âncora ao recurso ou posicione o rótulo com at="x% y%".

No painel Verificações do Sandbox, o aviso leva ao rótulo no painel Texto, e o botão com o alfinete abre as âncoras da imagem com esse nome pronto para colocar: um clique na imagem adiciona a âncora.

#anchorUnlabelled

Uma âncora do recurso da figura tem um estilo de rótulo, mas nenhum ::label da figura fica nela neste idioma: o mapa tem espaço para uma palavra que esta edição deixa de fora. É uma nota; o postext check a lista como info. Âncoras sem estilo, como a de um personagem de quadrinhos, não são apontadas. O aviso traz o recurso, a âncora, o estilo dela, o idioma, a página e o intervalo de origem da figura. Escreva o rótulo no Markdown deste idioma ou tire o estilo da âncora.

No painel Verificações, o aviso leva à figura no painel Texto, e o botão com o alfinete abre as âncoras da imagem nessa âncora.

#labelOverflow

Um rótulo continua mais largo do que a width da âncora na menor escala que o estilo de rótulo permite (minScale): é desenhado nessa escala e ultrapassa a medida. O aviso traz o recurso, o texto do rótulo, a âncora (nenhuma, se o rótulo foi posto com porcentagens), a largura que lhe foi dada, a escala atingida, o idioma, a página e o intervalo de origem do texto do rótulo. É verificado em cada edição; assim, um idioma de palavras mais longas transborda onde outro não. Alargue a width da âncora, encurte a palavra no Markdown desta edição ou baixe o minScale do estilo de rótulo. Um rótulo chinês ou japonês quebra entre caracteres e não transborda assim. Desde o postext 1.39.

#labelOverlap

Dois rótulos da mesma figura se tocam; num rótulo com placa, conta a placa. O aviso fica no rótulo posterior, na ordem em que foram escritos, com o texto do primeiro rótulo anterior que ele toca e quantos rótulos anteriores toca no total. O teste usa a caixa própria de cada linha, girada com o rótulo, de modo que o espaço ao lado de uma linha curta fica livre, e deixa duas linhas se invadirem em até um oitavo da altura de uma linha. É verificado em cada edição. Mova uma das âncoras, estreite a width de um rótulo para que ele quebre ou encurte as palavras no Markdown desta edição. No painel Verificações do Sandbox, o botão do alfinete abre as âncoras da imagem na âncora do rótulo. Desde o postext 1.39. Com overlap: 'allow' numa âncora, ou no estilo de rótulo dela, um rótulo que o original imprime tocando os vizinhos (um mapa denso) sai da verificação, e nenhum par de que ele faça parte é reportado. Desde o postext 1.42. As zonas avoid de uma imagem contam como os símbolos de um mapa: retângulos desenhados sobre os pontos e os ícones do mapa, no modo Zonas a evitar das marcas da imagem, em frações da imagem. Um rótulo que invade uma delas é reportado do mesmo modo, com symbol 2 no lugar de outro rótulo (withSymbol nos dados), e overlap: 'allow' deixa um rótulo fora das duas verificações. Desde o postext 1.42.

#figureWordsShared

Uma :::figure define palavras (alt, caption ou note) para um recurso cujas palavras uma figura anterior do mesmo capítulo já definiu, e elas são diferentes. As páginas mostram as palavras da primeira figura e omitem estas. O aviso traz o recurso, as palavras omitidas e o intervalo de origem da primeira delas; uma figura posterior que não dá palavras próprias não é problema. Dê à figura um recurso próprio: um segundo recurso que aponte para o mesmo arquivo de imagem, com legenda, número e âncoras próprios. No painel Verificações do Sandbox, ele aparece em Figuras. Desde o postext 1.42.