[perl-gnome2-canvas/doc-reorg] Moved main POD docs out of *.xs files and in to Canvas.pm




commit 5a4449829cf1b88c300f022229bdbf867a8644fe
Author: Brian Manning <bmanning src gnome org>
Date:   Wed Oct 28 19:37:48 2020 -0700

    Moved main POD docs out of *.xs files and in to Canvas.pm
    
    - Patch from Torsten applied that moves a majority of the docs out of
      the *.xs files, where they were dynamically generated into POD
      files, and into the Canvas.pm file, where they should be available
      for static viewing and parsing by CPAN search engines

 Canvas.pm             | 168 +++++++++++++++++++++++++++++++++++++++++++++++-
 xs/GnomeCanvas.xs     | 174 +-------------------------------------------------
 xs/GnomeCanvasUtil.xs |   3 +
 3 files changed, 169 insertions(+), 176 deletions(-)
---
diff --git a/Canvas.pm b/Canvas.pm
index 1034936..42e15b4 100644
--- a/Canvas.pm
+++ b/Canvas.pm
@@ -30,8 +30,170 @@ bootstrap Gnome2::Canvas $VERSION;
 1;
 __END__
 
-This is not the POD you're looking for.
+=head1 NAME
 
-The documentation for this module is generated from the XS source, and
-is stored in separate .pod files.
+Gnome2::Canvas - A structured graphics canvas
 
+=head1 SYNOPSIS
+
+  use strict;
+  use Gtk2 -init;
+  use Gnome2::Canvas;
+  my $window = Gtk2::Window->new;
+  my $scroller = Gtk2::ScrolledWindow->new;
+  my $canvas = Gnome2::Canvas->new;
+  $scroller->add ($canvas);
+  $window->add ($scroller);
+  $window->set_default_size (150, 150);
+  $canvas->set_scroll_region (0, 0, 200, 200);
+  $window->show_all;
+
+  my $root = $canvas->root;
+  Gnome2::Canvas::Item->new ($root, 'Gnome2::Canvas::Text',
+                             x => 20,
+                             y => 15,
+                             fill_color => 'black',
+                             font => 'Sans 14',
+                             anchor => 'GTK_ANCHOR_NW',
+                             text => 'Hello, World!');
+  my $box = Gnome2::Canvas::Item->new ($root, 'Gnome2::Canvas::Rect',
+                                       x1 => 10, y1 => 5,
+                                       x2 => 150, y2 => 135,
+                                       fill_color => 'red',
+                                       outline_color => 'black');
+  $box->lower_to_bottom;
+  $box->signal_connect (event => sub {
+          my ($item, $event) = @_;
+          warn "event ".$event->type."\n";
+  });
+
+  Gtk2->main;
+
+=head1 DESCRIPTION
+
+The Gnome Canvas is an engine for structured graphics that offers a
+rich imaging model, high-performance rendering, and a powerful,
+high level API.  It offers a choice of two rendering back-ends,
+one based on GDK for extremely fast display, and another based on
+Libart, a sophisticated, antialiased, alpha-compositing engine.
+This widget can be used for flexible display of graphics and for
+creating interactive user interface elements.
+
+To create a new Gnome2::Canvas widget call C<< Gnome2::Canvas->new >> or
+C<< Gnome2::Canvas->new_aa >> for an anti-aliased mode canvas.
+
+A Gnome2::Canvas contains one or more Gnome2::CanvasItem
+objects. Items consist of graphing elements like lines, ellipses,
+polygons, images, text, and curves.  These items are organized using
+Gnome2::CanvasGroup objects, which are themselves derived from
+Gnome2::CanvasItem.  Since a group is an item it can be contained within
+other groups, forming a tree of canvas items.  Certain operations, like
+translating and scaling, can be performed on all items in a group.
+
+There is a special root group created by a Gnome2::Canvas.  This is the top
+level group under which all items in a canvas are contained.  The root group
+is available as C<< $canvas->root >>.
+
+There are several different coordinate systems used by Gnome2::Canvas
+widgets.  The primary system is a logical, abstract coordinate space
+called world coordinates.  World coordinates are expressed as unbounded
+double floating point numbers.  When it comes to rendering to a screen
+the canvas pixel coordinate system (also referred to as just canvas
+coordinates) is used.  This system uses integers to specify screen
+pixel positions.  A user defined scaling factor and offset are used to
+convert between world coordinates and canvas coordinates.  Each item in
+a canvas has its own coordinate system called item coordinates.  This
+system is specified in world coordinates but they are relative to an
+item (0.0, 0.0 would be the top left corner of the item).  The final
+coordinate system of interest is window coordinates.  These are like
+canvas coordinates but are offsets from within a window a canvas is
+displayed in.  This last system is rarely used, but is useful when
+manually handling GDK events (such as drag and drop) which are
+specified in window coordinates (the events processed by the canvas
+are already converted for you).
+
+Along with different coordinate systems come methods to convert
+between them.  C<< $canvas->w2c >> converts world to canvas pixel
+coordinates and C<< canvas->c2w >> converts from canvas to
+world.  To get the affine transform matrix for converting
+from world coordinates to canvas coordinates call C<< $canvas->w2c_affine >>.
+C<< $canvas->window_to_world >> converts from window to world
+coordinates and C<< $canvas->world_to_window >> converts in the other
+direction.  There are no methods for converting between canvas and
+window coordinates, since this is just a matter of subtracting the
+canvas scrolling offset.  To convert to/from item coordinates use the
+methods defined for Gnome2::CanvasItem objects.
+
+To set the canvas zoom factor (canvas pixels per world unit, the
+scaling factor) call C<< $canvas->set_pixels_per_unit >>; setting this
+to 1.0 will cause the two coordinate systems to correspond (e.g., [5, 6]
+in pixel units would be [5.0, 6.0] in world units).
+
+Defining the scrollable area of a canvas widget is done by calling
+C<< $canvas->set_scroll_region >> and to get the current region
+C<< $canvas->get_scroll_region >> can be used.  If the window is
+larger than the canvas scrolling region it can optionally be centered
+in the window.  Use C<< $canvas->set_center_scroll_region >> to enable or
+disable this behavior.  To scroll to a particular canvas pixel coordinate
+use C<< $canvas->scroll_to >> (typically not used since scrollbars are
+usually set up to handle the scrolling), and to get the current canvas pixel
+scroll offset call C<< $canvas->get_scroll_offsets >>.
+
+=head1 SEE ALSO
+
+Gnome2::Canvas::index(3pm) lists the generated Perl API reference PODs.
+
+Gnome2::Canvas::main(3pm), in particular, lists the API in the Gnome2::Canvas
+package.
+
+Frederico Mena Quintero's whitepaper on the GNOME Canvas:
+http://developer.gnome.org/doc/whitepapers/canvas/canvas.html
+
+The real GnomeCanvas is implemented in a C library; the Gnome2::Canvas module
+allows a Perl developer to use the canvas like a normal gtk2-perl object.
+Like the Gtk2 module on which it depends, Gnome2::Canvas follows the C API of
+libgnomecanvas-2.0 as closely as possible while still being perlish.
+Thus, the C API reference remains the canonical documentation; the Perl
+reference documentation lists call signatures and argument types, and is
+meant to be used in conjunction with the C API reference.
+
+GNOME Canvas Library Reference Manual
+http://developer.gnome.org/doc/API/2.0/libgnomecanvas/index.html
+
+perl(1), Glib(3pm), Gtk2(3pm).
+
+To discuss gtk2-perl, ask questions and flame/praise the authors,
+join gtk-perl-list gnome org at lists.gnome.org.
+
+=cut
+
+=for position COPYRIGHT
+
+=head1 AUTHOR
+
+muppet <scott at asofyet dot org>, with patches from
+Torsten Schoenfeld <kaffetisch at web dot de>.
+
+The DESCRIPTION section of this page is adapted from the documentation of
+libgnomecanvas.
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2003-2004 by the gtk2-perl team.
+
+This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Library General Public
+License as published by the Free Software Foundation; either
+version 2 of the License, or (at your option) any later version.
+
+This library 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
+Library General Public License for more details.
+
+You should have received a copy of the GNU Library General Public
+License along with this library; if not, write to the
+Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+Boston, MA  02111-1307  USA.
+
+=cut
diff --git a/xs/GnomeCanvas.xs b/xs/GnomeCanvas.xs
index 2a00c63..8fc078a 100644
--- a/xs/GnomeCanvas.xs
+++ b/xs/GnomeCanvas.xs
@@ -110,181 +110,9 @@ BOOT:
 # and now back to Gnome2::Canvas
 #
 
-=for object Gnome2::Canvas A structured graphics canvas
-
-=cut
-
-=for position SYNOPSIS
-
-=head1 SYNOPSIS
-
-  use strict;
-  use Gtk2 -init;
-  use Gnome2::Canvas;
-  my $window = Gtk2::Window->new;
-  my $scroller = Gtk2::ScrolledWindow->new;
-  my $canvas = Gnome2::Canvas->new;
-  $scroller->add ($canvas);
-  $window->add ($scroller);
-  $window->set_default_size (150, 150);
-  $canvas->set_scroll_region (0, 0, 200, 200);
-  $window->show_all;
-
-  my $root = $canvas->root;
-  Gnome2::Canvas::Item->new ($root, 'Gnome2::Canvas::Text',
-                             x => 20,
-                             y => 15,
-                             fill_color => 'black',
-                             font => 'Sans 14',
-                             anchor => 'GTK_ANCHOR_NW',
-                             text => 'Hello, World!');
-  my $box = Gnome2::Canvas::Item->new ($root, 'Gnome2::Canvas::Rect',
-                                       x1 => 10, y1 => 5,
-                                       x2 => 150, y2 => 135,
-                                       fill_color => 'red',
-                                       outline_color => 'black');
-  $box->lower_to_bottom;
-  $box->signal_connect (event => sub {
-          my ($item, $event) = @_;
-          warn "event ".$event->type."\n";
-  });
-
-  Gtk2->main;
-
+=for object Gnome2::Canvas::main - A structured graphics canvas
 =cut
 
-=for position DESCRIPTION
-
-=head1 DESCRIPTION
-
-The Gnome Canvas is an engine for structured graphics that offers a
-rich imaging model, high-performance rendering, and a powerful,
-high level API.  It offers a choice of two rendering back-ends,
-one based on GDK for extremely fast display, and another based on
-Libart, a sophisticated, antialiased, alpha-compositing engine.
-This widget can be used for flexible display of graphics and for
-creating interactive user interface elements.
-
-To create a new Gnome2::Canvas widget call C<< Gnome2::Canvas->new >> or
-C<< Gnome2::Canvas->new_aa >> for an anti-aliased mode canvas.
-
-A Gnome2::Canvas contains one or more Gnome2::CanvasItem
-objects. Items consist of graphing elements like lines, ellipses,
-polygons, images, text, and curves.  These items are organized using
-Gnome2::CanvasGroup objects, which are themselves derived from
-Gnome2::CanvasItem.  Since a group is an item it can be contained within
-other groups, forming a tree of canvas items.  Certain operations, like
-translating and scaling, can be performed on all items in a group.
-
-There is a special root group created by a Gnome2::Canvas.  This is the top
-level group under which all items in a canvas are contained.  The root group
-is available as C<< $canvas->root >>.
-
-There are several different coordinate systems used by Gnome2::Canvas
-widgets.  The primary system is a logical, abstract coordinate space
-called world coordinates.  World coordinates are expressed as unbounded
-double floating point numbers.  When it comes to rendering to a screen
-the canvas pixel coordinate system (also referred to as just canvas
-coordinates) is used.  This system uses integers to specify screen
-pixel positions.  A user defined scaling factor and offset are used to
-convert between world coordinates and canvas coordinates.  Each item in
-a canvas has its own coordinate system called item coordinates.  This
-system is specified in world coordinates but they are relative to an
-item (0.0, 0.0 would be the top left corner of the item).  The final
-coordinate system of interest is window coordinates.  These are like
-canvas coordinates but are offsets from within a window a canvas is
-displayed in.  This last system is rarely used, but is useful when
-manually handling GDK events (such as drag and drop) which are 
-specified in window coordinates (the events processed by the canvas
-are already converted for you).
-
-Along with different coordinate systems come methods to convert
-between them.  C<< $canvas->w2c >> converts world to canvas pixel
-coordinates and C<< canvas->c2w >> converts from canvas to
-world.  To get the affine transform matrix for converting
-from world coordinates to canvas coordinates call C<< $canvas->w2c_affine >>.
-C<< $canvas->window_to_world >> converts from window to world
-coordinates and C<< $canvas->world_to_window >> converts in the other
-direction.  There are no methods for converting between canvas and
-window coordinates, since this is just a matter of subtracting the
-canvas scrolling offset.  To convert to/from item coordinates use the
-methods defined for Gnome2::CanvasItem objects.
-
-To set the canvas zoom factor (canvas pixels per world unit, the
-scaling factor) call C<< $canvas->set_pixels_per_unit >>; setting this
-to 1.0 will cause the two coordinate systems to correspond (e.g., [5, 6]
-in pixel units would be [5.0, 6.0] in world units).
-
-Defining the scrollable area of a canvas widget is done by calling
-C<< $canvas->set_scroll_region >> and to get the current region
-C<< $canvas->get_scroll_region >> can be used.  If the window is
-larger than the canvas scrolling region it can optionally be centered
-in the window.  Use C<< $canvas->set_center_scroll_region >> to enable or
-disable this behavior.  To scroll to a particular canvas pixel coordinate
-use C<< $canvas->scroll_to >> (typically not used since scrollbars are
-usually set up to handle the scrolling), and to get the current canvas pixel
-scroll offset call C<< $canvas->get_scroll_offsets >>.
-
-=cut
-
-=for position SEE_ALSO
-
-=head1 SEE ALSO
-
-Gnome2::Canvas::index(3pm) lists the generated Perl API reference PODs.
-
-Frederico Mena Quintero's whitepaper on the GNOME Canvas:
-http://developer.gnome.org/doc/whitepapers/canvas/canvas.html
-
-The real GnomeCanvas is implemented in a C library; the Gnome2::Canvas module
-allows a Perl developer to use the canvas like a normal gtk2-perl object.
-Like the Gtk2 module on which it depends, Gnome2::Canvas follows the C API of
-libgnomecanvas-2.0 as closely as possible while still being perlish.
-Thus, the C API reference remains the canonical documentation; the Perl
-reference documentation lists call signatures and argument types, and is
-meant to be used in conjunction with the C API reference.
-
-GNOME Canvas Library Reference Manual
-http://developer.gnome.org/doc/API/2.0/libgnomecanvas/index.html
-
-perl(1), Glib(3pm), Gtk2(3pm).
-
-To discuss gtk2-perl, ask questions and flame/praise the authors,
-join gtk-perl-list gnome org at lists.gnome.org.
-
-=cut
-
-=for position COPYRIGHT
-
-=head1 AUTHOR
-
-muppet <scott at asofyet dot org>, with patches from
-Torsten Schoenfeld <kaffetisch at web dot de>.
-
-The DESCRIPTION section of this page is adapted from the documentation of
-libgnomecanvas.
-
-=head1 COPYRIGHT AND LICENSE
-
-Copyright 2003-2004 by the gtk2-perl team.
-
-This library is free software; you can redistribute it and/or
-modify it under the terms of the GNU Library General Public
-License as published by the Free Software Foundation; either
-version 2 of the License, or (at your option) any later version.
-
-This library 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
-Library General Public License for more details.
-
-You should have received a copy of the GNU Library General Public
-License along with this library; if not, see
-L<https://www.gnu.org/licenses/>.
-
-=cut
-
-
 =for apidoc new_aa
 Create a new empty canvas in antialiased mode.
 =cut
diff --git a/xs/GnomeCanvasUtil.xs b/xs/GnomeCanvasUtil.xs
index 9a82121..d49e8c1 100644
--- a/xs/GnomeCanvasUtil.xs
+++ b/xs/GnomeCanvasUtil.xs
@@ -103,6 +103,9 @@ BOOT:
 
 MODULE = Gnome2::Canvas::Util  PACKAGE = Gnome2::Canvas        PREFIX = gnome_canvas_
 
+=for object Gnome2::Canvas::main
+=cut
+
 ##  int gnome_canvas_get_miter_points (double x1, double y1, double x2, double y2, double x3, double y3, 
double width, double *mx1, double *my1, double *mx2, double *my2) 
 =for apidoc
 =for signature ($mx1, $my1, $mx2, $my2) = Gnome2::Canvas->get_miter_points ($x1, $y1, $x2, $y2, $x3, $y3, 
$width)


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]