From f8ad857f3386264e752ef586959b65a7219538b1 Mon Sep 17 00:00:00 2001
From: P. J. McDermott <pjm@nac.net>
Date: Sun, 12 Aug 2012 09:29:45 -0400
Subject: Comment and clean up code.

---
(limited to 'scripts/MarkdownBook/Document/HTML.pm')

diff --git a/scripts/MarkdownBook/Document/HTML.pm b/scripts/MarkdownBook/Document/HTML.pm
index 5b3faca..9d61760 100644
--- a/scripts/MarkdownBook/Document/HTML.pm
+++ b/scripts/MarkdownBook/Document/HTML.pm
@@ -17,7 +17,9 @@ use strict;
 use warnings;
 
 use MarkdownBook::Document;
+use MarkdownBook::HTMLTree;
 use Text::Markdown;
+use HTML::TreeBuilder;
 use HTML::Template;
 
 package MarkdownBook::Document::HTML;
@@ -31,10 +33,12 @@ sub output
 	my $doc;
 	my $sec;
 
+	# Substitute macros.
 	$text = $self->{'book'}->subst_macros(
 		$self->{'source_text'});
 
-	$text .= "\n\n";
+	# Append link definitions.
+	$text .= "\n";
 	foreach $doc (@{$self->{'book'}->documents()}) {
 		$text .= "\n";
 		$text .= '[';
@@ -53,38 +57,45 @@ sub output
 		}
 	}
 
+	# Convert to HTML.
 	$text = Text::Markdown::Markdown($text);
 
+	# Set "id" attributes of headings.
 	$self->_do_set_heading_id_attrs($text);
 
+	# Output the templated HTML.
 	$self->_do_output_template();
 
+	# Clean up.
 	$self->{'tree'}->delete();
 }
 
 sub _do_set_heading_id_attrs
 {
 	my ($self, $text) = @_;
-	my @headers;
-	my $header;
+	my @headings;
+	my $heading;
 	my $i = -1;
 
+	# Parse HTML.
 	$self->{'tree'} = HTML::TreeBuilder->new();
 	$self->{'tree'}->parse($text);
 	$self->{'tree'}->eof($text);
 
+	# Find the "body" element.
 	@{$self->{'tree_body'}} = MarkdownBook::HTMLTree::find_elements_by_tag_names(
 		$self->{'tree'}, ('body'));
 
-	if ($self->{'type'} eq 'index') {
-		return;
-	}
+	# Don't modify headings of index documents.
+	return if $self->{'type'} eq 'index';
 	
-	@headers = MarkdownBook::HTMLTree::find_elements_by_tag_names(
+	# Find all headings.
+	@headings = MarkdownBook::HTMLTree::find_elements_by_tag_names(
 		@{$self->{'tree_body'}}[0], ('h1', 'h2'));
 
-	foreach $header (@headers) {
-		$header->attr('id', ${$self->{'sections'}}[++$i]->id());
+	# Set "id" attributes.
+	foreach $heading (@headings) {
+		$heading->attr('id', ${$self->{'sections'}}[++$i]->id());
 	}
 }
 
@@ -103,6 +114,7 @@ sub _do_output_template
 	# Don't omit any end tags.
 	%opt_end_tags = map([$_ => 0], %HTML::Element::optionalEndTag);
 
+	# Get HTML text of all children of the "body" element.
 	foreach $elem (@{$self->{'tree_body'}}[0]->content_list()) {
 		# It's safe to assume (ref($elem) eq 'HTML::Element').
 		$body .= $elem->as_HTML('<>&', '', \%opt_end_tags) . "\n";
--
cgit v0.9.1