Padrões de Formatação — Dev's Café Didática

Este documento define os padrões obrigatórios de formatação e estrutura para todos os livros da biblioteca Dev's Café. Todos os contribuidores devem seguir estas regras para garantir consistência visual e editorial entre volumes.

1. Tecnologia de Produção

Compilador: pdflatex ou lualatex (preferido para suporte Unicode completo)
Classe base: book (para volumes completos) ou article (para capítulos isolados)
Codificação: UTF-8 obrigatório em todos os ficheiros .tex
Idioma padrão: Português (Portugal) via babel com opção portuguese

2. Estrutura de Ficheiros de um Livro

<slug-do-livro>/
├── main.tex              # Ficheiro principal (entrada do compilador)
├── metadata.tex          # Título, autor, versão, data
├── preambulo.tex         # Pacotes, configurações globais
├── capitulos/
│   ├── 00-introducao.tex
│   ├── 01-<topico>.tex
│   ├── 02-<topico>.tex
│   └── ...
├── assets/
│   ├── imagens/          # Figuras, diagramas (.pdf, .png, .jpg)
│   └── codigo/           # Ficheiros de código-fonte referenciados
├── bibliografia.bib      # Referências bibliográficas (BibTeX)
└── output/               # PDFs gerados (não versionar)

Regras de nomenclatura de ficheiros

Usar kebab-case em minúsculas: introducao-a-algebra.tex
Capítulos numerados com dois dígitos: 01-, 02-, ..., 10-, 11-
Sem espaços, acentos ou caracteres especiais nos nomes de ficheiro

3. Preâmbulo Padrão (`preambulo.tex`)

O preâmbulo base obrigatório é:

% === CODIFICAÇÃO E LÍNGUA ===
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[portuguese]{babel}

% === TIPOGRAFIA ===
\usepackage{lmodern}          % Fonte Latin Modern (padrão)
\usepackage{microtype}        % Melhora tipografia (hifenação, espaçamento)

% === LAYOUT ===
\usepackage[
  a4paper,
  top=3cm, bottom=3cm,
  left=3cm, right=2.5cm
]{geometry}
\usepackage{setspace}
\onehalfspacing               % Espaçamento 1.5 entre linhas

% === MATEMÁTICA ===
\usepackage{amsmath}
\usepackage{amssymb}
\usepackage{amsthm}

% === CÓDIGO-FONTE ===
\usepackage{listings}
\usepackage{xcolor}

% === GRÁFICOS E FIGURAS ===
\usepackage{graphicx}
\usepackage{float}
\usepackage{caption}
\usepackage{subcaption}

% === HIPERLINKS ===
\usepackage[
  colorlinks=true,
  linkcolor=devcafe-blue,
  urlcolor=devcafe-blue,
  citecolor=devcafe-gray
]{hyperref}

% === BIBLIOGRAFIA (biblatex + biber — motor moderno) ===
% IMPORTANTE: não usar \bibliographystyle + \bibliography (bibtex antigo)
\usepackage[
  backend=biber,
  style=authoryear,    % citações no texto: (Stewart, 2016)
  sorting=nyt,         % ordenação: nome → ano → título
  maxbibnames=3,
  giveninits=true,
  dashed=false,
  doi=true,
  isbn=false,
  url=true,
  urldate=comp,
  language=portuguese,
]{biblatex}
\addbibresource{bibliografia.bib}

% === CAIXAS DIDÁTICAS ===
\usepackage{tcolorbox}
\tcbuselibrary{most}

% === CABEÇALHOS E RODAPÉS ===
\usepackage{fancyhdr}

4. Paleta de Cores (Dev's Café)

Definir no preâmbulo:

\definecolor{devcafe-blue}{HTML}{2563EB}
\definecolor{devcafe-dark}{HTML}{1E293B}
\definecolor{devcafe-gray}{HTML}{64748B}
\definecolor{devcafe-light}{HTML}{F1F5F9}
\definecolor{devcafe-green}{HTML}{16A34A}
\definecolor{devcafe-orange}{HTML}{EA580C}
\definecolor{devcafe-red}{HTML}{DC2626}
\definecolor{devcafe-yellow}{HTML}{CA8A04}

5. Hierarquia de Títulos

Nível LaTeX	Uso
`\part{}`	Partes grandes do livro (opcional, para volumes longos)
`\chapter{}`	Capítulo principal
`\section{}`	Secção dentro do capítulo
`\subsection{}`	Subsecção
`\subsubsection{}`	Nível mais fino (usar com moderação)

Regra: Não saltar níveis. Nunca usar \subsubsection sem antes ter uma \subsection.

6. Caixas Didáticas (tcolorbox)

Usar as seguintes caixas padronizadas:

Definição

\begin{tcolorbox}[colback=devcafe-light, colframe=devcafe-blue,
  title={\faBook\ Definição: <nome>}, fonttitle=\bfseries]
Texto da definição.
\end{tcolorbox}

Exemplo

\begin{tcolorbox}[colback=white, colframe=devcafe-green,
  title={\faCode\ Exemplo}, fonttitle=\bfseries]
Conteúdo do exemplo.
\end{tcolorbox}

Atenção / Aviso

\begin{tcolorbox}[colback=yellow!10, colframe=devcafe-yellow,
  title={\faExclamationTriangle\ Atenção}, fonttitle=\bfseries]
Texto de aviso.
\end{tcolorbox}

Dica

\begin{tcolorbox}[colback=green!5, colframe=devcafe-green,
  title={\faLightbulb\ Dica}, fonttitle=\bfseries]
Texto da dica.
\end{tcolorbox}

Erro Comum

\begin{tcolorbox}[colback=red!5, colframe=devcafe-red,
  title={\faTimes\ Erro Comum}, fonttitle=\bfseries]
Descrição do erro comum.
\end{tcolorbox}

7. Blocos de Código

Configuração padrão do listings:

\lstset{
  basicstyle=\ttfamily\small,
  keywordstyle=\color{devcafe-blue}\bfseries,
  stringstyle=\color{devcafe-green},
  commentstyle=\color{devcafe-gray}\itshape,
  numberstyle=\tiny\color{devcafe-gray},
  numbers=left,
  stepnumber=1,
  frame=single,
  backgroundcolor=\color{devcafe-light},
  breaklines=true,
  breakatwhitespace=true,
  tabsize=2,
  showstringspaces=false,
  captionpos=b,
}

Usar o ambiente lstlisting com indicação de linguagem:

\begin{lstlisting}[language=Python, caption={Meu primeiro programa}]
print("Olá, mundo!")
\end{lstlisting}

8. Matemática

Fórmulas inline: $f(x) = x^2$
Fórmulas em bloco: ambiente equation ou align
Nunca usar $$...$$ (usar \[...\] ou equation)
Teoremas, Lemas e Proposições usar amsthm:

\newtheorem{teorema}{Teorema}[chapter]
\newtheorem{lema}[teorema]{Lema}
\newtheorem{proposicao}[teorema]{Proposição}
\newtheorem{corolario}[teorema]{Corolário}
\newtheorem{definicao}{Definição}[chapter]
\newtheorem{exemplo}{Exemplo}[chapter]

9. Imagens e Figuras

\begin{figure}[H]
  \centering
  \includegraphics[width=0.8\textwidth]{assets/imagens/nome-figura}
  \caption{Descrição clara da figura.}
  \label{fig:nome-figura}
\end{figure}

Sempre usar [H] para posicionamento fixo
Sempre incluir \caption e \label
Imagens vetoriais (PDF) preferidas; PNG/JPG aceitáveis com resolução mínima 150dpi
Nunca usar extensão no \includegraphics (o LaTeX resolve automaticamente)

10. Tabelas

Usar o pacote booktabs para tabelas profissionais:

\usepackage{booktabs}

\begin{table}[H]
  \centering
  \caption{Título da tabela.}
  \label{tab:nome}
  \begin{tabular}{lcc}
    \toprule
    Coluna A & Coluna B & Coluna C \\
    \midrule
    valor    & valor    & valor    \\
    \bottomrule
  \end{tabular}
\end{table}

Nunca usar \hline (usar \toprule, \midrule, \bottomrule)
Sempre incluir \caption e \label

11. Exercícios

Cada capítulo deve terminar com uma secção de exercícios:

\section*{Exercícios}
\begin{enumerate}
  \item Enunciado do exercício 1.
  \item Enunciado do exercício 2.
\end{enumerate}

Soluções (quando existentes) vão num apêndice ao final do livro.

12. Página de Rosto e Metadados

Definir em metadata.tex:

\title{
  {\large Dev's Café — Biblioteca Didática} \\[1em]
  {\Huge \textbf{<Título do Livro>}} \\[0.5em]
  {\large Volume X}
}
\author{<Nome do Autor> \\ \small Dev's Café}
\date{<Mês> de <Ano> \\ \small Versão <X.Y>}

13. Versionamento

Seguir Versionamento Semântico adaptado:

Versão	Significado
`0.x.y`	Rascunho / Em desenvolvimento
`1.0.0`	Primeira edição publicada
`1.1.0`	Novos capítulos ou secções
`1.0.1`	Correções de erros tipográficos/conteúdo
`2.0.0`	Revisão estrutural completa

14. Bibliografia e Citações (biblatex + biber)

Motor e pacote

Todos os livros usam biblatex com o motor biber (substituto moderno do bibtex). Nunca usar \bibliographystyle + \bibliography — esses são da API antiga.

Ciclo de compilação obrigatório

lualatex main   ← gera ficheiros auxiliares
biber main      ← processa as referências
lualatex main   ← incorpora as referências
lualatex main   ← resolve referências cruzadas finais

Impressão da bibliografia no documento

\printbibliography[
  heading=bibintoc,          % aparece no índice geral
  title={Referências Bibliográficas}
]

Comandos de citação

Comando	Resultado	Uso
`\cite{chave}`	(Autor, Ano)	Referência entre parênteses
`\textcite{chave}`	Autor (Ano)	Referência integrada no texto
`\parencite{chave}`	(Autor, Ano)	Equivalente a `\cite` no estilo authoryear
`\footcite{chave}`	nota de rodapé	Referência discreta
`\citeauthor{chave}`	Autor	Só o nome
`\citeyear{chave}`	Ano	Só o ano

Entradas no `.bib` — exemplos canónicos

@book{apelido2024titulo,
  author    = {Apelido, Nome},
  title     = {Título Completo do Livro},
  edition   = {2},
  publisher = {Editora},
  year      = {2024},
  address   = {Cidade},
  isbn      = {978-0-000-00000-0},
}

@article{apelido2024artigo,
  author  = {Apelido, Nome and Outro, Nome},
  title   = {Título do Artigo},
  journal = {Nome da Revista},
  year    = {2024},
  volume  = {10},
  number  = {2},
  pages   = {100--120},
  doi     = {10.xxxx/xxxxxx},
}

@online{site2024recurso,
  author  = {{Nome da Organização}},
  title   = {Título da Página},
  year    = {2024},
  url     = {https://exemplo.com/pagina},
  urldate = {2025-01-01},
}

Regras editoriais

O ficheiro .bib do livro reside em <slug-do-livro>/bibliografia.bib
Chaves de entrada: apelido + ano + palavrachave (ex: strang2016introduction)
Campos obrigatórios: author/editor, title, publisher/journal, year
Incluir doi sempre que disponível; omitir isbn (reduz ruído visual)
Recursos online: sempre incluir urldate (data de acesso)
Ordenação automática por autor → ano → título (sorting=nyt)

15. .gitignore para Livros LaTeX

Adicionar ao .gitignore do repositório:

*.aux
*.log
*.out
*.toc
*.lof
*.lot
*.fls
*.fdb_latexmk
*.synctex.gz
*.bbl
*.blg
*/output/*.pdf

Os PDFs finais publicados devem ser incluídos via GitHub Releases, não versionados directamente.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Padrões de Formatação — Dev's Café Didática

1. Tecnologia de Produção

2. Estrutura de Ficheiros de um Livro

Regras de nomenclatura de ficheiros

3. Preâmbulo Padrão (`preambulo.tex`)

4. Paleta de Cores (Dev's Café)

5. Hierarquia de Títulos

6. Caixas Didáticas (tcolorbox)

Definição

Exemplo

Atenção / Aviso

Dica

Erro Comum

7. Blocos de Código

8. Matemática

9. Imagens e Figuras

10. Tabelas

11. Exercícios

12. Página de Rosto e Metadados

13. Versionamento

14. Bibliografia e Citações (biblatex + biber)

Motor e pacote

Ciclo de compilação obrigatório

Impressão da bibliografia no documento

Comandos de citação

Entradas no `.bib` — exemplos canónicos

Regras editoriais

15. .gitignore para Livros LaTeX

FilesExpand file tree

STANDARDS.md

Latest commit

History

STANDARDS.md

File metadata and controls

Padrões de Formatação — Dev's Café Didática

1. Tecnologia de Produção

2. Estrutura de Ficheiros de um Livro

Regras de nomenclatura de ficheiros

3. Preâmbulo Padrão (preambulo.tex)

4. Paleta de Cores (Dev's Café)

5. Hierarquia de Títulos

6. Caixas Didáticas (tcolorbox)

Definição

Exemplo

Atenção / Aviso

Dica

Erro Comum

7. Blocos de Código

8. Matemática

9. Imagens e Figuras

10. Tabelas

11. Exercícios

12. Página de Rosto e Metadados

13. Versionamento

14. Bibliografia e Citações (biblatex + biber)

Motor e pacote

Ciclo de compilação obrigatório

Impressão da bibliografia no documento

Comandos de citação

Entradas no .bib — exemplos canónicos

Regras editoriais

15. .gitignore para Livros LaTeX

3. Preâmbulo Padrão (`preambulo.tex`)

Entradas no `.bib` — exemplos canónicos