Processo Ágil de Produção de Livrosproducao.virtual.ufpb.br/books/edusantana/producao-computacao-ea… · Processo Ágil de Produção de Livros Sumário I O Processo de Produção

Processo Ágil de Produção de Livros


Ed. v1.b.0

i


Sumário

I O Processo de Produção 1

1 Visão Geral do Processo de Produção 3

2 Início rápido 5

2.1 Vídeo demonstrando as instruções deste capítulo . . . . . . . . . . . . . . . . . . . 5

2.2 Acesse o repositório deste manual . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2.3 Gerando o PDF através do Servidor da Produção . . . . . . . . . . . . . . . . . . . 7

2.4 Explorando a estrutura de diretórios do projeto . . . . . . . . . . . . . . . . . . . . 9

2.5 Realizando um fork no projeto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

2.6 Clonando o repositório do projeto . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

2.6.1 Clonando através da linha de comando . . . . . . . . . . . . . . . . . . . . 11

2.6.2 Clonando usando interface gráfico (no windows) . . . . . . . . . . . . . . . 11

2.7 Realizando alteração no projeto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

2.8 Comitando as alterações . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

2.8.1 No linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

2.9 Realize um push . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

2.10 Gerando nova versão do livro com as alterações realizadas . . . . . . . . . . . . . . 13

2.11 Realizando um pull-request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

2.12 Reportando sugestões, erros ou críticas . . . . . . . . . . . . . . . . . . . . . . . . . 14

2.13 Resumo técnico do processo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

2.14 Recapitulando . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

3 Revisão de conteúdo anterior 16

3.1 Benefícios desta etapa de revisão . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

3.2 Escolhendo um conteúdo para revisar . . . . . . . . . . . . . . . . . . . . . . . . . 16

3.3 Realize um fork do projeto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

3.4 Clone o projeto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

ii


3.5 Realize a sua contribuição . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

3.6 Visualizando sua revisão . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

3.7 Submetendo sua revisão . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

3.8 Recapitulando . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

4 Iniciando um livro 19

4.1 Repositório do seu livro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

4.2 Estrutura inicial dos projetos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

4.3 Gere o pdf inicial do livro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

4.4 Atualize metadados do livro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

4.5 Visualize as alterações . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

4.6 Configurando o livro e os capítulos . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

4.6.1 Atualize o nome da disciplina . . . . . . . . . . . . . . . . . . . . . . . . . 22

4.6.2 Criando um novo capítulo . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

4.6.3 Atualizando o conteúdo do novo capítulo . . . . . . . . . . . . . . . . . . . 23

4.6.4 Planejamento & Acompanhamento . . . . . . . . . . . . . . . . . . . . . . 23

4.7 Configurando webhook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

5 Portugues 26

5.1 Manuais gerais . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

5.2 Quando usar o ESTA, ESSA ou AQUELA . . . . . . . . . . . . . . . . . . . . . . . 26

II Ferramentas utilizadas no Processo de Produção 27

6 Instalação das Ferramentas 28

6.1 Requisitos mínimos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

6.1.1 Criando conta de usuário no github . . . . . . . . . . . . . . . . . . . . . . 28

6.1.2 Instalando git no Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

6.1.3 Instalando git(hub) no Windows . . . . . . . . . . . . . . . . . . . . . . . . 29

6.1.4 Instalando git no Mac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

6.1.5 Configurando sua identidade . . . . . . . . . . . . . . . . . . . . . . . . . . 29

6.1.6 Editor de texto no Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

6.1.7 Editor de texto no Windows . . . . . . . . . . . . . . . . . . . . . . . . . . 30

6.2 Instalando ambiente para desenvolvimento off-line . . . . . . . . . . . . . . . . . . 31

iii


7 AsciiDoc cheatsheet 32

7.1 Configurando o Cabeçalho do livro . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

7.1.1 Alterando o título do livro . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

7.2 Seções . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

7.3 Estilos de parágrafos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

7.4 Blocos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

7.5 Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

7.6 Macros: Referencias, images & include . . . . . . . . . . . . . . . . . . . . . . . . 36

7.7 Código fonte de programas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

7.7.1 Trecho de código . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

7.7.2 TABs, identação e estilos de códigos . . . . . . . . . . . . . . . . . . . . . . 37

7.8 Listas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

7.9 Tabelas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

7.10 Matemática . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

7.11 Comentários . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

8 Desenhando gráficos 45

8.1 Exemplos do graphviz . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

8.1.1 Grafos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

8.2 Outros gráficos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

8.2.1 Diagrama de Sequência . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

8.2.2 Diagramas usando ditaa . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

9 Vídeos 54

9.1 Problema da inserção de vídeos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

9.2 Solução adota . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

9.2.1 Exemplo do vídeo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

10 Git 56

10.1 Configurando o git com chave ssh . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

10.2 Configurando o git com cor no linux . . . . . . . . . . . . . . . . . . . . . . . . . . 57

10.3 Commit rápido . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

10.4 Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

10.4.1 Configuração dos scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

10.4.2 git-producao . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

10.4.3 git-producao-local . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

10.4.4 git-local . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

iv


10.4.5 git-livro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

10.5 Configurações avançadas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

10.6 Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

10.6.1 Listando tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

11 Outras Ferramentas 61

11.1 Convertendo arquivos do Word para Asciidoc . . . . . . . . . . . . . . . . . . . . . 61

11.2 Formatando código fonte . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

III Utilizando o processo 62

12 Processo para os autores 64

12.1 Pense no livro como um software . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

12.2 Planjenando da produção do livro . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

12.3 Trabalhando num issue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

12.4 Recebendo feedback durante a produção . . . . . . . . . . . . . . . . . . . . . . . . 66

12.5 Finalizando um capítulo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

12.6 Finalizando o livro e obtendo o ISBN . . . . . . . . . . . . . . . . . . . . . . . . . 66

12.7 Fase de Pós-produção . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

13 Autores avançados 68

13.1 Instalar o ambiente de produção local . . . . . . . . . . . . . . . . . . . . . . . . . 68

13.2 Utilizar o git-producao-local . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

13.2.1 Gera o livro do arquivo de teste sem realizar commit . . . . . . . . . . . . . 69

13.2.2 Commita, gera o livro com base no commit . . . . . . . . . . . . . . . . . . 69

13.2.2.1 Realizando um rebase antes . . . . . . . . . . . . . . . . . . . . . 70

IV Implementação do processo 71

14 Criando um novo livro 73

14.1 Baixando o projeto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

14.2 Criando a estrutura inicial do projeto . . . . . . . . . . . . . . . . . . . . . . . . . . 73

14.2.1 Gerando um pdf do livro (off-line) . . . . . . . . . . . . . . . . . . . . . . . 74

14.2.2 Gerando o pdf do livro (off-line estilizado) . . . . . . . . . . . . . . . . . . 74

v


15 Instalando ambiente para desenvolvimento off-line 75

15.1 Instalando o git . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

15.2 Instalando o mercurial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

15.3 Instalar o latex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

15.4 Instalar o asciidoc e dbaltex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

15.4.1 Removendo e atualizando o asciidoc e dbaltex . . . . . . . . . . . . . . . . 76

15.4.2 Instala nova versão do dblatex . . . . . . . . . . . . . . . . . . . . . . . . . 76

15.4.3 Instala nova versão do asciidoc . . . . . . . . . . . . . . . . . . . . . . . . . 76

15.5 graphviz . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

15.6 Instalando estilo do dblatex para geração do pdf estilizado . . . . . . . . . . . . . . 77

15.7 Instalação dos scripts cgi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

15.7.1 Dependencia dos scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

15.7.1.1 sejda . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

15.8 Instalando filtros do asciidoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

15.8.1 diag filter for Asciidoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

15.8.2 ditaa filter for AsciiDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

15.8.3 ditaa filter for AsciiDoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

15.8.4 Criando link simbólico para o .asciidoc . . . . . . . . . . . . . . . . . . . . 79

16 Gerenciando versões dos livros 80

16.1 Sobre o versionamento dos livros . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

16.2 Antes de iniciar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

16.2.1 Testando a configuração . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

16.2.2 Configurando caso o resultado não parecido com o esperado . . . . . . . . . 81

16.2.2.1 Configurando o protocolo . . . . . . . . . . . . . . . . . . . . . . 81

16.2.2.2 Configurando livro.url . . . . . . . . . . . . . . . . . . . . . . . . 81

16.3 Número da versão . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

16.4 Preparando o livro para a gráfica . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

16.4.1 Verifique pendências de revisão . . . . . . . . . . . . . . . . . . . . . . . . 82

16.4.2 Verifique pendências no issue track do projeto . . . . . . . . . . . . . . . . . 82

16.4.3 Verifique as versões anteriores . . . . . . . . . . . . . . . . . . . . . . . . . 82

16.4.4 Verificar o número da versão . . . . . . . . . . . . . . . . . . . . . . . . . . 82

16.4.5 Atualize o histórico de revisão . . . . . . . . . . . . . . . . . . . . . . . . . 83

16.4.5.1 Atualizando o revmark e gerando o release notes . . . . . . . . . . 83

16.4.6 Atualize a ficha catalográfica . . . . . . . . . . . . . . . . . . . . . . . . . . 84

16.4.7 Verificando se há alterações pendentes . . . . . . . . . . . . . . . . . . . . . 84

vi


16.4.8 Gerando o livro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

16.4.9 Aplicando uma tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

16.4.10 Excluindo uma tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

16.4.11 Verificando a tag aplicada . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

16.4.12 Submetendo tag para o github . . . . . . . . . . . . . . . . . . . . . . . . . 85

16.5 Gerando versão do livro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

16.6 Disponibilizando a release do livro . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

16.6.1 Atualizando livros.txt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

16.6.2 Publicando atualização no facebook do curso . . . . . . . . . . . . . . . . . 87

16.7 Criando estrutura de CD para enviar para a gráfica . . . . . . . . . . . . . . . . . . . 87

16.7.1 Criando estrutura inicial do cd . . . . . . . . . . . . . . . . . . . . . . . . . 87

16.7.2 Copiando os arquivos para dentro dos diretórios . . . . . . . . . . . . . . . . 88

16.7.2.1 Baixe os livros para os diretórios respectivos . . . . . . . . . . . . 88

16.7.2.2 Copie os arquivos das capas . . . . . . . . . . . . . . . . . . . . . 88

16.8 Gerando a imagem do cd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

V Outras 89

17 Capacitação 91

17.1 Marcando uma capacitação . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

17.2 Instalar os softwares necessários no laboratório . . . . . . . . . . . . . . . . . . . . 91

17.3 Coffee Break . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

17.4 Auxiliares para o Ministrante . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

18 Visão técnica 93

18.1 Ferramentas utilizadas no processo . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

18.2 Escrevendo o livro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

18.2.1 Iniciando um novo livro . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

18.3 Gerando edição para impressão . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

18.3.1 Revisando o livro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

18.3.2 Fechando versão para impressão . . . . . . . . . . . . . . . . . . . . . . . . 94

18.4 Erratas dos livros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

18.4.1 Onde encontrar a errata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

18.4.2 Contribuindo com correções . . . . . . . . . . . . . . . . . . . . . . . . . . 94

18.4.3 Contribuindo com indicações de erros . . . . . . . . . . . . . . . . . . . . . 94

18.5 Licença . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

vii


19 Escrevendo um livro 95

19.1 Estrutura inicial do projeto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

20 Inserindo caracteres especiais no texto 96

21 Comunicações 97

21.1 Capacitação . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

21.1.1 Convite e Agendamento para a capacitação . . . . . . . . . . . . . . . . . . 97

VI Projetos e Pessoas 99

22 Projetos de produção de livros 101

22.1 Este manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

22.2 Licenciatura em Computação a Distância - UFPB . . . . . . . . . . . . . . . . . . . 101

22.2.1 Período 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

22.2.2 Período 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

22.2.3 Período 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

22.2.4 Período 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

22.2.5 Período 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

22.2.6 Período 6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

22.2.7 Período 7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

22.2.8 Período 8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

23 Pessoas 105

24 Índice Remissivo 106

viii


Parte I

O Processo de Produção

1 / 106


Nesta parte apresentamos o processo de produção de livros adotado pelo nosso curso.

O primeiro capítulo apresenta rapidamente o processo geração dos livros a partir dos arquivos envia-dos para o Servidor de Produção.

Em seguida, apresentamos uma visão geral do fluxo de trabalho da produção dos livros.

Os capítulos seguintes apresentam detalhes sobre sobre o fluxo e as ferramentas utilizadas na produ-ção.

2 / 106


Capítulo 1

Visão Geral do Processo de Produção

Este capítulo demonstra uma visão geral de um Processo de Produção de materiais didáticos propostoe adotado no Curso de Licenciatura em Computação a distância na Universidade Federal da Paraíba.

A figura abaixo ilustra nosso processo de produção.

Figura 1.1: Fluxo de trabalho, visão geral.

A lista abaixo resume as etapas do processo:

Processo seletivo de autoresNesta etapa a coordenação divulga um processo seletivo e os autores são selecionados conformeo edital.

CapacitaçãoA capacitação é iniciada com apresentação do processo, e as ferramentas necessárias. Emseguida, uma revisão inicia o autor no processo de produção. Ao final da capacitação, cadaautor terá iniciado a produção de seu livro.

Capacitação dos autoresOs autores selecionados receberão capacitação sobre o processo e as ferramentas utiliza-das na produção (ver Parte II [28]).

3 / 106


Revisão de conteúdoDurante a capacitação, antes de iniciar a escrita, o novo autor é convidado a revisar umcapítulo das disciplinas relacionadas, já escritas anteriormente. Esta revisão é uma etapaeducativa e que possibilita:

1. Aprimorar os conteúdos já elaborados, contribuindo com sua qualidade;2. Tornar o autor ciente de como os conteúdos foram apresentados para os alunos;3. Integração entre os autores da mesma area.4. Introduzir, para o autor, as ferramentas necessárias para a produção;5. Conscientizar o autor sobre os direitos autorais dos livros;

Iniciando o livroNesta etapa o autor irá baixar o projeto do seu livro, configurar o título, autor, e outrospassos inicias.

EscritaNeste etapa o autor escreve os capítulos, elabora gráficos e está frequente enviando seu pro-gresso.

Envia conteúdoEste envio frequente possui várias utilizades:

1. Permite que os outros autores conheçam a estrutura do seu conteúdo e possam referenciarseu material;

2. Permite o editor intervenha na elaboração, seja realizando nova capacitação ou infor-mando sobre conteúdos semelhantes já abordados nos outros livros.

3. Acompanhamento do progresso para verificar necessidade de ajuda na escrita (co-autores).

4. Possibilitar antecipar o trabalho do revisor. Quando os capítulos vão sendo finalizados, orevisor pode iniciar a revisão neles.

5. Garantir backup dos conteúdos escritos.

Revisão do textoQuando um autor termina um capítulo, os revisores são acionados para realizarem as revisõesno texto referido.

Gerar ediçãoQuando os autores e o revisor finalizam seus trabalhos, o editor gera versão para impressão.

Contribuições para a ErrataDepois do livro impresso, tanto os autores como os leitores podem contribuir para a construçãoda errata. Os leitores devem ser incentivados a enviarem correções dos erros encontrados noslivros.

Manutenção da ErrataCom base nas correções enviadas, o editor mantém uma errata do livro atualizada.

O processo que propomos é assistido por diversas ferramentas. No próximo capítulo apresentaremoscomo utilizar as ferramentas necessárias para a produção dos livros.

4 / 106


Capítulo 2

Início rápido

OBJETIVOS DO CAPÍTULO

Ao final deste capítulo você deverá ser capaz de:

• Gerar PDFs dos livros a partir de seus repositórios

• Realizar forks em projetos no github

• Clonar repositórios, baixando seus conteúdos para seu computador

• Realizar alterações nos capítulos dos livros

• Enviar alterações para o github

• Verificar as alterações realizadas no PDF gerado

• Submeter as alterações ao repositório pai, através de um Pull Request• Submeter críticas e sugestões sobre um livro.

Esta seção contém é um guia rápido para iniciar os autores/contribuidores no Processo de Produção.

Nós iremos baixar o projeto deste manual, e editar o capítulo Capítulo 23 [105] incluindo nosso nomeà lista de nomes contida no capítulo referido.

As seções a seguir, ensinarão como realizar esta tarefa.

Instalação do ambiente mínimo de produçãoPara você poder prosseguir com as instruções deste capítulo você deve primeiro instalar oambiente mínimo de produção. Consulte as instruções de instalação em Seção 6.1 [28].Não prossiga enquanto não possuir o ambiente instalado e configurado.

2.1 Vídeo demonstrando as instruções deste capítulo

Para facilitar o entendimento deste capítulo, nós produzimos um vídeo demonstrando como realizaras instruções deste capítulo.

5 / 106


Figura 2.1: Início rápido: http://youtu.be/uDMs-TyjSek

DicaEmbora o livro demonstre como realizar o processo é importante ler este capítulo prestandobastante atenção em todas as informações.

2.2 Acesse o repositório deste manual

NotaUm repositório é um local onde são armazenados os arquivos de um projeto, neste caso,todos os textos e imagens necessários para produzir este manual.

Nossa primeira atividade será acessar o repositório deste manual que você está lendo:

REPOSITÓRIO DESTE MANUAL NO GITHUB

https://github.com/edusantana/producao-computacao-ead-ufpb.

6 / 106

http://youtu.be/uDMs-TyjSek

https://github.com/edusantana/producao-computacao-ead-ufpb


Figura 2.2: Página do repositório deste livro

DicaNeste momento não é necessário explorar o repositório, basta saber que ele existe e que otexto que gera este manual está lá. Você utilizará o endereço deste repositório na próximaseção para gerar o pdf.

2.3 Gerando o PDF através do Servidor da Produção

Nesta seção nós iremos aprender como gerar o PDF deste manual. A geração do PDF é através deuma operação no Servidor da Produção.

Para gerar o PDF precisamos informar qual o repositório que contém o livro que desejamos gerar,neste caso, portanto, precisamos informar o endereço do repositório acessado na seção anterior.

Importante

Servidor da ProduçãoEndereço da operação de geração de pdfs no servidor: http://producao.virtual.ufpb.br/-github.html.

Repositório deste manualÉ o mesmo endereço utilizado na seção anterior: https://github.com/edusantana/-producao-computacao-ead-ufpb

Acesse o servidor da produção, informe o repositório deste manual e gere o pdf do livro (ver Figura 2.3[8]).

7 / 106

http://producao.virtual.ufpb.br/github.html

http://producao.virtual.ufpb.br/github.html




Figura 2.3: Geração do PDF através do Servidor da Produção

Aguarde alguns instantes enquanto o PDF é gerado.

Figura 2.4: Tela de geração do PDF

DicaMatenha o hábito de verificar os logs gerados para certifica-se que não houve erros ou WAR-NINGs.

Depois da geração do pdf:

1. Clique no último link, producao-computacao-ead-ufpb (no topo da página).

8 / 106


2. Clique no diretório livro

3. Clique em livro.pdf para baixar o livro gerado.

ImportanteCaso não compreendeu como encontrar o PDf, consulte o vídeo (Seção 2.1 [5]) no iníciodeste capítulo.

NotaPronto! Você conseguiu gerar o PDF através dos arquivos que estavam no servidor. O nossotrabalho consistirá em enviar nossas alterações para o servidor e verificar o resultado final apartir da geração do PDF.

Na próxima seção iremos aprender a estrutura de diretórios dos projetos e o papel de alguns arquivos.

2.4 Explorando a estrutura de diretórios do projeto

No github ou no servidor da produção, explore a estrutura do projeto.

Estrura deste projeto

.|-- cgi/|-- dblatex-computacao-ufpb/|-- estrutura-inicial/ x1|-- git-scripts/|-- livro/| |-- capitulos/ x2| | |-- code/ x3| | |-- asciidoc.asc| | |-- capacitacao.asc| | |-- comunicacoes.asc| | |-- curso.asc| | |-- faq.asc| | |-- git.asc| | |-- graficos.asc| | |-- impl-ambiente-offline.asc| | |-- impl-novo-livro.asc| | |-- impl-versoes-gerenciamento.asc| | |-- iniciando-livro.asc| | |-- inicio-rapido.asc x4| | |-- instalacao-ferramentas.asc| | |-- outras.asc| | |-- pessoas.asc x5| | |-- portugues.asc| | |-- projetos.asc| | |-- revisao-conteudo-anterior.asc| | |-- usuario.asc

9 / 106


| | |-- videos.asc| | ‘-- visao-geral.asc| |-- images/ x6| |-- videos/ x7| | |-- inicio-rapido.html| | |-- install-github-windows.html| | ‘-- notepad_plugin.html| |-- docinfo.xml x8| ‘-- livro.asc x9|-- ignore-pdf|-- ignore-slide|-- README.asciidoc‘-- TODO.asc

x1 Estrutura padrão de novos projetos.x2 Todos os capítulos são criados neste diretório.x3 Os códigos fontes dos exemplos são organizadas em subdiretórios deste diretório.x4 Arquivo fonte deste capítulo.x5 Capítulo que iremos editar mais adiante (Seção 2.7 [11]).x6 As imagens do livro são organizadas em subdiretórios deste diretório.x7 Diretório para possibilitar incorporar vídeos no livro em html (Capítulo 9 [54]).x8 Arquivo contendo alguns metadados, como os nomes dos autores.x9 Ponto de partida do livro. Onde todos os capítulos são incluídos.

2.5 Realizando um fork no projeto

NotaCertifique-se que esteja logado no github com seu usuário antes de realizar o fork.

Na página inicial do projeto, no github, clique em Fork para gerar um fork do projeto para você. Ofork é necessário quando desejamos realizar alterações nos repositórios alheios.

DicaA ajuda do github pode conter informações para auxiliar na realização do fork:https://help.github.com/articles/fork-a-repo.

Quando você realiza um fork do repositório, o github irá criar um outro repositório onde somentevocê possui permissão de escrita.

Diferença dos repositórios após o fork

10 / 106

https://help.github.com/articles/fork-a-repo


http://github.com/edusantana/producao-computacao-ead-ufpb (read only)http://github.com/camyle/producao-computacao-ead-ufpb (depois do fork)

2.6 Clonando o repositório do projeto

A operação de clone baixa todos os arquivos do projeto para o seu disco local.

Como iremos realizar uma alteração no manual, precisaremos baixar os arquivos do projeto, clonandoo fork.

2.6.1 Clonando através da linha de comando

Em um diretório onde você deseja baixa o projeto, execute o seguinte comando:

git clone https://github.com/seu-usuario/producao-computacao-ead-ufpb ←↩.git

CuidadoNa operação de clone, o endereço clonado termina com .git.

2.6.2 Clonando usando interface gráfico (no windows)

ImportanteO vídeo no início do capítulo (Seção 2.1 [5]) demonstra todas as etapas necessária no win-dows.

Clique e arraste o endereço do repositório no github para o programa do github para o windows.

DicaO ajuda do github pode lhe auxiliar nesta tarefa: http://windows.github.com/help.html

2.7 Realizando alteração no projeto

NotaNeste momento, assumimos que você possui um editor de texto com highlight reconhecendoa linguagem asciidoc. Caso contrário, consulte Seção 6.1 [28] para efetuar a instalação.

11 / 106

http://windows.github.com/help.html


Após realizar o clone do projeto, encontre o arquivo livro/capitulos/pessoas.asc em seucomputador. Abra-o para edição.

DicaNo windows, clique com o botão direito no repositório e escolha "Open with Explorer"para irpara o diretório onde o github salva os arquivos: Documentos\Github.

Com o arquivo aberto, adicione o seu nome à lista. Por exemplo, adicionando Camyle:

. Camyle de Araújo Silva -- *Revisora Ortográfica*, ‘2013.1‘.

2.8 Comitando as alterações

O git funciona com múltimos repositórios. Quando nós clonamos um projeto, nós envolvemos doisrepositórios nesta operação:

O repositórioremoto

É o github. Onde os arquivos são salvos e disponibilizados para qualquerusuário com conexão a internet pode acessa-lo.

O repositóriolocal

Localizado em nosso computador. Mantém os arquivos orginais e todas asalterações que realizamos.

Antes de submeter nossas alterações para o repositório remoto, precisamos primeiro submete-las parao repositório local. Esta operação é conhecida por Commit.

Agora devemos submeter nossa alteração primeiro para o repositório local, realizando um commit.

2.8.1 No linux

Execute o comando dentro de qualquer diretório do projeto:

Ferramenta para realizar o commit

gitg

Marque os arquivos modificados (pessoas.asc) para stage, e adicione um comentário do commit, ex:"Inclusão do nome Camyle".

12 / 106


Figura 2.5: Commitando com o gitg no linux

O próximo passo será submeter os nossos commits para o servidor remoto, através de uma operaçãochamada de push.

2.9 Realize um push

Um push envia as alterações comitadas em seu repositório local para o servidor remoto (o github).

Comando para realizar push no linux

git push

No github do windows, esta operação é conhecida por Sync.

2.10 Gerando nova versão do livro com as alterações realizadas

ImportantePercebam que qualquer alteração realizada foi feita no seu fork. Portanto, a geração do livrodeverá ocorrer com o novo endereço.

https://github.com/camyle/producao-computacao-ead-ufpb (seu fork ←↩)

https://github.com/edusantana/producao-computacao-ead-ufpb ( ←↩original)

Re-execute a geração do livro (Seção 2.3 [7]) com o novo endereço do repositório forkado. Se vocênão lembra onde encontrar livro.pdf consulte Seção 2.3 [7].

13 / 106


DicaCaso sua alteração não apareça reveja suas ações:

1. Você realizou o commit com o arquivo modificado?

2. Você esqueceu de realizar o git push?

3. Você lembrou de informar o novo endereço contendo o nome do seu usuário?

4. Os logs da geração informou algum erro?

5. Seu navegador está retornando uma versão antiga do cache? Clique em atualizar!

2.11 Realizando um pull-request

Agora que verificou que sua alteração foi inserida com sucesso, é o momento de enviar as alteraçõespara o projeto original.

Clique em Pull Request, no github, para enviar as alterações para o projeto original.

As alterações enviadas não são incorporadas imediatamante, elas ficam em suspenso até que o res-ponsável pelo repositório (o Editor) aceite o Pull Request.

ImportanteVocê fará um Pull Request sempre que desejar enviar um capítulo para a Revisão.

2.12 Reportando sugestões, erros ou críticas

Em qualquer momento da produção do livro, qualquer usuário pode submeter sugestões, erros oucríticas. O github possui um sistema de gerenciamento de erros/tarefas (issue tracking) onde osusuários podem submetê-los.

ImportanteAdicione uma crítica no issue tracking deste manual! Acesse https://github.com/edusantana/-producao-computacao-ead-ufpb. Clique em Issues, em seguida em New Issue (Figura 2.6[15]). Escreva a sua crítica e clique em Submit new Issue.

14 / 106




Figura 2.6: Sistema de gerenciamento de erros do github

DicaÉ importante incentivar os leitores a submeter críticas para que os livros estejam sempresendo aprimorados.

2.13 Resumo técnico do processo

O processo técnico está ilustrado na Figura 2.7 [15].

processo-tecnico-sequencia-operacoes.svg

Figura 2.7: Sequencia das operações

2.14 Recapitulando

Este capitulo apresentou, de forma rápida, como funciona o processo de produção descrito nestemanual.

Nos próximos capítulos iremos descrever com mais detalhes cada uma das partes do Processo deProdução.

15 / 106


Capítulo 3

Revisão de conteúdo anterior



• Realizar contribuições em livros previamente escritos

• Realizar uma revisão num capítulo

Nesta etapa do processo ocorre durante a capacitação. O novo autor é convidado a revisar um capítulode um livro produzido anteriormente.

3.1 Benefícios desta etapa de revisão

1. Tornar o autor ciente de como os conteúdos foram escritos;

2. Aprimorar os conteúdos já elaborados, contribuindo com sua qualidade;

3. Integração entre os autores da mesma area.

4. Introduzir, para o autor, as ferramentas necessárias para a produção;

5. Conscientizar o autor sobre os direitos autorais dos livros;

3.2 Escolhendo um conteúdo para revisar

Escolha um repositório de uma disciplina que você tem afinidade em Seção 22.2 [101].

NotaVocê não precisará revisar todo o livro, basta escolher um capítulo como amostra.

16 / 106


3.3 Realize um fork do projeto

Para poder obter um repositório com permissão de escrita (modificar), é necessário realizar um forkno projeto desejado.

NotaVocê já realizou um fork antes (Seção 2.5 [10]), mas agora precisa fazer no livro que escolheupara revisar.

3.4 Clone o projeto

Após realizar o fork, você poderá baixar o projeto realizando a operação de clone (Seção 2.6 [11]) doprojeto.

3.5 Realize a sua contribuição

Nós temos as seguintes sugestões de como você pode contribuir:

Correção de textoBasta atualizar o texto.

Incluindo comentáriosVocê pode inserir diversos comentários (Seção 7.11 [44]) no texto que está sendo revisado.

3.6 Visualizando sua revisão

Para visualizar suas alterações é necessário:

1. Comitar as alterações (Seção 2.8 [12])

2. Enviar os commits para o seu fork (Seção 2.9 [13])

3. Utilizar o Servidor da Produção para gerar o pdf (Seção 2.10 [13])

DicaMesmo que você tenha contribuido somente com comentários, é um bom hábito sempreverificar o resultado final.

3.7 Submetendo sua revisão

Após terminar suas contribuições, você deve realizar um Pull Request (Seção 2.11 [14]) para dispo-nibilizar suas alterações no repositório de origem.

17 / 106


3.8 Recapitulando

Neste capítulo você teve a oportunidade de conhecer o trabalho de outro autor e contribuir com otrabalho realizado.

18 / 106


Capítulo 4

Iniciando um livro



• Configurar um novo livro

• Alterar conteúdo inicial do livro

• Adicionar novos capítulos ao livro

• Consultar manuais

• Como solicitar ajuda

Após a revisão de um capítulo de outro autor, você agora já teve experiência em participar na produçãode um livro em produção utilizando o nosso processo.

Esta etapa do processo ocorre durante a capacitação. Nela você irá aprender como configurar umnovo livro e iniciar sua escrita.

4.1 Repositório do seu livro

Todo livro possui um repositório único, um local para armazenar os arquivos diferente de todos osoutros livros.

Durante a capacitação os autores devem conhecer o endereço do seu repositório. Consulte Seção 22.2[101] para saber o seu. Caso você tenha dúvidas em saber qual é o seu, consulte o editor durante acapacitação.

ImportanteO autor deve receber um repositório não vazio, com um conjunto de arquivos e diretórios quechamandos de estrutura-inicial. O processo de replicar uma estrutura inicial nos repositó-rios está descrito em Seção 14.2 [73]. No entanto, o autor não deve se preocupar com isto,pois é esperado que este passo já tenha sido executado para ele.

19 / 106


4.2 Estrutura inicial dos projetos

Todo novo projeto possui uma estrutura inicial criada para o autor.

1. Realize um fork do seu repositório (Seção 2.5 [10])

2. Baixe o seu projeto realizando um clone do seu repositório forkado (Seção 2.6 [11]).

3. Abra o diretório onde o projeto foi baixado e perceba a estrutura inicial do projeto.

Estrutura inicial dos projetos

|-- livro/| |-- capitulos/| | |-- code/| | | ‘-- helloworld.c| | |-- asciidoc-cheatsheet.asc| | |-- novo-capitulo.asc| | ‘-- prefacio.asc| |-- images/| | ‘-- novo-capitulo| | ‘-- bug.png| |-- slides/| | ‘-- gerando-slides.asc| |-- livro.asc| |-- docinfo.xml| ‘-- slides.asc‘-- README.asciidoc

4.3 Gere o pdf inicial do livro

Sem realizar nenhuma alteração, gere o pdf do livro (Seção 2.10 [13]) para verificar a versão inicial.

DicaLembre-se de que o PDF gerado é do repositório do seu fork.

4.4 Atualize metadados do livro

Abra o arquivo livro/docinfo.xml e atualize o seu nome na lista de autores.

Código fonte livro/docinfo.xml

Não se deixe intimidar pelo tamanho do arquivo, apenas atualize o seus dados:

Seção do arquivo onde configurar os autores

20 / 106

http://github.com/edusantana/producao-computacao-ead-ufpb/blob/master/livro/estrutura-inicial/livro/docinfo.xml


<authorgroup><author>

<firstname>Nome</firstname><surname>Sobrenome</surname><affiliation>

<jobtitle>Professor</jobtitle><orgname>Universidade Federal da Paraíba</orgname>

</affiliation><authorblurb>

<para>Principal contribuidor do livro.

</para></authorblurb>

</author></authorgroup>

4.5 Visualize as alterações

Realize as seguintes instruções para gerar e visualizar o pdf com suas alterações.

1. Commite e sincronize (push) as alterações (Seção 2.8 [12] e Seção 2.9 [13]). Para agilizar oenvio consulte Seção 10.3 [57].

2. Gere uma versão do PDF através do Servidor da Produção (Seção 2.10 [13]).

3. Abra o PDF gerado e verifique a alteração.

4.6 Configurando o livro e os capítulos

Você deve ter percebido que o livro que se encontra no repositório já possui alguns capítulos.

O principal arquivo do livro é o livro/livro.asc. Neste arquivo são configurados:

• Nome da disciplina do livro

• Capítulos do livro

livro/livro.asc

= Nome da disciplinaAutor da disciplina:doctype: book:lang: pt-BR:keywords: Computação:description: Livro de Nome-da-disciplina:ascii-ids:

21 / 106


include::capitulos/prefacio.asc[]

////= Nome da Parte =////

include::capitulos/novo-capitulo.asc[]include::capitulos/asciidoc-cheatsheet.asc[]

// Sempre termine os arquivos com uma linha em branco.

4.6.1 Atualize o nome da disciplina

Onde atualizar o nome da disciplina

= Nome da disciplina

Exemplo de nome da disciplina atualizado

= Introdução à Computação

4.6.2 Criando um novo capítulo

O arquivo livro/capitulos/novo-capitulo.asc foi criado com o objetivo de você criaruma cópia deste arquivo sempre que desejar criar um novo capitulo.

1. Abra o arquivo, salve-o como outro nome dentro da pasta capitulos. Não utilize espaço nonome do arquivo.

2. Edite o arquivo livro.asc e adicione um include com o novo arquivo

3. Comente os capítulos que não serão utilizados

Exemplo de livro.asc após incluir um novo capítulo chamado História da Computação

include::capitulos/historia-da-computacao.asc[]// include::capitulos/novo-capitulo.asc[]// include::capitulos/asciidoc-cheatsheet.asc[]

DicaGere o livro novamente para verificar as alterações (Seção 4.5 [21]).

22 / 106


4.6.3 Atualizando o conteúdo do novo capítulo

O conteúdo do arquivo novo-capitulo foi elaborado para facilitar a edição de novos capítulos.

CuidadoLembre-se de que não pode existir nenhuma seção sem texto. Sempre que você criar umaseção, adicione quaquer texto dentro dela, caso contrário o PDF não será gerado.

4.6.4 Planejamento & Acompanhamento

O autor deve fornecer um planejamento de elaboração do livro através das seguintes ações:

Informar quais e quantos capítulos serão realizadosO autor informa quais capítulos serão realizados criando os arquivos de cada capítulo eenviando-os para o github.

Exemplo de planejamento de um livro de Introdução a Programação.

capitulos/computador.asccapitulos/algoritimos.asccapitulos/representacao-de-dados.asccapitulos/expressoes.asccapitulos/entrada-e-saida.asccapitulos/estruturas-de-controle.asccapitulos/estruturas-de-repeticao.asccapitulos/variaveis-compostas.asccapitulos/modularizacao.asccapitulos/novo-capitulo.asclivro.asc (com os includes dos novos capítulos)

NotaEmbora existam muitos arquivos acima, todos eles foram cópias do arquivonovo-capitulo.asc, com apenas o título do capítulo modificado.

Arquivo livro/livro.asc atualizado

= Introdução a ProgramaçãoEduardo Santana:doctype: book:lang: pt-BR:description: Livro de Introdução a Programação:ascii-ids:

include::capitulos/prefacio.asc[]include::capitulos/computador.asc[]include::capitulos/algoritimos.asc[]include::capitulos/representacao-de-dados.asc[]

23 / 106


include::capitulos/expressoes.asc[]include::capitulos/entrada-e-saida.asc[]include::capitulos/estruturas-de-controle.asc[]include::capitulos/estruturas-de-repeticao.asc[]include::capitulos/variaveis-compostas.asc[]include:: capitulos/modularizacao.asc[]

// Sempre termine os arquivos com uma linha em branco.

ImportanteNão esqueça de atualizar o arquivo livro.asc para incluir o novos capítulos. Con-sulte Seção 4.6.2 [22] se precisar lembrar como os novos capítulos são criados.

Em seguida, adicione os arquivos ao gitb e realize um push (sincronização) para enviar osarquivos para o github.

Informar um planejamento de conclusão dos capítulosO autor informa o planejamento de conclusão dos capítulos através da criação de um Issueentitulado "Planejamento de conclusão dos capítulos".

Figura 4.1: Exemplo do Issue de Planejamento de conclusão dos capítulos

24 / 106


CuidadoO Issue deve ser criado no projeto original, e não no fork do autor.

DicaVocê pode lembrar como criar issues em Seção 2.12 [14].

4.7 Configurando webhook

O github pode ser configurado para geração automática do livro após enviar os commits através doevento de push.

Para configurar o webhook, adicione o link http://producao.virtual.ufpb.br/webhook em Set-tings/Webhooks & Services no repositório do seu livro, conforme imagem a seguir:

Figura 4.2: Configurando webhook no github

RECOMENDAÇÕES DE USO NOS REPOSITÓRIOS

• Em que os arquivos são modificados pela Web

• Em que a geração do livro é feita localmente

25 / 106

http://producao.virtual.ufpb.br/webhook


Capítulo 5

Portugues

Neste capítulo registramos alguns pontos do portugues para ser utilizados na revisão ou escrita dotexto.

5.1 Manuais gerais

http://www.pucrs.br/manualred/

5.2 Quando usar o ESTA, ESSA ou AQUELA

• http://www.pucrs.br/manualred/pronomes.php

• http://tudibao.com.br/2010/05/quando-usar-o-esta-essa-ou-aquela.html

• http://exame.abril.com.br/carreira/noticias/este-esta-esse-ou-essa-como-usar

26 / 106

http://www.pucrs.br/manualred/

http://www.pucrs.br/manualred/pronomes.php

http://tudibao.com.br/2010/05/quando-usar-o-esta-essa-ou-aquela.html

http://exame.abril.com.br/carreira/noticias/este-esta-esse-ou-essa-como-usar


Parte II

Ferramentas utilizadas no Processo deProdução

27 / 106


Capítulo 6

Instalação das Ferramentas

Este capítulo possui as instruções de como instalar o ambiente de desenvolvimento necessário para aprodução dos materiais.

6.1 Requisitos mínimos

• Conta de usuário no github

• git

• Editor de Texto + highlight plugin.

6.1.1 Criando conta de usuário no github

Para poder contribuir com alterações nos livros é necessário possuir uma conta no github, portanto,caso você não tenha um usuário crie sua conta agora.

ImportanteAcesse agora https://github.com para criar uma conta de usuário para você, caso você aindapossua. OBS: No github a senha precisa conter pelo menos um número e uma letra.

6.1.2 Instalando git no Linux

O seguinte comando instala o git no linux:

sudo apt-get install git-core gitg

ImportanteNa instalação do git, recomendamos a criação de uma chave ssh, conforme as instruçõesem https://help.github.com/articles/generating-ssh-keys.

28 / 106

https://github.com

https://help.github.com/articles/generating-ssh-keys


CuidadoSe a versão do git (git --version) for inferior a 1.7.10, o clone com https não iráfuncionar. Neste caso você deve atualizar o git ou criar uma chave ssh e clonar o pro-jeto com o endereço ssh. Detalhes do erro e da solução pode ser encontrados respecti-vamente em: https://help.github.com/articles/https-cloning-errors e https://help.github.com/-articles/generating-ssh-keys.

6.1.3 Instalando git(hub) no Windows

DicaProduzimos um vídeo demonstrando a instalação no windows:

size=10

Figura 6.1: Instalação do github no windows: http://youtu.be/8XDR137mZK4

As instruções de instalação do git no windows pode ser consultada em https://help.github.com/-articles/getting-started-with-github-for-windows.

O binário do git pode ser baixado em http://github-windows.s3.amazonaws.com/GitHubSetup.exe.

NotaNo cliente do git no windows, uma chave ssh é automaticamente criada e adicionada ao git.

6.1.4 Instalando git no Mac

Para a instalação do git siga as intruções em http://mac.github.com.

6.1.5 Configurando sua identidade

Comando para configurar sua identidade

$ git config --global user.name "John Doe"$ git config --global user.email [email protected]

DicaPara mais configurações consulte http://git-scm.com/book/en/Getting-Started-First-Time-Git-Setup e Capítulo 10 [56].

29 / 106

https://help.github.com/articles/https-cloning-errors



http://youtu.be/8XDR137mZK4

https://help.github.com/articles/getting-started-with-github-for-windows

https://help.github.com/articles/getting-started-with-github-for-windows

http://github-windows.s3.amazonaws.com/GitHubSetup.exe

http://mac.github.com

http://git-scm.com/book/en/Getting-Started-First-Time-Git-Setup

http://git-scm.com/book/en/Getting-Started-First-Time-Git-Setup


6.1.6 Editor de texto no Linux

No linux recomendamos utilização do vim ou gedit para instalação do plugin de highlight do asciidoc.

Plugin de highlighthttps://launchpad.net/asciidoc-gtk-highlight ou https://launchpad.net/asciidoc-gtk-highlight/-trunk/0.1/+download/asciidoc-gtk-highlight.tar.gz. O arquivo possui um arquivo READMEcom as intruções de instalação.

Figura 6.2: Highlight do plugin no gedit

6.1.7 Editor de texto no Windows

No window recomendamos utilizar o Notepad++ para edição. Baixe e instale a versão que desejar.

Versão sem instalaçãohttp://download.tuxfamily.org/notepadplus/6.3.1/npp.6.3.1.bin.zip

Versão com instalaçãohttp://download.tuxfamily.org/notepadplus/6.3.1/npp.6.3.1.Installer.exe

DicaCriamos um plugin de highlight para o Notepad++, está disponível em https://github.com/-edusantana/asciidoc-highlight. O seguinte vídeo ensina como instalar o plugin:

30 / 106

https://launchpad.net/asciidoc-gtk-highlight

https://launchpad.net/asciidoc-gtk-highlight/trunk/0.1/+download/asciidoc-gtk-highlight.tar.gz

https://launchpad.net/asciidoc-gtk-highlight/trunk/0.1/+download/asciidoc-gtk-highlight.tar.gz

http://download.tuxfamily.org/notepadplus/6.3.1/npp.6.3.1.bin.zip

http://download.tuxfamily.org/notepadplus/6.3.1/npp.6.3.1.Installer.exe

https://github.com/edusantana/asciidoc-highlight

https://github.com/edusantana/asciidoc-highlight


size=10

Figura 6.3: Instalação do plugin de highlight no Notepad++: http://youtu.be/_i-KxSb7cJM

Figura 6.4: Highlight do plugin no Notepad++

6.2 Instalando ambiente para desenvolvimento off-line

Com as ferramentas descritas anteriormente são suficientes para a produção dos livros. Caso vocêdeseje desenvolver as atividades sem o Servidor da Produção, você necessitará instalar o ambientede desenvolvimento off-line (Capítulo 15 [75]).

ImportanteEmbora possa parecer que a geração através do servidor demore alguns instantes, a gera-ção em seu computador pessoal talvez demore ainda mais, dependendo da performance dasua máquina. A instalação off-line é recomendada quando o usuário possui acesso limitadoa internet.

31 / 106

http://youtu.be/_i-KxSb7cJM


Capítulo 7

AsciiDoc cheatsheet

Nesta seção são apresentadas vários recursos do asciidoc. Verifique o código fonte para aprender quala sintaxe que produz este texto.

A melhor forma de aprender o asciidoc é consultando o site oficial.

Sumário das funcionalidadeshttp://xpt.sourceforge.net/techdocs/nix/tool/asciidoc-syn/ascs01-AsciiDocMarkupSyntaxQuickSummary/single/

AsciiDoc cheatsheethttp://powerman.name/doc/asciidoc

Site oficialhttp://www.methods.co.nz/asciidoc/

Exemplo de livrohttps://asciidoc.googlecode.com/hg/doc/book.txt

Guida do usuáriohttp://www.methods.co.nz/asciidoc/userguide.html

Matemáticahttp://www.methods.co.nz/asciidoc/latexmath.pdf

FAQhttp://www.methods.co.nz/asciidoc/faq.html

Apresentaçãohttp://mojavelinux.github.com/decks/asciidoc-with-pleasure/

7.1 Configurando o Cabeçalho do livro

O cabeçalho de arquivo asciidoc contém:

1. Título do livro

2. Autor do livro

32 / 106

http://xpt.sourceforge.net/techdocs/nix/tool/asciidoc-syn/ascs01-AsciiDocMarkupSyntaxQuickSummary/single/

http://xpt.sourceforge.net/techdocs/nix/tool/asciidoc-syn/ascs01-AsciiDocMarkupSyntaxQuickSummary/single/

http://powerman.name/doc/asciidoc

http://www.methods.co.nz/asciidoc/

https://asciidoc.googlecode.com/hg/doc/book.txt

http://www.methods.co.nz/asciidoc/userguide.html

http://www.methods.co.nz/asciidoc/latexmath.pdf

http://www.methods.co.nz/asciidoc/faq.html

http://mojavelinux.github.com/decks/asciidoc-with-pleasure/


7.1.1 Alterando o título do livro

O título do livro é composto pelas é informado na primeira linha:

Título inicial= Meu livro

Exemplo de título alterado= Estágio Supervisionado II

7.2 Seções

== Nível de capítulo (section) 1Texto.

=== Nível de subseção 2Texto.

==== Level 3Texto.

===== Level 4Texto.

CuidadoNão pode existir seções sem texto. Sempre coloque algum texto, caso contrário o arquivonão será gerado.

7.3 Estilos de parágrafos

Título do parágrafo opcional Texto do parágrafo aqui.

Título do parágrafo opcionalTexto do parágrafo aqui.Precisa começar com espaço em branco.

Optional Titledie ’connect: ’.$dbh->errstr;

Este parágrafo não faz parte do código.

NotaThis is an example single-paragraph note.

33 / 106


NotaThis is an example single-paragraph note.

DicaTexto.

ImportanteTexto.

AtençãoTexto.

CuidadoTexto.

7.4 Blocos

Optional Title

*Listing* Block

Use: code or file listings

Optional Title

# *Source* block# Use: highlight code listings# (require ‘source-highlight‘ or ‘pygmentize‘)use DBI;my $dbh = DBI->connect(’...’,$u,$p)

or die "connect: $dbh->errstr";

Optional Title

Sidebar Block

Use: sidebar notes :)

34 / 106


Exemplo 7.1 Titulo do bloco de exemploBloco de Exemplo.Utilize exemplos! :)

Bloco de Exemplo sem título.

Utilize exemplos! :)

Título desde blocoNOTE BlockUse: multi-paragraph notes.

Título desde bloco (opcional)

*Literal* Block

Use: workaround when literalparagraph (indented) like

1. First.2. Second.

incorrectly processed as list.

OPTIONAL TITLE

Quote Block

Use: cite somebody

— cite author cite source

7.5 Text

forçandoquebra de linha.

normal, italic, bold, mono.

“double quoted”, ‘single quoted’.

normal, super, sub.

Command: ls -al

Path: /some/filez.txt, .b

© ® ™ — . . . →←⇒⇐ ¶

35 / 106


7.6 Macros: Referencias, images & include

Como inserir imagens[[minha_imagem_exemplo]].Exemplo de imagemimage::images/inicio-rapido/nova-sugestao.png[scaledwidth="60%"]

Figura 7.1: Exemplo de imagem

No trecho acima [[minha_imagem_exemplo]] é opcional. Deve ser usado apenas quando sedeseja fazer refência a ela.

Como fazer referências[[texto-secao]]=== Text

Exemplo de referencias: <<texto-secao>> e <<minha_imagem_exemplo>>.

Exemplo de referencia para seção: Seção 7.5 [35]. Exemplo de referência para imagem: Figura 7.1[36].

Axioma 1:

a+b = b+a, ∀a,b ∈ R.

Axioma 2:

(a+b)+ c = a+(b+ c), ∀a,b,c ∈ R.

Ver Axioma 1: [36].

7.7 Código fonte de programas

Exemplo de código fonte/* Hello World program */

#include<stdio.h> // x1main(){

36 / 106


printf("Hello World"); // x2 imprime "Hello Word" na tela.}

x1 Incluindo biblioteca de entrada/saída.x2 Chamada à função printf, que envia para a saída padrão (o console) o texto recebido.

NotaPadronizamos que os códigos devem ser salvos dentro da pasta capitulos/code/,mantendo o mesmo padrão de organização das imagens.

7.7.1 Trecho de código

Exemplo de trecho de código.

#include<stdio.h>main() { printf("Hello World"); }

7.7.2 TABs, identação e estilos de códigos

Quando os códigos fontes são inseridos no livro alguns considerações precisam serem feitas:

• É possível que o seu código seja quebrado em mais de uma página, o que costuma dificultar oentendimento.

• A identação com TABs é substituída por 8 espaços.

• Se a linha do código for longa ela será quebrada em mais linhas para caber no impresso.

• A codificação dos códigos fontes deve ser utf-8 para serem inseridos no livro.

37 / 106


ImportantePara manter uma legibilidade no impresso recomendo:

• Identar código com 2 espaços

• Diminuir a quantidade de linhas vazias

• Escrever linhas pequenas, com até 60 caracteres (1 TAB equivale a 8)

• Ao invés de bloco de comentário, usar comentário de linha sobre o código.

• Preferir abrir e fechar chaves sem criar uma nova linha:

Gasta apenas uma linha

if (x>2) { printf ("x é maior do que dois");}

Legível mas gastou 3 linhas

if (x>2) { // comentário de linha aquiprintf ("x é maior do que dois"); // identação com TAB

}

Legível mas gastou 6 linhas

/* evitar bloco de comentário em linha própria*/if (x>2){

printf ("x é maior do que dois"); // TAB e comentário ←↩deixando linha longa.

}

7.8 Listas

BULLETED

• bullet

• bullet

– bullet

– bullet

• bullet

– bullet

– bullet

* bullet

* bullet· bullet

38 / 106


· bullet[Error: itemizedlist too deeply nested]

· bullet

* bullet

– bullet

• bullet

BULLETED 2

• bullet

– bullet

ORDERED

1. number

2. number

a. letter

b. letter

3. number

a. loweralpha

b. loweralpha

i. lowerromanii. lowerroman

A. upperalphaB. upperalpha

[Error: orderedlist too deeply nested]C. upperalpha

iii. lowerroman

c. loweralpha

4. number

ORDERED 2

a. letter

b. letter

a. letter2

b. letter2

1. number

39 / 106


2. number1. number22. number23. number24. number2

3. number

c. letter2

c. letter

LABELED

Termo 1Definição 1


Termo 2.1Definição 2.1








LABELED 2



40 / 106


Tabela 7.1: Labeled horizontal

Termo 1 Definição 1. ashkjahgsjhagkjshgkjhag jhasgjh agfsjhgafsjhgafhsgfjasjh ajshgkjahsg khagskjhagskjhsak.

Termo 2 Definição 2 kajshkljahskjah lskjha lkjshlaksjlkagsksjahgskjhgk ahsgka lashlkajhsl kjahlskjahls.

Q&A

1. Questão 1

Resposta da pergunta 1 aqui.

2. Questão 2

Resposta da pergunta 2 aqui.

INDENT IS OPTIONAL

• bullet

– another bullet

1. number1. again number

a. lettera. again letterb. letter

2. number

– bullet

• bullet

BREAK TWO LISTS

1. number

2. number

Independent paragraph break list.

1. number

HEADER BREAK LIST TOO

1. number

41 / 106


1. List block define list boundary too

2. number

3. number

1. number

2. number

CONTINUATION

• bullet continuation

1. number continuation

– bullet

literal continuation

a. letterNon-literal continuation.

any block can be

included in list

Last continuation.

LIST BLOCK ALLOW SUBLIST INCLUSION

• bullet

– bullet

* bullet

* bullet

– bullet

• bullet

1. number

a. letter1. numbera. letter

b. letter

2. number

7.9 Tabelas

You can fill table from CSV file using include:: macros inside table.

42 / 106


Tabela 7.2: An example table

Col 1 Col 2 Col 31 Item 1 a2 Item 2 b3 Item 3 c6 Three items d

Tabela 7.3: CSV data, 15% each column

1 2 3 4a b c dA B C D

ID FName LName Address Phone1 Vasya Pupkin London +1232 X Y A,B 45678

Tabela 7.4: Multiline cells, row/col span

Date Duration Avg HR Notes22-Aug-08

10:24157 Worked out MSHR

(max sustainableheart rate) by goinghard for this interval.

22-Aug-08 152 Back-to-back withprevious interval.

24-Aug-08 none

7.10 Matemática

Ver https://asciidoc.googlecode.com/hg/doc/latexmath.txt e comparar comhttp://www.methods.co.nz/asciidoc/latexmath.pdf

C = α +βY γ + ε

EQUATION 7.1: Uma equação qualquer.

Colocar equação no meio do texto, C = α + βY γ + ε , também é possível. Mas o mais legal éreferencia-la (ver Equação 7.1 [43]).

43 / 106

https://asciidoc.googlecode.com/hg/doc/latexmath.txt

http://www.methods.co.nz/asciidoc/latexmath.pdf


7.11 Comentários

O Comentário é um importantíssemo recurso do nosso processo.

Como inserir um comentário

////Um comentário inicia com 4 barrase finaliza com outras 4 barras.Tudo que for inserido no meio nãoserá impresso.////

44 / 106


Capítulo 8

Desenhando gráficos

A elaboração de gráficos pode ser agilizada quando ela é feita dentro do próprio documento que estásendo escrito.

Através do graphviz é possível gerar várias imagens (Seção 8.1 [45]).

DOCUMENTAÇÃO DO GRAPHVIZ

Grafoshttp://www.graphviz.org/pdf/neatoguide.pdf

Dígrafoshttp://www.graphviz.org/pdf/dotguide.pdf

Layoutshttp://code.google.com/p/asciidoc/source/browse/filters/graphviz/asciidoc-graphviz-sample.txt?name=8.6.8

8.1 Exemplos do graphviz

Nas seções a seguir alguns exemplos de gráficos.

DicaNo site http://www.graphviz.org/Gallery.php temos uma galeria de gráficos que podem serbaixados e customizados.

8.1.1 Grafos

["graphviz", "grafo.png", width="30%"].Exemplo de grafo.--------------------------------------------------------------------- ←↩

graph G {n0 -- n1 -- n2 -- n3 -- n0;

45 / 106

http://www.graphviz.org/pdf/neatoguide.pdf

http://www.graphviz.org/pdf/dotguide.pdf

http://code.google.com/p/asciidoc/source/browse/filters/graphviz/asciidoc-graphviz-sample.txt?name=8.6.8

http://code.google.com/p/asciidoc/source/browse/filters/graphviz/asciidoc-graphviz-sample.txt?name=8.6.8

http://www.graphviz.org/Gallery.php


}--------------------------------------------------------------------- ←↩

Figura 8.1: Exemplo de grafo.

Figura 8.2: Exemplo de grafo (width="50%")

["graphviz"]--------------------------------------------------------------------- ←↩

digraph G { rankdir=LR; Graphviz->AsciiDoc->HTML}--------------------------------------------------------------------- ←↩

.Com tamanho menor["graphviz", "sample2x.png", width="60%"]--------------------------------------------------------------------- ←↩

46 / 106


digraph automata_0 {size ="4, 5";node [shape = circle];0 [ style = filled, color=lightgrey ];2 [ shape = doublecircle ];0 -> 2 [ label = "a " ];0 -> 1 [ label = "other " ];1 -> 2 [ label = "a " ];1 -> 1 [ label = "other " ];2 -> 2 [ label = "a " ];2 -> 1 [ label = "other " ];"Machine: a" [ shape = plaintext ];}--------------------------------------------------------------------- ←↩

Figura 8.3: Com tamanho menor

["graphviz", "sample3.png", "dot", width="70%"]--------------------------------------------------------------------- ←↩

digraph finite_state_machine {rankdir=LR;size="8,5"node [shape = doublecircle]; LR_0 LR_3 LR_4 LR_8;node [shape = circle];LR_0 -> LR_2 [ label = "SS(B)" ];LR_0 -> LR_1 [ label = "SS(S)" ];LR_1 -> LR_3 [ label = "S($end)" ];LR_2 -> LR_6 [ label = "SS(b)" ];LR_2 -> LR_5 [ label = "SS(a)" ];LR_2 -> LR_4 [ label = "S(A)" ];LR_5 -> LR_7 [ label = "S(b)" ];LR_5 -> LR_5 [ label = "S(a)" ];

47 / 106


LR_6 -> LR_6 [ label = "S(b)" ];LR_6 -> LR_5 [ label = "S(a)" ];LR_7 -> LR_8 [ label = "S(b)" ];LR_7 -> LR_5 [ label = "S(a)" ];LR_8 -> LR_6 [ label = "S(b)" ];LR_8 -> LR_5 [ label = "S(a)" ];}--------------------------------------------------------------------- ←↩

48 / 106


Figura 8.4: Tipo barramento

8.2 Outros gráficos

livro__3.svg

8.2.1 Diagrama de Sequência

AJUDA

• http://blockdiag.com/en/seqdiag/examples.html

livro__4.svg

49 / 106

http://blockdiag.com/en/seqdiag/examples.html


8.2.2 Diagramas usando ditaa

Figura 8.5: Blocks

Figura 8.6: Round corners

50 / 106


Figura 8.7: Color

Figura 8.8: Color codes

Figura 8.9: Dashed lines

51 / 106


Figura 8.10: Point markers

Figura 8.11: Text handling

Figura 8.12: Flowchart

52 / 106


Figura 8.13: Shapes

Resultadohttp://wiki.asciidoc-ditaa-filter.googlecode.com/hg/asciidoc-ditaa-readme.html

Fontehttps://code.google.com/p/asciidoc-ditaa-filter/source/browse/asciidoc-ditaa-readme.txt

53 / 106

http://wiki.asciidoc-ditaa-filter.googlecode.com/hg/asciidoc-ditaa-readme.html

https://code.google.com/p/asciidoc-ditaa-filter/source/browse/asciidoc-ditaa-readme.txt


Capítulo 9

Vídeos

Neste capítulo iremos aprender como inserir vídeos do youtube no nosso processo.

9.1 Problema da inserção de vídeos

O nosso modelo de produção gera arquivos para PDF/Impressão e HTML. Na geração para o HTMLé desejável que o vídeo possa ser imbutido

HTMLÉ desejável poder embutir o vídeo na página, de forma que basta clicar para executar o vídeona própria página.

PDFNo pdf é desejável que haja um link, que o usuário possa clicar e o vídeo ser aberto automati-camente. Neste caso, o endereço completo do livro não necessário apenas o link é importante.

ImpressoNo impresso o link apenas não é suficiente, temos que escrever o endereço completo(https://github.com/edusantana/producao-computacao-ead-ufpb), para que o usuário possadigita-lo no navegador. Um adicional é que podemos gerar um qrcode, que o usuário possautilizar em um disposito móvel para assistir o vídeo, não precisando digitar o endereço.

A nossa solução tenta atender a estes desejos.

9.2 Solução adota

O resultado abaixo é exibido diferente, de acordo com a fonte que você está consultando. No impressoou PDF irá aparecer o QRCode, no html teremos o vídeo incorporado:

Exemplo de inserção de vídeo entitulado "Início rápido":

.Início rápido: http://youtu.be/uDMs-TyjSekifdef::livro-pdf[][qrcode, size=10, scaledwidth="30%"]-------------------------

54 / 106




http://youtu.be/uDMs-TyjSek-------------------------endif::livro-pdf[]ifdef::livro-html[]+++<?dbhtml-include href="videos/inicio-rapido.html"?>+++endif::livro-html[]

Conteúdo de livro/videos/inicio-rapido.html

<iframe width="420" height="315" src="http://www.youtube.com/embed/ ←↩uDMs-TyjSek" frameborder="0"/>

ImportantePercebam que o link do vídeo deve ser informado em três locais diferentes: na legenda, noqrcode e html.

CuidadoQuando copiar o código de incorporação do youtube, lembre-se de remover allowfulls-creen.

CuidadoO código do video.html deve ser um xml válido. Você não pode deixar nenhuma tagaberta, <hr>,<br> → <hr/>,<br/>. Detalhes técnicos pode ser consultados emhttp://www.sagehill.net/docbookxsl/InsertExtHtml.html#CodeInPage.

9.2.1 Exemplo do vídeo

size=10

Figura 9.1: Início rápido: http://youtu.be/uDMs-TyjSek

55 / 106

http://www.sagehill.net/docbookxsl/InsertExtHtml.html#CodeInPage

http://youtu.be/uDMs-TyjSek


Capítulo 10

Git

Nesta seção mantemos referências a vários outros manuais sobre o git.

1. http://rogerdudler.github.com/git-guide/index.pt_BR.html

2. http://windows.github.com/help.html (github para o windows, em inglês)

3. http://ruby-br.org/?p=1318 (vários tutoriais)

4. http://git-scm.com/documentation (Inglês, possui vídeos)

10.1 Configurando o git com chave ssh

DicaNós recomendamos o uso do git com uma chave ssh configurada, agiliza a produção. Casovocê use o github para o Windows, você pode ignorar estes passos, pois ele configura auto-maticamente.

O git possibilita utilizar chaves ssh para conectar com o servidor. Uma vez que você configure aschaves num computador que você confia, não necessitará mais colocar a senha sempre que enviar umcommit.

Comandos para configurar git com sshcd ~/.sshssh-keygen -t rsa -C "[email protected]"

ImportanteQuando for solicitado para digitar uma senha, não coloque nenhuma senha, pressioneapenas ENTER.

Em seguida, vá no github https://github.com/settings/ssh e adicione sua chave, que é o conteúdo doarquivo ~/.ssh/id_rsa.pub.

56 / 106

http://rogerdudler.github.com/git-guide/index.pt_BR.html

http://windows.github.com/help.html

http://ruby-br.org/?p=1318

http://git-scm.com/documentation

https://github.com/settings/ssh


ImportanteEstas instruções foram extraídas de https://help.github.com/articles/generating-ssh-keys.Para maiores detalhes consulte o link (em inglês).

10.2 Configurando o git com cor no linux

Para configurar o git com cores no terminal do linux, digite o seguite comando:

git config color.ui true

10.3 Commit rápido

Para agilizar o trabalho, o seguinte comando commit e submete os arquivos alterados para o servidor:

Comitando e submetendo os arquivos modificados

git -a commit -m "mensagem do seu commit"; git push

CuidadoSomente os arquivos que já estavam adicionados. Se você criou um arquivo novo ou mesmouma nova imagem, este comando não adiciona eles.

Descobrindo endereço do repositório

git config --get remote.origin.url

10.4 Scripts

Baixe este projeto e adicione a pasta git-scripts ao seu PATH. Lembre-se de adicionar permissãode execução (Ex: chmod +x git-producao).

Quando os scripts forem copiados, você poderá executá-los da seguinte forma:

git producao "mensagem do commit"

Será o mesmo de:

git-producao "mensagem do commit"

57 / 106



10.4.1 Configuração dos scripts

Para o livro ser baixado automaticamente:

git config livro.url http://producao.virtual.ufpb.br/books/ ←↩edusantana/playground-asciidoc/livro/livro.pdf

Comando para executar um beep ao final da execução:

git config --global beep.player /usr/bin/playgit config --global beep.file ~/beep.mp3

10.4.2 git-producao

Este script:

• Commita todas as alterações realizadas nos arquivos já adicionados

– Ele não adiciona novos arquivos como imagens e código fontes

• Realiza um push (enviando as alterações para o repositório)

• Executa o comando para gerar o livro

• Baixa o livro em pdf automaticamente

• Toca um som quando terminar, caso exista o arquivo ~/beep.mp3

Após a execução do comando você só precisa acessar o link onde o arquivo foi gerado.

Execuçãogit producao "mensagem do commit"

ImportantePara que git-producao funcione, você precisa baixar o projeto utilizando o protocolo git aoinvés de https. Ver Seção 14.1 [73].Para testar o protocolo baixado digite:

git config --get remote.origin.url

Se o resultado começar com [email protected] então você está utilizando o proto-colo git, se começar com https, não irá funcionar.

10.4.3 git-producao-local

Com o ambiente de desenvolvimento off-line, permite gerar o livro localmente com diversas configu-rações.

Usage

58 / 106


git-producao-local options

options:-h This help message-c Run commit --interactive before-l Run local sync instead of git-archive during the build, ←↩

requires -b-r Run rebase --interactive before-b Build the PDF book-t Use test file instead, must be used wih -b-o Open produced PDF

DicaConfigurar um alias: git config --global alias.pl=producao-local

Como utilizar: Seção 13.2 [68].

10.4.4 git-local

O mesmo de git-producao, mas gera o livro no servidor localhost.

Execuçãogit local "mensagem do commit"

NotaApropriado para quem possui o servidor de produção executado localmente.

10.4.5 git-livro

Gera o livro do projeto localmente. Precisa estar na pasta raiz do projeto.

NotaAinda não foi implementado.

10.5 Configurações avançadas

As configurações avançadas do git podem ser consultadas em http://git-scm.com/book/en/-Customizing-Git-Git-Configuration.

59 / 106

http://git-scm.com/book/en/Customizing-Git-Git-Configuration

http://git-scm.com/book/en/Customizing-Git-Git-Configuration


10.6 Tags

A aplicação de tags permite marcar um estado do livro.

NotaMais informações podem ser consultadas em: http://git-scm.com/book/en/Git-Basics-Tagging.

10.6.1 Listando tags

git tag

Criando tags

$ git tag -a v1.4 -m ’my version 1.4’$ git tagv0.1v1.3v1.4

60 / 106

http://git-scm.com/book/en/Git-Basics-Tagging

http://git-scm.com/book/en/Git-Basics-Tagging


Capítulo 11

Outras Ferramentas

11.1 Convertendo arquivos do Word para Asciidoc

1. Salve uma cópia do arquivo do word

2. Atribua as marcações no arquivo do word:

a. titulos

b. negrito

c. itálico

d. monospace

3. Salve o arquivo como .txt

4. Separe cada parágrafo com uma linha em branco

a. No gedit você pode localizar e substituir \n por \n\n.

5. Execute o comando fold para quebrar as linhas em 80 caracteres:

Comando para dividir parágrafos em 80 caracteresfold -w 80 -s nome-do-arquivo.txt > nome-do-arquivo.asc

ImportanteNão utilize o comando fold redirecionando a saída para o mesmo arquivo, casocontrário você perderá o conteúdo dele. No exemplo acima temos dois arquivos, um.txt e outro .asc.

11.2 Formatando código fonte

Comando para formatar código fonte

astyle --style=java -s2 *.c

61 / 106


Parte III

Utilizando o processo

62 / 106


Nesta parte documentamos como utilizar o processo. Focamos em descrever o processo na visão dosautores, que possuem pouco conhecimento sobre o git.

63 / 106


Capítulo 12

Processo para os autores

Neste capítulo iremos descrever a parte do processo de produção dos livros para os autores.

12.1 Pense no livro como um software

A principal noção que precisamos ter ao produzir um livro, neste processo, é que o processo deprodução dos livros são similares aos processos de produção de softwares.

• O livro terá versões em produção (instáveis) e releases (estáveis)

• Cada versão do livro terá um release note, descrevendo quais as modificações da versão atual paraa versão anterior.

• Os livros estarão em constante atualização, mesmo após sua publicação.

• Os leitores poderão baixar todas as versões do livro, em especial: 1) a última release e 2) a versãoem produção.

• Os autores do livro não são os donos dos livros. Novos autores poderão serem convidados a atuali-zarem o livro, inclusive incluindo novos capítulos ou atualizando os capítulos atuais.

• O editor e o revisor irão trabalhar em conjunto com os autores para auxiliarem na produção do livro.

• Os erros são inerentes ao processo de produção, quando identificados eles poderão ser corrigidospor qualquer um dois envolvidos na produção.

• Os leitores dos livros serão incentivados a submeterem erros, sugestões e correções do livro, mesmoapós sua publicação.

• O texto e código do livro será gerenciado por sistema de controle de versão (o git).

ImportanteNesta seção é importante que você, autor, compreenda que o processo da produção do livrose importa com as modificações que estão sendo realizadas, será necessário registrar, dealguma forma, o que está sendo alterando durante todas as fases de produção do livro. Istoserá feito através dos issues (veremos mais adiante).

64 / 106


12.2 Planjenando da produção do livro

O processo de produção do livro, como qualquer outro processo de produção, necessita de planeja-mento e acompanhamento da execução.

O editor do livro irá criar um Issue no repositório do seu livro com o seguinte conteúdo:

Planejamento & Acompanhamento da produção do livroAguardando envio da estrutura inicial do livro e planejamento deentrega dos capítulos.

Nesta etapa você deverá commitar uma estrutura de capítulos que planeja executar. Basta que vocêcopie o arquivo novo-capitulo.asc e salve uma cópia para cada capítulo, renomeando a cópiacom o nome desejado para o capítulo.

Em seguida você deverá informar o planejamento de entrega dos capítulos. Você poderá fazer isto deduas formas:

• Acessar o Issue de planejamento e informar o planejamento de entrega dos capítulos no próprioissue.

• Enviar o planejamento para o editor através de e-mail. Quando ele receber, ele mesmo irá atualizaro issue informando o planejamento.

Exemplo de planejamento10/6 Cap_1_Introducao24/5 Cap_2_ModelosMetodologicos31/5 Cap_3_AtividadeCientifica20/6 Cap_4_Conclusoes

NotaUtilize o número do issue de planejamento para commitar a estrutura inicial.

12.3 Trabalhando num issue

O processo precisa manter um registro do que foi alterado em cada versão do livro, desta forma, todaalteração precisa ser registrada previamente através da referenciação de um issue.

Toda alteração no livro precisa ter sido registrada num issue anteriormente.

Para cada capítulo que será escrito deverá ser criado um issue para a elaboração dos capítulos. Onúmero do issue deverá ser referenciado na primeira linha de cada mensagem de commit, ex:

Títulos do issues de elaboração dos capítulos.Elaboração do Capítulo Introdução #2.Elaboração do Capítulo Modelos Metodológicos #3.Elaboração do Capítulo Atividade Científica #4.Elaboração do Capítulo Conclusões #5

65 / 106


Exemplo de mensagem de commit referenciando o issue #2

Escrevendo capítulo introdução - #2

Restante da mensagem aqui... (opcional)

NotaOs issues serão criados pelo editor, mas o autor precisa referenciar o número do issue nasmensagens de commit.

12.4 Recebendo feedback durante a produção

Assim que você iniciar sua produção o editor irá recomendar alterações no livro através da criação deissues.

Estas alterações costumam ser dicas de formatação do asciidoc, correções para adequação do padrãode produção ou até mesmo sobre apresentação do conteúdo.

Quando você for realizar as alterações recomendadas pelo editor através dos isses, lembre-se de refe-renciar o número do issue no commit da atualização.

12.5 Finalizando um capítulo

A finalização de um issue de produção de capítulo indica a conclusão da escrita do capítulo pelo autor.

Quando você finalizar a escrita de um capítulo deverá fechar o issue ou notificar o editor por e-mailna finalização.

Quando a escrita de um capítulo for finalizada, um issue de revisão do capítulo será criado pelo editor.

NotaVocê, autor, após finalizar um capítulo deverá se concentrar nos demais capítulos. O ca-pítulo finalizado irá para revisão e depois uma versão do livro será gerada com o conteúdorevisado.

Após a revisão do capítulo, o editor irá gerar uma release do livro com o capítulo concluído e revisado.Nesta release também estarão presentes os demais capítulos, ainda em produção. O release note daversão do livro irá indicar o estado dos capítulos.

12.6 Finalizando o livro e obtendo o ISBN

Após a finalização de todos os capítulos o editor irá solicitar o ISBN da obra e publicar a primeiraedição do livro.

66 / 106


12.7 Fase de Pós-produção

Quando o processo de produção do livro é finalizado a etapa de pós-produção é iniciada.

Nesta etapa os leitores irão submeter erros, sugestões e críticas. O autor do livro também poderádesejar atualizar o texto.

Nesta etapa será criado um issue para cada modificação que será realizada no livro, e serão agendadosMinestones para geração de novas versões do livro.

O autor terá liberdade de atualizar o livro, mas sempre lembrando de criar um issue e associar onúmero do issue na mensagem de commit.

O editor é o responsável por gerar as versões do livro, que poderá ocorrer sempre que um leitorsubmeter alguma correção. Caso você realizou alguma alteração, pode solicitar que ele gere umanova release do livro.

67 / 106


Capítulo 13

Autores avançados

13.1 Instalar o ambiente de produção local

Os autores avançados poderão optar por instalar o ambiente de desenvolvimento off-line (Capítulo 15[75]).

13.2 Utilizar o git-producao-local

Documentação pode ser vista em Seção 10.4.3 [58]. Esta seção assume que o alias foi configuradoconforme descrito na documentação.

Consultando a documentação

git producao-local -h

Consultando a documentação, com o alias configurado

git pl -h

Ajuda

git-producao-local options

options:-h This help message-c Run commit --interactive before-l Run local sync instead of git-archive during the build, ←↩

requires -b-r Run rebase --interactive before-b Build the PDF book-t Use test file instead, must be used wih -b-o Open produced PDF

A ordem dos parâmetros não é importante.

68 / 106


13.2.1 Gera o livro do arquivo de teste sem realizar commit

git pl -bolt

Para os autores avançados, este seria o principal comando.

l (local sync)Copia os arquivos do diretório local para outro intermediário.

b (build)Gera o livro a partir do diretório intermediário.

t (test)Utilize o arquivo de teste livro/test.adoc ao invés de livro/livro.asc.

o (open)Após geração abre o arquivo pdf para leitura.

CARACTERÍSTICAS

• Rápido

• Focaliza no que está sendo produzido, o autor atualiza o arquivo de teste para conter apenas oscapítulos que está trabalhando.

• Mascara erro pois podem haver arquivos não comitados, como o livro é gerado por uma sincroni-zação local não há garantias que o livro seja gerado em outro local.

13.2.2 Commita, gera o livro com base no commit

git pl -cbo

c (commit)Realiza um commit e copia os arquivos do commit para o diretório intermediário.

b (build)Gera o livro a partir do diretório intermediário.

o (open)Após geração abre o arquivo pdf para leitura.

CARACTERÍSTICAS

• Produz o livro inteiro

• Produz o livro com base no que foi commitado localmente

• Abre o livro após a geração

• Requer mensagem do commit

69 / 106


13.2.2.1 Realizando um rebase antes

git pl -cbor

Esta é uma modificação incluindo o rebase.

CARACTERÍSTICAS

• As mesmas da anterior

• Realizar um rebase para unir os commits e editar uma mensagem significativa de commit.

• Utilizado ao final de alguma atividade.

70 / 106


Parte IV

Implementação do processo

71 / 106


Nesta parte documentamos a implementação do processo. Ela possui a dupla função de documentar oprocesso e de instruir como outras pessoas podem replicar a infraestrutura necessária para produçãodos materiais.

72 / 106


Capítulo 14

Criando um novo livro

No github, criamos um novo repositório com o nome da disciplina com o sufixo -livro, que tem afinalidade apenas de marcar quais repositórios estão em conformidade com este modelo.

Exemplo de repositório: https://github.com/edusantana/introducao-a-programacao-livro

14.1 Baixando o projeto

Se você possui o ssh configurado pelo github (preferível), baixe o projeto utilizando o protocolo git:

git clone [email protected]:edusantana/introducao-a-programacao-livro.git

Caso contrário, baixe utilizando o protocolo https:

git clone https://github.com/edusantana/introducao-a-programacao-livro.git

ImportanteA configuração do git está descrita em https://help.github.com/articles/set-up-git. A configu-ração avançada, com o ssh está disponível em: https://help.github.com/articles/generating-ssh-keys. Os comandos desta parte utilizam a configuração com ssh.Para utilizar a ferramenta git-producao (Seção 10.4.2 [58]), você precisa baixar o projeto daprimeira forma, com o protocolo git ao invés do https.

14.2 Criando a estrutura inicial do projeto

Os projetos devem possuir arquivos modelos para que os autores possam iniciar o trabalho com faci-lidade (Seção 4.2 [20]).

Os arquivos que compõe a estrutura inicial de um novo projeto serão mantidos no repositório destelivro. Baixe o projeto deste livro e copie os arquivos dentro do novo projeto.

$ git clone [email protected]:edusantana/producao-computacao-ead- ←↩ufpb.git

$ git clone [email protected]:seu-usuario/seu-projeto-livro.git$ cd seu-projeto-livro

73 / 106

https://help.github.com/articles/set-up-git




$ rsync -r ../producao-computacao-ead-ufpb/livro/estrutura- ←↩inicial/ .

$ cp ../producao-computacao-ead-ufpb/.gitignore .$ cp ../producao-computacao-ead-ufpb/.gitattributes .$ git rm README.md ; git add . ; git commit -m "Commit inicial"; ←↩

git push

14.2.1 Gerando um pdf do livro (off-line)

O seguinte comando gera o pdf do livro:

~/ambiente/asciidoc-8.6.8/a2x.py -v -f pdf livro.asc

NotaEste pdf gerado não possui os estilos utilizados na versão final do livro, mas serve para teruma idéia de como será gerado.

14.2.2 Gerando o pdf do livro (off-line estilizado)

O PDF estilizado utiliza um estilo (Seção 15.6 [77]) personalizado na geração.

O código para geração final do PDF é executado pelo script de geração contido no servidor web,disponível em: https://github.com/edusantana/producao-computacao-ead-ufpb/blob/master/cgi/pull-pdf.py

DicaQuem utiliza o ambiente para geração off-line pode ignorar a instalação deste estilo, uma vezque não há garantias que ele permaneça o mesmo ao longo da produção. É importante queos autores do livro compreendam que o visal do livro não é responsabilidade deles.

74 / 106

https://github.com/edusantana/producao-computacao-ead-ufpb/blob/master/cgi/pull-pdf.py

https://github.com/edusantana/producao-computacao-ead-ufpb/blob/master/cgi/pull-pdf.py


Capítulo 15

Instalando ambiente para desenvolvimentooff-line

Nas seções a seguir temos instruções para instalação do ambiente off-line.

ImportanteEste manual somente descreve as instruções para a instalação do ambiente off-line para olinux.

15.1 Instalando o git

Necessário para baixar e enviar os textos e imagens produzidas.

sudo apt-get install git-core

15.2 Instalando o mercurial

O mercurial não é necessário, mas será utilizado para baixar a nova versão do asciidoc.

sudo apt-get install mercurial

15.3 Instalar o latex

A produção do livro utiliza uma cadeia de várias ferramentas, uma delas é o latex.

sudo apt-get install texliveousudo apt-get install texlive-full

75 / 106


15.4 Instalar o asciidoc e dbaltex

Depois serão removidos, mas é importante porque instala as dependências.

sudo apt-get install asciidocsudo apt-get install dblatex

15.4.1 Removendo e atualizando o asciidoc e dbaltex

Em seguida, precisaremos instalar as novas versões do asciidoc e dblatex.

sudo apt-get remove asciidocsudo apt-get remove dblatex

15.4.2 Instala nova versão do dblatex

Instalando a nova versão do dblatex através do easy_install do python.

sudo apt-get install python-setuptoolssudo easy_install dblatex

NotaA instalação irá ocorrer um diretório parecido com: /usr/local/lib/python2.7/dist-packages/dblatex-0.3.4-py2.7.egg/share/doc/dblatex

15.4.3 Instala nova versão do asciidoc

Baixando e instalando a nova versão do asciidoc.

mkdir ~/ambientecd ~/ambientehg clone -r 8.6.8 https://asciidoc.googlecode.com/hg/ asciidoc ←↩

-8.6.8

ImportanteA nova versão é necessária principalmente devido a uma funcionalidade que permite ostítulos das seções possuirem acentos (atributo :ascii-ids:).

15.5 graphviz

Para gerar gráficos dentro do texto (Capítulo 8 [45]).

sudo apt-get install graphviz

76 / 106


15.6 Instalando estilo do dblatex para geração do pdf estilizado

O nosso estilo personalizado está disponível em: https://github.com/edusantana/producao-computacao-ead-ufpb/tree/master/dblatex-computacao-ufpb

O processo de instalação de estilos se encontra descrito no manual do dblatex, na seção Adding a NewFormatting Style.

Path: /usr/local/lib/python2.7/dist-packages/dblatex-0.3.4-py2.7.egg/share/doc/dblatex/manual.pdf

Instalação no servidor

mkdir ~/gitreposcd ~/gitreposgit clone [email protected]:edusantana/producao-computacao-ead-ufpb ←↩

.gitsudo mkdir /var/www/.dblatexsudo rsync -r ~/gitrepos/producao-computacao-ead-ufpb/dblatex- ←↩

computacao-ufpb/* /var/www/.dblatex/

15.7 Instalação dos scripts cgi

O Servidor da Produção funciona através de scripts cgi python, que recebem as solicitações html eexecutam os comandos para a geração do livro e slides.

A configuração do Servidor CGI foi realizada seguindo as intruções de http://jonathanferretti.com/-blog/?p=76.

Após a configuração do servidor e o projeto deste manual baixado em ~/gitrepos, os seguintescomandos instalam os scripts:

cd ~/gitrepossudo cp -v producao-computacao-ead-ufpb/cgi/*.py /var/www/cgi- ←↩

bin/sudo cp -v producao-computacao-ead-ufpb/cgi/*.html /var/www/

15.7.1 Dependencia dos scripts

15.7.1.1 sejda

More information can be found at issue #17.

Download sejda (http://www.sejda.org) and install it at ~/ambiente/sejda

Downloading and installing

cd ~/ambientewget https://bitbucket.org/torakiki/sejda/downloads/sejda- ←↩

console-1.0.0.M7-bin.zipunzip sejda-console-1.0.0.M7-bin.zipchmod -R go+rx ~/ambiente/sejda-console-1.0.0.M7ln -s sejda-console-1.0.0.M7 sejda

77 / 106

https://github.com/edusantana/producao-computacao-ead-ufpb/tree/master/dblatex-computacao-ufpb

https://github.com/edusantana/producao-computacao-ead-ufpb/tree/master/dblatex-computacao-ufpb

http://jonathanferretti.com/blog/?p=76

http://jonathanferretti.com/blog/?p=76

https://github.com/edusantana/producao-computacao-ead-ufpb/issues/17

http://www.sejda.org


ImportanteIt requires java.

15.8 Instalando filtros do asciidoc

Instalando dependencia

sudo apt-get install gcc python-devsudo apt-get install libjpeg libjpeg-dev libfreetype6 ←↩

libfreetype6-dev

15.8.1 diag filter for Asciidoc

Seguir as intruções do site para instalação:

Instruções

sudo easy_install blockdiag seqdiag actdiag nwdiag packetdiagwget https://asciidoc-diag-filter.googlecode.com/files/ ←↩

diag_filter.zip~/ambiente/asciidoc-8.6.8/asciidoc.py --filter install ←↩

diag_filter.zip

15.8.2 ditaa filter for AsciiDoc

Seguir as intruções do site para instalação: http://code.google.com/p/asciidoc-ditaa-filter/

Instruções

sudo apt-get install ditaawget http://asciidoc-ditaa-filter.googlecode.com/files/ditaa- ←↩

filter-1.1.zip~/ambiente/asciidoc-8.6.8/asciidoc.py --filter install ditaa- ←↩

filter-1.1.zip

15.8.3 ditaa filter for AsciiDoc

Seguir as intruções do site para instalação: http://code.google.com/p/asciidoc-ditaa-filter/

Instruções

sudo apt-get install qrencodewget http://asciidoc-qrencode-filter.googlecode.com/files/qrcode ←↩

-filter-1.0.zip~/ambiente/asciidoc-8.6.8/asciidoc.py --filter install qrcode- ←↩

filter-1.0.zip

78 / 106

http://code.google.com/p/asciidoc-ditaa-filter/

http://code.google.com/p/asciidoc-ditaa-filter/


15.8.4 Criando link simbólico para o .asciidoc

Este link é necessário pois os filtros são instalados no home do usuário.

Comandos para criar o link simbólico

cd /var/www/sudo ln -s /home/eduardo/.asciidoc/

79 / 106


Capítulo 16

Gerenciando versões dos livros

Durante o ciclo de vida dos livros serão elaboradas diversas versões dos livros, este capítulo descrevecomo gerenciar suas versões.

16.1 Sobre o versionamento dos livros

NotaA estratégia de versionamento dos livros foram baseados em http://semver.org/spec/-v2.0.0.html e https://medium.com/i-m-h-o/2aa5cff10010.

O número da edição evolui com o livro, a primeira edição, a segunda etc.. Mas quando lançar umaedição revisada ao invés de uma nova edição?

RESUMO DA ESTRATÉGIA DE VERSIONAMENTO

Summary

Given a version number MAJOR.MINOR.PATCH, increment the:

1. MAJOR version when you make incompatible API changes,

2. MINOR version when you add functionality in a backwards-compatible manner,and

3. PATCH version when you make backwards-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to theMAJOR.MINOR.PATCH format.

16.2 Antes de iniciar

16.2.1 Testando a configuração

80 / 106

http://semver.org/spec/v2.0.0.html

http://semver.org/spec/v2.0.0.html

https://medium.com/i-m-h-o/2aa5cff10010


PROTOCOLO=‘git config --get remote.origin.url‘;\PROJECT=‘git config --get remote.origin.url | cut -f 2 -d / | ←↩

cut -f 1 -d .‘;\LIVRO_EDICAO=‘grep ’<edition>.*</edition>’ docinfo.xml |xmllint ←↩

--xpath "string(//edition)" -‘;\LIVRO_URL=‘git config --get livro.url‘;\echo Protocolo $PROTOCOLO;\echo Projeto $PROJECT;\echo Edição $LIVRO_EDICAO;\echo livro.url $LIVRO_URL

Resultado esperado

Protocolo [email protected]:edusantana/calculo-diferencial-e- ←↩integral-livro.git

Projeto calculo-diferencial-e-integral-livroEdição v0.8.2livro.url http://producao.virtual.ufpb.br/books/edusantana/ ←↩

calculo-diferencial-e-integral-livro/livro/livro.pdf

16.2.2 Configurando caso o resultado não parecido com o esperado

Nesta seção serão apresentados vários comandos para realizas as atividades, alguns pré-requisitos sãonecessários:

16.2.2.1 Configurando o protocolo

Caso o protocolo comece com https, quer dizer que precisa ser alterado para algo parecido com:

git config remote.origin.url [email protected]:edusantana/producao- ←↩computacao-ead-ufpb.git

16.2.2.2 Configurando livro.url

O url do livro pdf deve estar configurado

git config livro.url http://producao.virtual.ufpb.br/books/.../ ←↩livro/livro.pdf

CuidadoA maioria dos comandos desta seção espera que você esta dentro da pasta livro, ondereside o arquivo docinfo.xml.

81 / 106


16.3 Número da versão

A versão atual do livro é definida dentro do arquivo livro/docinfo.xml.

DicaUm exemplo deste arquivo pode ser visto em: https://github.com/edusantana/producao-computacao-ead-ufpb/blob/master/livro/estrutura-inicial/livro/docinfo.xml.

<edition>v1.0.0</edition>

16.4 Preparando o livro para a gráfica

Quando o livro é enviado para a gráfica, marcamos uma tag no repositório..

16.4.1 Verifique pendências de revisão

Busque no texto por TODO, FIXME, XXX e REV. Você pode utilizar o script git-revisao paraisso.

16.4.2 Verifique pendências no issue track do projeto

Verifique no github do seu projeto se há issue pendentes que devem ser realizados na versão que vocêestá fechando.

16.4.3 Verifique as versões anteriores

1. Acesse a página do seu prejeto e entre no link releases.

2. Verifique as últimas versões do livro.

16.4.4 Verificar o número da versão

No diretório livro (que contém o arquivo docinfo.xml), execute o comando:

Comando para verificar a versão e as revisões dos livrosgrep ’<edition>.*</edition>’ docinfo.xml;grep ’<revnumber>.*</ ←↩

revnumber>’ docinfo.xml

AtençãoCertifique-se de que esteja dentro do diretório livro, que contem o arquivodocinfo.xml.

82 / 106

https://github.com/edusantana/producao-computacao-ead-ufpb/blob/master/livro/estrutura-inicial/livro/docinfo.xml

https://github.com/edusantana/producao-computacao-ead-ufpb/blob/master/livro/estrutura-inicial/livro/docinfo.xml


O resultado esperado é o número da edição, contido no arquivo livro/docinfo.xml:

<edition>v1.0.0</edition>

ImportanteAtualize o número da edição apropriadamente antes de continuar.

16.4.5 Atualize o histórico de revisão

O histórico de revisão é importante para que pessoas que já leram o livro possam saber o que mudou.

<revision><revnumber>v1.0.0</revnumber><date>Março de 2013</date><authorinitials>Eduardo Santana</authorinitials><revremark>

Primeira versão do livro.</revremark>

</revision>

O valores de <revnumber> devem ser os mesmos assumidos por <edition>.

Lembre também de:

• Atualizar a data

• Texto de revremark indicando o que foi alterado.

16.4.5.1 Atualizando o revmark e gerando o release notes

O textp do release notes (que será necessário mais adiante) será o mesmo de revmark.

Consulte os títulos do log para gerar o texto de revmark, substituindo v0.1.0 pela última versãogerada:

Consultando logs dos commits

git log --format="- %s" v0.1.0..HEAD

Atualize o revmark tomando como base os logs:

Exemplo de revmark atualizado

<revision><revnumber>v1.0.0</revnumber><date>12/03/2014</date><authorinitials>Eduardo</authorinitials><revremark>

- Como baixar o guia #2- Atualização do readme #2

83 / 106


- Comando curl para baixar livros ficando melhor no pdf #2- Mudança de repositório #2- Inclusão de banco-de-dados-livro- Se acessar webconf fora do horário- Comando único para baixar todos livros- Reformulação do guia para a WebConferência de Produção dos ←↩

Livros #2</revremark>

</revision>

16.4.6 Atualize a ficha catalográfica

• Atualize a edição da ficha catalográfica

• Atualize a quantidade de páginas na ficha

• Gere o arquivo editora.pdf

16.4.7 Verificando se há alterações pendentes

Comando para verificar se há alterações não enviadasgit status -s -b

Enviando alterações realizadasgit commit --interactive; git push

16.4.8 Gerando o livro

Antes de aplicar a tag é importante gerar novamente o livro, para se certificar que as alterações foramincorporadas.

LIVRO_EDICAO=‘grep ’<edition>.*</edition>’ docinfo.xml |xmllint -- ←↩xpath "string(//edition)" -‘;\

~/bin/git-producao "Gerando livro $LIVRO_EDICAO"

16.4.9 Aplicando uma tag

AtençãoAntes de aplicar uma tag você deve se certificar que não há alterações não comitadas (Se-ção 16.4.7 [84]).

A tag aplicada será o resultado do comando:

Visualizar edição do livro

84 / 106


LIVRO_EDICAO=‘grep ’<edition>.*</edition>’ docinfo.xml |xmllint -- ←↩xpath "string(//edition)" -‘; echo Edição do livro: $LIVRO_EDICAO

O comando a seguir irá aplicar uma tag, será solicitado informar uma mensagem ao cadastrar a tag.

Comando para aplicar a tagecho "Aplicando tag...";\LIVRO_EDICAO=‘grep ’<edition>.*</edition>’ docinfo.xml |xmllint -- ←↩

xpath "string(//edition)" -‘;\git tag -a $LIVRO_EDICAO -m "Gerando versão $LIVRO_EDICAO";git tag

ImportanteA aplicação de tag é uma operação no repositório local, será necessário submeter a tag parao github depois (Seção 16.4.12 [85]).

16.4.10 Excluindo uma tag

Caso você tenha criado uma tag e deseja excluí-la, utilize o seguinte comando:

LIVRO_EDICAO=‘grep ’<edition>.*</edition>’ docinfo.xml |xmllint -- ←↩xpath "string(//edition)" -‘;git tag -d $LIVRO_EDICAO;git tag

NotaÉ seguro criar e remover uma tag em seguida.

16.4.11 Verificando a tag aplicada

LIVRO_EDICAO=‘grep ’<edition>.*</edition>’ docinfo.xml |xmllint -- ←↩xpath "string(//edition)" -‘; git show $LIVRO_EDICAO

16.4.12 Submetendo tag para o github

git push origin --tags

16.5 Gerando versão do livro

ImportantePor enquanto não foi implementado nenhum controle para gerar o livro numa versão fora daHEAD.

85 / 106


Gere o livro novamente.

CuidadoAntes de executar os comandos a seguir certifique-se que passou no testes da configuração(Seção 16.2.1 [80]).

CuidadoBaixe o livro utilizando o wget link-do-livro.pdf para evitar problemas com chacheno navegador. O repositório precisa está configurado com SSH.

NotaRenomei o arquivo para o seguinte nome: disciplina-livro-vX.Y.Z.pdfComandos para baixar e renomear o livro

PROJECT=‘git config --get remote.origin.url | cut -f 2 -d ←↩/ | cut -f 1 -d .‘;\

LIVRO_EDICAO=‘grep ’<edition>.*</edition>’ docinfo.xml | ←↩xmllint --xpath "string(//edition)" -‘;\

LIVRO_URL=‘git config --get livro.url‘;\mkdir -p ~/releases/$PROJECT;\cd ~/releases/$PROJECT;\rm -rf livro.pdf;\wget $LIVRO_URL;\mv livro.pdf $PROJECT-$LIVRO_EDICAO.pdf

16.6 Disponibilizando a release do livro

NotaAjuda sobre como disponibilizar o livro nas releases do github: https://help.github.com/-articles/creating-releases e https://help.github.com/categories/85/articles

1. No site do seu projeto no github, acesse o página de releases.

NotaUma lista contendo as releases do livro estarão disponíveis lá.

2. Acesse a sua release

3. Clique em Draft release notes or downloads

86 / 106

https://help.github.com/articles/creating-releases

https://help.github.com/articles/creating-releases

https://help.github.com/categories/85/articles


4. Baixe o livro gerado

5. Renomei o livro colocando o nome do livro e versao (Ex: nome-do-livro-vX.Y.Z.pdf)

6. Anexo o arquivo pdf neste tela

7. Caso o livro não seja um rasculho, marque como pré-release.

8. Clique Update release

9. Atualize o texto de release com o conteúdo de revmark (Seção 16.4.5.1 [83])

16.6.1 Atualizando livros.txt

Atualize livros.txt que mantém atualizando todas as últimas releases de livros do curso.

16.6.2 Publicando atualização no facebook do curso

Toda vez que uma nova release é gerada deve ser gerado uma publicação no facebook do curso.

16.7 Criando estrutura de CD para enviar para a gráfica

16.7.1 Criando estrutura inicial do cd

Mensagem para ser gravada no CD-ROM:

LEIA-ME-GRAFICA.txt

Este CD-ROM contém os arquivos necessários para a impressão do(s ←↩) livro(s).

* O(s) livro(s) estão organizados em pastas

* O nome da pasta corresponde ao [nome-do-livro]-[versão-do- ←↩livro]

* Cada pasta possui:

** Um arquivo ’livro.pdf’ que corresponde ao livro

** Um diretório ’capa’ contendo a arte da capa do livro

Em caso de dúvia contactar:

Nome do responsável <[email protected]>Telefone: (XX) XXXX-XXXX (operadora)

Comando para preparar

PROJECT=‘git config --get remote.origin.url | cut -f 2 -d / | cut -f 1 ←↩-d .‘

LIVRO_EDICAO=‘grep ’<edition>.*</edition>’ docinfo.xml |xmllint -- ←↩xpath "string(//edition)" -‘

87 / 106

https://github.com/edusantana/guia-geral-ead-computacao-ufpb/edit/master/livro/capitulos/shared/livros.txt

https://www.facebook.com/pages/Licenciatura-em-Computa%C3%A7%C3%A3o-a-Dist%C3%A2ncia-UFPB-Virtual/472766296128281?fref=ts


mkdir -p ~/temp/grafica/$PROJECT-$LIVRO_EDICAO/capa

cd ~/temp/grafica

wget https://github.com/edusantana/producao-computacao-ead-ufpb/raw/ ←↩master/livro/capitulos/code/grafica/LEIA-ME-GRAFICA.txt

Atualize o arquivo LEIA-ME-GRAFICA.txt para conter os dados de contato apropriados.

16.7.2 Copiando os arquivos para dentro dos diretórios

16.7.2.1 Baixe os livros para os diretórios respectivos

Dentro do diretório do livro, baixe o livro.pdf com o wget.

Baixando o livro

wget http://producao.virtual.ufpb.br/books/edusantana/introducao-a- ←↩computacao-livro/livro/livro.pdf

16.7.2.2 Copie os arquivos das capas

Copie os arquivos das capas dos livros para dentro das pastas correspondentes.

16.8 Gerando a imagem do cd

mkisofs -J -R -o ~/temp/grafica-livros.iso ~/temp/grafica

88 / 106


Parte V

Outras

89 / 106


Esta parte contém capítulos que foram movidos ou serão reformulados.

90 / 106


Capítulo 17

Capacitação

Na seção anterior (Capítulo 2 [5]) foi informado que os autores dos livro iriam receber uma capacita-ção antes de iniciar a produzir os livros.

Este capítulo matém informações sobre esta etapa.

17.1 Marcando uma capacitação

Antes de marcar uma capacitação talvez será necessário consultar os autores (também chamados deprofessores conteudistas) para agendar um dia em que a maioria possa participar.

Com a data marcada, reserve um laboratório que comporte o público esperado.

Estenda o convite aos professores que não são conteudistas, a tutores que também possam estar in-teressados. Pois embora o público álvo seja os conteudistas, as outras pessoas podem aprender oProcesso de Produção e contribuir com melhorias nos materiais produzidos.

Preparamos uma recomendação de texto (Seção 21.1.1 [97]) que pode ser enviada por e-mail aosparticipantes da capacitação. O texto tem o propósito de agendar a reunião, e conter intruções que osprofessores podem realizar para se preparar para a reunião.

17.2 Instalar os softwares necessários no laboratório

Certifique-se de que os computadores possuem as ferramentas mínimas necessárias (Seção 6.1 [28])para a produção dos materiais.

Lembre-se que as vezes os computadores não possuem permissão para instalar aplicativos, sendonecessário contactar os responsáveis antecipadamente.

17.3 Coffee Break

A capacitação terá Coffee Break?

Caso a reunião tenha Coffee Break, organize-se para providenciar a compra e a entrega no horário elocal da capacitação.

Lista de perguntas a se fazer:

91 / 106


• O ambiente possui mesa para servir?

• Quem irá levar os copos descartáveis?

17.4 Auxiliares para o Ministrante

Durante uma capacitação é muito importante contar com a presença de outras pessoas, que tenhamconhecimentos técnicos de informática, para auxiliar o ministrante da capacitação. O ideal é que sejaalguém que também conheça o Processo de Produção.

Estas pessoas irão auxiliar os participantes nas realizações das atividades durante a capacitação, porexemplo:

• Como iniciar a máquina no Windows/Linux

• Como inserir um comando

• Como realizar as instruções apresentadas na capacitação

• Mostrar os erros cometidos pelos participantes ao seguir as instruções

Durante a capacitação o ministrante costuma ser bastante solicitado, portanto esta pessoa irá dividiras demandas.

92 / 106


Capítulo 18

Visão técnica

Figura 18.1: Fluxo de trabalho, visão técnica.

18.1 Ferramentas utilizadas no processo

texto.

18.2 Escrevendo o livro

texto.

18.2.1 Iniciando um novo livro

texto.

18.3 Gerando edição para impressão

texto.

93 / 106


18.3.1 Revisando o livro

texto.

18.3.2 Fechando versão para impressão

texto.

18.4 Erratas dos livros

texto.

18.4.1 Onde encontrar a errata

texto.

18.4.2 Contribuindo com correções

texto.

18.4.3 Contribuindo com indicações de erros

texto.

18.5 Licença

texto.

94 / 106


Capítulo 19

Escrevendo um livro

texto.

19.1 Estrutura inicial do projeto

texto.

95 / 106


Capítulo 20

Inserindo caracteres especiais no texto

Para inserir um caracter especial, basta copia-lo da internet e colar diretamente no arquivo. Os arqui-vos fontes devem está na codificação uft-8.

Ex: πρϕϷ

DicaVocê pode consultar vários simbolos em: http://www.utf8-chartable.de/unicode-utf8-table.pl?number=1024&names=-&view=2. Lembre de avançar a página para encontrar novossimbolos.

96 / 106

http://www.utf8-chartable.de/unicode-utf8-table.pl?number=1024&names=-&view=2

http://www.utf8-chartable.de/unicode-utf8-table.pl?number=1024&names=-&view=2


Capítulo 21

Comunicações

Nesta seção juntamos várias recomendações de comunicações que podem ser utilizadas durante oProcesso de Produção.

21.1 Capacitação

21.1.1 Convite e Agendamento para a capacitação

Capacitação dos professores conteudistasHoje tivemos uma reunião com os professores conteudistas.

- Apresentamos o formato de arquivo que iremos trabalhar (asciidoc)- Apresentamos o fluxo de trabalho- As ferramentas utilizadas

** Git(hub)

** Editor de texto (gedit ou notepad++)

Em seguida marcamos uma capacitação para iniciar o processo de ←↩produção:

- Capacitação: 3 de Abril, às 14:00, na ufpb virtual.

Os conteudistas poderão optar por duas formas de trabalho:1) Ambiente mínimo, com geração on-line da diagramação.ou2) Com todo o ambiente instalado no computador, com geração off-line ←↩

da diagramação.

As instruções abaixo são para os professores que optarem pela opção 2)

Os professores que optarem por possuir todo o ambiente instalado, ←↩tragam seus notebooks com os seguintes pacotes instalados:

Instalando o git:sudo apt-get install git

97 / 106


O mercurial não é necessário, mas será utilizado para baixar a nova ←↩versão do asciidoc.

sudo apt-get install mercurial

Instalar o latex:sudo apt-get install texliveousudo apt-get install texlive-full

Instalar o asciidoc e dbaltex. Depois serão removidos, mas é ←↩importante porque instala as dependências.

sudo apt-get install asciidocsudo apt-get install dblatex

Em seguida, precisaremos instalar as novas versões do asciidoc e ←↩dblatex:

-Remove asciidoc-Remove dbaltexsudo apt-get remove asciidocsudo apt-get remove dblatex

Instala nova versão do dblatexsudo apt-get install python-setuptoolssudo easy_install dblatex

Instala nova versão do asciidocmkdir ~/ambientecd ~/ambientehg clone -r 8.6.8 https://asciidoc.googlecode.com/hg/ asciidoc-8.6.8

98 / 106


Parte VI

Projetos e Pessoas

99 / 106


Esta parte do livro mantém um lista de repositórios de livros que podem ser gerados pelo Servidor deProdução.

Basicamente estamos mantendo os repositórios dos livros das disciplinas do curso de Licenciatura emComputação a distância na UFPB. No entanto, não há um compromisso com esta limitação.

O último capítulo desta parte é uma relação de colaboradores, que cresce sempre que alguém aprendea colaborar com o nosso processo (Capítulo 2 [5]).

100 / 106


Capítulo 22

Projetos de produção de livros

Nesta seção iremos manter os projetos dos livros que iremos produzir. Você poderá utiliza-la paraencontrar os endereços dos repositórios.

22.1 Este manual

Este Manual de Produçãohttps://github.com/edusantana/producao-computacao-ead-ufpb

22.2 Licenciatura em Computação a Distância - UFPB

Nesta seção encontram-se os repositórios das disciplinas deste curso.

22.2.1 Período 1

Matemática Elementarhttps://github.com/edusantana/matematica-elementar-livro-tex

Introdução a EaDhttps://github.com/edusantana/introducao-a-ead-livro

Fundamentos Sócio-Históricos da Educaçãohttps://github.com/edusantana/fundamentos-socio-historico-da-educacao-livro

Introdução à Programaçãohttps://github.com/edusantana/introducao-a-programacao-livro

Introdução à Computaçãohttps://github.com/edusantana/introducao-a-computacao-livro

101 / 106


https://github.com/edusantana/matematica-elementar-livro-tex

https://github.com/edusantana/introducao-a-ead-livro

https://github.com/edusantana/fundamentos-socio-historico-da-educacao-livro

https://github.com/edusantana/introducao-a-programacao-livro

https://github.com/edusantana/introducao-a-computacao-livro


22.2.2 Período 2

Cálculo Diferencial e Integralhttps://github.com/edusantana/calculo-diferencial-e-integral-livro

Inglês Instrumentalhttps://github.com/edusantana/ingles-instrumental-livro

Fundamentos Psicológicos da Educaçãohttps://github.com/edusantana/fundamentos-psicologicos-da-educacao-livro

Linguagem de Programação Ihttps://github.com/edusantana/linguagem-de-programacao-i-livro

Metodologia do Trabalho Científicohttps://github.com/edusantana/metodologia-do-trabalho-cientifico-livro

22.2.3 Período 3

Matemática Computacionalhttps://github.com/edusantana/matematica-computacional-livro

Pesquisa Aplicada à Computaçãohttps://github.com/edusantana/pesquisa-aplicada-a-computacao-livro

Fundamentos Antropo-Filosóficos da Educaçãohttps://github.com/edusantana/fundamentos-antropo-filosoficos-da-educacao-livro

Estruturas de Dadoshttps://github.com/edusantana/estruturas-de-dados-livro

Introdução a Arquitetura de Computadoreshttps://github.com/edusantana/introducao-a-arquitetura-de-computadores-livro

Ética Profissionalhttps://github.com/edusantana/etica-profissional-livro

22.2.4 Período 4

Probabilidade e Estatísticaindisponível

Optativa Iindisponível

Didáticaindisponível

Linguagem de Programação IIindisponível

102 / 106

https://github.com/edusantana/calculo-diferencial-e-integral-livro

https://github.com/edusantana/ingles-instrumental-livro

https://github.com/edusantana/fundamentos-psicologicos-da-educacao-livro

https://github.com/edusantana/linguagem-de-programacao-i-livro

https://github.com/edusantana/metodologia-do-trabalho-cientifico-livro

https://github.com/edusantana/matematica-computacional-livro

https://github.com/edusantana/pesquisa-aplicada-a-computacao-livro

https://github.com/edusantana/fundamentos-antropo-filosoficos-da-educacao-livro

https://github.com/edusantana/estruturas-de-dados-livro

https://github.com/edusantana/introducao-a-arquitetura-de-computadores-livro

https://github.com/edusantana/etica-profissional-livro


Banco de Dadosindisponível

Estagio Supervisionado Iindisponível

22.2.5 Período 5

Interface Humano-Computador de Software Educativoindisponível

Seminário Temático: Objeto Digitais e Educação em Computaçãoindisponível

Computadores e Sociedadeindisponível

Análise e Projeto de Sistemasindisponível

Sistemas Operacionaisindisponível

Estagio Supervisionado IIindisponível

22.2.6 Período 6

Teoria da Computaçãoindisponível

Seminário Temático: A Computação como Ciência Básicaindisponível

Produção de Materiais Instrucionaisindisponível

Engenharia de Softwareindisponível

Redes de Computadoresindisponível

Estagio Supervisionado IIIindisponível

103 / 106


22.2.7 Período 7

Optativa IIindisponível

LIBRASindisponível

Política e Gestão da Educaçãoindisponível

Sistema WEBindisponível

Agentes Inteligentes em Educaçãoindisponível

Estagio Supervisionado IVindisponível

22.2.8 Período 8

Trabalho de Conclusão de Cursoindisponível

Estagio Supervisionado Vindisponível

Optativa IIIindisponível

104 / 106


Capítulo 23

Pessoas

Esta seção é utilizada com o propósito de treinamento (Seção 2.7 [11]).

Importante

• Formato da lista: Nome — Função, Ano que iniciou as atividades.

• Adicione o seu nome na ordem alfabética.

• Mantenha a mesma formatação: normal — negrito, monospace.

Agora é sua vez, adicione o seu nome na lista abaixo:

1. Alisson Vasconcelos de Brito — Professor Conteudista, 2013.1.

2. Camyle de Araújo Silva — Revisora Ortográfica, 2013.1.

3. Eduardo de Santana Medeiros Alexandre — Editor, 2013.1.

4. Felipe Antonio Garcia Moreno — Professor Conteudista, 2013.1.

5. Gilberto Farias de Sousa Filho — Professor Conteudista, 2013.1.

6. Iguatemi Eduardo da Fonseca — Professor Conteudista, 2013.1.

7. Kely Diana Villacorta Villacorta — Professora Conteudista, 2013.1.

8. Natasha Correia Queiroz Lino — Professora Conteudista, 2013.1.

9. Miguel Aroztegui — Professor Conteudista, 2013.1.

105 / 106


Capítulo 24

Índice Remissivo

Bbaixando projeto, 73Baixar livro em PDF, 7

CCD

estrutura, 87ISO, 88

cor, 57

Ddblatex

Estilo do pdf, 77Diagrama de Sequência, 49

EEstilo do pdf, 77estrutura, 87

Ggit

cor, 57Mac, 29ssh, 28, 56

githubbaixando projeto, 73ssh, 73

graphviz, 76

IISO, 88

LLivro em PDF

Baixar livro em PDF, 7

MMac, 29

P

Pessoas, 105Projetos, 26, 101

RRepositórios, 26, 101

SServidor da Produção, 7ssh, 28, 56, 73

Ttag, 82

VVersionamento, 80

WWord para Asciidoc, 61

106 / 106

Documents

Processo Ágil de Produção de Livrosproducao.virtual.ufpb.br/books/edusantana/producao-computacao-ea… · Processo Ágil de Produção de Livros Sumário I O Processo de Produção