DirectMarkUP(tm)
Documentation
Trademark
Contents:
Copyright (C) 1998,1999,2000 Data Exchange Associates, Inc.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Contact information:
Data Exchange Associates, Inc.
230 Burnt Meadow Road
Groton, MA 01450-1539
http://www.dexa.com
support@dexa.com
DirectMarkUP is normally free of charge, and is distributed under the GNU general public license. This means that individuals and organizations, both commercial and non-commercial, may use DirectMarkUP without charge. If you modify and redistribute it, there are certain obligations you must fulfill. See the file COPYING which came with your DirectMarkUP distribution for the full license.
DirectMarkUP is not guaranteed to be supported other than by
making full source code available. If it breaks you get to keep both
pieces. However, Data Exchange Associates, Inc. (DEX) sometimes
answers questions. The more concise and better researched your
question, the more likely it is to get an answer. No tutorials will be
provided. You have to learn this stuff on your own.
If
you desire expert help installing or configuring DirectMarkUP, or enhancments
DEX can provide support at our prevailing hourly consulting rate.
The DirectMarkUP package enables the web designer to create sites that that can be revised while deployed on the Web. This makes it possible for web page site owners to make specific pre-planned changes to pages of their website without re-authoring the entire page. Examples are: special offers, prices, notices or other information that change frequently. DirectMarkUP requires no knowledge of web page authoring on the end-users part. All interaction with the target page or pages is through simple web browser form pages accesible only to the end-user.
In order to install DirectMarkUP "telnet" access to the host website is best. If you do not have telnet access you may use "ftp" to copy the installation files to your website.
Systems: UNIX, Linux.
Note: DirectMarkUP has been designed to be platform independent and should work on NT but we have not tested this.
Web Pages on your site are updated using a separate private "auto-revise" page. There is normally one auto-revise page for each DirectMarkUP web page. Once your web page has been composed and installed on your site, generate the auto-revise page. Next set up your authorizations. You can now use this DirectMarkUP form to update your web page.
1. Use your webbrowser to open the page to be revised.
2. Use your browser to access the auto-revise page. If access control has been enabled (See the section on Security) you will be challenged to provide a valid ID and password. After you've successfully answered the authorization challenge the DirectMarkUP auto-revision form will be displayed in your browser window.
3. Simply fill in the from with new text*. When you're satisfied with the content, click on the "Do Change Now" button. If you wish to start over you may clear the entire form by clicking on the "Clear Form" button.
*Note: Any fields that you do not fill in will be left unchanged on the target webpage.
That's it. If all went well you will be presented with a success message.
4. Go back to the page you selected for revision and ask your browser to "Reload" the page. You should see you changes.
DirectMarkUP.cgi makes a backup copy of each webpage before it is updated. The backup page is stored in the same location as the original and with the extension ".bak" added. For example if you change the webpage "index.html" in your HTML document root directory you will see a file "index.html.bak".
There are two methods to undo an update.
Method 1 - Using the Web. From the auto-revise web page simple click on the "UnDo Change" button. The use your browser to return to the original page. "Reload" the page and it should have returned to its previous state.
Method 2 - Using telnet. The change can be undone by using "telnet" to login to your web account, change to your document directory and replace the new webpage with the backup copy. For example you've just updated "public_html/index.html" and wish to restore the original, which was automatically saved as "index.html.bak". Do the following:
$ cd public_html
$ mv index.html.bak index.html
The original version of index.html is now your current webpage.
In order to make a text element modifiable, web designer simply surrounds the areas to be changed with special DirectMarkUP tags "<DIRECT..>, </DIRECT>" within the HTML document. A FORM generator supplied with the package is then used to read the HTML document and automatically produce a HTML FORM for updating the original document. This FORM is called the "auto-revise" page. Once the original document and the update FORM are ready, they are installed on the website. Authorized users are now free to access the update form and enter new information into the form. The changes are made when the update form is submitted to the DirectMarkUP CGI script.
In order to install DirectMarkUP you will need "telnet" and FTP access to the host website. If your ISP does not provide telnet access you may unpack the archive on your local system and perform the changes shown below there, and then ftp the results to your website. For the purposes of this discussion we will describe the "telnet" method. Begin the installation by using FTP to upload the DirectMarkUP archive, e.g. DirectMarkUP.tar, to your website. Once this step is completed begin the installation by initiating a telnet session and logging on to you website account.
1. Move the DirectMarkUP archive to the directory used to hold your CGI scripts, usually "cgi-bin". Example:
$ mv DirectMarkUP.tar cgi-bin
2. Upack the archive. Example:
$ tar -xvf DirectMarkUP.tar
3. Set the file access permissions on the scripts DirectMarkUP.cgi, DirectUndo.cgi and MakeDirectForm bto "executable". Example:
$ chmod a+x DirectMarkUP.cgi DirectUndo.cgi MakeDirectForm
4. If you perl interpreter is NOT "/usr/bin/perl" you must edit the scripts to reflect the location of your perl interpreter. You can find the perl interpreter with the "which" command. Example:
$ which perl
/bin/perl
Above the system responds that perl is located in "/bin/perl". If perl is NOT located in "/usr/bin/perl" use a programmers text editor and replace the first line of: DirectMarkUP.cgi, MakeDirectForm, and DirectUndo.cgi with the result from the "which" command above. Example your perl is in "/bin/perl". Use a programmers text editor and change the first line of each script from "#!/usr/bin/perl" to "#!/bin/perl".
5. You may configure DirectMarkUP by changing variables in the DirectMarkUP.pm file. The three variables of primary interest will be $tempDir, $logFile and $actionURL.
$tempDir - Controls where DirectMarkUP.cgi writes scratch or temporary files. The default "/tmp" is a reasonable choice for most UNIX/Linux systems.
$logFile - Controls the location and name of the log file which is used by DirectMarkUP.cgi to track changes to webpages as they are updated. You should select a location where other log files about your website are kept.
$actionURL - Controls the path portion of URL used by MakeDirectForm to call the DirectMarkUP CGI scripts. The default is "/cgi-bin". If your using "cgiwrap" (see the Security and Setting Up Password Protection section) you should check with your ISP to determine the proper URL for accessing cgiwrap for example: "/cgi-bin/cgiwrap/USERID", where USERID is your login ID. You can change the configuration variables using any programmers text editor.
Creating A DirectMarkUP Web Page
Step 1.
Create an HTML document using your favorite authoring tool: PageMill(tm), FrontPage(tm), or programmers text editor. You don't need to take any special steps as long as your tool accepts non-standard keywords such as "DIRECT" as most do. A completed sample web page "Sample.html" is provided with the package as a guide.
Step 2.
Next decide which sections of the document will be auto-revised.
Using your favorite HTML authoring tool open the document in "source" mode, or use a text editor. This is the mode that gives you access to the actual HTML text.
Move to a section that is to be auto-revised. Enclose the text between DirectMarkUP tags (See WARNINGbelow). For example:
<DIRECT NAME=specials LABEL="This Weeks Special:">
This text will be changed by the user!
</DIRECT>
In the above example the text "This text will be changed by the user!" will be changeable by a user over the web. The tag <DIRECT...>introduces the section to be revised. The <DIRECT...>tag contains two properties: NAME and LABEL. The NAME property must be a unique name that you assign to a DIRECT tag. The LABEL property is a string that will be used to describe the input on the automatically generated (see section Generating The Update Page) update page. Both the NAME and LABEL properties are REQUIRED!
The </DIRECT> tag closes an auto-revise section.
WARNING: HTML tags placed between the <DIRECT..>and </DIRECT>tags should be avoided. This is an expert usage which may lead to unpredictable results. Any HTML tags embedded in a DIRECT block will be treated as ordinary text in the update process and replaced. You should therefore place all tags OUTSIDE the DIRECT block.
You may include as many DirectMarkUP sections in a document as you wish. However, it is probably preferable to keep the number to a minimum.
For a full description of the DIRECT tags see the "DirectMarkUP Tags Reference" section. Once the HTML document is marked up with the DirectMarkUP tags proceed to the section "Generating The Update Page".
DirectMarkUP includes a utility to automatically generate an HTML form for auto-revising the target document. Throughout this section it is assumed you are logged in via telnet.
Step 1.
Change to the cgi-bin directory: Example:
$ cd cgi-bin
Step 2.
Create the auto-revision page using the MakeDirectForm utility. For example assume you've added DirectMarkUP sections to the document /home/ralphs/public_html/index.html. Invoke the MakeDirectForm utility:
$ ./MakeDirectForm ../public_html/index.html >../public_html/private/update.html
The above reads the input document "index.html" and writes a new web page to standard out (stdout) which is directed to the file "update.html" in the "private" directory. The resulting web page will be used to update/change the input document over the web.
The resulting HTML form may be further adorned. However, care should be taken when altering the update form as it is synchronized to the target web pages DirectMarkUP tags. Also any changes you make will be lost the next time you generate a new update form.
A sample auto-revise form "updateform.html" is provided with the package for you to examine.
If you do not have telnet access to your website you may wish to install a copy of perl on your local system. If that is not possible we suggest that you use the supplied file "updateform.html" as a guide for creating a revision form.
Security and Password Protection
DirectMarkUP requires both "read" and "write" access to the web pages it is to revise. This can be accomplished by setting "world" read/write permissions on your web directories and files. Example:
$ chmod o+rw public_html
$ chmod o+rw public_html/index.html
The above grants all users on your system and across the web permission to change your web pages. As you can guess this is not a good idea and we do NOT recommend it. We suggest that you ask your ISP if you can use "cgiwrap" or for Apache sites "suEXEC". Either of these facilities will allow your scripts to be run as user ID of the script owner. This allows you to keep the more restrictive world "read/execute" permissions on all your files. The utility "cgiwrap" is freely available.
Access to DirectMarkUP auto-revision web pages should also be restricted only to those you wish to authorize. Authentication is available through the HTTP 1.0 Authentication mechanism. This section gives a brief description on how to setup a password protected directory on your webserver.
Policies and configurations vary widely between webservers. The following description applies specifically to the Apache webserver. You should consult your ISP or webmaster for complete details concerning authentication configuration. If your ISP does not offer authentication look for one that does. The following description is intended by way of an example only.
Security Hint; Your auto-revise/update web pages should reside in a directory separate from the target web pages. This will allow you to control and authorize access to the update form(s).
Step 1.
From your "Document Root Directory" create a new subdirectory which will hold your update forms. Example:
$ mkdir private
Makes a new subdirectory called "private".
Step 2. Change to the new subdirectory.
$ cd private
Step 3. Create a password file add an authorization.
$ htpasswd -c .users ralph
Adding password for ralph.
New password: *******
Re-type new password: *******
$
This creates the password file ".users" and adds the authorization ID "ralph" and a password.
Step 4. The next step is to enable your webservers access control. This is accomplished by creating an access control file ".htaccess" in the directory which will contain your access options. Use a programmers text editor to create the file ".htaccess". Enter the following:
AuthType Basic
AuthName "Private Area"
AuthUserFile /home/ralph/public_html/private/.users
require valid-user
AuthType Basic enables basic password authentication. AuthName "Private Area" is a simple name to identify this area of your websever. AuthUserFile /home/ralph/public_html/private/.users tells the webserver where to find the file containing valid ID's. The option require valid-user tells the webserver to only permit access to this directory to those ID's contianed in the AuthUserFile. For example, if you wish to restrict access to this directory only to "ralph," use this option: require user ralph. This allows only ralph access to this directory. Again, for specific detailed information regarding security features on your site, consult your webmaster or your webserver documentation.
After installation you should have the following files:
/home/USERID/cgi-bin/DirectMarkUP.cgi
/home/USERID/cgi-bin/DirectMarkUP.pm
/home/USERID/cgi-bin/DirectUndo.cgi
/home/USERID/cgi-bin/HTMLParser.pm
/home/USERID/cgi-bin/MakeDirectForm
/home/USERID/cgi-bin/cgi-lib.pl
/home/USERID/cgi-bin/Sample.html
/home/USERID/cgi-bin/direct.gif
/home/USERID/cgi-bin/updateform.html
/home/USERID/cgi-bin/READ.ME
/home/USERID/cgi-bin/COPYING
/home/USERID/cgi-bin/DirectMarkUP.html
Regression test scripts:
/home/USERID/cgi-bin/DirectMarkUP_
/home/USERID/cgi-bin/HTMLParser_
/home/USERID/cgi-bin/dumpHTML.pl
Regression test standard files:
/home/USERID/cgi-bin/std/HTMLParser.out
/home/USERID/cgi-bin/std/Test1.out
/home/USERID/cgi-bin/std/Test2.out
/home/USERID/cgi-bin/std/Test3.out
/home/USERID/cgi-bin/std/Test4.out
/home/USERID/cgi-bin/std/Test5.out
/home/USERID/cgi-bin/std/Test6.out
/home/USERID/cgi-bin/std/Test7.out
/home/USERID/cgi-bin/std/Test8.out
The DirectMarkUP(tm)files are briefly described below.
DirectMarkUP.cgi The CGI script that performs the actual update of the target web pages.
DirectMarkUP.pm A library used by the DirectMarkUP package.
DirectUndo.cgi A utility used by MakeDirectForm to perform the "UnDo Change" action in an update from.
HTMLParser.pm A primitive HTML parser used by DirectMarkUP derived from libwww-perl.pl
MakeDirectForm The program that generates an auto-revision web page from the target document.
cgi-lib.pl A public domain CGI utility library used by DirectMarkUP.
Sample.html A sample web page showing the use of the DirectMarkUP tags.
direct.gif DirectMarkUP icon.
updateform.html A sample auto-revise web page generated by MakeDirectForm. This page is included as a reference ONLY.
READ.ME a simple read me file.
COPYING GNU Public License
DirectMarkUP.html An HTML version of the DirectMarkUP documentation (this file).
Regression test scripts and standards QA scripts used when making changes to DirectMarkUP source code. These scripts will let you know if you've broken anything important. If you add features you SHOULD add new tests.
dumpHTML.pl Utility script dumps a tokenized version of an HTML file to stdout.
This section describes the syntax of the DirectMarkUP tags. The <DIRECT></DIRECT>tags must be in pairs.
<DIRECT NAME=value LABEL="string">
The DIRECT tag introduces or begins a section of a web page that is to be changeable over the web.
Attributes:
</DIRECT>NAME - a unique name for a section. Names cannot contain spaces. Duplicate Names within a document are treated as the same and are updated accordingly.Note: Duplicate names are ignored by MakeDirectForm. DirectMarkUP.cgi will replace text at each duplciate named location with the same text.
LABEL - A quoted string which is used to provide a description on the auto-revision/update form for the section.
Signals the end of a DirectMarkUP section.
1. The webserver complains that it cannot execute "DirectMarkUP.cgi". This is because the webserver usually runs as an unprivileged user.
$ chmod +x DirectMarkUP.cgi
Solution 2 (not recommended): You must change the persmission on the offending file or directory to allow "world" "write" permission. For example you've configured DirectMarkUP to keep its log file in "mylogs/direct.log".
$ chmod o+w mylogs
Copyright © 1998,1999,2000 by Data Exchange Associates, Inc. Under the GNU general public license.
trademark