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.

---
diff --git a/scripts/MarkdownBook/Book.pm b/scripts/MarkdownBook/Book.pm
index 5047974..cf706a2 100644
--- a/scripts/MarkdownBook/Book.pm
+++ b/scripts/MarkdownBook/Book.pm
@@ -16,9 +16,6 @@
 use strict;
 use warnings;
 
-use MarkdownBook::Document::Txt;
-use MarkdownBook::Document::HTML;
-
 package MarkdownBook::Book;
 
 sub new
@@ -32,12 +29,15 @@ sub new
 	bless($self, $class);
 
 	if ($format eq 'html') {
+		use MarkdownBook::Document::HTML;
 		$self->{'format'} = 'html';
 		$self->{'format_mod'} = 'HTML';
 	} elsif ($format eq 'txt') {
+		use MarkdownBook::Document::Txt;
 		$self->{'format'} = 'txt';
 		$self->{'format_mod'} = 'Txt';
 	}
+
 	$self->{'dir'} = $dir;
 	$self->{'docs'} = [];
 	$self->{'sections'} = [];
@@ -88,7 +88,7 @@ sub documents
 	return $old;
 }
 
-sub get_document_module
+sub _get_document_module
 {
 	my ($self) = @_;
 
@@ -106,17 +106,19 @@ sub create_documents
 	my $doc_prev;
 	my @letters;
 
-	$i = 0;
-	$doc = $self->get_document_module()->new($self, 'index', 'index',
+	# Create index document.
+	$doc = $self->_get_document_module()->new($self, 'index', 'index',
 		undef, $self->{'title'});
 	$doc_prev = $doc;
 	push(@{$self->{'docs'}}, $doc);
 
+	# Create chapter documents.
+	$i = 0;
 	open($series_fh, '<', $self->{'dir'} . '/chapters');
 	while (<$series_fh>) {
 		chomp($_);
 		($file, $title) = split(/[ \t]+/, $_, 2);
-		$doc = $self->get_document_module()->new($self, 'chapter', $file,
+		$doc = $self->_get_document_module()->new($self, 'chapter', $file,
 			++$i, $title);
 		$doc->prev($doc_prev);
 		$doc_prev->next($doc) if defined $doc_prev;
@@ -125,15 +127,15 @@ sub create_documents
 	}
 	close($series_fh);
 
+	# Create appendix documents.
 	$i = -1;
 	@letters = ('A' .. 'Z');
-
 	if (-e $self->{'dir'} . '/appendices') {
 		open($series_fh, '<', $self->{'dir'} . '/apendices');
 		while (<$series_fh>) {
 			chomp($_);
 			($file, $title) = split(/[ \t]+/, $_, 2);
-			$doc = $self->get_document_module()->new($self, 'appendix', $file,
+			$doc = $self->_get_document_module()->new($self, 'appendix', $file,
 				$letters[++$i], $title);
 			$doc->prev($doc_prev);
 			$doc_prev->next($doc) if defined $doc_prev;
@@ -150,6 +152,7 @@ sub add_section
 
 	push(@{$self->{'sections'}}, $section);
 
+	# Index sections (not documents) by ID.
 	if (ref($section) eq 'MarkdownBook::Section') {
 		$self->{'sections_by_id'}->{$section->id()} = $section;
 	}
@@ -159,6 +162,7 @@ sub subst_macros
 {
 	my ($self, $text) = @_;
 
+	# Substitute macros with arguments.
 	$text =~ s/
 		\$                              # Dollar sign
 		\[                              # Left square bracket
@@ -166,10 +170,12 @@ sub subst_macros
 		\]                              # Right square bracket
 		(
 		  \[                            # Left square bracket
-		    ([^\]]+)                    # Macro parameters
+		    ([^\]]+)                    # Macro arguments
 		  \]                            # Right square bracket
 		)
 		/$self->_do_subst_macro($1, split(m@[ \t]+@, $3))/exg;
+
+	# Substitute macros without arguments.
 	$text =~ s/
 		\$                              # Dollar sign
 		\[                              # Left square bracket
@@ -182,7 +188,7 @@ sub subst_macros
 
 sub _do_subst_macro
 {
-	my ($self, $macro, @params) = @_;
+	my ($self, $macro, @args) = @_;
 
 	if ($macro eq 'toc') {
 		return $self->_do_gen_toc();
diff --git a/scripts/MarkdownBook/Document.pm b/scripts/MarkdownBook/Document.pm
index 575ce16..b84503d 100644
--- a/scripts/MarkdownBook/Document.pm
+++ b/scripts/MarkdownBook/Document.pm
@@ -17,8 +17,6 @@ use strict;
 use warnings;
 
 use MarkdownBook::Section;
-use MarkdownBook::HTMLTree;
-use HTML::TreeBuilder;
 
 package MarkdownBook::Document;
 
@@ -149,6 +147,7 @@ sub parse
 	$source_text = join('', <$source_fh>);
 	close($source_fh);
 
+	# Parse headings of non-index documents.
 	if ($self->{'type'} ne 'index') {
 		$self->{'section_level_numbers'} = [0, 0];
 		$self->{'section_level'} = -1;
@@ -160,13 +159,14 @@ sub parse
 			(=+|-+)                     # Underline
 			[ \t]*                      # Optional trailing whitespace
 			$
-			/$self->_do_header($1, $2)/mexg;
+			/$self->_do_heading($1, $2)/mexg;
 	}
 
+	# Store parsed text.
 	$self->{'source_text'} = $source_text;
 }
 
-sub _do_header
+sub _do_heading
 {
 	my ($self, $text, $underline) = @_;
 	my $level;
@@ -176,13 +176,17 @@ sub _do_header
 	my $section_id;
 	my $section;
 
+	# Shorten underline to one character.
 	$underline =~ s/^([=-]).*$/$1/;
+
+	# Detect heading level.
 	if ($underline eq '=') {
 		$level = 1;
 	} else {
 		$level = 2;
 	}
 
+	# Calculate section number.
 	$levels = $#{$self->{'section_level_numbers'}};
 	if ($level != $self->{'section_level'}) {
 		foreach (@{$self->{'section_level_numbers'}}[$level .. $levels]) {
@@ -192,9 +196,14 @@ sub _do_header
 	$self->{'section_level'} = $level;
 	++${$self->{'section_level_numbers'}}[$level - 1];
 	$section_number = join('.', @{$self->{'section_level_numbers'}});
+
+	# Add document ID to section number.
 	$section_number = $self->{'id'} . '.' . $section_number;
+
+	# Trim off unused subsection parts.
 	$section_number =~ s/(?:\.0)*$//;
 
+	# Parse out section title.
 	$section_title = $text;
 	$section_title =~ s/
 		^
@@ -206,6 +215,7 @@ sub _do_header
 		$
 		/$1/x;
 
+	# Parse out section ID.
 	$section_id = $text;
 	$section_id =~ s/
 		^
@@ -217,13 +227,16 @@ sub _do_header
 		$
 		/$1/x;
 
+	# Create and store section object.
 	$section = MarkdownBook::Section->new($self,
 		$level, $section_number, $section_id, $section_title);
 	push(@{$self->{'sections'}}, $section);
 	$self->{'book'}->add_section($section);
 
+	# Prepend number to section title.
 	$text = $section_number . ' ' . $section_title;
 
+	# Return underlined section title.
 	return $text . "\n" . $underline x length($text);
 }
 
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);
diff --git a/scripts/MarkdownBook/Section.pm b/scripts/MarkdownBook/Section.pm
index 39b29eb..82ff897 100644
--- a/scripts/MarkdownBook/Section.pm
+++ b/scripts/MarkdownBook/Section.pm
@@ -45,21 +45,21 @@ sub level
 
 sub number
 {
-	my ($self, $number) = @_;
+	my ($self) = @_;
 
 	return $self->{'number'};
 }
 
 sub id
 {
-	my ($self, $id) = @_;
+	my ($self) = @_;
 
 	return $self->{'id'};
 }
 
 sub title
 {
-	my ($self, $title) = @_;
+	my ($self) = @_;
 
 	return $self->{'title'};
 }
--
cgit v0.9.1