2 files changed, 23 insertions, 9 deletions

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";
diff --git a/scripts/MarkdownBook/Document/Txt.pm b/scripts/MarkdownBook/Document/Txt.pm
index e03a1bb..6c7f038 100644
--- a/scripts/MarkdownBook/Document/Txt.pm
+++ b/scripts/MarkdownBook/Document/Txt.pm
@@ -30,9 +30,11 @@ sub output
 	open($out_fh, '>',
 		$self->{'book'}->dir() . '/' . $self->{'file'} . '.txt');
 
+	# Print document title.
 	print($out_fh $self->{'title'} . "\n" .
 		'*' x length($self->{'title'}) . "\n\n\n");
 
+	# Print document text with macro substitutions.
 	print($out_fh $self->{'book'}->subst_macros($self->{'source_text'}));
 
 	close($out_fh);