Pular para o conteúdo principal

Guias

Esta seção é escrita à mão e versionada; a Referência e as páginas de Testes são geradas a cada build. Os guias explicam como usar e como interpretar o que o gerador mostra.

Trilhas de leitura​

Você quer…Comece porDepois
escrever o primeiro programaComeçarReferência de palavras-chave
entender o que o compilador faz com seu códigoArquiteturaMapeamento para C
confiar nos números e nas evidênciasComo lerTestes
portar para outro compilador ou SOPortabilidadeMatriz de compatibilidade
manter ou publicar a documentaçãoPublicaçãoBuild e CI

O que está em cada guia​

A documentação em números​

CamadaComo é produzidaO que garante
Guiasescrita manual, versionadaexplicação e contexto
Referênciaextração estática do códigonomes, expansões, guards, usos
Testesextração dos casos em discoentradas, saídas, negativos, avisos
Projetoimportação de docs/ e READMEhistórico, decisões e relatórios
Internosextração de tools/teststranspilador, harness e scripts
# reconstruir o site do zero
python3 -m venv .venv
.venv/bin/python -m pip install -r tools/documentacao/requirements.txt
cd website && npm ci && npm run build

Como os guias evitam promessas vazias​

Cada afirmação sobre comportamento aponta para uma página gerada, um teste ou um documento datado. Quando não há execução registrada, o texto diz isso explicitamente — por exemplo, MSVC é avaliado, não “suportado”. Se um guia contradizer o código, o código e a página gerada vencem, e o guia deve ser corrigido.

Perguntas frequentes​

Por onde começo se nunca usei BASICGOL?​

Comece por Começar: instale um compilador C11, rode make, escreva o programa mínimo e compile. Só depois avance para o caminho M1.

#include <basicgol.h>

INICIO
ESCREVAL("ola, mundo");
FIM

Qual é a diferença entre “Guias”, “Referência” e “Projeto”?​

Guias explicam o uso; a Referência é gerada do código atual; Projeto preserva especificação, decisões e relatórios históricos. Uma página de referência descreve o que o fonte faz agora; um relatório descreve o que foi executado em uma fase.

Preciso ler a especificação para programar?​

Não para começar. A referência e os guias bastam para o uso diário. A especificação é útil quando você precisa saber por que uma construção existe, qual é o contrato de erro ou se algo está fora do escopo.

Onde encontro exemplos prontos?​

Em Exemplos, com fontes versionados e saídas douradas quando existem. Eles também são compilados por make exemplos.

make exemplos

Os guias são atualizados automaticamente?​

Não. Eles são escritos à mão e copiados para o build. O gerador atualiza a referência, os testes, os exemplos e a importação de docs/; se um guia ficar desatualizado, ele deve ser corrigido no próprio arquivo.

Como sugiro uma correção na documentação?​

Abra um pull request alterando o guia em website/manuais/ ou o contrato em tools/documentacao/contratos.json, rode o gerador e inclua o resultado de npm run build na descrição. O build trata links quebrados como erro.

python3 tools/gerar_documentacao.py --strict
cd website && npm run build