[docs] update equo man page, correct formatting, make it easier to use

docs/man/pod-generator/Pod.pm

@@ -0,0 +1,173 @@
+use warnings;
+use strict;
+use 5.010;
+
+# by Enlik
+# April 2011
+
+package Pod;
+
+sub new {
+	my $class = shift;
+	my $strs = shift || die "specify parameter";
+	
+	unless (ref $strs eq "ARRAY") {
+		die "wrong parameter";
+	}
+	
+	my $self = {
+		strs => $strs
+	};
+	
+	bless $self, $class;
+}
+
+sub generate {
+	my $self = shift;
+	my @strs = @{$self->{strs}};
+	
+	print q{
+=head1 NAME
+
+B<equo> - Official Sabayon Linux Package Manager Client
+
+=head1 SYNOPSIS
+
+B<equo> [action] [basic_options] [options|extended_options] [atom | package_file | @set] ...
+
+B<equo> [action] [basic_options] [options|extended_options] ...
+
+B<equo> --info
+
+B<equo> --help
+
+B<equo> --version
+
+=head1 DESCRIPTION
+
+B<equo> is the definitive (rofl)... scratch it.
+B<equo> is the official command-line interface to the Entropy framework. Primarily
+used to ease packages management on Gentoo-based, Entropy-enabled distributions.
+
+With B<equo> you can easily install and remove any application inside available and
+enabled repositories: it's a binary package manager which brings the best from
+apt, yum and rpm, keeping 100% backward Portage (see 'man emerge') compatibility.
+Being Entropy a framework means that it's not just ended here.
+
+For example, through B<equo> you can build your own software repository (called
+Community Repository), do searches, keep your system secure, download packages'
+source code, sanity check your system, see and be part of the User Generated
+Content produced by other users.
+
+};
+
+	my $indent_lvl = 0;
+	
+	for my $h (@strs) {
+		my ($indent, $cmd, $desc);
+		$indent = $h->{indent};
+		$cmd = $h->{command};
+		$desc = $h->{desc};
+		
+		while ($indent_lvl > $indent) {
+			print "\n=back\n\n";
+			$indent_lvl--;
+		}
+		while ($indent_lvl < $indent) {
+			print "\n=over\n\n";
+			$indent_lvl++;
+		}
+		
+		if ($indent == 0) {
+			my $out;
+			given($desc) {
+				when (/Basic Options/) {
+					$out = "BASIC_OPTIONS";
+				}
+				when (/Application Options/) {
+					$out = "OPTIONS";
+				}
+				when(/Extended Options/) {
+					$out = "EXTENDED_OPTIONS";
+				}
+				$out = uc($desc);
+				$out =~ s/\s/_/g;
+			}
+			$desc = $out;
+			print "=head1 ", $self->conv($desc), "\n";
+		}
+		else {
+			if ($cmd) {
+				my $out = "[$indent] B<" . $self->conv($cmd) . ">";
+				print "=item ", $out, "\n";
+			}
+			
+			print "\n", $self->conv($desc), "\n\n";
+		}
+	}
+	
+	print q{
+=back
+
+=head1 ENVIRONMENT
+
+B<ETP_NOCACHE>=1: if set, all the Entropy framework will never use its internal
+on-disk cache.
+
+
+B<FORCE_EAPI>=N: if set to 1, 2 or 3 and used with 'B<equo> update', Entropy
+repository synchronized will be force to use the provided EAPI to update
+repositories.
+
+B<ACCEPT_LICENSE>=license_id1:license_id2:...: this is a way to avoid equo
+asking to accept specific licenses.
+
+B<ETP_NO_COLOR>=1: disable entropy coloured output.
+
+=head1 BUGS
+
+Please report bugs to http://bugs.sabayonlinux.org.
+B<equo> has a nice bug-reporting feature: whenever a valid exception occurs, it
+asks the user to automatically submit the issue. B<WARNING>: to do efficient bug
+squashing, some hardware specs are going to be collected, ask wrote before
+submitting any data. No personal data is going to be uploaded and your report
+will be kept private.
+
+=head1 EXAMPLES
+
+ work in progress
+
+=head1 EXIT STATUS
+
+B<equo> returns a zero exit status if the called command succeeded. Non zero is
+returned in case of failure.
+
+=head1 AUTHOR
+
+Fabio Erculiani <lxnay@sabayon.org>
+
+=head1 SEE ALSO
+
+reagent(1), activator(1)};
+}
+
+sub conv {
+	my $self = shift;
+	my $line = shift || return "";
+	# $line =~ s/</E<lt>/g;
+	# $line =~ s/>/E<gt>/g;
+
+	my $c;
+	my $o = "";
+	for my $c (split //,$line) {
+		if ($c eq "<")		{ $o .= "E<lt>" }
+		elsif ($c eq ">")	{ $o .= "E<gt>" }
+		else				{ $o .= $c }
+	}
+	$line = $o;
+	
+	$line =~ s/&/E<amp>/g;
+	$line;
+}
+
+1;

docs/man/pod-generator/halp.pl

@@ -0,0 +1,101 @@
+#!/usr/bin/env perl
+
+use warnings;
+use strict;
+use 5.010;
+
+# tool to make a pod file generated from equo --help
+# which can be used to make a manual page
+
+# A tip:
+# if this tool gives badly formatted text due to missing \t etc. in equo
+# output, it's easier to save equo output to file, correct it and pipe
+# using cat.
+
+# by Enlik
+
+my @strs;
+# @strs: { <el> }, { <el> }, ...
+# el - hash: indent => <0..n>, command => <str>, desc => <str>
+
+# command line arg:
+# -p	generate pod file
+
+# pass to stdin equo --help (English),
+# you may use: LANG=en_US.UTF-8 equo | perl <this script>
+
+if (@ARGV and $ARGV[0] eq "-p") {
+	require Pod;
+	@strs = parse_input();
+	
+	my $conv = Pod->new(\@strs);
+	$conv->generate;
+}
+else {
+	print "bad command, use -p\n";
+	exit 1;
+}
+
+sub parse_input {
+	my @strs = ();
+	my $level;
+	my ($cmd, $desc);
+	
+	while (my $line = <STDIN>) {
+		chomp $line;
+		
+		next unless $line; # omit empty
+		
+		# 0 level
+		if ($line =~ /^  \S/) {		
+			$line = substr $line, 2;
+			$level = 0;
+		}
+		elsif ($line =~ /^\t/) {
+			$level = 0;
+			while ($line =~ /^\t/) {
+				$level++;
+				$line = substr $line, 1;
+			}
+		}
+		else {
+			if ($line and not $line =~ /~ equo ~/) {
+				die "badly formatted line: $line\n";
+			}
+			next;
+		}
+
+		if ($line =~ /^([^\t]+)\t+(.*)/) {
+			$cmd = $1;
+			$desc = $2;
+		}
+		else {
+			$cmd = "";
+			$desc = $line;
+		}
+		## hop <branch>	upgrade your distribution to a new release (branch)
+		#if ($line =~ /^(\S+ <.+>)\s*(.*)/) {
+			#$cmd = $1;
+			#$desc = $2;
+		#}
+		## notice [repos]	repository notice board reader
+		#elsif ($line =~ /^(\S+ \[.+\])\s*(.*)/) {
+			#$cmd = $1;
+			#$desc = $2;
+		#}
+		## search		search packages in repositories
+		#elsif ($line =~ /^(\S+)\s*(.*)/) {
+			#$cmd = $1;
+			#$desc = $2;
+		#}
+		#else {
+			## ?
+			#$level = 0;
+			#$cmd = "";
+			#$desc = $line;
+		#}
+		
+		push @strs, { indent => $level, command => $cmd, desc => $desc };
+	}
+	@strs;
+}