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.pm')

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);
 }
 
--
cgit v0.9.1