Home

WebBook
Toolkit para Navegação em Documentação
Versão 3

WebBook é um toolkit para criar a navegação para manuais em HTML.

Gerência do Projeto:

Antonio Escaño Scuri

Tecgraf - Grupo de Tecnologia em Computação Gráfica, PUC-Rio, Brazil
http://www.tecgraf.puc-rio.br/webbook


Produto

Visão Geral

Este é um toolkit para criar a navegação para manuais em HTML. Já que a grande maioria dos manuais possui uma estrutura hierárquica simples, implementamos algumas funções em JavaScript para ajudar na criação de vários manuais do Tecgraf - mas não é necessário conhecer JavaScript para usar o WebBook.

Utilizamos a metáfora de um livro: ele é composto por várias páginas, arrumadas em seqüência, com um sumário para localizar determinadas informações. O usuário pode ir para a primeira página, para a seguinte, para a anterior ou para uma página qualquer localizada pelo índice de páginas. A mesma metáfora é utilizada por sistemas comerciais como o HTML Help da Microsoft, usado nas distribuições do MSDN e do TechNet.

O toolkit oferece todo o suporte necessário para se navegar pelas diversas páginas do livro e permite alternar entre os diferentes idiomas disponíveis. Mas o diferencial do WebBook é sua portabilidade, pois ele depende apenas de um navegador, podendo ser utilizado para qualquer tipo de documentação online e offline. E o melhor: está disponível de graça para todos.

Para entender como o toolkit funciona, consulte o Guia.

O WebBook está disponível em http://www.tecgraf.puc-rio.br/webbook.

Autores

WebBook foi criado por:

Antonio Escaño Scuri
Mark Stroetzel Glasberg

Agradecimentos

Agradecemos a Diego Nehab, pela primeira versão do código JavaScript para o gerenciamento da árvore e a Mark Stroetzel Glasberg pelo conversor para HTML Help da primeira versão do webbook.

A Henrique Pinheiro por várias melhorias na versão 2.

A Nalla Senthilnathan pelo Applet Java de busca simples. A Cristina Ururahy pela ajuda no Applet Java.

Download

Versão | Arquivos
3.03 | webbook303.tar.gz or webbook303.zip
3.02 | webbook302.tar.gz ou webbook302.zip

Histórico

Versão 3.0.3 (Ago 2012)

Atualizado o "Google Search".

Versão 3.0.2 (Dez 2006)

Modificado o Applet Java para funcionar com muitos arquivos. Java não estava conseguindo abrir muitos arquivos simulaneamente nas respectivas threads. Agora abre apenas um arquivos por vez em uma única thread. O código foi atualizado para poder ser compilado em versões atuais do Java.

Versão 3.0.1 (Nov 2006)

Adicionado suporte para uma busca simples usando um Applet Java creado por Nalla Senthilnathan.
Corrigidos os links de download.

Versão 3.0 (Nov 2006)

O arquivo de configuração em Lua está de volta. O código em JavaScript foi reduzido ao minimo. A árvore é agora descrita em Lua, então um script constroi a árvore em HTML com JavaScript somente onde é necessário.

Os frames e a árvore são agora arquivos estáticos em HTML de forma que mecanismos de busca possam facilmente encontrar as páginas internas do manual a partir do frame inicial (index.html).

A barra de ferramentas foi movida para dentro da área da árvore e a barra de título agora possui uma caixa de pesquisa do Google para um determinado site. A localização dos arquivos de configuração mudou da pasta "wb_usr" para a pasta corrente. Visual mais limpo da árvore sem imagens em nós ou folhas (parametros use_items e use_folders não são mais suportados).

O parametro revision_date não é mais usado. Novo parametro search_link deve ser acrescentado. As funções para sincronização automática a partir de links nas páginas de conteúdo não são mais suportadas e devem ser removidas. Veja no Guia como migrar do WebBook 2 para o WebBook 3.

Versão 2.1 (Dez 2004)

Novo script em Lua 3 para gerar um arquivo HTML Help em Windows a partir dos arquivos do WebBook.

Versão 2.0 (Nov 2002)

Árvore totalmente nova, navegação mais rápida, novo design, melhor organização de código, descrição da árvore mais simples em Javascript (independência de Lua).

Versão 1.1 (Ago 2002)

Permite chamadas externas para posicionar em uma determinada página. Ver exemplo.

Versão 1.0 (Jan 2001)

Primeira versão.

Pendências

  • Nada planejado.

Licença

Copyright 1994-2010 Tecgraf / PUC-Rio.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


Guia

Descrição

O toolkit permite criar uma estrutura de navegação para as suas páginas em HTML. Basta editar um arquivo de configuração e adicionar suas páginas no lugar certo. Você não precisará de nenhuma configuração especial de CGI ou Java para rodá-lo, e também não é necessário um servidor WWW. Basta abrir o arquivo "index.html".

Podem ser vistas 3 regiões divididas por molduras. A área de Título contém algumas informações sobre o livro online. A área da Árvore exibe a hierarquia de páginas do livro com algumas ferramentas para ajudar na navegação. E a área de Conteúdo mostra as páginas do usuário.

Você pode utilizar qualquer editor de HTML para gerar as páginas para a área de Conteúdo, incluindo páginas com código CGI.

As informações na área de Título e na Árvore são modificadas editando-se o arquivo de configuração "wb_usr.lua".

Instalando

Em primeiro lugar você deve copiar os arquivos do toolkit para a sua pasta:

wb      (Pasta)
wb_img  (Pasta)

Edite o arquivo de configuração "wb_usr.lua" que fica na pasta "wb". Este arquivo irá conter a diversas definições sobre o livro incluindo a definição da árvore. Também deve ser fornecido na pasta corrente um arquivo "logo.gif" que será a imagem a ser usada na barra de título.

Os seus arquivos do livro devem estar localizados na pasta correspondente ao idioma, mesmo que você ofereça apenas uma língua. Seguem os nomes pré-definidos:

en = English - United States
es = Spanish - Standard
pt = Portuguese - Brazil

Só foram criados ícones para os idiomas pt, en e es, mas é bastante simples criar um ícone novo com base em um dos já existentes.

Os arquivos respectivos em cada idioma devem possuir os mesmos nomes, assim como os bookmarks dentro deles de forma que o link na árvore possa ser único para todos os idiomas.

Arquivo de Configuração

É um arquivo texto, escrito em Javascript, que descreve todas as opções configuráveis do toolkit. Possui 3 tabelas, formando 3 grupos de parâmetros.

A seção User contém os parâmetros principais:

wb_usr
  langs          (uma tabela que conta os identificadores dos idiomas disponíveis)
  start_size     (a largura inicial da área da Árvore)
  title_bgcolor  (cor de fundo da área do Título, embora a imagem "title_background.png" seja usada como fundo)
  contact        (endereço de e-mail para a ferramenta de mail da Barra de Ferramentas)
  copyright_name (texto de direitos autorais para a área de título)
  copyright_link (URL para o link do texto de direitos autorais)
  search_link    (URL para o recurso de busca)
  file_title     (prefixo para o nome do arquivo, em geral uma versão curta do nome, ex: "webbook", usado pelo HTML Help)
  start_open     (Indica o estado dos ramos da árvore. Use "yes" ou "no" para alterar todos os nós ou apenas o número de um nó)
  google_id      (Identificador do Google Custom Search Engine)

A seção Messages contém os parâmetros dependentes do idioma:

wb_usr.messages
  xx              (identificador do idioma, pode ser "nl" de "neutral language" usado para todos os idiomas)
    title         (texto do título da janela do navegador)
    bar_title     (texto da área de Título)

A seção Tree contém a árvore com a hierarquia de tópicos:

wb_usr.tree
  (para cada tópico)
    name        (uma tabela com o título do tópico. Deve conter campos com o título para cada idioma ou nl para todos os idiomas. É possível utilizar tags HTML para alterar o estilo do texto)
    link        (nome de arquivo com a extensão. Se for deixado em branco o ítem ficará indisponibilizado sendo pintado de preto. Um link externo ao manual começado por http: também funcionará)
    folder      (subárvore de tópicos. Deve ser um array de outros tópicos)

Exemplo

Para um exemplo de um arquivo de configuração faça download do Webbook e veja o arquivo "wb/wb_usr.lua". Veja aqui uma parte dele:

wb_usr = {
   langs = {"en","pt"},
   start_size = "200",
   contact = "webbook@tecgraf.puc-rio.br",
   copyright_link = "http://www.tecgraf.puc-rio.br",
   search_link = "http://www.tecgraf.puc-rio.br/webbook",
   copyright_name = "Tecgraf/PUC-Rio",
   title_bgcolor = "midnightblue",
   file_title = "wb",
   start_open = "1"
}

wb_usr.messages = {
  pt = {
     title = "WebBook",
     bar_title = "WebBook - Versão 3.0"
  },
  en = {
     title = "WebBook",
     bar_title = "WebBook - Version 3.0"
  }
}

wb_usr.tree =
{
  name= {nl= "Webbook"},
  link= "home.html",
  folder=
  {
    {
      name= {en= "Product", pt= "Produto"},
      link= "prod.html",
      folder=
      {
        {
          name= {en= "Overview", pt= "Visão Geral"},
          link= "prod.html#over"
        },
        {
          name= {en= "Authors", pt= "Autores"},
          link= "prod.html#aut"
        },
...

Gerando

Os arquivos HTML para o conjunto de frames, a área de título e a árvore precisam ser gerados usando um interpretador de Lua na pasta "wb":

lua5.1 wb_build.lua

Os arquivos: "index.html", "wb_title.html" e "wb_tree.html" serão gerados na pasta que contém a pasta "wb". A pasta "wb" não precisa ser distribuída com seu manual nem colocada no servidor. Mas a pasta "wb_img" deve ser incluída.

Quando mais de um idioma é configurado então haverá um arquivo para cada idioma com um sufixo do idioma no nome do arquivo.

Para Windows o interpretador Lua é incluido nos arquivos de distribuição do WebBook. Mas para UNIX eles devem ser baixados do site LuaBinaries.

Página Inicial

A página inicial do webbook será sempre o link definido em wb_usr.tree.link. Todavia, é possível abrir o Webbook diretamente em um tópico específico. Para tanto, é necessário que seja fornecido na URL qual é o tópico em que desejamos abrir o webbook. O formato é descrito abaixo:

http://webbook_url/index.html?url=file.html#bookmark

Onde:

webbook_url é o endereço do seu Webbook;
file.html#bookmark é um link existente dentro da descrição da árvore fornecida no arquivo wb_usr.js.

Exemplo:

http://www.tecgraf.puc-rio.br/webbook/index.html?url=guide.html#init

Para acessar um arquivo local no seu computador use:

file:///d:/tecgraf/webbook/html/index.html?url=guide.html#init

HTML Help

Em Windows pode-se construir um arquivo HTML Help a partir dos arquivos de um WebBook. Para fazer isso voce precisa ter instalados alguns utilitários que são necessários para a conversão: o Microsoft Help Compiler (hhc.exe) e o interpretador de Lua (lua5.1.exe). Não é necessário instalar o HTML Help Workshop, mas é a maneira mais fácil de instalar o "hcc.exe".

Voce pode obter o HTML Help Workshop da Microsoft:

http://go.microsoft.com/fwlink/?LinkId=14188
ou
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp
ou
../download/htmlhelp.exe

A distribuição do WebBook inclue o interpretador Lua para Windows.

Atualmente ja´ existem ferramentas para visualizar arquivos CHM tambem em Linux e outras plataformas (http://xchm.sourceforge.net/).

O script de Lua "wb_hh\make_hh.lua" irá gerar um projeto para o HTML Help Workshop a partir da configuração do WebBook. O arquivo batch "wb2hh.bat" irá ajuda-lo a gerar o projeto e compilar o arquivo de HTML Help. Basta rodar "wb2hh myhelp en" e o arquivo "myhelp.chm" para o idioma "en" será gerado. Voce pode editar esse arquivo batch e adapta-lo para o seu caso.

Lembre-se que tudo que for referenciado localmente nos arquivos HTML será incluído no arquivo CHM. Veja aqui um exemplo para o próprio WebBook: wb_pt.chm. É importante que sua páginas HTML tenha títulos diferentes para que no resultado de buscas cada página aparece com um nome diferente.

Busca

Quando estiver online e o manual também estiver online então pode-se usar o recurso de busca restrita do Google diaponível na área de título.

Uma busca mais simples também é possível usando um Applet Java. O Applet foi baseado na implementação do ssSearch de Nalla Senthilnathan.

Utilizando o manual no diso local, para fazer uma busca apenas no computador local pode-se usar o Applet Java ou então sugerimos que você use as ferramentas de busca do HTML Help.

Migrando do WebBook 2

Para migrar antigos arquivos de configuração do WebBook 2 para o WebBook 3 apenas execute na pasta "wb":

lua5.1 js2lua.lua ../wb_usr/wb_usr.js wb_usr.lua
copy ../wb_usr/logo.gif ..
remove ../index.html ../wb_hh ../wb_core ../wb_usr   (somente necessário para remover arquivos do wb2)

Então edite manualmente o arquivo "wb_usr.lua" e acrescente os parametros "wb_usr.search_link" e "wb_usr.file_title". Os parametros antigos não suportados podem ser removidos mais tarde.

Gere os novos arquivos para WebBook 3:

lua5.1 wb_build.lua

Finalmente se os seus arquivos HTML contém chamadas para funções JavaScript do WebBook 2 então voce deve removê-las.