Post without Account — your post will be reviewed, and if appropriate, posted under Anonymous. You can also use this link to report any problems registering or logging in.

RT 98540 - Content.pm "developer method" future?

  • 1 Replies
  • 1260 Views
*

Offline Phil

  • Global Moderator
  • Hero Member
  • *****
  • 586
    • View Profile
RT 98540 - Content.pm "developer method" future?
« October 21, 2016, 03:27:08 PM »
Subject:    Content.pm "developer method" future?
Date:    Tue, 02 Sep 2014 11:12:31 -0400
To:    bug-PDF-API2 [...] rt.cpan.org
From:    Phil M Perry

PDF::API2 v2.022   Perl 5.16.3  Windows 7   severity: Wishlist

In Content.pm, there are still three methods marked "developer method". They are paragraph(), section(), and textlabel(). Should they be "promoted" to supported methods and documented in the POD, or left hidden for an indefinite time, or even deprecated and eventually removed? From the code, I can figure out what paragraph() and section() are intended to do (fill and format a single paragraph or multiple paragraphs), but I have no idea what textlabel() is supposed to be doing. Does anyone know? Do any of these methods look useful?
#
Subject:    [rt.cpan.org #98540]
Date:    Mon, 25 Jan 2016 09:57:52 -0500
To:    bug-PDF-API2 [...] rt.cpan.org
From:    Phil M Perry

Thinking about this some more, I'm not sure that paragraph() and section() are all that useful. If your text has no markup within a paragraph, it could work (calling a "fill" routine to assemble a paragraph line by line from single-line input). However, if you want any markup within a paragraph (bold, italic, color, font change, etc.), it doesn't work. I'm thinking about a revised paragraph() (and section()) where you could either embed various "in line" changes into a data structure of text and commands (build it up), and then output the whole thing in one call; or give a "start paragraph", standard calls to output text, and an "end paragraph" call to reflow and patch up as necessary. If you're doing justification, you don't want to use standard Content methods to output content without taking justification and spill to the next line into account. Probably the former method (data structure) would work better. It will also need to allow the user to specify what kind of justification (left, center, right, full). Since these three methods are not yet officially supported, they might be extensively changed (no existing usage to break). Thoughts from the community?

Quote
I still haven't figured exactly what "textlabel()" is supposed to do.
Maybe something for brief labels or captions?
#
Subject:    [rt.cpan.org #98540]
Date:    Tue, 26 Jan 2016 22:31:02 -0500
To:    bug-PDF-API2 [...] rt.cpan.org
From:    Phil M Perry

I see that the textlabel() method is used extensively in the "examples" codes, to provide "all in one call" text output at a given position, angle, color, underline, justification, hscale, etc. This could be useful for various short pieces of text in a document, and so probably should be promoted to fully documented status.
#
Wed Feb 17 18:52:24 2016 steve [...] deefs.net - Correspondence added

Undocumented developer methods should not be used, and can disappear at any time.

These three in particular don't really belong in the Content module.  They could potentially go in a supporting module, either as part of the PDF::API2 distribution or as a separate distribution that makes use of and supports PDF::API2.
#
Wed Feb 17 18:52:24 2016 The RT System itself - Status changed from 'new' to 'open'
#
Wed Feb 17 18:52:36 2016 steve [...] deefs.net - Status changed from 'open' to 'rejected'
#
Subject:    [rt.cpan.org #98540]
Date:    Thu, 18 Feb 2016 15:03:46 -0500
To:    bug-PDF-API2 [...] rt.cpan.org
From:    Phil M Perry 

OK, I can live with removing these three methods from Content. As they are potentially useful to someone, it would be nice to keep them somewhere in some sort of supporting .pm module. Note that textlabel() appears to be only used by examples/ code, which has been removed, yet could be quite useful by itself. If anyone screams loudly enough that they had been using this "developers code", they can either be pointed to the new module, or it can be restored to Content.pm. Further note that paragraph() and section(), while not terribly useful (as they can only use a simple string input, i.e., no markup within them), could still be useful to someone with simple needs. Perhaps I will write either an extension to paragraph() and section(), or new routines in the same module, that can handle inline markup changes (bold, italic, typeface, typesize, type color, background color, etc., and maybe even change bars), but that will be a while off.

*

Offline Phil

  • Global Moderator
  • Hero Member
  • *****
  • 586
    • View Profile
Re: RT 98540 - Content.pm "developer method" future?
« Reply #1: March 30, 2017, 10:13:54 AM »
I have moved paragraph(), section(), and textlabel() out of PDF::API2::Content to module PDF::API2::Content::Text, along with several other advanced text-processing methods: text_center(), text_right(), text_justified(), text_fill_left(), text_fill_center(), text_fill_right(), and text_fill_justified(). text_left() (an alias for text) and text_fill() (an alias for text_fill_left()) have also been added for symmetry. POD documentation has been updated.

paragraph() and section() have been improved a bit (including indent/outdent and interparagraph spacing), but are still fairly primitive — limited to the same font, size, styling, etc. throughout them. I have no plans to improve upon this.

These changes will appear in release 3.003.