# Guia de Estilo
:toc:
:toc-title: Seções
:sectnums:

Padrões gráficos e de linguagem adotados nesta tradução.

## Formatação

### Uso de maiúsculas em títulos

Somente a primeira letra do título das partes, capítulos e seções deve estar em maiúsculas
(além de nomes próprios ;-).

Padrão: +
*Aventuras aquáticas ao longo do Amazonas*

Fora do padrão: +
*Aventuras Aquáticas ao Longo do Amazonas*


### Uso de pontuação

#### Legendas de exemplos



### Código dentro do texto corrido

`Identificadores` de Python devem ser marcados no Asciidoc como `pass:[`monospace`]` (delimitado por crases, `chr(96)`, Unicode GRAVE ACCENT).

Nos identificadores `+__dunder__+`, é preciso colocar um par de `{plus}` dentro das crases, assim: `pass:[`+__dunder__+`]`.
Isso se aplica também a expressões compostas como `+complex.__float__+` que precisa ser escrita como `pass:[`+complex.__float__+`]`

Ver https://docs.asciidoctor.org/asciidoc/latest/text/literal-monospace/[literal monospace] na documentação do Asciidoctor.


### Usar atributos pré-definidos para caracteres especiais

O Asciidoctor tem uma série de atributos pré-definidos que são úteis para evitar conflitos de marcação.
Por exemplo, o caractere {plus} serve para marcar quebra de linha, e {cpp}
pode ser ainda mais complicado, então é melhor usar os atributos `pass:[{plus}]` e `pass:[{cpp}]`.

Lista completa: https://docs.asciidoctor.org/asciidoc/latest/attributes/character-replacement-ref/[Character Replacement Attributes Reference]


### Reiniciar numeração de exemplos e figuras por capítulo

Logo abaixo do título do capítulo, zere os atribuitos `:example-number:` e `:figure-number:`.

Exemplo de `cap06.adoc`:

++++
<pre>
[[ch_refs_mut_mem]]
== Referências, Mutabilidade, e Memória
:example-number: 0
:figure-number: 0
</pre>
++++

### Formatação de links externos

O título do recurso externo em língua estrangeira deve estar em itálico, assim:

https://fpy.li/15-47[_Programming TypeScript_]

Quando for interessante traduzir o título da página de destino,
a tradução deverá aparecer depois e fora do link, entre parêntesis, assim:

https://fpy.li/15-51[_Generics Considered Harmful_] (Genéricos considerados nocivos_)

O título original pode ficar em Title Case, a tradução deve começar com maíuscula e
usar maiúscula só para siglas e nomes próprios.

O tradutor usou esta convenção:

https://fpy.li/15-51["Generics Considered Harmful" (_Genéricos Considerados Nocivos_)]

Para transformar, no VS Code esta expressão regular funciona:

----
DE: "([^"]+)" \(_([^)]+)_\)\]
PARA: _$1_] ($2)
----


## Termos adotados

Os termos abaixo geram dúvidas sobre tradução:
se devem ser traduzidos ou não, e qual tradução adotar.
Estas foram as decisões que tomamos nesta tradução.

Quando o termo em inglês for adotado, faremos uma
opção de gênero do substantivo.
Ex.: o _framework_ (s.m.), a _thread_ (s.f.)

A opção será subjetiva, baseada no uso cotidiano na
bolha dev ao redor do autor.
Para manter a consistência, a opção de gênero está registrada
nos termos adotados em inglês na tabela.

Sempre que um desses termos aparecer pela primeira vez no livro,
o termo adotado deve ser seguido da alternativa no outro idioma,
para familiarizar a leitora com o vocabulário nos dois idiomas.

O termo em inglês deve ser sempre escrito em itálico. Se houver parênteses em torno do termo em inglês,
o parênteses também deve estar em itálico _(italic)_.

Exemplos:

Termo em português adotado::
    embutido _(built-in)_

Termo em inglês adotado::
    _cluster_ (agrupamento)

**Legenda**

[cols="1,10"]
|===
|✅| termo adotado
|❗| termo não adotado
|❓| não conhecemos uma boa tradução
|🔎| possíveis ocorrências para buscar e corrigir
|===


[cols="3,3,4"]
|===
|🇺🇸|🇧🇷|Observações
|❗ _abstract base class_ |✅ classe base abstrata| plural: classes base abstratas
|✅ _alias_ (s.m.)     |❗ apelido      |
|✅ _aliasing_ (s.m.)  |❗ apelidamento |
|✅ _array_ (s.m.)     |❗ arranjo      | 🔎 a array
|❗ _bitwise_          |✅ bit-a-bit    | 🔎 bit a bit
|❗ _built-in_         |✅ embutido     |
|✅ _cache_ (s.m.)     |❓              |
|✅ _caching_ (s.m.)   |❓              |
|❗ _call_ (verb)      |✅ invocar (executar uma função) | ex: "a função é invocada pelo pelo interpretador", 🔎 chamar 
|❗ _call_ (verb)      |✅ chamar (dar nome) | ex: "a função chamada `bla`"
|❗ _callable_         |✅ invocável | 🔎 chamável
|✅ _callback_ (s.f.)  |❗ função que trata o evento | 🔎 função de retorno
|❗ _closure_          |✅ clausura     | preserva variáveis livres no momento da definição da função
|✅ _cluster_ (s.m.)   |❓              | 🔎 agrupamento
|❗ _container_        |✅ o contêiner  | plural: contêineres
|❗ _contention_       |✅ disputa      |
|❗ _core_             |✅ núcleo       | "CPU de 8 núcleos"
|❗ _coroutine_        |✅ corrotina    |
|❗ _CPU bound_        |✅ limitado pela CPU |
|❗ _custom_           |✅ customizado  | 🔎 personalizado
|✅ _deadlock_ (s.m.)  |❗ impasse      |
|❗ _duck typing_      |✅ tipagem pato |
|❗ _evaluate_ (verb)  |✅ avaliar      | contraste com "analisar" (_parse_)
|❗ _evaluation_       |✅ avaliação    |
|❗ _factory_          |✅ fábrica      |
|❗ _forward reference_  |✅ referência futura  | 🔎 referência adiantada
|✅ _framework_ (s.m.) |❗ arcabouço    | 🔎 a framework
|❗ _Further Reading_  |✅ Para saber mais| título de seção (note: apenas 1ª letra maiúscula)
|✅ _future_ (s.m.)    |❓            |
|❗ _goose typing_     | ✅ tipagem ganso |
|✅ _hashable_ (adj.)  |❓            |
|✅ _hook_ (s.m.)      |❗gancho      |
|❗ _I/O bound_        | ✅ limitado por E/S |
|❗ _import time_      | ✅ momento da importação | 🔎  tempo de importação
|❗ _in place_        | ✅ internamente, interno | 🔎  no mesmo lugar
|❗ _keyword argument_ | ✅ argumento nomeado | 🔎 argumento de palavra-chave
|❗ _lock_             | ✅ trava  |
|❗ _loop_             | ✅ laço  | ex: laço `for`, laço de eventos, laço infinito
|❗ _match_ (s.m.)     | ✅ casamento | substantivo; aplica-se a `match/case` e `re.match`
|❗ _match_ (v.)       | ✅ casar | verbo; aplica-se a `match/case` e `re.match`
|✅ MRO (s.m.)  |❓ | Ordem de Resolução de Métodos (_Method Resolution Order_)
|✅ _offset_ (s.m.)    | ❗ deslocamento | 🔎 a offset
|❗ _override_         | ✅ sobrescrever | 🔎 sobrepor
|❗ _overload_         | ✅ sobrecarregar | 🔎 sobrepor
|❗ _overloading_      | ✅ sobrecarga |
|❗ _overloaded signatures_ |✅ assinaturas sobrecarregadas|
|❗ _parse_            |✅ analise (ou análise sintática) | contraste com "avaliar" (_evaluate_)
|✅ _parser_ (s.m.)    |❗ analisador sintático| 🔎 a parser
|❗ _pattern_          |✅ padrão      | aplica-se a `match/case` e `re.match`
|✅ _pattern matching_ (s.m.)|❗ casamento de padrões| ver. _match_
|❗ _performance_      |✅ desempenho      |
|❗ _query_            |✅ consulta        |
|❗ _queue_            |✅ fila            |
|❗ _receiver_         |✅ receptor        | 🔎 recebido, recipiente, destinatário
|❗ _return_ (flow control)  |✅ retorna | "A função retorna após 10s."
|❗ _return_ (value)         |✅ devolve | "A função devolve a lista de estudantes."
|❗ _reversed_ (operador)    |✅ reverso (ex.: `+__rmul__+`)  | 🔎 inverso, invertido
|❗ _reversed_ (ordem)    |✅ invertido  | "reversed(x) devolve uma lista invertida"
|❗ _S-expression_     |✅ expressão-S     |
|❗ _source code_      |✅ código-fonte    | 🔎 código fonte
|❗ _stack_            |✅ pilha           |
|❗ _statement_        |✅ instrução       |
|✅ _status_ (s.m.)    |❗ situação        |
|❗ _subject_          |✅ sujeito         | no contexto de _pattern matching_
|✅ _template_ (s.m.)  |❗ gabarito        | "o template"
|✅ _thread_ (s.f.)    |❓                 | "a thread"
|❗ _tuple_            |✅ tupla           | usar 🇧🇷 exceto menção específica à classe `tuple`
|❗ _type checker_     |✅ checador de tipos| 🔎 verificador de tipos(s)
|❗ _type hint_        |✅ dica de tipo    |
|❗ _type variable_    |✅ variável de tipo|
|❗ _type-driven development_|✅ desenvolvimento orientado a tipos|
|❗ _weak reference_|✅ referência fraca   |
|===


