$1<\/b>/;
### END filtering rules for $statement->{'data'}
if ($indent_level == $current_indent_level) {
push @{$current_branch}, $statement;
}
elsif ($indent_level > $current_indent_level) {
while ($indent_level > $current_indent_level) {
push @branches, $current_branch;
push @{$current_branch}, [];
$current_branch = $current_branch->[$#$current_branch];
$current_indent_level++;
}
push @{$current_branch}, $statement;
}
else {
while ($indent_level < $current_indent_level) {
$current_branch = pop @branches;
$current_indent_level--;
}
push @{$current_branch}, $statement;
}
$current_indent_level = $indent_level;
undef $statement;
}
# parse metadata
$location_string =~ s/\#$//;
$location_string =~ s/(^\s*)//;
### Indent_level can be determined either by parsing the hierarchical address,
### or by measuring the number of spaces the statement is indented. I chose
### the latter method, because I'm lazy.
$indent_level = length($1) / 3;
($statement->{'address'}, $statement->{'sid'}, $statement->{'label'}) =
split(/:/, $location_string);
}
# clean up $line and append it to $statement->{'data'}
$line =~ s/^\s*//; # delete all whitespace at beginning of line
$line =~ s/\s*$/ /; # replace all whitespace at end of line with one space
$statement->{'data'} .= $line;
}
# add last $statement to $statements
$current_branch = $statements;
while ($current_indent_level > 0) {
$current_branch = $current_branch->[$#$current_branch];
$current_indent_level--;
}
push @{$current_branch}, $statement;
$fh->close;
$parse_tree{'statements'} = $statements;
return \%parse_tree;
}
=head2 _statements_to_html($statements, $fh, $indent_level)
pre:
$statements - parse tree (w/o root metadata)
$fh - file handle to where converted HTML is printed.
$indent_level - current indentation level. Used to determine which
HTML header style to print.
post:
none
Recursive function that traverses the parse tree and prints HTML
statements with appropriate addresses, indentation, and other special
formatting (such as the infamous "purple" numbers).
=cut
sub _statements_to_html {
my ($statements, $fh, $indent_level) = @_;
my ($statement);
foreach $statement (@{$statements}) {
if (ref $statement eq 'HASH') { # print statement
if ($statement->{'data'} eq uc($statement->{'data'})) {
print $fh "";
}
else {
print $fh '';
}
print $fh '';
print $fh '';
print $fh ''
unless (!$statement->{'label'});
print $fh $statement->{'data'};
# purple numbers
if ($statement->{'address'} ne '0') {
print $fh '';
print $fh $statement->{'address'} . '';
}
if ($statement->{'data'} eq uc($statement->{'data'})) {
print $fh "
\n\n";
}
else {
print $fh '' . "\n\n";
}
}
elsif (ref $statement eq 'ARRAY') {
# indent...
print $fh '' . "\n\n";
# ... recurse...
&_statements_to_html($statement, $fh, $indent_level + 1);
# ... and unindent...
print $fh '
' . "\n\n";
}
}
}
=head2 _html_header($fh, $fname, $date)
pre:
$fh - file handle to where converted HTML is printed.
$fname - name of Augment file
$date - date of Augment file
post:
none
Prints the HTML header tags with embedded stylesheet and other
metadata.
=cut
sub _html_header {
my ($fh, $fname, $date) = @_;
print $fh <
$fname -- $date
EOM
}
=head2 _html_footer($fh)
pre:
$fh - file handle to where converted HTML is printed.
post:
none
Prints the HTML footer tags.
=cut
sub _html_footer {
my $fh = shift;
print $fh <
EOM
}
=head2 _convert_filename($a_fname)
pre:
$a_fname - original Augment filename
post:
$a_fname - converted filename
Converts an Augment filename to a Web/UNIX-friendly filename by
replacing the trailing comma with '.html' and all other commas with
forward slashes.
=cut
sub _convert_filename {
my $a_fname = shift;
chomp $a_fname;
# replace last comma with .html
$a_fname =~ s/,\s*$/.html/;
# replace commas with forward slashes
$a_fname =~ s/,/\//g;
return $a_fname;
}
=head2 _create_subdirectories($path)
pre:
$path - fully qualified UNIX path and filename
post:
none
Creates the appropriate directories if they do not already exist.
=cut
sub _create_subdirectories {
my $path = shift;
my (@dirs, $dir);
@dirs = split(/\//, $path);
# remove filename
pop(@dirs);
$path = $_HTML_FILES_DIR . '/';
foreach $dir (@dirs) {
$path .= $dir;
if (!-d $path) {
mkdir($path, 0755);
}
$path .= '/';
}
}
1;
=head1 TO DO
=head2 Better Exception Handling
Augment.pm does very little error handling. This is a bad thing.
=head2 Better Object-Orientation
It might be nice to have a generic write() method and to separate the
HTML-related methods into a subclass. Then, anytime someone wanted to
write a new conversion module, that person could just subclass
Augment, and overload write().
There's not a great need for this. It's fairly straightforward to add
new methods to the class as it currently stands.
=head2 Generic Manipulation Methods
It might be nice to have some generic functions for manipulating the
parse tree, perhaps a traverse() method. However, as I said before,
there's no great need for this right now; time is better spent on
other areas, especially the ones listed below.
=head2 Augment Links
This version of a2h.pl does not convert Augment links to HTML links.
This is nontrivial for a number of reasons. Syntactically, any text
in an Augment file delimited by parentheses or angle brackets is
potentially a link. (At some point, Doug's Augment team standardized
on angle brackets for their link format, but some documents still use
parentheses.) In Augment, if you pointed to some text so delimited
and tried to jump to that location, if it were a valid link
(i.e. entry in the link database), Augment would go there; otherwise,
Augment would just ignore the command.
In order to do Augment link conversion, this script should assemble
all of the legal addresses within this document and store them in a
link database. It should then identify anything that looks like a
link, and search the database for such a link. If that link exists,
then it should create the appropriate HTML link.
An additional challenge is that Augment had a number of linking
semantics not supported by HTML links, such as sophisticated
addressing and indirect links. These can be mapped to the XML XLink
specification fairly easily, but determining how to map these XLinks
to HTML links is a nontrivial problem.
Both of the above issues are opportunities for synergy with the main
OHS development. For example, we could use the OHS link database
specification to generate a database of Augment links. We could also
use the OHS XML->HTML transcoder to determine how XLink links are
converted to HTML links. Of course, both of these components are
currently non-existent.
=head2 Improved parsing
Augment had a fairly generic markup language that did not specify
things such as headlines, lists, tables, etc. It would be nice to
develop a more sophisticated set of rules that did a better job of
deciding whether something should be an HTML list or table.
=head2 Augment->XML
This script was developed primarily as a quick and dirty way to let
Doug post old and new Augment documents on the Web in an addressable
manner. Eventually, this script should convert Augment files to XML,
which could then be transcoded into HTML. Once an appropriate DTD is
developed, this should be fairly trivial, because the Augment file is
converted into an intermediate parse tree that could easily be used to
generate all sorts of output.
=head1 HISTORY
Shinya Yamada wrote the first Augment->HTML
convertor in Java, and released it on August 20, 2000. Doug Engelbart
made changes to his export script and suggested
improvements to Shinya's work, which led to this rewrite of the
convertor in Perl.
I released the first version of a2h.pl on October 6, 2000. On October
9, 2000, I rewrote and released Augment.pm, an object-oriented version
of the appropriate a2h.pl functions.
=head1 AUTHOR
Eugene Eric Kim
=cut