Bugtracker with GitHub instead. Improve POD.

README.pod

@@ -79,6 +79,24 @@ The options have the following interpretation:
      multiline_type => 'join_last' : Multi-line parser, that continues previous line in the current line
                     => undef (Default)
 
+=head3 Which C<multiline_type> is right for me?
+
+If your text format allows users to break up their text into another line while indicating a continuation, you need to use the C<multiline_type> option. The option allows you to join those lines back into a single line, so that your C<save_record> method doesn't have to bother about joining the continued lines, stripping any continuation characters, line-feeds etc. If your text format does not allow users to break up information into multiple lines like that, then this is not what you want.
+
+If you need to write a multi-line parser, then you need to set C<multiline_type> option to one of the values shown above. How do you decide which one?
+
+=over 4
+
+=item *
+
+If your format allows something like a trailing back-slash or some other character to indicate that text on I<B<next>> line is to be joined with this one, then choose C<join_next>.
+
+=item *
+
+If your format allows some character to indicate that text on the current line is part of the I<B<last>> line, then choose C<join_last>.
+
+=back
+
 =head2 setting
 
 Takes a single string as argument, and returns the value of that setting. The string must be one of:
@@ -460,8 +478,7 @@ Try this parser with a simple SPICE deck and see what you get. You may now write
 =head1 BUGS
 
 Please report any bugs or feature requests on the bugtracker website
-L<http://rt.cpan.org/Public/Dist/Display.html?Name=Text-Parser> or by email
-to L<bug-text-parser at rt.cpan.org|mailto:bug-text-parser at rt.cpan.org>.
+L<http://github.com/me/Text-Parser/issues>
 
 When submitting a bug or request, please include a test-file or a
 patch to an existing test-file that illustrates the bug or desired

dist.ini

@@ -7,16 +7,18 @@ copyright_year   = 2018
 
 ;; Determine the next version from the Git repo
 [Git::NextVersion]
-first_version = 0.001       ; this is the default
-version_by_branch = 0       ; this is the default
-version_regexp  = ^v(.+)$   ; this is the default
+first_version = 0.001
+version_by_branch = 0
+version_regexp  = ^v(.+)$
 [PkgVersion]
 use_package = 1
 
 ;; All plugins for POD
 ;; PodWeaver should come before PodVersion because PodVersion looks for =head1 NAME
 ;; Check weaver.ini for order of sections in POD
 [Bugtracker]
+web = http://github.com/me/%s/issues
+
 [Git::Contributors]
 include_releaser=0
 

lib/Text/Parser.pm

@@ -114,6 +114,16 @@ The options have the following interpretation:
      multiline_type => 'join_last' : Multi-line parser, that continues previous line in the current line
                     => undef (Default)
 
+=head3 Which C<multiline_type> is right for me?
+
+If your text format allows users to break up their text into another line while indicating a continuation, you need to use the C<multiline_type> option. The option allows you to join those lines back into a single line, so that your C<save_record> method doesn't have to bother about joining the continued lines, stripping any continuation characters, line-feeds etc. If your text format does not allow users to break up information into multiple lines like that, then this is not what you want.
+
+If you need to write a multi-line parser, then you need to set C<multiline_type> option to one of the values shown above. How do you decide which one?
+
+=for :list
+* If your format allows something like a trailing back-slash or some other character to indicate that text on I<B<next>> line is to be joined with this one, then choose C<join_next>.
+* If your format allows some character to indicate that text on the current line is part of the I<B<last>> line, then choose C<join_last>.
+
 =cut
 
 sub new {

lib/Text/Parser/Multiline.pm

@@ -46,7 +46,7 @@ This extension allows users to use the familiar C<save_record> interface to save
 To create a multi-line text parser you need to know:
 
 =for :list
-* L<Determine|Text::Parser/new> if your parser is a C<'join_next'> type or a C<'join_last'> type. This depends on which line has the continuation character.
+* L<Determine|Text::Parser/new> if your parser is a C<'join_next'> type or a C<'join_last'> type.
 * Recognize if a line has a continuation pattern
 * How to strip the continuation character and join with last line
 
@@ -59,19 +59,19 @@ So here are the things you need to do if you have to write a multi-line text par
 * Override the C<new> constructor to add C<multiline_type> option by default. Read about the option L<here|Text::Parser/new>.
 * Override the C<is_line_continued> method to detect if there is a continuation character on the line.
 * Override the C<join_last_line> to join the previous line and the current line after stripping any continuation characters.
-* Implement your C<save_record> as if you always get joined lines, and
+* Implement your C<save_record> as if you always get joined lines!
 
-There are some default implementations for both these methods, but for most practical purposes you'd want to override those in your own parser class.
+That's it! What's more? There are some default implementations for these methods in L<Text::Parser> class already. But if you want to do any stripping of continuation characters etc., you'd want to override these in your own parser class.
 
-=head2 C<< $self->new(%options) >>
+=head2 C<< Text::Parser->new(%options) >>
 
-Decide if you want to set any options like C<auto_chomp> by default. In order to get a multi-line parser, you I<must> select one of C<multiline_type> values: C<'join_next'> or C<'join_last'>.
+L<Decide|Text::Parser/new> if you want to set any options like C<auto_chomp> by default. In order to get a multi-line parser, you I<must> select one of C<multiline_type> values: C<'join_next'> or C<'join_last'>.
 
-=head2 C<< $self->is_line_continued($line) >>
+=head2 C<< $parser->is_line_continued($line) >>
 
 Takes a string argument as input. Returns a boolean that indicates if the current line is continued from the previous line, or is continued on the next line (depending on the type of multi-line text format). You don't need to bother about how the boolean result of this routine is interpreted. That is handled depending on the type of multi-line parser. The way the result of this function is interpreted depends on the type of multi-line parser you make. If it is a C<'join_next'> parser, then a true value from this routine means that some data is expected to be in the I<next> line which is expected to be joined with this line. If instead the parser is C<'join_last'>, then a true value from this method would mean that the current line is a continuation from the I<previous> line, and the current line should be appended to the content of the previous line.
 
-=head2 C<< $self->join_last_line($last_line, $current_line) >>
+=head2 C<< $parser->join_last_line($last_line, $current_line) >>
 
 Takes two string arguments. The first is the line previously read which is expected to be continued on this line. You can be certain that the two strings will not be C<undef>. Your method should return a string that has stripped any continuation characters, and joined the current line with the previous line. You don't need to bother about where and how this is being saved. You also don't need to bother about where the last line is stored/coming from. The management of the last line is handled internally.