protecting my newly podded docs against a rogue README generator.

3 files changed, 167 insertions, 93 deletions

diff --git a/history-search/rl_history_search.pl b/history-search/rl_history_search.pl
index e9a365e..7561386 100644
--- a/history-search/rl_history_search.pl
+++ b/history-search/rl_history_search.pl
@@ -1,75 +1,147 @@
-# Search within your typed history as you type (like ctrl-R in bash)
-#
-# INSTALL:
-#
-# This script requires that you have first installed and loaded 'uberprompt.pl'
-# Uberprompt can be downloaded from:
-#
-# http://github.com/shabble/irssi-scripts/raw/master/prompt_info/uberprompt.pl
-#
-# and follow the instructions at the top of that file for installation.
-#
-# USAGE:
-#
-# * Setup: /bind ^R /history_search_start
-#
-# * Then type ctrl-R and type what you're searching for
-#
-# * You can cycle through multiple matches with ^R (older matches), and
-#   ^S (newer matches)
-#
-# NOTE: Ctrl-S may not work if you have software flow control configured for
-# your terminal. It may appear to freeze irssi entirely. If this happens, it can
-# be restored with Ctrl-Q, but you will be unable to use the Ctrl-S binding.
-# You can disable flow control by running the command `stty -ixon' in your
-# terminal, or setting `defflow off' in your ~/.screenrc if using GNU Screen.
-#
-# * Hitting enter selects a match and terminates search mode.
-#
-# * You can use ^G to exit search mode without selecting.
-#
-# * Pressing <TAB> whilst the search is active will open a new split
-#   window, showing all matching completions.  <Esc> will close the window
-#   again, as will any other action that exits history search mode.
-#   Possible candidates can be cycled through as normal using C-r and C-s.
-#
-# * Any other ctrl- or meta- key binding will terminate search mode, leaving the
-#   selected item in the input line.
-#
-# Original script Copyright 2007  Wouter Coekaerts <coekie@irssi.org>
-# Heavy modifications Copyright 2010-11 Tom Feist <shabble+irssi@metavore.org>
-#
-# This program is free software; you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation; either version 2 of the License, or
-# (at your option) any later version.
-#
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with this program; if not, write to the Free Software
-# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
-
-# TODO:
-#
-# * DONE document tab behaviour
-# * add keys (C-n/C-p) to scroll history list if necessary.
-# * DONE if list is bigger than split size, centre it so selected item is visible
-# * INPROG allow a mechanism to select by number from list
-# * steal more of the code from ido_switcher to hilight match positions.
-# * make flex matching optional (key or setting)
-# * add some online help (? or C-h triggered, maybe?)
-# * make temp_split stuff more generic (to be used by help, etc)
-# * figure out why sometimes the split list doesn't update correctly (eg: no matches)
-# * consider tracking history manually (via send command/send text)
-#  * Pro: we could timestamp it.
-#  * Con: Would involve catching up/down and all the other history selection
-#         mechanisms.
-#  * Compromise - tag history as it comes it (match it with data via sig handlers?)
-# * Possibility of saving/restoring history over sessions?
+=pod
+
+=head1 NAME
+
+rl_history_search.pl
+
+=head1 DESCRIPTION
+
+Search within your typed history as you type (something like ctrl-R in bash or other
+readline-type applications.)
+
+=head1 INSTALLATION
+
+Copy into your F<~/.irssi/scripts/> directory and load with
+C</SCRIPT LOAD F<filename>>.
+
+This script requires that you have first installed and loaded F<uberprompt.pl>
+
+Uberprompt can be downloaded from:
+
+L<https://github.com/shabble/irssi-scripts/raw/master/prompt_info/uberprompt.pl>
+
+and follow the instructions at the top of that file or its README for installation.
+
+If uberprompt.pl is available, but not loaded, this script will make one
+attempt to load it before giving up.  This eliminates the need to precisely
+arrange the startup order of your scripts.
+
+=head1 SETUP
+
+C</bind ^R /history_search_start>
+
+Where C<^R> is a key of your choice.
+
+=head1 USAGE
+
+Type C<ctrl-R> followed by your search string.  The prompt line will show
+you the most recent command to match the string you've typed.
+
+B<Tip:> You can cycle through multiple matches with C<Ctrl-R> (to select older
+matches), and <Ctrl-S> (to select newer matches).  Cycling off the end of the
+history list returns you to the other end again.
+
+B<NOTE:> C<Ctrl-S> may not work if you have software flow control configured for
+your terminal. It may appear to freeze irssi entirely. If this happens, it can
+be restored with C<Ctrl-Q>, but you will be unable to use the C<Ctrl-S> binding.
+You can disable flow control by running the command C<stty -ixon> in your
+terminal, or setting C<defflow off> in your F<~/.screenrc>if using GNU Screen.
+
+=head2 COMMANDS
+
+=over 4
+
+=item C<Enter>
+
+Selects a match and terminates search mode.
+B<It will also run the currently selected command.>
+
+=item C<Ctrl-G>
+
+Exits search mode without selecting.
+
+=item C<E<lt>TABE<gt>
+
+Opens a new split window, showing all matching completions.  C<E<lt>EscE<gt>>
+will close the window again, as will any other action that exits history search
+mode.  Possible candidates can be cycled through as normal using C<C-r> and
+<C-s>.
+
+=item Any other ctrl- or meta- key
+
+This will terminate search mode, leaving the selected item in the input line.
+It will not run the command (Except for C<Ctrl-J> and C<Ctrl-M>, which are
+functionally equivalent to C<Enter>).
+
+=back
+
+=head1 AUTHORS
+
+Original script L<history_search.pl|https://github.com/coekie/irssi-scripts/blob/master/history_search.pl> Copyright E<copy> 2007 Wouter Coekaerts <coekie@irssi.org>
+
+Most of the other fancy stuff Copyright E<copy> 2011 Tom Feist
+C<E<lt>shabble+irssi@metavore.orgE<gt>>
+
+=head1 LICENCE
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+
+=head1 BUGS
+
+Yeah, probably.
+
+=head1 TODO
+
+=over 1
+
+=item * B<DONE> document tab behaviour
+
+=item * add keys (C-n/C-p) to scroll history list if necessary.
+
+=item * B<DONE> if list is bigger than split size, centre it so selected item is visible
+
+=item * I<INPROG> allow a mechanism to select by number from list
+
+=item * steal more of the code from ido_switcher to hilight match positions.
+
+=item * make flex matching optional (key or setting)
+
+=item * add some online help (? or C-h triggered, maybe?)
+
+=item * make temp_split stuff more generic (to be used by help, etc)
+
+=item * figure out why sometimes the split list doesn't update correctly (eg: no matches)
+
+=item * consider tracking history manually (via send command/send text)
+
+=over 4
+
+=item * Pro: we could timestamp it.
+
+=item * Con: Would involve catching up/down and all the other history selection mechanisms.
+
+=item * Compromise - tag history as it comes it (match it with data via sig handlers?)
+
+=back
+
+=item * Possibility of saving/restoring history over sessions?
+
+=back
+
+=cut
+
 
 use strict;
 use Irssi;
@@ -86,7 +158,8 @@ our %IRSSI =
    . ' (like ctrl-R in readline applications)',
    license     => 'GPLv2 or later',
    url         => 'http://github.com/shabble/irssi-scripts/tree/master/history-search/',
-   changed     => '14/4/2011'
+   changed     => '14/4/2011',
+   requires    => [qw/uberprompt.pl/],
   );
 
 my $search_str = '';
diff --git a/ido-mode/ido_switcher.pl b/ido-mode/ido_switcher.pl
index ea19afd..81f49ff 100644
--- a/ido-mode/ido_switcher.pl
+++ b/ido-mode/ido_switcher.pl
@@ -16,7 +16,7 @@ Uberprompt can be downloaded from:
 
 L<https://github.com/shabble/irssi-scripts/raw/master/prompt_info/uberprompt.pl>
 
-and follow the instructions at the top of that file for installation.
+and follow the instructions at the top of that file or its README for installation.
 
 If uberprompt.pl is available, but not loaded, this script will make one
 attempt to load it before giving up.  This eliminates the need to precisely
@@ -26,6 +26,8 @@ arrange the startup order of your scripts.
 
 C</bind ^G /ido_switch_start [options]>
 
+Where C<^G> is a key of your choice.
+
 =head2 USAGE
 
 C<C-g> (or whatever you've set the above bind to), enters IDO window switching mode.
diff --git a/readme_generator.pl b/readme_generator.pl
index 2062ad1..5052afb 100644
--- a/readme_generator.pl
+++ b/readme_generator.pl
@@ -8,10 +8,12 @@ use warnings;
 #
 # Not sure how it's going to work with multiple files in a dir though. Sections?
 
+# Change of plan! Github supports POD, so we just use Pod::Select to scrape it.
 
 use File::Find;
 use File::Spec;
-use Pod::Markdown;
+use Pod::Select;
+
 use feature qw/say/;
 use Cwd;
 
@@ -32,9 +34,11 @@ find(\&wanted, @dirs);
 sub wanted {
     my ($file, $dir, $path) = ($_, $File::Find::dir, $File::Find::name);
     return unless $file =~ m/\.pl$/;
+    return if $file =~ m/^\./;
 
     _err("processing file: $path");
-    read_input_file($dir, $file);
+    #read_input_file($dir, $file);
+    create_output_file($dir, $file);
 }
 
 sub read_input_file {
@@ -43,39 +47,34 @@ sub read_input_file {
     my $filepath = File::Spec->catfile($dir, $filename);
     _err("reading $filepath");
 
-    my $parser = Pod::Markdown->new;
-    $parser->parse_from_file($filepath);
-
     create_output_file($dir, "README.md", $parser);
 }
 
 sub create_output_file {
-    my ($dir, $filename, $parser) = @_;
-
-    my $filepath = File::Spec->catfile($dir, $filename);
-
-    my $markdown = $parser->as_markdown;
+    my ($dir, $in_file) = @_;
 
-    return unless length chomp($markdown);
-    return if $markdown =~ m/^\s*$/;
+    my $parser = Pod::Select->new;
 
+    my $out_file = "README.pod";
 
+    my $in_file_path = File::Spec->catfile($dir, $in_file);
+    my $out_file_path = File::Spec->catfile($dir, $out_file);
     my $sec_sep = '';
 
-    if (-f $filepath and not $overwrite) {
-        _err("$filepath already exists, going to append") unless $overwrite;
-        $sec_sep = "\n\n* * * *\n\n";
+    if (-f $out_file_path and not $overwrite) {
+        _err("$out_file_path already exists, going to append") unless $overwrite;
+        $sec_sep = "\n\n=for html <br />\n\n";
     }
 
     my $mode = $overwrite ? '>' : '>>';
 
     _err("Writing to $mode $filepath");
 
-    open my $wfh, $mode, $filepath
-      or die "Couldn't open $filepath for $mode output: $!";
+    open my $wfh, $mode, $out_file_path
+      or die "Couldn't open $out_file_path for $mode output: $!";
+
+    $parser->parse_from_file($in_file_path, $wfh);
 
-    print $wfh $sec_sep;
-    print $wfh $parser->as_markdown; # fetch it again since we chomped $markdown.
     close $wfh;
 }