[6141] regenerate pod doc for Convert/*.pm

[karl]

Revision: 6141
          http://svn.sv.gnu.org/viewvc/?view=rev&root=texinfo&revision=6141
Author:   karl
Date:     2015-02-22 23:35:32 +0000 (Sun, 22 Feb 2015)
Log Message:
-----------
regenerate pod doc for Convert/*.pm

Modified Paths:
--------------
    trunk/ChangeLog
    trunk/tp/Makefile.am
    trunk/tp/Texinfo/Convert/DocBook.pm
    trunk/tp/Texinfo/Convert/HTML.pm
    trunk/tp/Texinfo/Convert/Info.pm
    trunk/tp/Texinfo/Convert/Plaintext.pm
    trunk/tp/Texinfo/Convert/TexinfoXML.pm
    trunk/tp/maintain/regenerate_converters_documentation.sh

Property Changed:
----------------
    trunk/tp/maintain/regenerate_converters_documentation.sh

Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog     2015-02-22 23:34:38 UTC (rev 6140)
+++ trunk/ChangeLog     2015-02-22 23:35:32 UTC (rev 6141)
@@ -1,5 +1,12 @@
 2015-02-22  Karl Berry  <address@hidden>
 
+       * tp/maintain/template.pod: tweak text, add __HTML signal.
+       * tp/maintain/regenerate_converters_documentation.sh: HTML-specific.
+       * tp/Makefile.am (do-pm-doc): new target to call that script.
+       * tp/Texinfo/Convert/*.pm: remake pod with that script/target.
+
+2015-02-22  Karl Berry  <address@hidden>
+
        * info/Makefile.am (EXTRA_DIST): remove t/Cleanup.inc (gone).
        * README-hacking,
        * tp/README,

Modified: trunk/tp/Makefile.am
===================================================================
--- trunk/tp/Makefile.am        2015-02-22 23:34:38 UTC (rev 6140)
+++ trunk/tp/Makefile.am        2015-02-22 23:35:32 UTC (rev 6141)
@@ -212,6 +212,9 @@
   $(perl_specific_files) \
   maintain/lib
 
+# MANIFEST is used for the Perl module.
+# maintain/MANIFEST_generated_files is used for dist(check).
+# They are made by maintain/prepare_perl_module_files.sh.
 MANIFEST: maintain/MANIFEST_generated_files Makefile.am Makefile.tres
        LC_ALL=C; export LC_ALL; LANGUAGE=C; export LANGUAGE; \
        echo "$(dist_modules_DATA) $(dist_converters_DATA)" \
@@ -223,6 +226,14 @@
         | cat - $(srcdir)/maintain/MANIFEST_generated_files \
         | sort >$@
 
+# template.pod is the basis for the .pm documentation, and the script
+# invoked here updates them; to be run when template.pod changes.
+# 
+# If we ever make that documentation more extensive, the .pm doc could
+# (and probably should) just be maintained separately, by hand.
+do-pm-doc:
+       ./maintain/regenerate_converters_documentation.sh
+
 maintain/catalog.xml: maintain/catalog.xml.in Makefile
        $(MKDIR_P) maintain
        sed -e 's|address@hidden@]|$(abs_top_srcdir)|' \

Modified: trunk/tp/Texinfo/Convert/DocBook.pm
===================================================================
--- trunk/tp/Texinfo/Convert/DocBook.pm 2015-02-22 23:34:38 UTC (rev 6140)
+++ trunk/tp/Texinfo/Convert/DocBook.pm 2015-02-22 23:35:32 UTC (rev 6141)
@@ -1410,6 +1410,7 @@
 1;
 
 __END__
+# $Id$
 # Automatically generated from maintain/template.pod
 
 =head1 NAME
@@ -1422,6 +1423,8 @@
     = Texinfo::Convert::DocBook->converter({'parser' => $parser});
 
   $converter->output($tree);
+  $converter->convert($tree);
+  $converter->convert_tree($tree);
 
 =head1 DESCRIPTION
 
@@ -1433,7 +1436,7 @@
 
 =item $converter = Texinfo::Convert::DocBook->converter($options)
 
-Initialize a DocBook converter.  
+Initialize converter from Texinfo to DocBook.  
 
 The I<$options> hash reference holds options for the converter.  In
 this option hash reference a parser object may be associated with the 
@@ -1455,9 +1458,9 @@
 
 =item $result = $converter->convert_tree($tree)
 
-Convert a Texinfo tree portion I<$tree> and return the resulting output.
-This function do not try to output a full document but only portions.
-For a full document use C<convert>.
+Convert a Texinfo tree portion I<$tree> and return the resulting 
+output.  This function does not try to output a full document but only
+portions.  For a full document use C<convert>.
 
 =back
 
@@ -1467,7 +1470,7 @@
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 2012, 2013, 2014, 2015 Free Software Foundation, Inc.
+Copyright 2015 Free Software Foundation, Inc.
 
 This library is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by

Modified: trunk/tp/Texinfo/Convert/HTML.pm
===================================================================
--- trunk/tp/Texinfo/Convert/HTML.pm    2015-02-22 23:34:38 UTC (rev 6140)
+++ trunk/tp/Texinfo/Convert/HTML.pm    2015-02-22 23:35:32 UTC (rev 6141)
@@ -7645,6 +7645,7 @@
 1;
 
 __END__
+# $Id$
 # Automatically generated from maintain/template.pod
 
 =head1 NAME
@@ -7657,6 +7658,9 @@
     = Texinfo::Convert::HTML->converter({'parser' => $parser});
 
   $converter->output($tree);
+  $converter->convert($tree);
+  $converter->convert_tree($tree);
+  $converter->output_internal_links(); # HTML only
 
 =head1 DESCRIPTION
 
@@ -7668,7 +7672,7 @@
 
 =item $converter = Texinfo::Convert::HTML->converter($options)
 
-Initialize an HTML converter.  
+Initialize converter from Texinfo to HTML.  
 
 The I<$options> hash reference holds options for the converter.  In
 this option hash reference a parser object may be associated with the 
@@ -7691,14 +7695,14 @@
 =item $result = $converter->convert_tree($tree)
 
 Convert a Texinfo tree portion I<$tree> and return the resulting 
-output.  This function do not try to output a full document but only
-portions of document.  For a full document use C<convert>.
+output.  This function does not try to output a full document but only
+portions.  For a full document use C<convert>.
 
 =item $result = $converter->output_internal_links()
 
-Returns text representing the links in the document.  At present the format 
-should follow the C<--internal-links> option of texi2any/makeinfo specification
-and this is only relevant for HTML.
+Returns text representing the links in the document.  The format should
+follow the C<--internal-links> option of the texi2any/makeinfo
+specification.  This is only supported in (and relevant for) HTML.
 
 =back
 
@@ -7708,7 +7712,7 @@
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 2012, 2013, 2014, 2015 Free Software Foundation, Inc.
+Copyright 2015 Free Software Foundation, Inc.
 
 This library is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by

Modified: trunk/tp/Texinfo/Convert/Info.pm
===================================================================
--- trunk/tp/Texinfo/Convert/Info.pm    2015-02-22 23:34:38 UTC (rev 6140)
+++ trunk/tp/Texinfo/Convert/Info.pm    2015-02-22 23:35:32 UTC (rev 6141)
@@ -511,6 +511,7 @@
 1;
 
 __END__
+# $Id: template.pod 6140 2015-02-22 23:34:38Z karl $
 # Automatically generated from maintain/template.pod
 
 =head1 NAME
@@ -523,6 +524,8 @@
     = Texinfo::Convert::Info->converter({'parser' => $parser});
 
   $converter->output($tree);
+  $converter->convert($tree);
+  $converter->convert_tree($tree);
 
 =head1 DESCRIPTION
 
@@ -534,7 +537,7 @@
 
 =item $converter = Texinfo::Convert::Info->converter($options)
 
-Initialize an Info converter.  
+Initialize converter from Texinfo to Info.  
 
 The I<$options> hash reference holds options for the converter.  In
 this option hash reference a parser object may be associated with the 
@@ -557,15 +560,9 @@
 =item $result = $converter->convert_tree($tree)
 
 Convert a Texinfo tree portion I<$tree> and return the resulting 
-output.  This function do not try to output a full document but only
-portions of document.  For a full document use C<convert>.
+output.  This function does not try to output a full document but only
+portions.  For a full document use C<convert>.
 
-=item $result = $converter->output_internal_links()
-
-Returns text representing the links in the document.  At present the format 
-should follow the C<--internal-links> option of texi2any/makeinfo specification
-and this is only relevant for HTML.
-
 =back
 
 =head1 AUTHOR
@@ -574,7 +571,7 @@
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 2012 Free Software Foundation, Inc.
+Copyright 2015 Free Software Foundation, Inc.
 
 This library is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by

Modified: trunk/tp/Texinfo/Convert/Plaintext.pm
===================================================================
--- trunk/tp/Texinfo/Convert/Plaintext.pm       2015-02-22 23:34:38 UTC (rev 
6140)
+++ trunk/tp/Texinfo/Convert/Plaintext.pm       2015-02-22 23:35:32 UTC (rev 
6141)
@@ -3375,6 +3375,7 @@
 1;
 
 __END__
+# $Id$
 # Automatically generated from maintain/template.pod
 
 =head1 NAME
@@ -3387,6 +3388,8 @@
     = Texinfo::Convert::Plaintext->converter({'parser' => $parser});
 
   $converter->output($tree);
+  $converter->convert($tree);
+  $converter->convert_tree($tree);
 
 =head1 DESCRIPTION
 
@@ -3398,7 +3401,7 @@
 
 =item $converter = Texinfo::Convert::Plaintext->converter($options)
 
-Initialize a Plaintext converter.  
+Initialize converter from Texinfo to Plaintext.  
 
 The I<$options> hash reference holds options for the converter.  In
 this option hash reference a parser object may be associated with the 
@@ -3432,7 +3435,7 @@
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 2010, 2011, 2012, 2013, 2014, 2015 Free Software Foundation, Inc.
+Copyright 2015 Free Software Foundation, Inc.
 
 This library is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by

Modified: trunk/tp/Texinfo/Convert/TexinfoXML.pm
===================================================================
--- trunk/tp/Texinfo/Convert/TexinfoXML.pm      2015-02-22 23:34:38 UTC (rev 
6140)
+++ trunk/tp/Texinfo/Convert/TexinfoXML.pm      2015-02-22 23:35:32 UTC (rev 
6141)
@@ -1647,6 +1647,7 @@
 1;
 
 __END__
+# $Id: template.pod 6140 2015-02-22 23:34:38Z karl $
 # Automatically generated from maintain/template.pod
 
 =head1 NAME
@@ -1659,6 +1660,8 @@
     = Texinfo::Convert::TexinfoXML->converter({'parser' => $parser});
 
   $converter->output($tree);
+  $converter->convert($tree);
+  $converter->convert_tree($tree);
 
 =head1 DESCRIPTION
 
@@ -1670,7 +1673,7 @@
 
 =item $converter = Texinfo::Convert::TexinfoXML->converter($options)
 
-Initialize an TexinfoXML converter.  
+Initialize converter from Texinfo to TexinfoXML.  
 
 The I<$options> hash reference holds options for the converter.  In
 this option hash reference a parser object may be associated with the 
@@ -1693,15 +1696,9 @@
 =item $result = $converter->convert_tree($tree)
 
 Convert a Texinfo tree portion I<$tree> and return the resulting 
-output.  This function do not try to output a full document but only
-portions of document.  For a full document use C<convert>.
+output.  This function does not try to output a full document but only
+portions.  For a full document use C<convert>.
 
-=item $result = $converter->output_internal_links()
-
-Returns text representing the links in the document.  At present the format 
-should follow the C<--internal-links> option of texi2any/makeinfo specification
-and this is only relevant for HTML.
-
 =back
 
 =head1 AUTHOR
@@ -1710,7 +1707,7 @@
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 2012 Free Software Foundation, Inc.
+Copyright 2015 Free Software Foundation, Inc.
 
 This library is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by

Modified: trunk/tp/maintain/regenerate_converters_documentation.sh
===================================================================
--- trunk/tp/maintain/regenerate_converters_documentation.sh    2015-02-22 
23:34:38 UTC (rev 6140)
+++ trunk/tp/maintain/regenerate_converters_documentation.sh    2015-02-22 
23:35:32 UTC (rev 6141)
@@ -1,12 +1,35 @@
 #! /bin/sh
-
-# This file pastes the content of maintain/template.pod at the end of 
-# converter modules, with the output format name suitably setup.
+# $Id$
+# This little script pastes the content of maintain/template.pod at the
+# end of converter modules, with the output format name suitably defined.
 # This file should be run when maintain/template.pod is modified.
+#
+# Copyright 2011, 2012, 2013, 2014, 2015 Free Software Foundation, Inc.
+#
+# This file is free software; as a special exception the author gives
+# unlimited permission to copy and/or distribute it, with or without
+# modifications, as long as this notice is preserved.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY, to the extent permitted by law; without even the
+# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+#
+# Originally written by Patrice Dumas.
 
 for format in HTML TexinfoXML DocBook Info Plaintext; do
-  sed -e '/^__END__/q' Texinfo/Convert/$format.pm > 
Texinfo/Convert/$format.pm.$$.tmp || exit 1
-  sed "s/OUTFORMAT/$format/g" maintain/template.pod > maintain/$format.pod
-  sed -e "/^__END__/r maintain/$format.pod" Texinfo/Convert/$format.pm.$$.tmp 
> Texinfo/Convert/$format.pm || exit 1
+  sed -e '/^__END__/q' Texinfo/Convert/$format.pm \
+    > Texinfo/Convert/$format.pm.$$.tmp || exit 1
+
+  sed -e "s/OUTFORMAT/$format/g" maintain/template.pod \
+  | if test $format = HTML; then
+      sed 's/^__HTML \?//'
+    else
+      sed -e '/^__HTML/d'
+    fi \
+  > maintain/$format.pod || exit 1
+  
+  sed -e "/^__END__/r maintain/$format.pod" Texinfo/Convert/$format.pm.$$.tmp \
+    > Texinfo/Convert/$format.pm || exit 1
+
   rm -f maintain/$format.pod Texinfo/Convert/$format.pm.$$.tmp
 done


Property changes on: trunk/tp/maintain/regenerate_converters_documentation.sh
___________________________________________________________________
Added: svn:keywords
   + Date Author Id