💾 Archived View for geminiprotocol.net › docs › pt-PT › gemtext.gmi captured on 2023-11-04 at 11:51:31. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2023-09-08)
-=-=-=-=-=-=-
A forma mais comum de disponibilizar conteúdo textual no Gemini não se processa como no Gopher, onde se usa apenas texto simples. O Gemini usa uma linguagem de formatação simplificada (markup) chamada "Gemtext" (que é codificada com o tipo MIME não oficial text/gemini). Este documento pretende ser uma introdução básica a essa linguagem de formatação, que tem algumas semelhanças, ainda que superficiais, com o Markdown. Quem já conhecer o Markdown terá a sua aprendizagem mais facilitada, ainda que o Gemtext seja um pouco diferente em alguns aspetos.
Depois de ter lido este documento, poderá refrescar a sua memória consultando:
Nos documentos Gemtext, o texto escreve-se com "linhas longas". O seu editor (ou você) não deve inserir carateres de nova linha, mesmo que a linha exceda 80 carateres de comprimento. Essa tarefa de quebra de linha é deixada para o cliente Gemini, que as quebrará de acordo com o tamanho disponível no ecrã do dispositivo e de acordo com a preferência do utilizador. Desta forma, o conteúdo do Gemtext terá sempre uma boa aparência, sendo facilmente lido em monitores de desktop, ecrãs de laptop, tablets e smartphones.
Note que, embora os clientes Gemini dividam as linhas de texto longas de forma a caberem no ecrã, as linhas mais curtas não são unidas, contrariamente ao que acontece com Markdown, HTML ou LaTeX. Isso significa que, por exemplo, listas bullet ou poemas com linhas deliberadamente curtas sejam exibidas corretamente, sem que o autor tenha que fazer qualquer trabalho extra ou sem que o cliente tenha necessidade de reconhecer e lidar corretamente com esse tipo de conteúdo.
Na maior parte dos casos que configuram uma escrita puramente descritiva, a chamada escrita do "dia-a-dia", usar-se-á uma linha por parágrafo.
Note que as linhas em branco são reproduzidas de forma literal pelos clientes, ou seja, se existirem duas ou três linhas em branco entre os parágrafos, o leitor verá no ecrã essas mesmas duas ou três linhas em branco.
Como acontece no Gopher (e ao contrário do Markdown ou do HTML), no Gemtext os links para outros documentos devem ser colocados numa linha própria. Significa que não é possível transformar, no meio de uma frase, uma palavra ou um conjunto de palavras num link. Levará algum tempo até que este conceito seja interiorizado, mas, em contrapartida, os links serão extremamente fáceis de encontrar no documento. Outra vantagem é o facto dos clientes poderem estilizá-los de forma diferente (para, por exemplo, evidenciar o protocolo usado, ou para exibir o nome de domínio, ajudando os utilizadores na hora de decidir se desejam ou não seguir os links), sem que isso signifique interferir na legibilidade do conteúdo textual real.
As linhas de link têm o seguinte aspeto:
=> https://example.com A cool website => gopher://example.com An even cooler gopherhole => gemini://example.com A supremely cool Gemini capsule => sftp://example.com
Ou seja:
Nos exemplos acima mostrados, todos os URLs e descrições estão bem alinhados, porque o autor foi zeloso. Mas o Gemini não se importa com esse facto, e isso também pode ser o pretendido:
=>https://example.com A cool website =>gopher://example.com An even cooler gopherhole => gemini://example.com A supremely cool Gemini capsule => sftp://example.com
O Gemtext suporta três níveis de títulos (headings). Os títulos estão limitados a uma única linha e começam com um, dois ou três símbolos #, seguidos por um espaço obrigatório:
# Título de nível 1 ## Título de nível 2 ### Título de nível 3
Esta é a única sintaxe de título suportada. Sublinhar os títulos usando os símbolos - ou =, como no Markdown, não terá nenhuma consequência.
Apresentar os títulos de uma forma especial é algo que os clientes podem fazer opcionalmente. Muitos clientes, ao reconhecê-los, usarão uma fonte maior ou uma cor diferente, ou algum outro tipo de estilo. Outros há que os tratarão apenas como linhas de texto normais, exibindo-os desse modo. Esse comportamento é desejável, uma vez que os títulos não devem ser usados para controlar a aparência do conteúdo do documento. A sua função é a de fornecer informações semânticas importantes sobre a estrutura do conteúdo. Alguns clientes usarão os títulos para gerar automaticamente um índice analítico que apresentarão ao utiizador, o que pode ser útil para navegar em documentos extensos. O software de geraração de feeds Atom ou RSS pode usar os títulos para nomear os posts do gemlog.
O Gemtext tem suporte para listas não ordenadas. Os items numa lista escrevem-se numa única linha longa, que começa com o símbolo *, seguido por um caratere de espaço obrigatório:
Esta é a única sintaxe de lista suportada. Usar - em vez de *, como no Markdown, não terá nenhum efeito. Listas hierarquizadas não são suportadas.
Apresentar os items de uma lista de uma forma especial é algo que os clientes podem fazer opcionalmente. Alguns clientes vão tratá-los como qualquer outra linha de texto. A única razão pela qual eles são definidos, é para que os clientes mais avançados possam substituir o * por um símbolo de marcador de aparência mais agradável e, no caso dos items da lista serem muito longos, quebrá-los em várias linhas, de forma a que caibam no ecrã do dispositivo. As linhas posteriores à primeira podem ser indentadas usando o mesmo espaço do símbolo de marcador. Contudo, esta é apenas uma subtileza tipográfica.
O Gemtext suporta blocos de citação. O conteúdo citado é escrito numa única linha longa, que começa com o caractere >:
> Gemtext supports blockquotes. The quoted content is written as a single long line, which begins with a single > character
Apresentar os blocos de citação de uma forma especial é algo que os clientes podem fazer opcionalmente. Alguns clientes tratá-los-ão como qualquer outra linha de texto. A exemplo do que acontece com os items de uma lista, os blocos de citação são definidos estritamente para permitir uma tipografia mais agradável em clientes com mais potencialidades.
O Gemtext foi projetado de forma a poder ser facilmente analisado e renderizado. Ele é processado pelos clientes através da análise e renderização de uma linha de cada vez, independentemente de quaisquer linhas que estejam antes ou depois. Os clientes inspecionam os primeiros carateres da linha para verificar se encontram os símbolos =>, #, *, ou outros.
Uma linha começada por ```(ou seja, com três acentos graves de crase) indica ao cliente que ele deve alternar entre o modo de análise normal e o "modo pré-formatado". No modo pré-formatado, os clientes não ligam aos símbolos de formatação que normalmente identificam links, títulos ou quaisquer outras formatações. As linhas são exibidas exatamente como estão escritas. Outra diferença reside no facto dos clientes, no modo pré-formatado, usarem uma fonte de largura fixa, ao passo que no texto comum usam fontes de largura variável. Assim, um par de linhas ``` apresenta um resultado visual muito semelhante às tags <pre> e </pre> em HTML.
O texto pré-formatado pode ser usado para incluir arte ASCII, código-fonte ou conteúdo semelhante num documento Gemtext, evitando-se, dessa forma, que os clientes interpretem as linhas como contendo títulos, itens de lista, entre outros. O texto pré-formatado pode também ser usado para escrever documentos como este, que contém exemplos de sintaxe Gemtext - os exemplos de sintaxe acima mostrados não são interpretados pelo cliente, como normalmente aconteceria, uma vez que eles estão renderizados no modo pré-formatado.
Qualquer conteúdo que exista após os carateres ``` de uma linha, que colocam o modo de linha pré-formatada a *on* (ou seja, a primeira, terceira, quinta, etc., linhas alternadas num documento), pode ser tratado como "texto alternativo" para o conteúdo pré-formatado. Normalmente, esse conteúdo não é visível para o utilizador, mas ele pode ser indexado pelos motores de pesquisa e pode ser lido pelos leitores de ecrã, de modo a que o utilizador decida se deve ser lido em voz alta (no caso da arte ASCII provavelmente não, mas no caso do código-fonte talvez deva ser). De momento, não existem convenções estabelecidas para a formatção de texto alternativo.