GPAGE Documentation

.
Syntax The Source File Line Breaks Special Symbols More Pages Background Demo File Favorites Subfolders Handling

GPAGE is a small DOS utility that generates a local home page with your favorite web links from a simple text file.

Features:

The text file with your links can easily be edited and rearranged. No need to worry about HTML tags, layout or index generation, all are handled automatically..
The links are ordered in groups, with an index at the top for quick access to a large number of web sites. You can even have direct links from the index to other local pages..
Text can be added in many ways, from simple comment lines to text with embedded links.
As an option, the links in Microsoft Internet Explorer's FAVORITES can be adopted into your text file, a new HTML file being generated at the same time. You can continue to add new web links to the FAVORITES, and later run GPAGE again to add them to your local page. GPAGE can also delete links from FAVORITES to avoid duplication in your local page, and to keep FAVORITES to a manageable size.

Syntax

GPAGE textfile [options]

There are always two files involved: the text file (source) that is specified on the command line (default extension .TXT), and the HTML file that is generated in the same folder, with the same name, extension .HTM.

Long filenames (WIN95) supported. If the HTM file already exists (after the first generation), the top section will be preserved, with background colors or patterns that you may have inserted. However, GPAGE will only accept an existing HTML file when it finds this line: 
Option /P to pause on errors. If you setup the GPAGE task to close on exit, this option will keep the window open when an error occurs. Other options: see FAVORITES.

The Source File

The source file is an ASCII text file that you can create or edit with any DOS or WIN editor. Maximum file size is 50Kb. The word GPAGE is expected at the beginning of the first line to prevent accidental processing of unqualified files. The rest of the first line can be used for comments.

The source (see Demo.txt ) is divided into a number of groups, each identified by a label that begins with a colon. This label serves as a group header, and will also appear in the index section at the top of the page. Each of the following URL lines has an item text (to click on), plus the URL itself.

Example (source, result):

:Search Engines Yahoo http://www.yahoo.com Metacrawler http://www.metacrawler.com Alta Vista http://www.altavista.digital.com

Search Engines: Yahoo
Metacrawler
Alta Vista

Blank spaces between item text and URL, as well as empty lines, may be inserted for better readability. They will not show in the HTML page.

The URL's are identified by the strings "http://" , "ftp://" or "file://" , optionally preceded by "URL=". For any other references the prefix "URL=" is mandatory. (Case ignored for all keywords.)

Note: Local references are specified either relative (based on the directory of the HTML document) or with full path.

For relative references GPAGE needs the prefix "URL=".
References with full path must be preceded by either "file:///" (correct HTML syntax, two slashes also accepted) or "URL=" (which will be translated by GPAGE).

Backslashes in a path specification are converted to normal slashes.

Examples:

Programming URL=links/program.htm Search Engines URL=search.htm HTML Guide file:///C:/web/html/guide/index.htm HTML Guide URL=C:\web\html\guide\index.htm

Lines without a URL are considered plain text, and can be added anywhere - to the group header or to the URL lines.

Before you read the following details about text formatting you may want to go to the Favorites section to see how you can generate your own page from the FAVORITES folder.

Line Breaks

Since the browser will handle line wrapping depending on the window size (and the current font face/size), you have to tell GPAGE whether you want to force a new line, or leave the line wrapping to the browser. This is done by indent:

Text beginning at the leftmost column will always force a new line.
Indented text will continue wherever the preceding output ended. This way you can also add more information right behind the item text or the group identifier.

Example (source, result):

:WIN95 ... lots of information ClubWin http://www.clubwin.com - Tips, FAQs from people who eat, sleep, and breathe Windows Frank Condron's http://www.conitech.com/windows World of Windows - Windows 95 and NT drivers, news, tips

WIN95 ... lots of information: ClubWin - Tips, FAQs from people who eat, sleep, and breathe Windows
Frank Condron's World of Windows - WIN95 and NT drivers, news, tips

Text may be of any length broken into any number of lines. As long as it is indented, it will appear as a continuous paragraph. The indent scheme also applies to URL lines: if they are indented, the item text will be placed right behind the preceding text or item.

Example (source, result):

:Search Engines Yahoo http://www.yahoo.com * Metacrawler http://www.metacrawler.com * Alta Vista http://www.altavista.digital.com

Search Engines: Yahoo * Metacrawler * Alta Vista

Note: The browser will show the group identifiers (and associated text) beginning at the leftmost column, while the link lines (and associated text) are indented. However these indents have nothing to do with the indents in the source file.

Text lines following a group label belong to the header, until a URL line or an empty line is encountered. The empty line will separate the header from the list of links, in case the latter begins with text.

Example (source, result):

:Text Demo This line belongs to the header This text precedes the first item Link URL=any.htm with more text

Text Demo
This line belongs to the header: This text precedes the first item
Link with more text

Special Symbols: A line with nothing but a period will produce an extra empty line. Lines beginning with a semicolon are ignored by GPAGE (comments).

The less/greater symbols <> and the ampersand are reserved for HTML tags. If you want these symbols to appear in normal text, please double them.

Special European characters and other symbols are not converted to make them available under different operating systems, because pages generated by GPAGE will run in the local environment, and the browser is expected to use the same character set as the editor.

As an extra, Option /i is offered to convert extended ASCII characters, entered in a DOS editor, to ISO code used in WINDOWS browsers.

More Pages - "direct links"

If your file becomes too large, you may wish to break it up, by creating separate pages.
Of course you can put local links anywhere in the source file, but GPAGE has a special feature to generate direct links right from the index section:
Just make a label (anywhere) with a local URL on the same line.

Example:

:Search Engines URL=SEARCH.HTM

This link will appear only in the index section at the top.

Background

The top section of the generated HTML file always has a <BODY ...> line. You may modify this line for background colors or tiled patterns from a GIF or JPG file. This information will be preserved when a new page is generated. Use any text editor to make changes.

Examples: <BODY BACKGROUND="Wall.GIF"> <BODY BGCOLOR="#FFF0E0">
The background color is defined thru the red/green/blue components, each represented by two hex digits (00:off ... FF:bright). Use rather high values for a bright background (unless you know how to change the foreground colors as well).

If you want a yellow background, for example, the first two values (red+green=yellow) will be at maximum, and the third value is a little less for pastel, or much less for intense yellow. Note that the lowest of the three values always represents the white component.

For testing: edit the HTML file from within your browser (right mouse click, source..), modify values, save, and refresh the page.

Favorites

Microsoft Internet Explorer (MSIE) saves links in a folder called FAVORITES. This contains one *.URL file per link. The WIN95 long file name (without the extension) is also the name of the link, the text that MSIE shows you when you open the FAVORITES folder. Inside each file is the URL information.

With GPAGE you can move the links from the FAVORITES folder to your local home page. You may continue to add new links to the FAVORITES any time you visit web pages, and later insert these links in your text file (and HTML page) using the GPAGE option /F.
The FAVORITES should be deleted after extraction, because you will want to copy these links only once (see option /D).

Note: Read-only files in the FAVORITES folders will be ignored (and never deleted). This way you can keep certain links (to a file generated by GPAGE, for example) by making them read-only.

GPAGE handles the main folder as well as subfolders (only one level):

Links from the main folder will be appended at the end of the text file. It is recommended that you always have a label "New Links" (any name you like) at the bottom, so the new links will appear in this group until you move them to other groups (sooner or later...).
The FAVORITES subfolders are processed only if a group label with the name of this folder exists anywhere in the text file (remember to keep the "New Links" label at the end). See next section for details and an extra startup option to take over all subfolders.

Option /F activates the extraction of FAVORITES.

The favorites folder is assumed to be C:\WINDOWS\FAVORI~1, which is a short (DOS) name that covers several language dependent long names. If it is different on your system, pls. specify the full path either long or short. Example: GPAGE My_Page.txt /F="C:\WIN95\My Favorites"

In case the specified text file does not exist, it will be created (only with option /F).

Option /D deletes the *.URL files after the information was extracted.

Omit this option only for testing, because GPAGE will not check whether any FAVORITES links have already been extracted previously. As a safety feature, each URL file is only deleted after the link was successfully written to the specified TXT file.

Subfolders of FAVORITES

There is a special startup option to generate a new text file with all your FAVORITES, including subfolders (see below). This way you will get a complete image of your FAVORITES to start with.

Once the text file exists you will have to add a new group whenever you created a new FAVORITES subfolder, because GPAGE will only look for subfolders with the names of existing groups (labels). This has the advantage that you will be able to extract certain subfolders to different text files, depending on the groups you have in these files.

Note: Subfolders of the FAVORITES are not removed by GPAGE, though the files inside will be deleted by option /D.

Long subfolder names are supported under WIN95 (DOS box) only.
The new links will be added at the end of the group.

Option /A (in conjunction with /F) makes a new text file with groups from all FAVORITES subfolders. The links from the main FAVORITES folder will appear at the beginning under the label "Favorites".

This option only works for a new text file, that means: the specified text file must not exist.

Command: GPAGE My_Page /F /D /A

If you are not sure whether you want to continue to use GPAGE, you may omit option /D, so the FAVORITES will not be deleted. Later you can delete the URL files manually, or redo the above command with option /D (make sure to delete the specified text file before, because option /A will only work on a new file).

Handling

Your local home page will serve you best if you make it the homepage of your browser (View/Options/Navigation).

To run GPAGE with favorites handling, you can use a batch file thru a link on your Desktop or in the Start Menu: @echo off GPAGE My_Page.txt /F /D start /W My_Page.txt GPAGE My_Page.txt

This will extract the FAVORITES, start the editor and run GPAGE again for the final HTML file. When you run this batch while you have the HTML file in your browser, you just have to "refresh" to see the result.

Other ways of handling depend on the editor you use. I recommend Eric Fooke's great Super Notetab freeware editor. You can setup this editor to run from the system tray, pick the source file from a list of favorites, and launch GPAGE before and after editing (using the "clipbook" feature).

<End of file>