Home

WebBook
Documentation NavigationToolkit
Version 3

WebBook is a toolkit for creating the navigation of manuals in HTML.

Project Management:

Antonio Escaño Scuri

Tecgraf - Computer Graphics Technology Group, PUC-Rio, Brazil
http://www.tecgraf.puc-rio.br/webbook


Product

Overview

WebBook is a toolkit for creating the navigation of manuals in HTML. Since most manuals have a natural and simple hierarchical structure, we implemented some JavaScript functions to help creating many of Tecgraf's online manuals - but you do not need to know JavaScript at all to use WbeBook.

We use the metaphor of a book: it is composed by several pages in a sequence, with a table of contents to locate particular information. The user can go to the first page, to the next one, to the previous one or to any particular page using the table of contents. This is the same metaphor used by commercial systems such as Microsoft HTML Help, distributed with MSDN and TechNet.

The toolkit provides all the necessary tools to make navigation simple through the book's pages. It also allows you to switch between the available languages. WebBook's singularity is its portability, because it depends only on a Web browser. It can be used for any kind of online and offline documentation, and the best: it is available for free to everyone.

To understand how the toolkit works, please refer to the Guide section.

WebBook is available at http://www.tecgraf.puc-rio.br/webbook.

Authors

WebBook was created by:

Antonio Escaño Scuri
Mark Stroetzel Glasberg

Acknowledgments

We would like to thank Diego Nehab for the first version of the Tree-management JavaScript code and Mark Stroetzel Glasberg for the HTML Help conversion in the first version of webbook.

To Henrique Pinheiro for several enhancements for version 2.

To Nalla Senthilnathan for the Java Applet simple search. To Cristina Ururahy for helping with the Applet Java.

Download

Version | Files
3.03 | webbook303.tar.gz or webbook303.zip
3.02 | webbook302.tar.gz or webbook302.zip

History

Version 3.0.3 (Aug 2012)

Updated the Google Search feature.

Version 3.0.2 (Dez 2006)

Changed the Applet Java to be abble to search many files. Java was not able to open too many files in several treads. Now opens only one file at a time in one thread. The source code was updated so it can be compiled in newer Java versions.

Version 3.0.1 (Nov 2006)

Added a simple search using a Java Applet created by Nalla Senthilnathan.
Fixed download links.

Version 3.0 (Nov 2006)

The Lua configuration file is back. JavaScript code has been reduced to a minimum. The tree now is written in Lua, then a script builds an HTML tree with JavaScript only when it is necessary.

The frames and the tree are now static HTML files so search engines can easily find internal pages from the initial frame set page (index.html).

The toolbar moved to inside the tree area and the title bar now have a Google Search button that restrict the search for a given site. The configuration files location changed from the "wb_usr" folder to the current folder. Cleaner view of the tree with no images in nodes or leafs (parameters use_items and use_folders are not supported anymore).

The parameter revision_date is not used anymore. New parameter search_link must be added. The functions for automatic syncronization are not supported anymore and must be removed. See in Guide how to migrate from WebBook 2 to WebBook 3.

Version 2.1 (Dez 2004)

New Lua 3 script to build a HTML Help file in Windows from the WebBook files.

Version 2.0 (Nov 2002)

Total new tree, faster navigation, new design, better code organization, simpler description of tree in Javascript (Lua independence.)

Version 1.1 (Aug 2002)

New feauture, webbbook now accepts external calls to position a page. Check sample.

Version 1.0 (Jan 2001)

First version.

To Do

  • Nothing planned.

License

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.


Guide

Description

WebBook allows you to create a navigation structure for your HTML pages. All you have to do is edit a configuration file and add your pages to the right place. You do not need any special CGI or Java configuration to run it, and you can use it without any WWW server. Simply open the "index.html" file.

There are 3 noticeable areas divided by frames. The Title area contains some information about the online book. The Tree area contains the book's hierarchy of pages with some tools to help navigation. The Contents area shows the user's pages.

You can use any HTML editor to build the pages for the Contents area. CGI documents are also valid.

The information on the Title area and on the Tree area can be changed by editing the configuration file "wb_usr.lua".

Installing

First of all, download a copy of the toolkit files:

wb      (Folder)
wb_img  (Folder)

Edit a new configuration file named "wb_usr.lua" in the "wb" folder. This file must contain information about the book, including the tree definition. A file named "logo.gif" will be used in the title area before the text title.

The book files must be located in the respective language folder, even if only one language is provided. Here are the pre-defined language strings:

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

There are icons only for pt, en and es, but it is very simple to edit a new one based on these.

The respective files in each language must have the same name as the bookmarks inside them so the links in the tree can be only one for all languages.

Configuration File

It is a text file, coded in Lua, that describes all the configurable options of the toolkit. It has 3 tables, forming 3 groups of parameters.

The User section contains the main configuration parameters:

wb_usr
  langs          (a table containing the language strings of the available languages)
  start_size     (the initial width of the Tree area)
  title_bgcolor  (background color of the Title area, not used anymore, the "title_background.png" image is usd instead)
  contact        (contact e-mail for the Title area)
  copyright_name (copyright text for the Title area)
  copyright_link (URL for the link to the copyright text)
  search_link    (URL for the search site)
  file_title     (prefix name of the file, usually the short product name, ex: "webbook", used by the HTML Help)
  start_open     (Indicates the state of the first tree node when the page is loaded)
  google_id      (Identifier of the Google Custom Search Engine)

The Messages section contains language-dependent parameters:

wb_usr.messages
  xx              (language string, can be "nl" - neutral language used for all languages)
    title         (text of the browser's window title)
    bar_title     (text of the Title area)

The Tree section contains the topic-hierarchy tree:

wb_usr.tree
  (for each topic)
    title       (a table with the topic's title in each language - nl stands for all languages.
                 It is allowed to use HTML tags to alter the style of the text)
    link        (name of a file with extension. If left blank the item will be unavailable and painted black)
    folder      (subtree of topics. Must be an array with other topics)

Sample

For an example of a configuration file, download Webbook and check the file "wb/wb_usr.lua". Here is an extract:

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"
        },
...

Building

The HTML files for the frame set, the title area and the tree must be generated using the Lua 5 interpreter in the "wb" folder:

lua5.1 wb_build.lua

The files: "index.html", "wb_title.html" e "wb_tree.html" will be generatedin the folder that contains the folder "wb". The forlder "wb" does not needs to be distributed or copied to the web server. But the folder "wb_img" must be included.

When more than one language is configured there will be one file for each language with a language suffix in the file name.

In Windows the Lua interpreter is included in the WebBook distribution files. But for UNIX they must be downloaded from the site LuaBinaries.

First Page

Webbook's initial page is always the link defined in the "wb_usr.tree.link" parameter. Nonetheless, it is possible to start Webbook in a specific topic. To accomplish this, the specific topic must be included in the given URL in the following format:

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

Where:

webbook_url is the location of your webbook;
file.html#bookmark is a link that exists in the tree description provided in the "wb_usr.lua" file.

Example:

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

To access a local file in your computer use:

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

HTML Help

In Windows you can build a HTML Help file from the WebBook files. To do that you must have installed some utilities necessary to the conversion: the Microsoft Help Compiler (hhc.exe) and the Lua interpreter (lua5.1.exe). It is not necessary to have the HTML Help Workshop installed, but it is a simple way to install the "hcc.exe" program.

You can download the HTML Help Workshop from Microsoft:

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

The WebBook distribution files include the Lua interpreter for Windows.

There are tools to access CHM files also in Linux and other platforms (http://xchm.sourceforge.net/).

The Lua script "wb\make_hh.lua" will build a HTML Help project from the WebBook configuration file. The batch file "wb2hh.bat" will help you build the project and compile the HTML Help. Just run "wb2hh myhelp en" and the "myhelp_en.chm" file will be built for the "en" language. You can edit the batch file so the final folder were the file is copied can be adjusted to your case.

Remember that everything that is locally referenced by your HTMLs will be included in the CHM file. Here is an example for the WebBook pages: wb_en.chm. It is important that your pages have different titles so in the search results each page found appears with a different name.

Searching

When online and the manual is also online, you can use the Google restricted search available in the title area.

A simple search is available using a Java Applet. The Applet was based in the ssSearch Applet from Nalla Senthilnathan.

When using the manual in the local disc, to search only in the local computer use the Java Applet or we suggest you to use the HTML Help search tools.

Migration From WebBook 2

To migrate old WebBook 2 configuration files to WebBook 3 just do in the "wb" folder:

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   (only necessary to remove wb2 files)

Then manually edit the "wb_usr.lua" file and add the paramaters "wb_usr.search_link" and "wb_usr.file_title". The unsupported parameters can be removed later.

Build the new WebBook 3 files:

lua5.1 wb_build.lua

Finally if your HTML files contain calls to WebBook 2 JavaScript functions you must remove them.