Documentação Oficial do Raku

Uma versão HTML dessa documentação disponível em https://docs.perl6.org/. Que é a versão recomendada.

Também disponível uma ferramenta de linha de comando: "p6doc".

(Se está acessando pelo GitHub, a maioria dos documentos não serão exibidos corretamente, pois estão escritos em Raku Pod6 mas o GitHub assume que são Perl Pod.)

README em outras línguas

• README em alemão

• README em chinês

• README em italiano

• README em inglês

• README em francês

• README em espanhol

• README em japonês

• README em neerlandês

Instalar p6doc

Este módulo está disponivel no ecosistema de módulos do Raku. Use:

$ zef install p6doc

para instalar os binários e adicionar ao path.

Usar p6doc

Com o perl6 (Rakudo) no PATH, execute

$ ./bin/p6doc Str

para ver a documentacão da clase Str, ou

$ ./bin/p6doc Str.split

para ver a documentacão do método split da clase Str. Pode omitir ./bin se o p6doc foi instalado com o zef. Também pode executar

$ p6doc -f slurp

para pesquisar a documentacão padrão de subrotinas. Dependendo da velocidade do disco rígido e da versão do Rakudo, é possivel que demore minutos.

Gerando a documentacão HTML

Instale as dependências executando o siguinte no directório onde estão as fontes:

$ zef --deps-only install .

rakubrew, precisa que seja executado tabém:

$ rakubrew rehash

para atualizar os links de compatibilidade de executáveis.

Além das dependências de Raku, precisa do graphviz instalado. No Debian instale usando:

$ sudo apt-get install graphviz

Para suporte ao destaque de código, precisa também do nodejs instalado e disponível no path. E também das suas depedências, incluindo g++.

Para gerar as páginas web da documentacão com destaque de código, executa:

$ make html

Para gerá-las sem destaque de código, use:

$ make html-nohighlight

Após estarem criadas, pode ver localmente no teu computador com o incluso app.pl, executando:

$ make run

Feito o anterior, a documentacão estará dsiponível em http://localhost:3000.

app.pl depende do Mojolicious instalado. Tamabém é necesário o nodejs para que funcione o destaque de código. E também outros módulos Perl, instalados executando:

$ cpanm --installdeps .

Precisamos de Ajuda!

Raku não é uma linguagem de programação pequena, e documentá-la requer bastante esforço. Qualquer ajuda é bem-vinda.

Algumas maneira de nos ajudar:

• Adicionando documentacão de classes, roles, métodos e operadores.

• Adicionando exemplos de uso à documentacão existente.

• Revisando e corrigindo.

• Abrindo issues no GitHub se acha que falta documentacão.

• Fazendo git grep TODO neste repositório, e substituindo os items TODO por documentação.

Esta página tem uma lista de issues atuais e partes da documentação que faltam. CONTRIBUTING explica brevemente como começar a contribuir.

Algumas questões:

P: Por que não estão incluindo a documentação no código fonte do CORE? R: Várias razões:

1. Esta documentação pretende ser universal com respeito a uma versão dada de uma especificacão, e não necesariamente estar ligada a uma implementação específica de Raku.

2. O tratamento das implementações ao Pod6 é inconsistente; assim se evita impactos potenciais durante a execução.

3. Um repo separado na conta do Raku de GitHub convida mais contribuidores e editores a participar.

P: Eu deveria incluir os métodos das superclases ou dos roles? A: Não. A versão HTML já os inclui, e o p6doc também.

Objetivo

Quero que p6doc e docs.perl6.org se tornem o recurso número 1 para consultar quando quiser conhecer qualquer característica do Raku, seja a linguagem ou seus tipos e rotinas. Quero que seja útil para todo programador de Raku.

-- moritz

ENV VARS

• RAKU_DOC_TEST_VERBOSE como true para mostrar mensajens durante a execução do conjunto de testes. Prático para depurar testes que falham.

• RAKU_DOC_TEST_FUDGE muda testes skip-test para TODO no teste xt/examples-compilation.t.

LICENÇA

O código neste repositório está disponível sob a Artistic License 2.0 como publicado pela Perl Foundation. O arquivo LICENSE contém o texto completo.

Este repositório também contém código de terceiros que podem ter outra licença, em cujo caso indicam o copyright e licença no topo do próprio arquivo. Atualmente incluem:

• Exemplos do StackOverflow Licença MIT; (ref #1 for 1f7cc4e)

• Table sorter plugin from https://github.com/christianbach/tablesorter ; Licença MIT