Guia de escrita de documentação para o Firebird
Contents
1. eee eeeeeananana caraca nana na nana na nana nana na nanananaa 9 Ferramentas para criar documentos DocBook XML e rerererananananana nana nananananaa 11 Escrevendo seu documento DocBook sssssnicerneioeia neni a i aea en a a a O eta e 13 Criando O documento ss cs as duea A riren ap E EENE E Cn EIEE EEVEE R E datas E EEE 13 Digitando tekto n rnn initie a ie iiaa aa i aa ie a ia i ae a i i ai 14 Elementos que usamos frequentemente rr er esen er erererererererereraren s 15 Aspectos do processo de escrita n o relacionados com o DocBook 29 Linguagem e estilo recesie ea aaa Si ipa d A a USE ad A a NIO aU Nas Pu a EEE A E EREA 29 Direitos AULOTAIS n sention erei e ee aTe the EE E E a T ES ua deb a aea ia arenada 31 Usando os documentos do PostgreSQL c area erererererererererererereren s 32 Adicionando seu documento ao m dulo de manuais eee ne nene nene nene nene ae aeaeanaa 32 Pedindo direitos de ENVIO svene E Danado EAE R Tina as AE Set oba as aaa vos AN S 32 O que se pode ou n o fazer assim que voc tem direito de envio 33 Enviando seu trabalho seiaasairs corona benicaetiagialo o nenn DeRiabapiido dane reta sar io datam EESTE EE EE OE datos 33 Ap ndice A Hist ria do Documento rr erer er erer er ererererererenererererererererans 35 Ap ndice B Aviso de Lic nsa niren anias terea aE vinis a aA Ee LEA GS Ob2. Guia de escrita de documenta o para o Firebird Paul Vinkenoog 26 Mar 2005 Documento vers o 1 1 pt br Tradu o para o Portugu s do Brasil Fabr cio Ara jo ndice Introdu o ses i sussa lotes E ido EAE aa DO saias pu aG So Sho SAS Ras ONA E SAGA Spa CABUL DO Ea AEE rP Aa ana E cho TETS 3 Prop sito deste documento e p blico alvo erre renanana nana na nana nana nananananaa 3 Pr regtisito Sn ann cega pstades lotado Prada INES nos o rao E Ea E EE asda Loo EO paS EEEa ERDO ss pasa riso 3 T picos discutidos neste documento sieren ii a a a Lapas dad a i Ea E aaa 3 Onde os documentadores se encontram errar er er area rara area rara ea area ea en en eaaaeaaaana 4 A p gina do SUbprojeto ssa se gos bra a gos bum ruins Senar usa quot is A GALO Gai E e a Aa 4 A ista tirebird dOCS a zo as aasst ires furo unia e e LEO poa e va add Rob a linda EE Ho qd aU aa Ho lia E o na 4 Usando a interface news do servidor Atkin rr rererererererererererererererererens 5 Achar UM ASSUNtO esni a e EE a E E E E US EEE ET EEE EE E Ea EENE 5 Preparando se para escrever fa a um resumo eee eae erar ea aa area er en er eneaananaaana 6 DocBook XML uma introdu o sasesana is Seo EEEE ERAO tao E SETEC E EERE do Epei E eS 6 Uma introdu o bem gen rica a XML seesesesessressrsrsressrersrerersrererererstererererererererererererererererereretet 7 Uma introdu o ao DocBook XML
3. A p gina de documenta o do PostgreSQL aqui http www postgresgl org docs A licensa mais recente do PostgreSQL est atualmente aqui http www postgresgl org about licence Uma coisa bacana sobre a documenta o do PostgreSQL que ela foi elaborada em DocBook assim como a nossa Por m eles usam DocBook SGML em vez de XML o que significa que algumas ajustes ser o necess rios Os fontes em DocBook SGML podem ser encontrados aqui http developer postgresql org cvsweb cgi pgsql server doc src sgml Adicionando seu documento ao m dulo de manuais Quando seu documento finalizado e voc o verificou que o mesmo gerado corretamente voc deseja que o mesmo seja adicionado ao m dulo de manuais Se esta a primeira contribui o ao projeto de documenta o voc deve ter concordado com os coordenadores que voc os enviar para eles para revis o ou colocar no ar a vers o html num website de modo que a mesma possa ser discutida na lista Depois disso e ap s algumas corre es feitas seu documento ser adicionado ao m dulo Se voc j possui direito de envio voc pode fazer isso voc mesmo se n o possui um dos coordenadores far isso por voc Pedindo direitos de envio Para receber direitos de envio primeiro voc precisa de uma conta de usu rio no SourceForge Se n o uma registre se em http sourceforge net account register php Ent o poste uma mensagem na lista firebird do
4. lt para gt Neste cap tulo iremos demonstrar como baixar e instalar o Firebird lt para gt lt section id usersguide download gt lt title gt Baixando o Firebird lt title gt lt para gt Para baixar o Firebird voc deve ir primeiro na seguinte URL etc etc etc lt para gt lt mais par grafos possivelmente mais subse es gt lt section gt lt section id usersguide install gt lt title gt Instalando o Firebird lt title gt lt para gt Instala o do Firebird no seu sistema ser deste jeito etc etc etc lt para gt lt mais par grafos possivelmente mais subse es gt lt section gt lt chapter gt lt l 0 mais capitulos a gt lt book gt Algumas regras e coment rios Primeiro note de novo que valores de atributos sempre devem estar entre aspas Mas se voc os preencher em editor de atributos n o as coloque o editor cuidar desse detalhe O title t tulo de um livro ou artigo deve aparecer no pr prio elemento book livro ou article artigo E at legal incluir em ambos mas nesse caso os dois t it le s t tulos devem possui o mesmo conte do Em outras palavras fique com one ou outro n o ambos se quizer evitar encrenca Todos atributos id devem ser nicos dentro do mesmo conjunto de livros Note que vers es em diferentes linguagens est o contidas cada uma em seu pr prio conjunto perfeitamente poss vel manter as i
5. o Voc deve ter notado que as palavras important caution etc t m apar ncia diferente do resto do texto da dica Como Bem para dizer a verdade eu as coloquei entre tags especiais as primeiras com lt sgmltag gt s nas segundas com lt literal gt s para faz las aparecerem diferente do resto do texto Mas a o fonte em XML ficaria muito polu do ent o eu decidi tir las do c digo exemplo que apresentei a voc Se voc destacar um bloco de texto daquilo que o circunda sem marc lo como uma dica ou o que seja use a tag lt blockquote gt V rios elemento em linha Para concluir a subse o sobre elementos do DocBook agora eu falarei sobre um certo n mero de elementos em linha Eles s o chamados em linha porque n o interrompem o fluxo do texto Se voc usa por exemplo um elemento emphasis lt emphasis gt Em hip tese alguma lt emphasis gt me chame de gordo de novo o resultado ser Em hip tese alguma me chame de gordo de novo A express o Em hip tese alguma est enfatizada mas mant m se no seu lugar na senten a N s j encontra mos alguns elementos em linha antes os v rios tipos de links Outros elementos como table warning blockquote e programlist ing s o todos mostrados como um bloco aparte do texto em volta mesmo que voc os coloque em linha no seu fonte em XML N o muito surpreendente que sejam chamados de elementos de bloco Elementos de bloco fregiientemente
6. formate o texto em uma forma que a estrutura seja t o clara quanto poss vel Como os profetas disseram Indente Indente Indente Se na outra vertente voc usa um editor XML dedicado pressionando Enter pode automaticamente fechar o lt para gt corrente e abrir um novo Tenha certeza de como o seu editor se comporta e use a tecla Enter de acordo Verifique tamb m o que acontece com m ltiplos caracteres espa o em branco porque certos editores XML podem user certos truques para preserv los Elementos que usamos frequentemente Esta se o discute os elementos DocBook que n s mais usamos em nossos documentos do Firebird Isso inclui montes de exemplos em formato DocBook XML Se voc usa uma ferramenta de elabora o XML o que voc v na sua tela pode ser completamente diferente da maneira que aparece em nossos exemplos mas se voc abrir o arquivo XML em um editor de texto ou escolher a vis o de texto da sua ferramenta XML voc ver o XML por baixo Voc devia dar uma olhada nos fontes em XML que j est o no m dulo de manuais para ver como os outros autores criaram seus documentos e aplicam as tags 15 Guia de escrita Dica Esta uma longa se o mas n o deixe isso desencoraj lo Meu conselho que voc cuidadosamente leia a subse o em elementos hier rquicos e folheie as outras N o se preocupe se h coisas que voc ainda n o entende de uma vez n o tente decorar o material Apenas tenha
7. o E alguns escritores de documenta o realmente preferem essa abordagem em vez de ferramentas mais sofisticadas por que isso lhes d controle 11 Guia de escrita completo do texto e as tags digitadas s o sempre vis veis Mas o pre o disso que os editores de texto puro n o podem validar seu documento em DocBook de modo que somente ap s a gera o dos documentos finais falhar que voc se dar conta do problema E as estrutura do seu documento especialmente quando o mesmo grande tamb m dif cil de visualiza em modo texto embora um uso consistente de indenta o possa melhorar muito a situa o Se voc deseja seguir por este caminho ou apenas tentar para ver como funciona seria uma boa id ia de um editor que permita realce de sintaxe no XML Um muito bom e tamb m gr tis o ConText Obtenha o em http www fixedsys com context Mas para a maioria das pessoas desej vel o uso de uma ferramenta dedicada Ferramentas de elabora o de XML geralmente possuem interfaces gr ficas que fazem as tags sobressa rem muito bem e algumas vezes irritantemente muitas permitir o que recolham e expandam elementos de modo que voc possa ver a estrutura do seu documento e ao mesmo tempo fazer zoom no elemento que voc est trabalhando podem tamb m voc trocar diferentes vis es Algumas tem um modo DocBook especial onde seu documento ser validado n o somente como XML mas tamb m validado como Doc
8. DTD Document Type Definition ou Defini o de Tipo de Documento um conjunto de defini es e regras descrevendo exatamente como um documento DocBook v lido estruturado Este formato est se tornando um padr o de fato para documentos t cnicos para computa o e suportado por um crescente n mero de aplica es e ferramentas Caracter sticas do DocBook XML Caracter sticas importantes do DocBook ao inv s de um XML genericamente s o e A DTD do DocBook define um n mero limitado de tags e d regras exatas em como us las quais atributos s o v lidos para a tag A que elemento B pode ser aninhado dentro do elemento C e por a vai Usando tags indefinidas ou n o seguindo as regras seu documento n o DocBook mais e as ferramentas que suportam o DocBook provavelmente n o ser o capazes de process lo sem erros e As tags do DocBook trabalham com estrutura e sem ntica significado nunca cosm tica No DocBook voc achar tags estruturais como lt book gt lt part gt lt chapter gt lt section gt lt para gt lt table gt e tags sem nticas como lt fi lename gt lt warning gt lt emphasis gt lt postcode gt mas nada como lt font gt lt bold gt lt center gt lt indent gt lt backgroundcolor gt ou seja nada que tenha a ver com layout ou cosm tica e Por causa disso uma decis o deve ser tomada em como as tags do DocBook ser o transfomadas em maqui agem apresent vel Esta dec
9. XML e Raz es para a nossa forte prefer ncia ao DocBook em detrimento de outros formatos e Ferramentas que voc pode utilizar para produzir textos em DocBook N o se preocupe se o DocBook n o significa nada para voc ainda o conhecimento requerido pode ser aprendido em menos de uma hora e h uma boa chance de que voc pode se beneficiar deste conhecimento em outros projeto quando voc tiver que escrever documenta o t cnica Guia de escrita A pr xima parte sobre escrever os documentos inclui e Configurando o pr prio documento e Usando elementos do DocBook e Algumas notas sobre linguagem e estilo de escrita e Direitos autorais e a Licensa de Documenta o P blica e Usando os documentos do PostgreSQL como base Finalmente n s mostraremos como adicionar seu documento finalizado ao projeto Firebird Os t picos princi pais desta se o s o e Submetendo seus documentos ao m dulo de manuais e Onde pedir para ter direitos de submiss o se voc n o os possui e Oque se pode e n o pode assim que voc recebeu seus direitos de submiss o Onde os documentadores se encontram A p gina do subprojeto A p gina do subprojeto de documenta o aqui http www firebirdsql org index php op devel amp sub doc Ela cont m novidades sobre nossas atividades links para os documentos que j foram publicados planos para o futuro etc A lista firebird docs Se voc est falando s rio sobre escrever docume
10. claro que voc configurando um novo documento ele tem que ser colocado no conjunto principal mas isso algo que discutiremos quando voc estiver preparado come ar a escrever N o colocamos uma regra geral aqui por causa que isso depende do que voc ir escrever um livro artigo um ou alguns cap tulos e como seu trabalho se encaixa no resto Todo documento DocBook tem que inicar com esta linha lt xml version 1 0 encoding UTF 8 2 gt Se voc escreve sua documenta o na m o por exemplo em um editor de texto voc deve digitar a linha acima Se voc usa um editor espec fico de XML esta ser inserida automaticamente no novo documento Voc deve sempre colocar sua documenta o na pasta src docs firebirddocs da rvore dos manuais pelo menos se este estiver em ingl s Em documentos em outras l nguas deve se colocar o documento em pastas tipo src docs firebirddocs fr src docs firebirddocs es etc Digitando texto Se voc digitar seu texto DocBook XML em um editor tipo o Bloco de Notas emacs ou ConText voc pode usar quebras de linha endenta o e m ltiplos espa os do jeito que desejar Cada ocorr ncia de whitespace uma 14 Guia de escrita sequ ncia de um ou mais caracteres space tab linefeed or formfeed ser convertida em um nico espa o em branco na sa da Ent o isto lt section gt lt title gt Arquiteturas do Firebird lt title gt lt para gt Agora vamos dar uma olhada
11. de XML em texto puro e epcEdit 89 para uso n o comercial Vers o de avalia o 60 dias dispon vel http www epcedit com Rode em Linux Windows Solaris Requer Tcl Tk 8 1 ou acima inclu do na instala o Funcionalidades Painel da rvore de estrutura Seletor de Elementos Editor de Atributos Painel de docu mento pode intercambiar com modo texto puro e modo XML gr fico N o possui nenhum modo especial para DocBook mas pode validar qualquer documento XML baseado sobre uma DTD Runs on Linux Windows Solaris Requires Tcl Tk 8 1 or above included in package 12 Guia de escrita Altova XMLSpy Home Edition US 49 Vers o de avalia o 30 dias dispon vel http www altova com products ide html Roda em Windows Algumas pessoas j disseram que roda em linux usando Wine e no Mac OS X usando o Virtual PC 6 Funcionalidades Vis es Texto Grid caixas em caixas Navegador Todos os elementos recolh veis exceto na vis o texto Vis o Browser apenas para leitura Seletor de elementos Editor de atributos Fun es de Busca e Edi o Seletor de caracteres especiais Corretor ortogr fico e Altova Authentic Gr tis http www altova com products_doc htm1 Tem as mesmas funcionalidades exceto as vis es de Texto e Grid e roda nos mesmos ambientes do XML Spy Possui a vis o Authentic em vez disso e um corretor ortogr fico Este editor na verdade uma interface a
12. elementos de listas dos quais s o usados fregiientemente itemizedlist Uma itemizedlist usada para enumerar items cuja ordem n o muito importante lt itemizedlist spacing compact gt lt listitem gt lt para gt Laranjas s o suculentas lt para gt lt listitem gt lt listitem gt lt para gt Ma s supostamente s o saud veis lt para gt lt listitem gt lt listitem gt lt para gt A maioria das pessoas acham o lim o muito cido lt para gt lt listitem gt lt itemizedlist gt Os items na lista s o geralmente marcados com um marcador nos documentos de sa da e Laranjas s o suculentas e Ma s supostamente s o saud veis e A maioria das pessoas acham o lim o muito cido orderedlist Use uma lista ordenada tag lt orderedlist gt quando se deseja for ar a ordem entradas lt orderedlist spacing compact numeration loweralpha gt lt listitem gt lt para gt Sum rios 3300 AC 1900 AC lt para gt lt listitem gt lt listitem gt lt para gt Imp rio Ass rio 1350 AC 612 AC lt para gt lt listitem gt lt listitem gt lt para gt Imp rio P rsio 6 s culo AC 330 AC lt para gt lt listitem gt lt orderedlist gt Por padr o numerais ar bicos 1 2 3 ser o colocados antes dos items mas voc pode mudar isso com o atributo numeration Sa da a Sum rios 3300 AC 1900 AC b Imp rio Ass rio 1350 AC 612 AC c Imp rio P rsio 6 s culo AC 33
13. este aqui Passos para serem seguidos num procedimento Solu es alternativas para um problema Mas se h apenas um pequeno n mero de itens curtos use uma senten a simples Minha m e ama tr s ho mens John Dick e Dave Bloqueio do escritor de documentos Algumas vezes voc sabe o que deseja escrever e tem as palavras prontas mas n o consegue iniciar a frase voc n o consegue fazer isso fluir Isso muito frustrante e s vezes bloqueia o avan a do seu texto por v rios minutos E mais frustrante de tudo isso fato de que voc sabe o que deseja passar para seus leitores mas n o parece capaz de produzi uma senten a decente Ap s muitas experi ncias dolorosas deste tipo eu desenvolvi a seguinte estrat gia n o que eu pense que sou o primeiro 1 Escreva o que voc tem que dizer em senten as soltas e grupinhos de palavras N o se esquente com estilo nem que isso pare a feio Apenas escreva o que voc deseja passao ao leitor tenha certeza que est tudo l e na ordem certa Se enquanto voc estiver fazendo isto voc notar que n o tem certeza de alguma coisa inclua um coment rio exatamente nesse ponto Fa a os coment rios se destacarem do texto em volta por exemplo lt lt deste jeito gt gt ou IDESTE OUTRO JEITO Isso pode resultar num texto assim 30 Guia de escrita CVS significa Sistema de Vers es Concorrentes lt lt verifique gt gt Prop sito gerenciamento de vers es d
14. gt lt entry align center gt Banco de Dados lt entry gt lt entry align center gt Votos lt entry gt lt entry align center gt Porcentagem lt entry gt lt row gt lt thead gt lt tfoot gt lt row gt lt entry gt Total lt entry gt lt entry gt 1111 lt entry gt lt entry gt 99 99 lt entry gt lt row gt S E EGOE lt tbody gt lt row gt lt entry gt MySQL lt entry gt lt entry gt 405 lt entry gt lt entry gt 36 45 lt entry gt lt row gt lt row gt lt entry gt Firebird lt entry gt lt entry gt 403 lt entry gt lt entry gt 36 27 lt entry gt lt row gt e mais 5 linhas n o mostradas aqui 24 Guia de escrita lt tbody gt lt tgroup gt lt table gt E aqui a tabela resultante Tabela 2 Pesquisa LinuxQuestions org Banco de Dados of ano de 2003 Banco de Dados Porcentagem MySQL 36 45 Firebird 36 27 Postgres 2421 Oracle 2 25 Berkeley DB 0 36 Sybase 0 27 DB2 0 18 Total 99 99 A prop sito esses s o resultados atuais de uma pesquisa real no LinuxQuestions org Como voc pode ver faltaram 3 votos para o Firebird vencer a pesquisa Se voc conhece essas pessoas por favor reporte as ao seu Inquisitor Chefe Ele gostaria de ter uma pequena ahhh humm conversa com eles Tabelas s o automaticamente indexadas Uma lt informaltable gt tabela informal tem a mesma estrutura de uma lt table gt
15. lo nisso s o 29 Guia de escrita e Use um dicion rio Simples efetivo e n o high tech e Quando estiver indeciso entre duas escritas de uma palavra ou entre v rias poss veis vers es de uma expres s o google procurar no site de busca Google um verbo criado por causa da popularidade desse site pelas alternativas e veja suas fregii ncias E siga alguns dos links resultantes da pesquisa para ver como os falantes nativos usam a palavra ou express o e Tenha um falante nativo para revisar seu texto e corrig lo onde necess rio Estilo N o espere um Guia de Estilo aqui eu n o saberia como escrever um mesmo Apenas algumas diretrizes e dicas e Tente escrever em linguagem simples e quotidiana sempre que poss vel Evite palavras dif ceis se existem alternativas similares mais simples e Evite frases longas acima de 25 palavras se puder especialmente duas ou mais frases longas uma ap s a outra e Seja cuidadoso em constru es como negativos duplos ou triplos Eu n o posso negar que n o estou abor recido e voz passiva Cuidados devem ser tomados Voc n o precisa evit las a todo custo mas lem bre se que elas podem fazer a senten a mais dif cil de entender Nesse caso use o positivo Estou satisfeito e a voz ativa Tenha cuidado e Use listas para enumerar um n mero de items paralelos por exemplo Uma cole o de sugest es e dicas Uma sequ ncia de exemplos como
16. m um livro tag book ou artigo tag article se o alvo est fora do documento corrente use a tag ulink em de link veja abaixo Nota Como voc j deve ter percebido a regi o clic vel por vezes recuada com respeito ao texto do link Isso um problema conhecido no Apache FOP n o havendo muito que possamos fazer a respeit ulink Use um ulink para linkar para um recurso na Internet O atributo url obrigat rio Clique lt ulink url http docbook org tdg en gt neste link lt ulink gt para ler o O Guia Definitivo para DocBook As palavras neste link aparecer o como um hiperlink para http docbook org tdg en assim Clique neste link para ler O Guia Definitivo para DocBook email Voc pode fazer um link para email com um ulink por m mais f cil usando o elemento email Este ir mostrar o endere o de email como texto clic vel na sa da Esta linha de XML Envie mensagem para lt email gt firebird docs request tlists sourceforge net lt email gt para assinar resulta na seguinte sa da Envie mensagem para lt firebird docs requestflists sourceforge net gt para se assinar Se voc deseja que o texto clic vel seja diferente do pr prio endere o de email use um ulink com uma URLmailto 20 Guia de escrita Aten o Se voc incluir links para endere os de email seja com emai 1 ou com ul ink ou mesmo se voc apenas mencion los no seu
17. nas diferentes arquiteturas do Firebird lt para gt lt itemizedlist gt lt listitem gt lt para gt Primeiro existe a chamada arquitetura lt firstterm gt Classic Server lt firstterm gt lt para gt lt listitem gt lt listitem gt lt para gt E tamb m existe a arquitetura lt firstterm gt Superserver lt firstterm gt lt para gt lt listitem gt lt listitem gt lt para gt E finalmente com o lan amento do Firebird 1 5 n s tamb m temos o lt firstterm gt embedded server lt firstterm gt lt para gt lt listitem gt lt itemizedlist gt lt section gt resulta na mesma sa da disto lt section gt lt title gt Arquiteturas do Firebird lt title gt lt para gt Vamos dar uma olhada nas diferentes arquiteturas do Firebird lt para gt lt itemizedlist gt lt listitem gt lt para gt Primeiro temos a chamada arquitetura lt firstterm gt Classic Server lt firstterm gt lt para gt lt listitem gt lt listitem gt lt para gt Entar temos a arquitetura lt firstterm gt Superserver lt firstterm gt lt para gt lt listitem gt lt listitem gt lt para gt E finalmente com o lan amento do Firebird 1 5 n s tamb m temos o lt firstterm gt embedded server lt firstterm gt lt para gt lt listitem gt lt itemizedlist gt lt section gt N o necess rio dizer a segunda foma muito mais f cil de ler e entender para um humanos Ent o se voc digita seu XML na m o
18. o quando voc escrever seu documento e revisite as subse es de vez em quando tipo quando voc precisar dele Elementos Hier rquicos A hierarquia mais comum partindo do topo lt set gt lt book gt lt chapter gt lt section gt lt para gt Elementos de se o s o um pouco diferentes do resto por haver dois sabores deles e Oelemento lt sect ion gt como colocado acima Ele pode ser usado recursivamente por exemplo voc pode ter uma lt section gt dentro de uma outra lt section gt e da por diante Este sabor tem a vantagem de que voc pode mover sub rvores para cima ou abaixo sem ter que mudar as tags E tamb m existe a faixa de lt sect1 gt lt sect2 gt lt sect5 gt Esses elementos devem ser devidamente aninhados com o lt sect 1 gt no topo lt sect 2 gt dentro lt sect 1 gt e assim por diante N o se pode colocar lt sect 3 gt diretamente dentro de lt sect 1 gt menos flex vel que lt section gt mas raramente isso causa problemas na pr tica Afinal a mesma rigidez tamb m se aplica a lt set gt lt book gt e lt chapter gt e n s conseguimos viver com isso sem problemas Nota Em vers es anteriores deste documento a s rie lt sect N gt nos recomend vamos por raz es de apresenta o Devido melhores nas folhas de estilo tais raz es n o mais se aplicam Siga o estilo que melhor lhe convier Livros cap tulos e se es de topo devem
19. que voc precisa conhecer o elemento O elemento a combina o de uma tag inicial uma tag final respectiva e tudo que estier no meio Esse tudo que est no meio chamado Guia de escrita de conte do do elemento e pode incluir outros elementos Elementos s o nomeados de acordo com suas tags de modo que podemos falar em elementos do par grafo elementos do it lico etc Nota Verdadeiramente elementos s o um conceito mais b sico que as tags as tags na verdade s o coisas que iden tificam os elementos Ent o melhor dizer que as tags s o nomeadas de acordo com seus elementos Mas como as tags s o mais f ceis de reconhecer que os elementos eu acabei mostrando as primeiro a voc Isto um elemento lt alto gt Nao lt alto gt Isto tamb m um elemento lt paragrafo gt Este e um elemento contendo lt negrito gt outro lt negrito gt elemento lt paragrafo gt Tags de elemento vazio constituem um elemento por si mesmas Esses elementos n o possuem nenhum conte do porque n o possuem um par de tags lt figura arquivo bloody hand png gt Importante N o confunda conte do com atributos Conte do ficam entre tags e os atributos dentro das tags O tag de elemento vazio do ltimo exemplo possui um atributo mas n o possui conte do Estou insistindo no conceito de elementos por causa que grande parte da documenta o tende a falar em ele mentos d
20. realmente tive vontade de um copo de H lt subscript gt 2 lt subscript gt O l quido Sa da Ap s inventar a f rmula e mc eu realmente tive vontade de um copo de H20 l quido varname constant database O uso de varname e constant nome de var avel e constante respectivamente deve ser bvio A tag lt database gt n o s para bancos de dados mas tamb m para objetos do banco de dados A tabela lt database class table gt COUNTRY lt database gt tem dois campos lt database class field gt COUNTRY lt database gt e lt database class field gt CURRENCY lt database gt Sa da A tabela COUNTRY tem dois campos COUNTRY e CURRENCY function parameter returnvalue fun o par metro e valor de retorno respectivamente Esses tr s falam por si mesmos eu confio A fun o lt function gt log lt function gt tem os par metros lt parameter gt a lt parameter gt e lt parameter gt b lt parameter gt Sa da A fun o log tem os par metros a e b prompt userinput computeroutput Nota do Tradutor prompt ser usado no original seu significado no caso poderia ser indica o de prontid o tradu o que realmente ajuda user input entrada do usu rio e computeroutput sa da do com putador prompt usado para uma string que indica que o usu rio deve entrar algum texto user input refere se ao texto entrado pelo usu rio n o necessariamente num p
21. seja f cil procurar por nomes de arquivos por exemplo ou gerar um ndice de todas aplica es mencionadas em seu documento Por outro lado existem tantos desse elementos sem nticos de fato n s discutimos apenas uns poucos deles que se voc aplicar todos em todo lugar que voc possa provavelmente 28 Guia de escrita ficar maluco antes de terminar o documento N o isso que desejamos se voc realmente tiver que ficar doido por favor fa a o depois de terminar seu documento Ent o como um conselho geral v devagar com esses elementos use os toda vez que voc achar que fazem sentido mas n o exagere Para empacotar os elementos Voc deve ter notado que os documentos renderizados voc est lendo um agora a n o ser que voc tenha aberto a vers o XML muitos diferentes elementos t m a mesma apar ncia um filename um literal e uma application t m exatamente a mesma tipografia o mesmo valendo para emphasis firstterme citetitle Ent o qual o sentido de todas essas tags diferentes Por que n o usar umas poucas tipo emphasis e lite ral se todos aparacer da mesma maneira Bem h duas boas raz es para n o fazer isso e Primeiro se n s deixarmos de usar a maior parte de nossos elementos em linha em favor de por exemplo emphasiseliteral a sem ntica seria perdida E lembramos que o DocBook XML todo sobre estrutura e sem ntica firstterme citetitle podem parecer a mesma coisa uma vez r
22. vez disso se voc deseja que os seus leitores possam v lo voc digita isso amp lt um amp seguido pelas letras 1 e t para menos que em ingl s seguido de um ponto e v rgula Voc pode usar tamb m amp gt maior que para o s mbolo gt embora n o seja necess rio XML tem montes de c digos como estes eles s o chamados entidades Alguns representam caracteres como amp lt e amp uml e alguns servem para outros prop sitos completamente diferentes Mas todos come am com um amp e terminam com um ponto e v rgula Mas espere um minuto Se um amp marca o in cio de uma entidade como voc o inclui como um literal no seu texto Claro que existe uma entidade para isso tamb m amp amp Ent o esta linha de XML Kernigan amp amp Ritchie escolheram amp lt como o operador menos que para o Cr vir no documento final como Kernigan amp Ritchie escolheram lt como o operador menos que para o C E aqui v o algumas boas not cias se voc usar algum editor especializado em XML para criar o seu documento voc provavelmente apenas precisar digitar lt e amp normalmente onde voc gostaria que eles estivessem O editor cuida para que saia exatamente como literal e n o como um in cio de tag ou entidade no XML que ser salvo no disco Neste documento voc encontrar mais adiante algumas sugest es de editores de XML DocBook Elementos Tem mais um conceito importante de XML
23. 0 AC procedure Um procedimento tag lt procedure gt frequentemente renderizado como uma lista ordenada tag lt or deredlist gt mas com uma sem ntica diferente um procedimento denota uma segii ncia de passos a serem executados numa dada ordem lt procedure gt lt step gt lt para gt Arrombe a fechadura lt para gt lt step gt lt step gt lt para gt Roube a casa lt para gt lt step gt lt step gt lt para gt Seja preso lt para gt lt step gt lt procedure gt Aqui est a sa da 1 Pick the lock 2 Rob the house 18 Guia de escrita 3 Get arrested Dentro de um passo voc pode incluir um elemento subpasso tag lt substep gt o qual pode conter mais passos variablelist Uma lista vari vel tag lt variablelist gt feita de entradas de lista vari vel tag lt varlistentry gt cada uma das quais possuem um termo tag lt term gt seguido de um item de lista tag lt listitem gt lt variablelist gt lt varlistentry gt lt term gt Tag lt term gt lt listitem gt lt para gt Uma pe a de texto entre um lt e um gt lt para gt lt listitem gt lt varlistentry gt lt varlistentry gt lt term gt Element lt term gt lt listitem gt lt para gt Uma tag inicial uma tag final correspondendo e tudo entre elas lt para gt lt listitem gt lt varlistentry gt lt varlistentry gt lt term gt Cote do de um elemento lt term gt lt listitem gt lt para gt Tudo den
24. 1 4 2 01 b06 Java HotSpot TM Client VM build 1 4 2 01 b06 mixed mode Buildfile build xm BUILD FAILED Target ugh does not exist in this project lt screen gt E aqui como isso renderizado D NFirebirdimanual incl howtolsrceNbuild gt build ugh java version 1 4 2 01 Java TM 2 Runtime Environment Standard Edition build 1 4 2 01 b06 Java HotSpot TM Client VM build 1 4 2 01 b06 mixed mode Buildfile build xmil BUILD FAILED Target ugh does not exist in this project literallayout literallayout assim como screen e programlisting mant m seu layout intacto mas geral mente n o muda a fonte a n o ser que voc altere o atributo class para monospaced E tamb m mais gen rico que os outros dois anteriores no contexto de que n o h nenhum significado atrelado a seu conte do voc pode colocar qualquer tipo de texto aqui o qual voc deseje preserver o layout Exemplo de fonte lt literallayout gt The Sick Rose Oh Rose thou art sick The invisible worm That flies in the night In the howling storm Has found out thy bed Or crimson joy 22 Guia de escrita And his dark secret love Doth thy life destroy William Blake lt literallayout gt Sa da The Sick Rose Oh Rose thou art sick The invisible worm That flies in the night In the howling storm Has found out thy bed Of crimson jo
25. 33 Guia de escrita cvs commit m Alguma mensagem informativa aqui Depois do m e dentro de aspas voce digita uma mensagem curto sobre este envio algo como Adiciona das algumas fun es para a refer ncia da API ou Erros no tutorial do isql corrigidos D a sua senha do SF quando perguntado e todas as mudan as que voc fez incluindo nas subpastas ser o enviadas Seu cliente CVS sabe qual servidor deve contatar esta e outras informa es s o armazenadas nos subdiret rios CVS que foram criados no checkout Se voc usa outro cliente CVS reveja sua do programa documenta o 34 Guia de escrita Ap ndice A Hist ria do Documento A hist ria exata do arquivo gravado no m dulo manual na nossa rvore do CVS veja http sourceforge net cvs group id 9028 Hist rico de Revis es 0 1 17 Jan 2004 PV Primeiro rascunho incompleto publicado sob o t tulo Writing Documen tation for Firebird aka Firebird Docwriting Howto 0 2 27 Jan 2004 PV Primeira vers o completa Entrou no CVS 31 Jan 2004 1 0 8 Mar 2004 PV Primeira vers o original no site do Firebird 11 26 Fev 2005 PV As seguintes mudan as foram acumuladas entre Mar o 2004 e Fev 2005 O t tulo foi modificado para Guia de escrita de documenta o para o Firebird Adicionada se o sobre a documenta o do PostgreSQL Explicado o termo XML bem formado Lista de benef cios do DocBook sintetizada Recomenda o sobre e
26. Book O autor deste documento tentou diversas dessas ferramentas algumas gr tis outras baratas e vers es de avali a o e descobriu que o XMLMind XML Editor XXE como sendo o mais tl Essa uma opini o pessoal claro sua experi ncia pode ser diferente Nota Do Tradutor Fa o coro com o autor com rela o ao XXE Excelente editor mas tenha um outro editor de XML m o para editar o arquivo firebirddocs pt br xml Alguns editores que voc talvez deseje avaliar e XMLMind XML Editor ou XXE A Edi o Standard gr tis http www xmimind com xmleditor Roda em Linux Windows Mac OS X Requer Java mas voc precisa do Java de qualquer maneira ou voc n o ser capaz de gerar os documentos a partir dos fontes veja o Howto Gerando as manuais Firebird Funcionalidades Vis o em rvore todos os elementos recolh veis e vis o estilizada Cap tulos e se es recolh veis A ltima aquela na qual eu trabalho mostra o documento num simples mas limpo layout imitando processador de texto definido numa stylesheel que v m com o programa Ambas as vis es podem estar ativas simultaneamente O modo DocBook n o deixa voc entrar nada inv lido Seletor de elementos Editor de atributos Fun es de busca e edi o Barra de bot es para criar elementos mais utilizados como se es listas tabelas etc Seletor de caracteres especiais Corretor ortogr fico O que eu sinto falta uma vis o
27. a antes do in cio da escrita porque em alguns casos uma pe a de informa o anteriormente desconhecida pode faz lo escolher uma estrutura de documento diferente De modo que bem melhor ter esta informa o ainda na fase de resumo DocBook XML uma introdu o O formato escolhido para a documenta o do m dulo de manuais do Firebird o DocBook XML Para quem n o familiar com XML e ou Docbook seguem se algumas introdu es curtas ao XML em geral e DocBook XML em particular Esteja avisado que estas introdu es d o uma imagem grosseiramente simplificada Mas est tudo bem n o necess rio ser um especialista em DocBook para escrever documentos para o Firebird O necess rio algum conhecimento b sico o qual voc pode depreender em meia hora dos par grafos abaixo e uma pequena experi ncia em aplicar tags do DocBook XML em seus textos o qual voc ir obter assim que come ar a escrever Para pular a introdu o ao XML se voc n o precisa saber nada sobre XML tags elementos atributos rende riza o e publica o multicanal Pule ambas as introdu es se j for um autor j experiente com o DocBook Nota Embora n s fortemente insistamos que voc ao menos tente entregar seu trabalho no formato DocBook tamb m sabemos que algumas pessoas n o tem o tempo necess rio para aprend lo ou converter seus documentos existentes para DocBook Se isso se aplica a voc por favor fale sobre isso na
28. adere Ta Gas PAS a gal AVEA a aa DERE E ssa 36 Introdu o Prop sito deste documento e p blico alvo Este documento discute os v rios aspectos of escrever documenta o para o Firebird destinado a pessoas que desejam ajudar a escrever documenta o para o projeto Firebird ou quem pelo menos considera seriamente fazer isto Ap s esta leitura voc deve o conhecimento necess rio para come ar a escrever documentos para o Firebird em nosso formato escolhido o DocBook XML Pr requisitos Antes de come ar a ler este documento certifique se que voc sabe e Oque o m dulo de manuais do Firebird e O que o CVS e como se usa o cliente CVS para baixar o m dulo de manuais corrente e Como gerar a documenta o atual do m dulo de manuais que voc baixou Este conhecimento essencial se voc ir contribuir com o nosso projeto de documenta o Se voc se sente inseguro sobre algum desses pr requisitos ent o leia o primeiro o Howto Gerando as manuais Firebird e depois volte a ler este texto T picos discutidos neste documento Come aremos com alguns cap tulos curtos sobre e A lista de discuss o firebird docs e Achar um assunto e Fazer um esbo o para o seu documento Depois disso iremos gastar algum tempo para explicar os conceitos b sicos do DocBook XML porque este o formato em que desejamos que voc nos entregue os seu s documento s Os t picos discutidos incluem e Oque o DocBook
29. cs com o seu nome no SF e pedindo para ser adicionado ao projeto Firebird O l der subprojeto de manuais e de 32 Guia de escrita v rios outros projetos l em a lista eles ir o considerar sua requisi o Como regra geral voc deve perguntar sobre direitos de envio ap s sua primeira contribui o porque as pessoas que decidem sua precisam de algo para se basearem As seguintes frases atualmente significam a mesma coisa a prop sito e Se tornar um membro do projeto e Ter direitos de envio e Ter acesso de leitura e escrita ao reposit rio O que se pode ou n o fazer assim que voc tem direito de envio Assim que voc for aceito como membro do projeto voc ter acesso a todo o reposit rio Firebird n o apenas ao m dulo de manuais N o existe nenhuma barreira t cnica que o impe a de enviar mudan as aos outros m dulos o m dulo n cleo fi rebird2 por exemplo ou mesmo CVSROOT onde importantes informa es do projeto s o guardadas Voc j deve ter adivinhado que isso N O a id ia Siga as seguintes regras e Nunca envie nada aos outros m dulos a n o ser que as pesoas respons veis pe am isso explicitamente e Apenas envio trabalho para o m dulo de manuais se isso uma tarefa designada para voc E mesmo assim de bom tom que voc anuncie suas mudan as e adi es para lista de discuss o de modo que outros docu mentadores tenham uma chance de coment las Afinal isto um esfor o col
30. cumentos mas importante n o confundir informa o com texto literal N s n o podemos copiar e colar texto de outros trabalhos na nossa documenta o a n o ser que o autor explicitamente permita nos isso Verifique o aviso de copyright da obra em quest o se n o h nenhum considere que a obra est automaticamente sujeita conven o de Berne e voc deve entender que ilegal copi la mesmo parcialmente o mesmo caso da obra dispon vel gr tis N o ter que pagar por um documento n o significa que voc pode copiar livremente partes do mesmo em uma obra sua Mais especificamente a documenta o beta do Interbase 6 da Borland mesmo gr tis n o fazem parte do pacote do Interbase que foi aberto em julho de 2000 N s perguntamos Borland diversas vezes se n s poder amos usar esses documentos como se estivessem sob a Licensa P blica do Interbase mas eles sequer se deram ao trabalho de responder Ent o sinta se livre para usar essa documenta o como fonte de informa o mas n o copie texto diretamente dela Seu direito autoral e a LDP Se voc contribui para o projeto de documenta o do Firebird seu trabalho ser inclu do no reposit rio de c digo aberto no SourceForge Em Janeiro de 2005 o time de documenta o do Firebird decidiu que as documenta o geradas por ele estariam sob a Licensa de Documenta o P blica Licensiar seu trabalho sob a LDP significa que voc manter o direito autoral mas ga
31. d iguais aos originais Dentro de um livro ou artigo todos os id s identificadores devem come ar com a mesma paravra em mi n sculas por exemplo usersguide seguida de um tra o seguido por uma ou mais paravras em min scu las Exemplos s o usersguide intro eusersguide download install Esta n o um requisito do DocBook mas nossa pr pria conven o Como voc pode ver no exemplo chapter s e section s cap tulos e se es respectivamente podem iniciar diretamente com um ou mais elementos para Mas uma vez que voc inclua se es num cap tulo ou subse es numa se o voc n o pode adicionar mais elementos para depois deles somente dentro deles Bom editores com suporte a DocBook simplesmente n o permitir que voc cometa tal erro mas caso voc digite seu XML do DocBook na m o isso algo que voc precisa ficar atento Se voc utiliza um editor de XML bem prov vel que voc raramente tenha que criar os elementos explici tamente Por exemplo se voc inserir um chapter ou uma section um cap tulo ou uma se o respec tivamente no XMLMind XML Editor o primeiro para par grafo vazio automaticamente criado E quando voc digita texto em um par grafo e pressiona ENTER esse par grafo automaticamente fechado e um novo criado Pule o resto das subse es sobre elementos DocBook se voc j conhece tudo sobre elementos do DocBook 17 Guia de escrita Listas DocBook oferece v rios
32. e software Voc pode us lo sozinho ou em um grupo Voc precisa de um cliente CVS para us lo Um cliente CVS um programa com o qual voc pode acessar o reposit rio do CVS lt lt explicar este termo gt gt Para verificar se um cliente CVS est instalado no seu systema digite cvs na linha de comando Se n o est la v para estar URL para baix lo 2 Sevoc tiver inclu do algum coment rio resolva os primeiro Verifique se CVS realmente significa Sistema de Vers es Concorrentes sim significa Decida se voc deve explicar o termo reposit rio do CVS agora sim deve 3 Agora trabalhe sobre o par grafo novamente e tente fazer o texto fluir mais naturalmente sempre que puder Muito provavelmente ser bem mais f cil do que voc imaginava 4 Se ainda est meio estranho n o se aborre a melhor esquisito e claro que fluindo macio e vago Talvez voc deva revisitar esta passagem mais tarde e ver se voc pode faz la ficar melhor Esta abordagem funciona para mim Se voc est travado dessa maneira tente a espero que funcione para voc Direitos Autorais Respeitando os Direitos Autorais de Outros Quando n s escrevemos manuais podemos consultar todo tipo de outras documentades e n s devemos porque n s desejamos o melhor resultado poss vel Qualquer informa o que publicamente dispon vel em manuais de terceiros guias de usu rio tutoriais etc pode ser livremente usado nos nossos do
33. ebsite voc n o ter muita dificuldade em criar tabelas no DocBook Existem diferen as por m e as tabelas do DocBook s o bem ricas Uma lt table gt tabela consiste de um lt title gt t tulo e um ou mais lt tgroup gt s mas geralmente apenas um Oelemento lt tgroup gt obrigat rio e tem um atributo obriagat rio cols Voc deve setar esse atributo com o n mero de colunas no lt tgroup gt Dentro de um lt tgroup gt voc pode colocar os elemento lt thead gt lt tfoot gt e lt tbody gt Cada um desses tem um ou mais lt row gt s os quais podem ter tantos lt ent ry gt s c lulas quanto forem necess rios para chegar ao n mero de colunas do atributo cols Voc pode combinar c lulas criando spans mas eu n o entrarei nesse m rito Tanta coisas para uma estrutura b sica Agora mostraremos um exemplo primeiro em fonte DocBook XML e depois a tabela resultante no documento de sa da renderizado N o se preocupe com os lt colspec gt por enquanto estes s o subelementos opcionais usados para ajustes finos lt table id docwritehowto table dboftheyear gt lt title gt Pesquisa LinuxQuestions org Banco de dados do ano de 2003 lt title gt lt tgroup cols 3 gt lt colspec align left colname col dbname colwidth 2 gt lt colspec align right colname col votes colwidth 1 gt lt colspec align right colname col perc colwidth 1 gt lt thead gt lt row
34. enderizado mas eles n o s o a mesma coisa O fonte em XML sabe disso apesar n o mostrar sempre Esta informa o til e n o queremos perd la e Al m disso n s podemos adaptar nossas folhas de estilos para cada de elemento individualmente Assim que decidirmos que um firstterm deva ter apar ncia diferente de um citetit 1e n s arranjamos isso mas somente se eles forem marcados com tags diferentes n o se eles forem ambos emphasis no fonte em XML Isso conclui as se es no DocBook Com o conhecimento apresentado acima voc deve saber o suficiente para elaborar documentos em DocBook XML para o projeto Firebird Claro que se voc usar um editor de XML dedicado o que altamente recomendado voc deve consultar a documenta o do mesmo para aprender como us lo o que uma que este documento n o cobre Aspectos do processo de escrita n o relacionados com o DocBook Ap s a enchente de informa o sobre DocBook nas se es anteriores n s discutiremos rapidamente algums outros aspectos importantes da escrita de documentos linguagem estilo e direitos autorais Linguagem e estilo Linguagem A comunidade Firebird bem diversa e feita de pessoas com muitas l nguas mater diferentes Se voc escrever documenta o em uma linguagem outra que n o a sua pr pria provavelmente cometer algums enganos Isso n o catastr fico mas voc deve tentar reduzir o n mero de erros Algumas estrat gias para ajud
35. etivo e Se voc pensa que um novo documento ou pasta deve ser adicionado n o crie e envie direto mas proponha isso na lista Na pr tica as coisas s o um pouco mais leves que o dito acima especialmente onde isso se refere s suas tarefas N s n o queremos que voc se sinta preso e tendo a sensa o de que tem de pedir permiss o para cada coisinha que tiver de mudar Mas n s queremos que voc aja responsavelmente e tamb m que saibamos o que cada um est fazendo Al m disso mantendo se em contato com os outros inspirativo Junto n s podemos fazer isso funcionar Enviando seu trabalho Mesmo que voc seja um membro do projeto voc pode apenas enviar mudan as de uma c pia local se o checkout for feito com o seu login no SF SourceForge Se voc ainda est trabalhando com uma c pia a qual voc fez check out anonimamente voc primeiro deve fazer um SSH check out e ent o reaplicar suas mudan as e envi las Reveja o Howto Gerando as manuais Firebird se voc n o lembra com fazer um SSH checkout Se algum tiver passado do seu ltimo checkout ou atualiza o ent o fa a uma atualiza o antes de enviar Isto far que sua c pia local esteja em sincronismo com o reposit rio e reduzir a possibilidade de conflitos Assim que voc esteja pronto para enviar v para a pasta manual Se voc usa um CVS em linha de comando digite cvs update d apenas se voc deseja fazer uma atualiza o antes
36. is o ou melhor as regras de renderiza o poderiam ser codificadas direto nas ferramentas mas isso tornaria tudo muito inflex vel Este o motivo pelo qual estas regras s o definidas em folhas de estilo stylesheets no original Uma folha de estilos um documento usualmente em texto puro que diz s ferramentas coisas como Imprima os t tulos dos cap tulos numa fonte preta de 24 pontos inicie cada cap tulo numa nova p gina use it lico para nfase renderize avisos com uma fonte vermelha 12 pontos em negrito use caixa baixa para acr nimos etc etc Esta abordagem permite que o usu rio altere as folhas de estilo se ele ou ela n o gosta do resultado final na apar ncia do documento Isto seria muito mais dif cil ou mesmo imposs vel sem ter que alterar as pr prias ferramentas Benef cios do DocBook XML DocBook tem uma monte vantagens para qualquer quem escreve documenta o t cnica Embora nenhum desses benef cios seja nico do DocBook ele possui todos e largamente suportado Isto o faz a escolha perfeita para a nossa documenta o do Firebird Cuidado Esta lista de benef cios est ligeiramente diferente da vers o original do autor Para n s estas s o as mais importantes e A primeira vantagem do DocBook inexist ncia de informa o de apresenta o Com isso temos apenas estrutura e conte do tornando o documento fonte independente dos formatos a serem acessados pelos leito
37. ks em caso voc deseje mais informa es sobre o DocBook todos em ingl s http opensource bureau cornavin com crash course Writing Documentation Using DocBook a Crash Course por David Rugge Mark Galassi e Eric Bischoff Um timo tutorial mesmo que a maior das ferramentas usadas n o s o as que n s usamos http docbook org tdg en DocBook The Definitive Guide por Normam Walsh e Leonard Muellner N o espere seja um tutorial para o iniciante de fato a primeira parte meio assustador se voc um novato em DocBook A raz o do mesmo estar listado aqui o fato de este site ser uma excelente refer ncia online para os elementos http www tidp org HOWTO DocBook Demystification HOW TO O DocBook Demystification Howto interessante que caso voc deseje conhecer um pouco mais sobre XML e DocBook do que mostrado aqui Possui tamb m um monte de material sobre SGML e de novo ferra mentas que n o s o utilizadas no subprojeto de documenta o do Firebird http sourceforge net projects docbook O projeto open source DocBook no SourceForge Se voc conhece algum outra fonte de informa o onlie deixe nos saber postando uma mensagem na lista de discuss o firebird docs Ferramentas para criar documentos DocBook XML Por causa que DocBook um formato n o bin rio voc pode usar qualquer editor de texto puro como emacs pico Bloco de Notas do Windows vi etc para escrever sua documenta
38. lementos section vs sectN modificada Retirados xr ef e alguns outros elementos raramente utilizados adicio nado procedure Atualizada informa o sobre literallayout n o monoespa ado Adicionada se o sobre LDP e como incluir um Aviso de Licensa e Hist ria do Documento Numerosas melhorias menores Adicionada hist ria do documento e n mero de revis o Este trabalho est licensiado sob a Licensa de Documenta o P blica 1 1 pt br 26 Mar 2005 FA Tradu o para o Portugu s do Brasil 35 Guia de escrita Ap ndice B Aviso de Licensa Os conte dos desta Documenta o s o sujeitos Licensa de Documenta o P blica vers o 1 0 a Licensa voc s pode usar esta documenta o caso se sujeite aos termos desta Licensa C pias da Licensa est o dispon veis em http www firebirdsgl org pdfmanual pdl pdf PDF e http www firebirdsgl org manual pdl html HTML A Documenta o Original entitulada Firebird Docwriting Guide O Escritor Inicial da Documenta o Original Paul Vinkenoog O Tradutor para o Portugu s do Brasil Fabr cio Pontes de Ara jo Copyright C 2003 2005 Todos os direitos reservados Contato com o Escritor Original paulvink at users dot sourceforge dot net Contato com o Tradutor para o Portugu s do Brasil fabricio araujo ARROBA infolink com br 36
39. lista de discuss o firebird docs N s certamente n o desejamos recusar documenta o til apenas porque n o est no formato certo Guia de escrita Uma introdu o bem gen rica a XML XML sigla de Linguagem de Marca o Extens vel a sigla est em ingl s o que na verdade significa texto puro com algumas tags de marca o Um fragmento de texto em XML seria algo como lt paragrafo gt lt alto gt Nao lt alto gt ela gritou lt assustador gt Mas a mao sangrenta lt italico gt continuou rastejando lt italico gt em direcao a ela lt assustador gt lt figura arquivo bloody hand png gt lt paragrafo gt Atributos e tags e6 939 669 No exemplo dado acima as palavras e frases entre os sinais de lt e gt s o tags de marca o lt italics gt uma tag inicial lt italico gt uma tag final e lt figura arquivo bloody hand png gt uma tag isolada cuja nomenclatura oficial tag de elemento vazio Tags em XML s o sempre formatadas deste jeito Tabela 1 Formato das tags em XML Tipo de Tag Inicia com Termina com Tag inicial lt gt Tag final lt gt Tag de elemento vazio lt gt Ainda nos referindo ao exemplo as palavras paragrafo alto assustador italico e figura s o nomes de tag Na tag lt figura gt archivo bloody hand png chamado de atributo com ar chivo sendo o nome do atributo e bloody hand png sendo o valor do at
40. m XML convertido para Guia de escrita diferente formatos de sa da exemplos um arquivo PDF uma p gina HTML ou mesmo um arquivo de som Isto chamado de publica o multicanal Neste contexto lt alto gt pode ser traduzido por negrito no formato PDF para uma fonte com cor vermelha em negrito numa p gina web e no sintetizador signifique um aumento de volume de 50 Olhando as outras tags lt figura gt obviamente uma instru o para inserir a imagem bloody hand png no documento e lt scary gt bem essa a bem menos clara que lt loud gt Talvez a frase entre as tags lt scary gt tenham que pingar sangue Ou talvez alguma m sica assustadora tenha que ser tocada aqui Isso tudo depende da pessoa que definiu as tags e do software que eles usam para renderiza o A tag lt paragrafo gt finalmente uma tag estrutural Ela nos diz algo sobre o lugar que as linhas tem dentro da hieraquia interna do documento No documento final par grafos podem ou n o ser separados por linhas vazias Novamente tudo depende no software de renderiza o e possivelmente em alguma op o de configu ra o Algumas outras tags estruturais que se pode pensar s o por exemplo lt capitulo gt lt se o gt and lt subdocumento gt Caracteres especiais e Entidades Por causa o caractere lt tem um significado especiais como o in cio de uma tag voc n o pode inclu lo dire tamente como um valor literal Em
41. mas n o requer um t tulo e n o ser colocada no ndice Tal como no caso do lt exam ple gt lt informal example gt Se voc deseja aninhar tabelas use uma lt table gt lt informaltable gt dentro de uma lt ent ry gt ou uma lt entrytb1l gt em vez de uma lt entry gt Tabelas possuem muitas outras funcionalidades al m das mostradas aqui mas essas n s deixaremos para voc as explorar Avisos DocBook tem muitas tags para marcar um bloco de texto como uma nota aviso dica etc Na sa da tais blocos tipicamente aparecem indentados e marcados com um cone ou palavra para denotar seu prop sito Estas tags s o em ordem alfab tica lt caution gt lt important gt lt note gt lt tip gt e lt warning gt Usarei uma lt tip gt em um exemplo as outras funcionam exatamente do mesmo jeito lt tip gt lt para gt Se voc inserir um elemento caution important note tip ou warning no seu texto n o inicie o mesmo com as palavras advert ncia importante nota dica ou aviso porque essas palavras geralmente s o geradas automaticamente pelo programa de renderiza o lt para gt lt tip gt E este o resultado 25 Guia de escrita Dica Se voc inserir um elemento caution important note tip ou warning no seu texto n o inicie o mesmo com as palavras advert ncia importante nota dica ou aviso porque essas palavras geralmente s o geradas automaticamente pelo programa de renderiza
42. nta o para o Firebird a primeira coisa que voc deve fazer assinar a lista de discuss o onde n s discutimos nossos planos e nosso trabalho Esta lista aberta a todos e a assinatura n o o compromete em nada Envie um email para lt firebird docs request tlists sourceforge net gt com a palavra subscribe ou como assunto ou como a primeira e nica linha do corpo da mensagem propria mente dita Al m desta forma existe outra alternativa usar o formul rio desta p gina no link abaixo http lists sourceforge net lists listinfo firebird docs Independente do meio utilizado voc receber uma mensagem de email do programa da lista em alguns minutos Siga as instru es e voc est na lista Guia de escrita Usando a interface news do servidor Atkin Existe tamb m uma interface news para esta e outras listas do discuss o relacionadas ao Firebird um pouco problem tica no seu funcionamento em algumas raras situa es n o funciona e eu n o usaria a mesma para postar mensagens Mas a grande utilidade desta interface tima para os fins de arquivamento e busca O per odo de reten o um pouco longo tamb m de modo que se voc baixar todas as mensagens no servidor ter uma bom peda o da hist ria da lista antes da sua chegada Para acessar essas newsgroup aponte seu leitor favorito para news atkin com E baixe a lista de grupos Assine os grupos que desejar Note que a lista firebird d
43. o cap tulo elementos do t tulo etc em vez de tags de capitulo ou tags de t tulo Embora estes termos possam ser intercambi veis na maior parte do tempo existem situal es onde importante saber a di feren a Conclus o do XML Bom isso tudo que voc necessita saber sobre XML Agora voc deve ter uma id ia geral de como um texto em XML se aparenta o que s o tags e elementos e para qu eles existem E como eu disse antes a id ia supersimplificada mas suficiente para os nossos prop sitos Deve se entender tamb m que escrever puramente em um XML auto inventado algo sem muito sentido a n o ser que voc tenha software que entenda e processe suas tags Sen o como voc vai tornar o seu XML em um documento bem formatado e apresent vel Felizmente n o temos que nos preocupar em desenvolver nossas defini es de elementos e software de conver s o Existem alguns tipos de XML formalizados cada um definindo um n mero de tags e igualmente impor tante algumas regras sobre como us las DocBook XML um desses tipos Uma introdu o ao DocBook XML DocBook foi projetado tendo em mente a escrita de documentos estruturados usando SGML ou XML mas n o se preocupe com SGML n s utilizamos a variante XML E particularmente interessante para escrever livros t cnicos e artigos especialmente em assuntos relacionados a computadores DocBook XML definido em uma Guia de escrita
44. o como estiver escrto incluindo quebras de linhas espa os em branco etc E al m disso uma fonte de tamanho fixo ser utilizada nos documentos renderizados O termo listagem de programa pode interpretado de forma abrangente aqui voc pode us lo para fragmentos de SQL ou exemplos de DocBook XML Este documento especialmente na se o sobre elementos a qual voc est lendo agora cheia de programlist ing s de modo que voc j viu como elas se parecem Programlistings s o renderizadas deste jeito 21 Guia de escrita Importante Em listagens de programas tag programlist ing voc deve limitar o tamanho da linha por volta de 70 caracteres caso contr rio o texto sair das margens quando renderizado em PDF A mesma regra vale para outros elements que preservam layout como screen literallayout etc screen Use um elemento screen tela para mostrar o que o usu rio v ou dever ver numa tela de computador em modo texto ou numa janela de terminal Aqui tamb m seu layout ser preservado e uma fonte de tamanho fixo ser usada mas a sem ntica diferente Ela pode ou n o ter apar ncia diferente de uma listagem de programa na sa da Este um exemplo curto mostrando o que acontece se voc tentar gerar um alvo n o existente na rvore de manuais lt screen gt D NFirebirdimanual incl howtoisrcNbuild gt build ugh java version 1 4 2 01 Java TM 2 Runtime Environment Standard Edition build
45. ocs mapeada para o grupo sourceforge firebird doc sem o s no servidor news Atkin Dependendo do seu navegador ou leitor de news este links j o coloca direto no grupo news news atkin com sourceforge firebird doc Voc pode postar no newsgroup at mesmo se voc n o faz parte na lista de discuss o mas neste caso sua mensagem ser retida para ser aprovada por um moderador humano Isso significa um atraso de um dia em algumas raras ocasi es mais Achar um assunto Estas diretrizes talvez possam ajud lo a achar um assunto para escrever sobre e Primeiro tenha certeza que sabe o que j est dispon vel ningu m precisa de um terceiro guia de convers o de MSSQL para o Firebird e Ent o pergunte a voc mesmo que est faltando e que seria til para os usu rios do Firebird em geral ou talvez algum grupo espec fico e E tamb m pergunte a voc mesmo sobre o que voc gostaria de escrever A escolha mais l gica seria um t pico o qual lhe familiar mas voc pode tamb m pegar um assunto sobre o qual voc deseja pesquisar e aprender primeiro claro que bem mais trabalhoso mas tamb m uma grande experi ncia de aprendizado se voc deseja investir o tempo e Voc n o necessariamente precisa escrever o livro inteiro guia ou artigo Talvez j hava pessoas trabalhando numa produ o maior na qual voc pode ajudar Talvez voc possa escrever um ou dois cap tulos para um livro Ou talvez voc pos
46. possui elementos em linha o inverso n o poss vel Ok vamos come ar a experimentar esses elementos em linha Incluirei exemplos tanto como fonte XML e sa da renderizada para a maior parte deles filename command application envar Use atag filename para marcar nomes de arquivos no mais abrangente sentido Atributos podem opcio nalmente indicar que o mesmo um arquivo de cabe alho um diret rio etc Coloque seu documento no subdiret rio lt filename class directory gt src docs firebirddocs lt filename gt Na sa da l se Coloque seu documento no subdiret rio src docs firebirddocs command e application s o ambos usados para programas execut veis command geralmente esco lhido para programas menores e comandos internos seu conte do deve ser o comando exato de disparado em uma linha de comando application usado para programas maiores e n o precisa ser o nome do arquivo execut vel Ambos podem se referir ao mesmo programa Digite lt command gt netscapesamp lt command gt numa janela de terminal para iniciar o lt application gt Netscape Navigator lt application gt Isto renderizado como 26 Guia de escrita Digite netscape amp numa janela de terminal para iniciar o Netscape Navigator envar denota uma vari vel de ambiente subscript superscript subscrito sobrescrito Fazem o que esperado Ap s inventar a f rmula e mc lt superscript gt 2 lt superscript gt eu
47. qual usa uma vers o mais restrita do XMLSpy como base Esta lista n o tem a intens o de ser exaustiva mas se voc conhece alguma bom XML editor bom sob a pers pectiva de um escritor de documentos do Firebird que voc acha que deva estar aqui deixe nos saber via a lista de discuss o Escrevendo seu documento DocBook Al ainda conosco Eu seu que gastei um bom tempo escrevendo sobre XML e DocBook mas eu realmente sinto que era necess rio devido ao fato que esses conceitos s o novos para muita gente Apenas jogando alguns links e dizendo os para se virarem por si mesmo certamente faria com que perd ssemos alguns escritores valiosos De qualquer modo aqui estamos finalmente prontos para escrever nossos documentos Esta se o descreve como configurar seu documento DocBook e aplicando as tags e atributos corretos nos lugares de direito Por favor leia a subse o sobre elementos hier rquicos mesmo que voc seja um escritor DocBook experiente pois cont m algumas diretrizes espec ficas do nosso projeto Depois disso pode pular o resto da subse es sobre DocBook Criando o documento Todo a nossa documenta o parte um grande elemento DocBook o lt set gt Este o mais alto elemento na hierarquia DocBook Nosso conjunto cont m um n mero de livros tag lt book gt os quais cont m cap tulos tag lt chapter gt e por a afora A vantagem de p r todos os livros em um nico conjunto que podem referencia
48. r os outros por exemplo pode se colocar links em sua documenta o apontando para um determinado ponto em outro livro Felizmente colocando todos os livros num nico conjunto n o implica em que eles tenham que estar em um nico grande documento DocBook permite que se possa configurar um documento principal como mostrado abaixo N o se preocupe se voc n o entende a se o iniciada com lt DOCTYPE n s j temos um documento principal de modo que voc n o tem que escrever tal tipo de coisa horr vel por voc mesmo lt xml version 1 0 encoding UTF 8 9 gt 13 Guia de escrita lt DOCTYPE set PUBLIC OASIS DTD DocBook XML V4 1 2 EN rilesdocbooles dear SEND Escepira Anitiro SYSTEM Cetefointrosmin gt lt lIENTITY firebird sqgql ref SYSTEM file fbsglref xml gt STENTEC LASIN IRIEAR no lt set id firebird books gt amp firebird intro amp firebird sql ref lt set gt Com o documento principal configurado os v rios outros livros podem estar em arquivos separados fbintro xml fbsglref xml etc o quais podemos editar independentemente Tal arquivo o seu por exemplo mais ou menos estruturado deste jeito lt xml version 1 0 encoding UTF 8 9 gt lt book id fbintro gt lt chapter id fbintro preface gt lt chapter gt lt chapter id fbintro installing firebird gt lt chapter gt lt book gt E
49. rante aos outros certos direitos e Uso livre todos podem usar e distribuir seu trabalho gr tis ou por dinheiro desde que o aviso da licensa esteja intacto e Direito de modifica o todos podem modificar e redistribuir seu trabalho desde que as vers es modificadas sejam licensiadas tamb m pela LDP o aviso da licensa esteja intacto e as modifica es sejam documentadas 31 Guia de escrita e Trabalhos maiores todos podem incorporar sua documenta o modificada ou n o em um trabalho maior O trabalho maior como um todo n o necessita estar licensiado pela LDP mas os requisitos da licensa devem ser cumpridos para as partes que est o sob a LDP O que t o bom a respeito da LDP que esta prov os mesmos direitos e restri es em termos de uso de nossos documentos quanto a IPL e IDPL licensas do c digo do Firebird para o c digo do FlIrebird Para o texto completo da licensa veja os links no aviso de licensa abaixo o fonte DocBook est em src docs firebirddocs licenses xml Usando os documentos do PostgreSQL PostgreSQL outro grande banco de dados de c digo abreto com surpresa surpresa muitas similaridades com o Firebird mas tamb m muitas diferen as Dependendo do tipo de documenta o voc ir escrever pode ser beneficial basea la no documenta o j existente do PostgreSQL Mas lembre se se voc usar o material do PostgreSQL voc TEM que incluir o aviso de licensa deles no seu documento
50. res finais e Al m disso o fato de DocBook estar focado na estrutura do documento torna a tarefa de transferir um rascunho de assuntos para a estrutura do documento final muito mais f cil 10 Guia de escrita DocBook um padr o aberto Com isso um documento fonte pode gerar documentos finais em qualquer sistema operacional que tenha ferramentas dispon veis para isso E tamb m permite que um documento fonte seja gerado por exemplo em Mac OS X e tenha seus documentos finais renderizados em Windows Ao baixar o m dulo de manuais do Firebird s o inclu das ferramentas de renderiza o em PDF e HTML tanto para Linux e Windows e no futuro poderemos abranger mais plataformas conforme seja necess rio Integra o simplificada com o CVS uma vez que o DocBook baseado em texto puro com isso habilitan do nos a utilizar diversas funcionalidades do CVS que s s o utiliz veis com texto puro Simplifica enormemente o gerenciamento da documenta o devido ao fato que as regras de renderiza o s o centralizadas e com isso todos ganham Ningu m necessita ficar seguindo regras chatas de formata o e as decis es sobre a identidade visual dos documentos ficam todas armazenadas nas stylesheets folhas de estilos Com isso todos ganham os escritores se preocupam com o conte do e os gerentes da documenta o com as regras de formata o e renderiza o Documenta o sobre DocBook na Internet Aqui est o alguns lin
51. ributo Os valores dos atributos devem sempre estar entre aspas tanto faz aspas duplas ou simples XML permite que voc defina do jeito que voc desejar desde que voc as construa corretamente Deste modo lt estatag gt lt aquelatag gt e lt isto nao e uma tag gt s o todas tags XML corretamente formadas Por que eu disse corretamente formadas em vez de v lidas Por causa de que o termo validar s usado para algumas implementa es especificamente definidas como por exemplo o DocBook Obviamente as tags propriamente ditas n o s o para aparecer no documento final isto aquele que apresentado aos leitores Em vez disso ele cont m instru es que afetam sua apar ncia XML quando usado para escrever documenta o um t pico formato fonte criado para ser processado por software para produzir documentos de sa da bem formatados Este processo chamado renderiza o Algumas tags s o sem sombra de d vida instru es de maquiagem lt italico gt continuou rastejando lt italico gt significando que as palavras continuou rastejando sejam mostradas em it lico Por m lt alto gt Nao lt alto gt menos bvio Deve a palavra N o aparecer em negrito Ou sublinhada Ou mesmo em it lico Ou talvez este texto para ser lido em voz alta por sintetizador de discurso e a tag lt alto gt o instrua a levantar a voz Todas essas coisas s o poss veis e tem mais frequentemente um documento fonte e
52. rompt computeroutput texto exibido pelo computador Digite lt userinput gt convidado lt userinput gt no prompt lt prompt gt login lt prompt gt e o servidor ir saud lo com um lt computeroutput gt Bem vindo usu rio convidado lt computeroutput gt Sa da Digite convidade no prompt login eo servidor ir saud lo com um Bem vindo usu rio convidade 27 Guia de escrita keycap O texto de uma tecla do teclado ou o seu nome comum Pressione a tecla lt keycap gt Del lt keycap gt para apagar a mensagem ou lt keycap gt ESPA O lt keycap gt para mov la Sa da Pressione a tecla Del para apagar a mensagem ou SPACE para mov la sgmitag Este elemento foi usado extensivamente durane este docuemento ele marca tags elementos atributos en tidades etc de SGML e XML Se um diret rio ajuste o atributo lt sgmltag class attribute gt class lt sgmltag gt do elemento lt sgmltag class element gt filename lt sgmltag gt para to lt sgmltag class attvalue gt directory lt sgmltag gt Sa da Se um diret rio ajuste o atributo class do elemento fi lename para directory Outros poss veis valores de para sgmltag class s o starttag endtag emptytage genentity para uma entidade emphasis citetitle firstterm nfase t tulo de cita o primeiro termo Use emphasis para enfatizar palavras em geral citetitle para t tulos de livro etc e firstterm se
53. sa suprir material de documenta o bruta sobre um assunto que voc conhe a muito bem e Fale sobre suas id ias ou sua busca por id ias na lista de discuss o firebird docs A frequ ncia de postagem pode ser muito baixa s vezes mas tenha certeza que se voc postar l sua mensagem ser lida e respondida Guia de escrita Preparando se para escrever fa a um resumo 2 E sempre uma boa id ia pazer um resumo antes de escrever o texto propriamentedito Preparar um resumo ajuda voc a ficar organizado isso reduz a chance de esquecer alguma coisa vital e faz o pr prio trabalho de escrever muito mais f cil Voc pode seguir estes passos quando fizer um resumo e Defina exatamente o que voc deseja que seus leitores aprendam com o seu trabalho e Divida a mat ria do assunto em unidades l gicas cap tulos e ou se es e ou sub se es e Tenha certeza que a ordem das unidades fa a sentido especialmente para um passo a passo tutorial e ou guia do usu rio Assim arrume as unidades de forma que se algo tiver de ser feito ou entendido primeiro esse algo apare a primeiro em sua documenta o e Mostre seu resumo na lista firebird docs no sourceforge net e pergunte por coment rios Quando estiver satisfeito com seu resumo examine o inteiramente e decida se voc j tem toda informa o b sica para iniciar a escrita Numa situa o ideal voc dever contar com toda a informa o necess ri
54. sempre possui um id e um title um identificador e um t tulo respec tivamente O id permite que o elemento seja referenciado de uma outra parte do documento e at mesmo de outros documentos no mesmo conjunto Id um atributo o que significa que aparece dentro de uma tag n o vis vel nos documentos renderizados exceto no texto fonte do HTML mais ainda os identificadores da se o de alto n vel s o utilizados para nomear os arquivos HTML Title um elemento geralmente o primeiro elemento filho a ser achado no pai O conte do of elemento t tulo aparecer nos documentos gerados Se voc for rescrever um livro ou artigo tamb m uma boa id ia incluir um elemento lt bookinfo gt ou lt ar ticleinfo gt onde voc pode a informa o de autor e mais coisas Eis um exemple de como estruturar seu documento lt xml version 1 0 encoding UTF 8 9 gt lt book id usersguide gt lt bookinfo gt lt title gt Guia do Usu rio do Firebird lt title gt lt author gt lt firstname gt william lt firstname gt lt surname gt Shakespeare lt surname gt lt author gt lt bookinfo gt lt chapter id usersguide intro gt lt title gt Introdu o lt title gt 16 Guia de escrita lt para gt Al Este texto introdut rio do Guia do Usu rio do Firebird lt para gt lt chapter gt lt chapter id usersguide download install gt lt title gt Baixnado e instalando o Firebird lt title gt
55. texto e seu documento subseqiientemente publicado na Internet esses endere os de email ser o expostos a rob s de explora o usados por spammers De modo que ser previs vel um aumento de spam nesses endere os Tenha sempre certeza que os donos dos endere os concordam em t los publicados na internet anchor Um anchor ncora um elemento vazio marcando um local exato dentro de um documento Ele n o mostrado no texto que seus leitores l em mas podem ser usados como alvos para links Isto til se voc deseja linkar para um local qualquer no meio de um grande par grafo lt para id lost at sea gt Bila folen DaN e algo mais e ent o algo Agora aqui est um lugar interessante no par grafo que eu quero ser capaz de linkar lt anchor id captain haddock gt A est Drones de par grafo ligados e ligados e ligados lt para gt Tendo colocado a ncora voc pode criar um link para ela lt link linkend captain haddock gt V para o lugar interessante lt link gt nesse longo longo par grafo Se voc linkar para um elemento curto ou para o in cio de um elemento mais f cil dar ao dito elemento uma id e us la como alvo do link Listagens de programas telas layout literal e exemplos programlisting Se voc incluir fragmentos de c digo no seu documento coloque os num elemento programlisting listagem de programa Tudo que voc digitar ser renderizad
56. tro das tags correspondentes lt para gt lt listitem gt lt varlistentry gt lt variablelist gt A lista que voc est vendo agora enumerando os diferentes tipos de listas uma lista vari vel com os nomes dos elementos itemi zedlist orderedlist etc como termos A pr xima se o sobre links tamb m consiste de uma senten a introdut ria seguida de uma lista vari vel Links Voc pode criar hiperlinks para alvos no seu pr prio documento em outro documento no mesmo conjunto ou na internet link link o elemento gen rico que aponta para qualquer local no conjunto de documentos O atributo linkend sempre deve estar presente seu valor deve ser o id de um alvo de link o elemento para o qual se ir saltar Clique lt link linkend docwritehowto introduction pt br gt aqui lt link gt para saltar para a introdu o No documento renderizado a palavra aqui ficar quente o que significa um link clic vel apontando para a introdu o Clique aqui para pular a introdu o 19 Guia de escrita Cuidado Embora voc possa usar a tag link para apontar para qualquer elemento no conjunto inteiro voc s deve faz lo se o alvo do link estiver estiver no mesmo documento PDF que o pr prio link A vers o em HTML pode ser totalmente hiperlinkada mas links na vers o em PDF n o podem ser feitos para fora do mesmo documento Nossos PDFs tipicamente cont
57. voc introduzir um novo conceito ou palavras para os seus leitores N s usamos lt firstterm gt DocBook XML lt firstterm gt para nossa documenta o do Firebird Uma introdu o curta segue lt emphasis gt por favor lt emphasis gt leia a cuidadosamente Se voc deseja saber mais sobre o assunto compre lt citetitle gt DocBook The Definitive Guide lt citetitle gt Sa da N s usamos DocBook XML para nossa documenta o do Firebird Uma introdu o curta segue por favor leia a cuidadosamente Se deseja saber mais sobre o assunto compre DocBook The Definitive Guide quote literal cita o literal Use quote para uma cita o em linha ao oposto de um blockquote Caracteres aspas ser o inseridas automaticamente Usando quote ao inv s de digitando as aspas por voc mesmo o que perfeitamente le gal tem a vantagem de que n s podemos alterar o tipo de aspas atrav s das folhas de estilo se n s quisermos Um literal um fragmento de texto ou palavra para ser lido literalmente um elemento bem gen rico frequentemente usado para fazer certas palavras se destacarem tipograficamente A qualquer custo evite usar a palavra lt literal gt monstruoso lt literal gt em sua documenta o Sa da A qualquer custo evite usar a palavra monstruoso em sua documenta o Voc deve usar esses elementos em linha onde voc puder Bem se o fizer certamente far o seu documento ficar mais rico far com que
58. y And his dark secret love Doth thy life destroy William Blake Nota Nas vers es anteriores deste documento voc era avisado para n o usar a variante com fonte de tamanho n o fixo de literallayout porque ficava horr vel a apar ncia na sa da em PDF Mas o problema j foi resolvido como voc pode ver nos PDFs example Um example um exemplo formal com um t tulo Geralmente se d um id ao mesmo para possa ser referenciado de outros lugares no documento Um ndice de exemplos gerado automaticamente quando o documento renderizado Voc fregientemente encontrar programlist ing s em um exemplo mas este pode conter screens paras listas etc Eis um exemplo de um example lt example id docwritehowto sql example gt lt title gt Um exemplo SQL lt title gt lt para gt Com este comando voc pode listar todos os registros na tabela COUNTRY lt para gt lt programlisting gt SELECT FROM COUNTRY lt programlisting gt lt example gt Na sa da ter o seguinte aspecto Exemplo 1 Um exemplo de SQL Com este comando voc poder listar todos os registros na tabela COUNTRY SELECT FROM COUNTRY Se voc deseja um exemplo sem um t tulo obrigat rio use um informalexample exemplo informal Exemplos informais s o tamb m deixados de fora do ndice de exemplos 23 Guia de escrita Tabelas Se voc j fez alguma vez uma tabela HTML para um w
Download Pdf Manuals
Related Search