#!perl

# fsh-builddocs

# 

# Copyright (c) 2010 Accenture. All rights reserved.

# This component and the accompanying materials are made available

# under the terms of the "Eclipse Public License v1.0"

# which accompanies this distribution, and is available

# at the URL "http://www.eclipse.org/legal/epl-v10.html".

# 

# Initial Contributors:

# Accenture - Initial contribution

#

# Description:

# fsh-builddocs - A tool that generates HTML documentation from POD source files.

use strict;

use Cwd;

use Pod::Html;

use IO::File;

use File::Basename;

use File::Path;

use File::Copy;

use Getopt::Long;

use FindBin;

use lib "$FindBin::Bin";

use fshu;

use CommandInfoFile;

#

# Constants.

#

my $kCpp = "$ENV{EPOCROOT}epoc32\\gcc\\bin\\cpp -I. ";

#

# Globals.

#

my %options = (

	       verbose => 0,

	       includes => []

	      );

#

# Main.

#

my $podListFile = ProcessCommandLine();

my $podListDirName = dirname($podListFile);

my $cwd = cwd();

chdir ($podListDirName) or die "Error: Couldn't chdir to '$podListDirName' - $!\n";

my $spec;

eval {

  $spec = ParsePodList($podListFile);

  CopyCss($spec);

  CopyPod($spec);

  IdentifyIndexPod($spec);

  IdentifyCifPod($spec);

  GenerateIndexPod($spec);

  GenerateCifPod($spec);

  BuildHtml($spec);

};

my $error = $@;

chdir ($cwd) or die "Error: Couldn't chdir back to '$cwd': $!\n";

die $error if ($error);

#

# Subs.

#

sub ProcessCommandLine {

  my $help;

  GetOptions('h|help' => \$help,

	     'v|verbose' => \$options{verbose},

	     'w|what' => \$options{what},

	     'c|clean' => \$options{clean},

	     'i|include=s' => $options{includes}) or DisplayHelp();

  DisplayHelp() if ($help);

  warn "Invalid arguments\n" and DisplayHelp() unless (@ARGV == 1);

  my $relativeEpocRootPath = fshu::RelativePath($ENV{EPOCROOT}, cwd());

  $relativeEpocRootPath =~ s/\\/\//g; # '\' -> '/'.

  foreach my $include (@{$options{includes}}) {

    if ($include =~ /^epoc32/i) {

      $include = "${relativeEpocRootPath}$include";

    }

  }

  return shift @ARGV;

}

sub DisplayHelp {

  require Pod::Text;

  print "\n";

  my $parser = Pod::Text->new();

  $parser->parse_from_file($0);

  exit;

}

sub ParsePodList {

  my $podListFileName = shift;

  local $_;

  my $command = $kCpp . join (' ', map {"-I$_"} @{$options{includes}}) . " $podListFileName 2>&1 |";

  print "Running '$command'\n" if ($options{verbose});

  open (CPP, $command) or die "Error: Couldn't run 'cpp.exe': $!\n";

  my $spec;

  my $currentDir;

  my $currentFile = $podListFileName;

  my $currentLine = 0;

  while (my $line = <CPP>) {

    ++$currentLine;

    $line =~ s/^\s+//;

    next if (!$line); # Blank lines.

    if ($line =~ /^#\s+(\d+)\s+"([^"]+)"/) {

      $currentLine = $1;

      $currentFile = fshu::TidyPath($2);

      $currentDir = dirname($currentFile);

    }

    elsif ($line =~ /^doc-root\s+(\S+)\s*$/) {

      $spec->{docRoot} = fshu::TidyPath($1);

    }

    elsif ($line =~ /^temp-root\s+(\S+)\s*$/) {

      $spec->{tempRoot} = fshu::TidyPath($1);

    }

    elsif ($line =~ /^css\s+(\S+)\s*$/) {

      $spec->{cssFile} = fshu::TidyPath("$currentDir\\" . fshu::TidyPath($1));

    }

    elsif ($line =~ /^pod\s+(\S+)\s+(\S+)\s*$/) {

      my $podFileName = fshu::TidyPath("$currentDir\\" . fshu::TidyPath($1));

      my $htmlFileName = fshu::TidyPath($2);

      # If this HTML file matches one we already have in the list, allow this one to override.

      my $found = 0;

      foreach my $podFile (@{$spec->{podFiles}}) {

	if (lc($podFile->{htmlFileName}) eq lc($htmlFileName)) {

	  $podFile->{podFileName} = $podFileName;

	  $found = 1;

	  last;

	}

      }

      unless ($found) {

	push (@{$spec->{podFiles}}, {

				     podFileName => $podFileName,

				     htmlFileName => $htmlFileName

				    });

      }

    }

    elsif ($line =~ /^index\s+(\S+)/) {

      my $htmlDirName = fshu::TidyPath($1);

      my $podFileName;

      if ($line =~ /^index\s+\S+\s+(\S+)\s*$/) {

	$podFileName = fshu::TidyPath("$currentDir\\" . fshu::TidyPath($1));

      }

      push (@{$spec->{indices}}, {

				   podFileName => $podFileName,

				   htmlDirName => $htmlDirName

				  });

    }

    elsif ($line =~ /^cif\s+(\S+)\s+(\S+)/) {

      my $cifDirName = fshu::TidyPath($1);

      my $htmlDirName = fshu::TidyPath($2);

      my $podFileName;

      if ($line =~ /^cif\s+\S+\s+\S+\s+(\S+)\s*$/) {

	$podFileName = fshu::TidyPath("$currentDir\\" . fshu::TidyPath($1));

      }

      push (@{$spec->{cifIndices}}, {

				      podFileName => $podFileName,

				      htmlDirName => $htmlDirName,

				      cifDirName => $cifDirName

				     });

    }

    else {

      die "Error: Invalid pod-list line at $currentFile($currentLine):\n$line";

    }

  }

  close (CPP);

  die "Error: No 'doc-root' in pod-list\n" unless ($spec->{docRoot});

  die "Error: No 'temp-root' in pod-list\n" unless ($spec->{tempRoot});

  return $spec;

}

sub CopyCss {

  my $spec = shift;

  if ($spec->{cssFile}) {

    my $target = "$spec->{docRoot}\\" . basename($spec->{cssFile});

    if ($options{what}) {

      print "$target\n";

    }

    elsif ($options{clean}) {

      unlink ($target);

    }

    else {

      fshu::CopyFile($spec->{cssFile}, $target, $options{verbose});

    }

  }

}

sub CopyPod {

  my $spec = shift;

  foreach my $podEntry (@{$spec->{podFiles}}) {

    my $targetFileName = "$spec->{tempRoot}\\$podEntry->{htmlFileName}";

    $targetFileName =~ s/\.[^\.]+$/\.pod/;

    $podEntry->{tempPodFileName} = $targetFileName;

    if ($options{what}) {

      # Do nothing.

    }

    elsif ($options{clean}) {

      unlink ($targetFileName);

    }

    else {

      fshu::CopyFile($podEntry->{podFileName}, $targetFileName, $options{verbose});

    }

  }

}

sub IdentifyIndexPod {

  my $spec = shift;

  # This sub-routine identifies the index POD files that will be generated later on.

  # This is done as a separate phase to allow indices to contain links generated POD.

  foreach my $indexEntry (@{$spec->{indices}}) {

    push (@{$spec->{podFiles}}, {

				 podFileName => "$indexEntry->{htmlDirName}.pod",

				 tempPodFileName => "$spec->{tempRoot}\\$indexEntry->{htmlDirName}.pod",

				 htmlFileName => "$indexEntry->{htmlDirName}.html"

				});

  }

}

sub GenerateIndexPod {

  my $spec = shift;

  foreach my $indexEntry (@{$spec->{indices}}) {

    my $tempDir = "$spec->{tempRoot}\\$indexEntry->{htmlDirName}";

    my $indexPodFileName = "$tempDir.pod";

    if ($options{what}) {

      # Do nothing.

    }

    elsif ($options{clean}) {

      unlink ($indexPodFileName);

    }

    else {

      print "Building $indexPodFileName\n" if ($options{verbose});

      fshu::MakePath($tempDir);

      open (INDEX, ">$indexPodFileName") or die "Error: Couldn't open '$indexPodFileName' for writing - $!\n";

      # Copy the contents of the introductory POD.

      if ($indexEntry->{podFileName}) {

	open (POD, $indexEntry->{podFileName}) or die "Error: Couldn't open '$indexEntry->{podFileName}' for reading - $!\n";

	while (my $line = <POD>) {

	  print INDEX $line;

	}

	close (POD);

      }

      else {

	print INDEX "=head1 $indexEntry->{htmlDirName}\n\n";

      }

      # Add the links.

      my $htmlDir = lc($indexEntry->{htmlDirName});

      foreach my $podEntry (@{$spec->{podFiles}}) {

	if (lc(dirname($podEntry->{htmlFileName})) eq $htmlDir) {

	  my $fileName = $podEntry->{htmlFileName};

	  $fileName =~ s/\.[^\.]+$//;

	  $fileName =~ s/\\/\//g;

	  my $presentableFileName = basename($fileName);

	  $presentableFileName = ucfirst($presentableFileName);

	  $presentableFileName =~ s/_/ /g;

	  $fileName =~ s/\//::/g;

	  print INDEX "\nL<$presentableFileName|$fileName>\n";

	}

      }

      close (INDEX);

    }

  }

}

sub IdentifyCifPod {

  my $spec = shift;

  # This sub-routine identifies the CIF index POD files that will be generated later on.

  # This is done as a separate phase to allow indices to contain links generated POD.

  foreach my $podEntry (@{$spec->{cifIndices}}) {

    push (@{$spec->{podFiles}}, {

				 podFileName => "$podEntry->{htmlDirName}.pod",

				 tempPodFileName => "$spec->{tempRoot}\\$podEntry->{htmlDirName}.pod",

				 htmlFileName => "$podEntry->{htmlDirName}.html"

				});

  }

}

sub GenerateCifPod {

  my $spec = shift;

  foreach my $podEntry (@{$spec->{cifIndices}}) {

    my $tempDir = "$spec->{tempRoot}\\$podEntry->{htmlDirName}";

    my $indexPodFileName = "$tempDir.pod";

    my $indexFile;

    if ($options{what}) {

      # Do nothing.

    }

    elsif ($options{clean}) {

      unlink ($indexPodFileName);

    }

    else {

      print "Building $indexPodFileName\n" if ($options{verbose});

      fshu::MakePath($tempDir);

      $indexFile = IO::File->new(">$indexPodFileName") or die "Error: Couldn't open '$indexPodFileName' for writing: $!\n";

      # Copy the contents of the introductory POD.

      if ($podEntry->{podFileName}) {

	open (POD, $podEntry->{podFileName}) or die "Error: Couldn't open '$podEntry->{podFileName}' for reading - $!\n";

	while (my $line = <POD>) {

	  print $indexFile $line;

	}

	close (POD);

      }

      else {

	print $indexFile "=head1 $podEntry->{htmlDirName}\n\n";

      }

      # Add an entry for the index .pod to cause the HTML to be generated later.

      push (@{$spec->{podFiles}}, {

				   tempPodFileName => $indexPodFileName,

				   htmlFileName => "$podEntry->{htmlDirName}.html"

				  });

    }

    # Generate a POD file for each CIF and add a line for each to the index file.

    opendir(DIR, $podEntry->{cifDirName}) or die "Error: Couldn't opendir '$podEntry->{cifDirName}' - $!\n";

    while (defined(my $file = readdir(DIR))) {

      my $cifFileName = "$podEntry->{cifDirName}\\$file";

      if (-f $cifFileName and ($cifFileName =~ /\.cif$/i)) {

	my $podFileName = "$tempDir\\$file";

	$podFileName =~ s/\.cif$/\.pod/i;

	my $htmlFileName = "$podEntry->{htmlDirName}\\$file";

	$htmlFileName =~ s/\.cif$/\.html/i;

	print "Reading '$cifFileName'...\n" if ($options{verbose});

	my $cif = CommandInfoFile->New($cifFileName);

	Cif2Pod($cif, $podFileName, $htmlFileName, $indexFile, $spec->{podFiles});

      }

    }

    closedir(DIR);

    if ($indexFile) {

      $indexFile->close();

    }

  }

}

sub BuildHtml {

  my $spec = shift;

  my $cwd = cwd();

  unless ($options{what} or $options{clean}) {

    chdir ($spec->{tempRoot}) or die "Error: Couldn't chdir to '$spec->{tempRoot}' - $!\n";

  }

  eval {

    my $first = 1;

    foreach my $podEntry (@{$spec->{podFiles}}) {

      DoBuildHtml($podEntry->{tempPodFileName}, $podEntry->{htmlFileName}, $spec->{docRoot}, $spec->{cssFile}, $first);

      $first = 0 if ($first);

    }

  };

  my $error = $@;

  chdir $cwd;

  die $@ if $@;

}

sub DoBuildHtml {

  my $podFileName = shift;

  my $htmlFileName = shift;

  my $docRoot = shift;

  my $css = shift;

  my $first = shift;

  my $outputFileName = "$docRoot\\$htmlFileName";

  if ($options{what}) {

    print "$outputFileName\n";

  }

  elsif ($options{clean}) {

    unlink ($outputFileName);

  }

  else {

    print "Building $outputFileName\n" if ($options{verbose});

    fshu::MakePath(dirname($outputFileName));

    my @elements = split /\\/, $htmlFileName;

    my $numElements = @elements;

    my $pathRelativeToDocRoot = '.';

    for (my $i = 0; $i < ($numElements - 1); ++$i) {

      if ($pathRelativeToDocRoot eq '.') {

	$pathRelativeToDocRoot = '..';

      }

      else {

	$pathRelativeToDocRoot = "..\\$pathRelativeToDocRoot";

      }

    }

    my @args = ("--podpath=.",

		"--podroot=.",

		"--htmlroot=$pathRelativeToDocRoot",

		"--recurse",

		"--infile=$podFileName",

		"--outfile=$outputFileName");

    #  push (@args, '--verbose') if ($options{verbose});

    if ($css) {

      my $relativeCssName = "$pathRelativeToDocRoot\\" . basename($css);

      push(@args, "--css=$relativeCssName");

    }

    if ($first) {

      push (@args, '--flush');

    }

    print "Calling pod2html - ", join(' ', @args), "\n" if ($options{verbose});

    pod2html(@args);

  }

}

sub Cif2Pod {

  my $cif = shift;

  my $podFileName = shift;

  my $htmlFileName = shift;

  my $indexFile = shift;

  my $podFileList = shift;

  # Add an entry for the CIF .pod to cause the HTML to be generated later.

  push (@$podFileList, {

			tempPodFileName => $podFileName,

			htmlFileName => $htmlFileName

		       });

  if ($options{what}) {

    # Do nothing.

  }

  elsif ($options{clean}) {

    unlink ($podFileName);

  }

  else {

    open (OUTPUT, ">$podFileName") or die "Error: Couldn't open '$podFileName' for writing: $!\n";

    print OUTPUT "=head1 SYNTAX\n\n";

    my $fullName = $cif->FullName();

    $fullName =~ s/^\S+\s//; # Remove the root command name if this is a sub-command.

    print OUTPUT '    ', $fullName;

    my $options = $cif->Options();

    if ($options and (@$options > 0)) {

      print OUTPUT ' [options]';

    }

    my $arguments = $cif->Arguments();

    foreach my $argument (@$arguments) {

      if ($argument->{flags}->{optional}) {

	print OUTPUT ' [<';

      }

      else {

	print OUTPUT ' <';

      }

      print OUTPUT $argument->{name};

      if ($argument->{flags}->{optional}) {

	print OUTPUT '>]';

      }

      else {

	print OUTPUT '>';

      }

      if ($argument->{flags}->{multiple}) {

	print OUTPUT ' ...';

      }

    }

    print OUTPUT "\n\n";

    if ($options and (@$options > 0)) {

      print OUTPUT "=head1 OPTIONS\n\n";

      print OUTPUT "=over5\n\n";

      foreach my $option (@$options) {

	print OUTPUT "=item -$option->{short_name} (--$option->{long_name}) $option->{type}\n\n$option->{description}";

	if ($option->{type} eq 'enum') {

	  FormatEnum($option->{enum_values});

	}

	if ($option->{flags}->{multiple}) {

	  print OUTPUT " Can be specified more than once.";

	}

	if ($option->{env_var}) {

	  print OUTPUT " Can also be specified by defining the environment variable '$option->{env_var}'.";

	}

	print OUTPUT "\n\n";

      }

      print OUTPUT "\n\n=back\n\n";

    }

    if ($arguments and (@$arguments > 0)) {

      print OUTPUT "=head1 ARGUMENTS\n\n\n\n";

      print OUTPUT "=over5\n\n";

      foreach my $argument (@$arguments) {

	print OUTPUT '=item ';

	if ($argument->{flags}->{optional}) {

	  print OUTPUT '[<';

	}

	else {

	  print OUTPUT '<';

	}

	print OUTPUT $argument->{name};