Commits

pa...@9ae0c189-cd1f-4510-a509-f4891f5cf20d  committed 2603c87

documentation fixes

  • Participants
  • Parent commits 225a95b

Comments (0)

Files changed (4)

    - skip tests that require Encode module if not available (perl 5.6)
    - finally removed the iterator() method deprecated since 1.54
    - set_document_locator support in XML::LibXML::SAX::Parser
-   
+   - SYNOPSIS sections of the docs now mention which module to use
+     and which other manpage to look into for inherited methods
 
 1.63
    - added no_network parser flag
 after an upgrade of libxml2.
 
 If your libxml2 installation is not within your $PATH, you can pass the
-XMLPREFIX=$YOURLIBXMLPREFIX parameter to Makefile.PL determining
-the correct libxml2 version in use. e.g.
+XMLPREFIX=$YOURLIBXMLPREFIX parameter to Makefile.PL determining the correct
+libxml2 version in use. e.g.
 
 >  perl Makefile.PL XMLPREFIX=/usr/brand-new 
 
 CONTACT
 =======
 
-For suggestions etc. you may contact the maintainer directly at "pajas at
-ufal.mff.cuni.cz".
-
 For bug reports, please use the CPAN request tracker on
 http://rt.cpan.org/NoAuth/Bugs.html?Dist=XML-LibXML
 
-Also XML::LibXML issues are discussed among other things on the perl XML
-mailing list (perl-xml@listserv.ActiveState.com). In case of problems you
-should check the archives of that list first. Many problems are already
-discussed there. You can find the list's archives at
-http://mailarchive.activestate.com/browse/perl-xml/
+For suggestions etc. you may contact the maintainer directly at "pajas at ufal
+dot mff dot cuni dot cz", but in general, it is recommended to use the mailing
+list given below.
+
+For suggestions etc., and other issues related to XML::LibXML you may use the
+perl XML mailing list (perl-xml@listserv.ActiveState.com), where most
+XML-related Perl modules are discussed. In case of problems you should check
+the archives of that list first. Many problems are already discussed there. You
+can find the list's archives and subscription options at
+http://aspn.activestate.com/ASPN/Mail/Browse/Threaded/perl-xml
 
 
 PACKAGE HISTORY

File docs/libxml.dbk

                  XML::LibXML::Common and run its tests after an upgrade of libxml2.
 	        </para>
 
-                <para>If your libxml2 installation is not within your
-                  $PATH. you can set the environment variable
-                  XMLPREFIX=$YOURLIBXMLPREFIX to make XML::LibXML
-                  recognize the correct libxml2 version in use.</para>
-
-                <para>e.g.</para>
+	<para>If your libxml2 installation is not within your $PATH,
+	  you can pass the XMLPREFIX=$YOURLIBXMLPREFIX parameter to Makefile.PL
+	  determining the correct libxml2 version in use. e.g.
+	</para>
 
                 <programlisting> perl Makefile.PL XMLPREFIX=/usr/brand-new </programlisting>
 
         <sect1>
             <title>Contact</title>
 
-            <para>For suggestions etc. you may contact the maintainer directly at "pajas at ufal.mff.cuni.cz".</para>
-
             <para>For bug reports, please use the CPAN request tracker on http://rt.cpan.org/NoAuth/Bugs.html?Dist=XML-LibXML</para>
 
-            <para>Also XML::LibXML issues are discussed among other
-            things on the perl XML mailing list
-            (<email>perl-xml@listserv.ActiveState.com</email>). In
-            case of problems you should check the archives of that
+            <para>For suggestions etc. you may contact the maintainer directly at "pajas at ufal dot mff dot cuni dot cz", but in general, it is recommended to use the mailing list given below.
+            </para>
+
+            <para>For suggestions etc., and other issues
+	    related to XML::LibXML you may use the perl XML mailing list
+            (<email>perl-xml@listserv.ActiveState.com</email>),
+	    where most XML-related Perl modules are discussed.
+	    In case of problems you should check the archives of that
             list first. Many problems are already discussed there. You
-            can find the list's archives at
-            http://mailarchive.activestate.com/browse/perl-xml/</para>
+            can find the list's archives and subscription options at
+	    http://aspn.activestate.com/ASPN/Mail/Browse/Threaded/perl-xml</para>
         </sect1>
 
         <sect1>
                 </varlistentry>
             </variablelist>
         </sect1>
+        <sect1>
+            <title>CONTACTS</title>
+
+            <para>For bug reports, please use the CPAN request tracker on http://rt.cpan.org/NoAuth/Bugs.html?Dist=XML-LibXML</para>
+            <para>For suggestions etc., and other issues
+	    related to XML::LibXML you may use the perl XML mailing list
+            (<email>perl-xml@listserv.ActiveState.com</email>),
+	    where most XML-related Perl modules are discussed.
+	    In case of problems you should check the archives of that
+            list first. Many problems are already discussed there. You
+            can find the list's archives and subscription options at
+  	    <ulink url="http://aspn.activestate.com/ASPN/Mail/Browse/Threaded/perl-xml">http://aspn.activestate.com/ASPN/Mail/Browse/Threaded/perl-xml</ulink>.
+            </para>
+        </sect1>
     </chapter>
 
     <chapter>
         <sect1>
             <title>Synopsis</title>
 
-            <programlisting>my $builder = XML::LibXML::SAX::Builder-&gt;new();
+            <programlisting>use XML::LibXML::SAX::Builder;
+my $builder = XML::LibXML::SAX::Builder-&gt;new();
 
 my $gen = XML::Generator::DBI-&gt;new(Handler =&gt; $builder, dbh =&gt; $dbh);
 $gen-&gt;execute("SELECT * FROM Users");
         <title>XML::LibXML DOM Document Class</title>
 
         <titleabbrev>XML::LibXML::Document</titleabbrev>
+        <sect1>
+            <title>Synopsis</title>
+            <programlisting>use XML::LibXML;
+# Only methods specific to Document nodes listed here,
+# see XML::LibXML::Node manpage for other methods</programlisting>
+        </sect1>
 
         <para>The Document Class is in most cases the result of a parsing process. But sometimes it is necessary to create a Document from scratch. The DOM
         Document Class provides functions that conform to the DOM Core naming style.</para>
         <title>Abstract Base Class of XML::LibXML Nodes</title>
 
         <titleabbrev>XML::LibXML::Node</titleabbrev>
-
+        <sect1>
+            <title>Synopsis</title>
+            <programlisting>use XML::LibXML;</programlisting>
+        </sect1>
         <para>XML::LibXML::Node defines functions that are common to
         all Node Types. A LibXML::Node should never be created
         standalone, but as an instance of a high level class such as
         <title>XML::LibXML Class for Element Nodes</title>
 
         <titleabbrev>XML::LibXML::Element</titleabbrev>
-
+        <sect1>
+            <title>Synopsis</title>
+            <programlisting>use XML::LibXML;
+# Only methods specific to Element nodes listed here,
+# see XML::LibXML::Node manpage for other methods</programlisting>
+        </sect1>
         <variablelist>
             <varlistentry>
                 <term>new</term>
         <title>XML::LibXML Class for Text Nodes</title>
 
         <titleabbrev>XML::LibXML::Text</titleabbrev>
+        <sect1>
+            <title>Synopsis</title>
+            <programlisting>use XML::LibXML;
+# Only methods specific to Text nodes listed here,
+# see XML::LibXML::Node manpage for other methods</programlisting>
+        </sect1>
 
         <para>Different to the DOM specification XML::LibXML implements the text node as the base class of all character data node. Therefor there exists no
         CharacterData class. This allow one to use all methods that are available for text nodes as well for Comments or CDATA-sections.</para>
         <title>XML::LibXML Comment Class</title>
 
         <titleabbrev>XML::LibXML::Comment</titleabbrev>
+        <sect1>
+            <title>Synopsis</title>
+            <programlisting>use XML::LibXML;
+# Only methods specific to Comment nodes listed here,
+# see XML::LibXML::Node manpage for other methods</programlisting>
+        </sect1>
 
         <para>This class provides all functions of <emphasis>XML::LibXML::Text</emphasis>, but for comment nodes. This can be done, since only the output of the
         node types is different, but not the data structure. :-)</para>
         <title>XML::LibXML Class for CDATA Sections</title>
 
         <titleabbrev>XML::LibXML::CDATASection</titleabbrev>
+        <sect1>
+            <title>Synopsis</title>
+            <programlisting>use XML::LibXML;
+# Only methods specific to CDATA nodes listed here,
+# see XML::LibXML::Node manpage for other methods</programlisting>
+        </sect1>
 
         <para>This class provides all functions of <emphasis>XML::LibXML::Text</emphasis>, but for CDATA nodes.</para>
 
         <title>XML::LibXML Attribute Class</title>
 
         <titleabbrev>XML::LibXML::Attr</titleabbrev>
+        <sect1>
+            <title>Synopsis</title>
+            <programlisting>use XML::LibXML;
+# Only methods specific to Attribute nodes listed here,
+# see XML::LibXML::Node manpage for other methods</programlisting>
+        </sect1>
 
         <para>This is the interface to handle Attributes like ordinary nodes. The naming of the class relies on the W3C DOM documentation.</para>
 
         <title>XML::LibXML's DOM L2 Document Fragment Implementation</title>
 
         <titleabbrev>XML::LibXML::DocumentFragment</titleabbrev>
+        <sect1>
+            <title>Synopsis</title>
+            <programlisting>use XML::LibXML;</programlisting>
+        </sect1>
 
         <para>This class is a helper class as described in the DOM Level 2 Specification. It is implemented as a node without name. All adding, inserting or
         replacing functions are aware of document fragments now.</para>
         <title>XML::LibXML Namespace Implementation</title>
 
         <titleabbrev>XML::LibXML::Namespace</titleabbrev>
+        <sect1>
+            <title>Synopsis</title>
+            <programlisting>use XML::LibXML;
+# Only methods specific to Namespace nodes listed here,
+# see XML::LibXML::Node manpage for other methods</programlisting>
+        </sect1>
 
         <para>Namespace nodes are returned by both $element-&gt;findnodes('namespace::foo') or by $node-&gt;getNamespaces().</para>
 
         <title>XML::LibXML Processing Instructions</title>
 
         <titleabbrev>XML::LibXML::PI</titleabbrev>
+        <sect1>
+            <title>Synopsis</title>
+            <programlisting>use XML::LibXML;
+# Only methods specific to Processing Instruction nodes listed here,
+# see XML::LibXML::Node manpage for other methods</programlisting>
+        </sect1>
 
         <para>Processing instructions are implemented with XML::LibXML with read and write access. The PI data is the PI without the PI target (as specified in
         XML 1.0 [17]) as a string. This string can be accessed with getData as implemented in XML::LibXML::Node.</para>
         <title>XML::LibXML DTD Handling</title>
 
         <titleabbrev>XML::LibXML::Dtd</titleabbrev>
+        <sect1>
+            <title>Synopsis</title>
+            <programlisting>use XML::LibXML;</programlisting>
+        </sect1>
 
         <para>This class holds a DTD. You may parse a DTD from either a string, or from an external SYSTEM identifier.</para>
 
         <title>XML::LibXML Class for Input Callbacks</title>
 
         <titleabbrev>XML::LibXML::InputCallback</titleabbrev>
+        <sect1>
+            <title>Synopsis</title>
+            <programlisting>use XML::LibXML;</programlisting>
+        </sect1>
 
         <sect1>
             <title>Synopsis</title>
         <title>RelaxNG Schema Validation</title>
 
         <titleabbrev>XML::LibXML::RelaxNG</titleabbrev>
+        <sect1>
+            <title>Synopsis</title>
+            <programlisting>use XML::LibXML;
+$doc = XML::LibXML->new->parse_file($url);</programlisting>
+        </sect1>
 
         <para>The XML::LibXML::RelaxNG class is a tiny frontend to libxml2's RelaxNG implementation. Currently it supports only schema parsing and document
         validation.</para>
         <title>XML Schema Validation</title>
 
         <titleabbrev>XML::LibXML::Schema</titleabbrev>
+        <sect1>
+            <title>Synopsis</title>
+            <programlisting>use XML::LibXML;
+$doc = XML::LibXML->new->parse_file($url);</programlisting>
+        </sect1>
 
         <para>The XML::LibXML::Schema class is a tiny frontend to libxml2's XML Schema implementation. Currently it supports only schema parsing and
         document validation.</para>

File example/xmllibxmldocs.pl

         my ( $ttlabbr ) = $chap->getChildrenByTagName( "titleabbrev" );
         my $str =  $ttlabbr->string_value() . " - ".$title->string_value();
         $self->{OFILE}->print(  "=head1 NAME\n\n$str\n\n" );
+	my ($synopsis) = $chap->findnodes( "sect1[title='Synopsis']" );
         my @funcs = $chap->findnodes( ".//funcsynopsis" );
+	if ($synopsis or scalar @funcs) {
+            $self->{OFILE}->print( "=head1 SYNOPSIS\n\n" )
+	}
+	if ($synopsis) {
+	  $self->dump_pod( $synopsis );
+	}
         if ( scalar @funcs ) {
-            $self->{OFILE}->print( "=head1 SYNOPSIS\n\n" );
             foreach my $s ( @funcs ) {
                 $self->dump_pod( $s );
             }
         }
         elsif ( $node->nodeName() eq "sect1" ) {
             my ( $title ) = $node->getChildrenByTagName( "title" );
-            my $str = $title->string_value();
-
-            $self->{OFILE}->print( "\n=head1 " . uc($str) );
-            $self->{OFILE}->print( "\n\n" );
-            $self->dump_pod( $node );
+	    my $str = $title->string_value();
+	    unless ($chap->nodeName eq "chapter" and $str eq 'Synopsis') {
+	      $self->{OFILE}->print( "\n=head1 " . uc($str) );
+	      $self->{OFILE}->print( "\n\n" );
+	      $self->dump_pod( $node );
+	    }
         }
         elsif (  $node->nodeName() eq "sect2" ) {
             my ( $title ) = $node->getChildrenByTagName( "title" );