Bill Pringle - Bill@BillPringle
This page describes the web tools package developed by Bill Pringle. This package allows the user to create web sites quickly and easily, so that all the pages have a consistent look and feel. This package can generate web pages for a wide variety of web sites.
The main element of this package is the bld_page program, which translates text files into HTML (web) pages. This is done by copying the input file and expanding any macros it encounters. Furthermore, certain pre-defined macros are called at certain times to create the beginning and end of the page. Users may define the code to be expanded for each of the macros, which controls the look and feel of the web site.
The first thing we will do is to install a web server on your computer. This is not absolutely necessary for these demo pages, but will be needed if you begin to add features to your pages.
The package we will be installing is called xampp and can be downloaded from here. Follow the installation instructions,and when done, you can resume reading this tutorial.
Assuming you installed the xampp package in the default location, when you are done, you should see a directory C:\xampp. The subdirectory C:\xampp\htdocs is the root directory of your web server. This means you can create several web sites on your local computer by creating subdirectories for each site under C:\xampp\htdocs.
We are now ready to create our first web site. Let's look at a short example to illustrate the use of the webtools package. The bld_page program reads files from an input directory, converts the input file to an HTML (web) file, and writes the resulting page to an output directory. By default, the input directory is called in and the output directory is called out.
To get started, download the Bld Page package, which contains a subset of the webtools package, and unzip it to the C:\xampp\htdocs folder.
This will create the directories listed below, as well as the input pages that are described after that. If you want to enter everything yourself, then unzip the package into a different directory, and then copy the files you need into the directory you created.
When you are done with this step, you should have the following files and directories:
Next you want to set up the files you will need to build your web site. We will use the default macros from the webtools package, and create a small set of files to start with. Once you get the initial web site created, you can start adding your own content by filling in the web page files.
Double-click on C:\xampp\htdocs\Web\include\include.txt. This should bring the include file in notepad. If you have a favorite text editor, use it to edit the include file.
There are several places in the include file containing your-name and your-email-addr. Change these to your actual name and e-mail address. Save the file.
You are ready to create your first web page. When you unzipped the bld_page file, you already created the web pages described below. You can create them yourself and overwrite the pages that were downloaded, or simply examine the downloaded files to follow the tutorial. (I find that I learn better if I create the files myself rather than just reading, but whatever works for you is fine.)
Assuming you want to create your own web pages, you will need a text editor (like notepad). If you have a text editor that you like, then you can use that. Using whatever text editor you want, enter the following text:
My Web Site >Normal This is my first web page. >NormNext I will add some more information later. >NormEnd
Save this file as C:\xampp\htdocs\Web\in\index.html.
We will create two more pages that will be used for additional major categories. Links to these pages will appear on the top of all the pages on your web site.
Major Category 2 >Normal This page will contain information about a major category of my web site. >NormEnd
Save this file as C:\xampp\htdocs\Web\in\page2.html.
The last page has some extra macros that we will explain in more detail later on. For now, simply create this page:
Major Category 3 >Normal This page will contain information about another major category of my web site. >NormEnd >SubLink|parta|Part A|h2 >Normal This is a sub-section of this page. >NormEnd >SubLink|partb|Part B|h2 >Normal Here is another sub-section of this page. >NormEnd
Save this file as C:\xampp\htdocs\Web\in\page3.html
If you unzipped the bld_page package into your C:\xampp\htdocs\Web directory, this page will have some additional text as well as some pictures. If you are entering the pages by hand, just do the above text, and then look at the provided page3.html to see what else you can do.
You are now ready to build your web pages. Using your windows explorer, double-click on the bld_dir.bat script file in the C:\xampp\htdocs\Web directory. This will run the bld_page program to read the files in your input directory and create your web pages in the output directory.
After the program finishes, use your windows explorer to look at the C:\xampp\htdocs\Web\out directory. You should see output files with the same names as those found in your input directory (index.html, page2.html, and page3.html). However, the files in the output directory are actual HTML pages, while those in the input directory are used by the bld_dir.bat command to create the output HTML pages.
In your web browser, enter the following address:
This should cause the web site you just created to be displayed inside your browser. Although you probably use Internet Explorer, there are significant advantages to using Firefox instead. Regardless of which browser you use, you should see something like the following in your browser:
If you have changed the C:\xampp\htdocs\Web\include\include.txt file and inserted your actual name and e-mail address, you should see your name along the top of the home page, with links marked Home, Page 2, and Page 3. If you click on those three links, you will see that the corresponding web pages are displayed. Congratulations! You have just created a web site! Of course, it isn't on the Internet yet, but you will be able to view it from your own computer.
If you compare your input files to the web pages they create, you can get an overview of the process. The first line of the input file is both the title of the page and the top header as well. If you look at the top of the browser, you will see that it has the same thing as the header at the top of the page. You will also notice lines that start with a greater than sign (>). These are macro commands. Each time the bld_page program encounters a macro, it substitutes the macro definition found in the include file (C:\xampp\htdocs\Web\include\include.txt), inserting the macro arguments where specified. The sample pages don't use any macros with arguments, but they will be discussed later.
Assuming you obtain hosting for your web site, you would follow the instructions from your ISP to copy the pages from the C:\xampp\htdocs\Web\out directory to the web site, probably using the ftp program. Although this takes some extra steps: (1) create the input files, (2) generate the web pages, and (3) upload the pages to your web site, there are some advantages to this approach. To begin with, you can experiment with changes and not have to worry about breaking your web site. Once you have the new version of your site the way you want it, you simply upload the pages and your site has been changed.
Another advantage of this approach is that it provides the functionality of what is called a Content Manager, something that large commercial web sites pay lots of money for, without the overhead of needing a database. A content manager allows you to develop a template for your web pages, and then insert content into the appropriate sections for each page. This means that all the pages on the site have common elements, which helps make the web site look professional.
Most content managers use a database to store all the information needed for the web pages, and then builds each web page when the user visits the page. The bld_page program uses the macros you have defined (or the default macros if you haven't made any changes) to create a consistent look and feel for all the web pages. And since the bld_page program creates the actual HTML pages, you don't need a database. And best of all, you don't have to pay for it!
You can experiment by changing the content of the pages, running bld_pages again, and see the results. Don't make any changes to the macros just yet; we will cover that topic later. Once you are ready, the next section will teach you some of the commands that you can insert on your pages to make them look the way you want.
There are a number of macros in the macro definition file (C:\xampp\htdocs\Web\include\include.txt), and you can even add new ones once you are more familiar with how the package works. A macro definition begins with a greater-than sign (>) followed by the name of the macro. Everthing that follows up to a line containing only a greater-than sign is the definition of that macro.
To understand macros, you need some understanding of HTML, which is the language used to create web pages. HTML consists of different kinds of elements, like paragraphs, headers, hyperlinks, etc. These elements are identified with tags, which indicates the nature of the element. A tag consists of a tag name surrounded by angle brackets, some text which is the content of the element, and a closing tag which looks like the open tag, except that there is a slash in front of the tag name. (There is a lot more to HTML, but that is enough for now.)
For example, the tag for a paragraph is the "p" tag, which looks like this: <p>. This tag marks the start of a paragraph. Everything that appears between the start tag and its closing tag (</p>) is considered a paragraph.
Tags can have attributes, which can be used to change how the tag is handled. The two attributes that all tags can have are id and class. The values of these attributes must be a string that starts with a letter and has only letters or digits. Most of the time you won't actually specify these attributes, but you will see them in the macro definitions. For a further discussion of these attributes, see the macro definition for Top Banner.
The id attribute identifies the specific tag. There can only be one tag with a specific id attribute; it must be unique. The class attribute defines a sub-class of the tag, which often changes the way that the element will appear.
Now that you understand a little about HTML, look at the top of the macro definition file, where you can find the macros for Normal, NormNext, and NormEnd:
>Normal <p> > >NormNext </p><p> > >NormEnd </p> >
You can see from the above definitions that the Normal macro inserts a paragraph tag (<p>) into the page. The NormNext inserts a closing paragraph tag (</p>) and an open paragraph tag, while the NormEnd tag inserts a closing paragraph tag.
This means that the Normal macro starts a paragraph. The NormNext closes the previous paragraph and starts a new one. And finally, the NormEnd closes the current paragraph and doesn't start a new one.
This is why when you want to write a block of text on your web page, you should start out with the Normal macro. Each time you want to start a new paragraph, you use the NormNext macro. And when you are done with the block of text, you finish up with a NormEnd tag. If you forget the Normal tag or the NormEnd tag, your web page will have an error in it. Sometimes the browser will still be able to display the web page, but you should try to make sure your page doesn't have any errors. Part of the problem is that different browsers on different systems might display pages with errors differently. If you want to be sure that everyone can read your web pages, you should find and get rid of any errors that appear.
If you look at the pages you created for your first web site, you will notice that you have already been using macros. If a line starts with a greater-than sign (>), it means that it is a macro line. Right after the greater-than sign will be the name of the macro. So, when you typed the line ">Normal", you were using a macro.
If the macro takes any arguments, they should appear after the macro name, separated by vertical bars (|). The SubLink macro on page3.html used arguments. If you look at the definition for that macro, and then compare what you entered and what the web page contains, you will get a better understanding of how macros with arguments work.
There are also some macros that are called automatically at certain times, such as the start of a page or the end of a page. This means you should never enter these macros in any of your pages, since that will call the macro twice, which will probably mess up your page.
Here is a list of the macros you will find in the default include file. If a macro takes any arguments, they will be indicated in the list below:
These macros define paragraphs of text. In general, there is one macro that begins a block of text, and another that ends the block. If more than one paragraph appears in the block, a macro defines where the new paragraphs are located.
For example, on the input file index.html you will see the Normal macro start the block, the NormNext macro create new paragraphs, and finally the NormEnd macro to terminate the block of text.
These macros can be used to create hyper-links to other locations within the page, or even other web sites.
Each page will have two menus: a global menu that appears exactly the same on all of the pages, and a sub-menu that contains links to the sections of each page. The global menu is defined within the TopBanner macro. The same global menu appears on each page. The submenu is generated by the bld_page program by creating an index to each subsection defined for the current page using the SubLink macro. Page 3 contains SubLink macros. Look at the input file and the web page to see how they work.
>Image|images/foobar.jpg|50%|This is my picture
These macros affect the page layout, and are automatically called by the bld_page program. This means that you will not want to insert these macros in any of your pages, but you might want to customize these macros to produce the look and feel that you want. You must be very careful when making any changes to the macros. It won't take much to totally mess up your pages if you make the wrong change. You probably want to make a copy of the include file before you start making any changes. That way, if something goes wrong, you can restore the last working version.
>TopBanner <div id="beg"> <p class="larger">your-name</p> <p> | >HRef|index.html|Home | >HRef|page2.html|Page 2 | >HRef|page3.html|Page 3 | </p> </div> >
>TopBanner <div id="beg"> <p class="larger">Bill's Web Site</p> <p> | >HRef|index.html|Home | >HRef|music.html|Music | >HRef|books.html|Books | >HRef|pics.html|Pictures | </p> </div> >
>Trailer <p class="trailer"> © 2007 <a href="mailto:your-email-addr?subject=Comments_on_Your_Site">your-name.</a> </p> >
Whenever you make any changes to the input files, you have to double-click on the bld_pages script to run the bld_page program, and re-create new web pages. After the program finishes, look at the web pages and see if the changes look the way you wanted them. If not, make more changes and generate the web pages again. Keep this up until you are happy with your changes. Remember to refresh your browser to see the changed pages.
It is best to make one set of changes at a time rather than a bunch of changes before rebuilding the web pages. That way, if something goes wrong, you have a better idea of where the problem is. For example, if you made only one change, then that change is what introduced the error. If, however, you made a bunch of changes, it will be a lot harder to find out what went wrong. Until you get comfortable with the process, making one change at a time will seem time consuming, but it will make fixing errors much easier. In summary, you will do the following steps over and over again until you are done with all your changes:
Once you have your web pages the way you want them, you can upload the pages to your web site. Usually this means you need some kind of FTP program. The program I use is an free open-source program called Filezilla.
The easy way to update your web site is to tranfer all the files. If you have a lot of pages, then you might want to only upload the pages that have changed since your last upload. You can do that by comparing the modification dates of the files on your computer and the files on your web site.
If you have a lot of pages, you might want to break your web site into different subdirectories. For example, you could create a subdirectory for each major section of the web site. If you look at my site, and my Cheryl Wheeler site, you will see that is what I do. This might make it easier to keep your pages organized. It all depends on your preferences.