Bug #98540 for PDF-API2: Content.pm "developer method" future?

Tue Sep 02 11:14:01 2014 philperry [...] hvc.rr.com - Ticket created

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 <philperry [...] hvc.rr.com>

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?

Mon Jan 25 09:57:57 2016 philperry [...] hvc.rr.com - Correspondence added

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 <philperry [...] hvc.rr.com>

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? I still haven't figured exactly what "textlabel()" is supposed to do. Maybe something for brief labels or captions? To add a comment to this thread, just email bug-PDF-API2 [at] rt.cpan.org with subject line [rt.cpan.org #98540]. Note 1 space between org and #, and the [ ] around the whole subject. Nothing else. If you don't follow this format carefully, you will end up creating a new bug report! HTML formatting within the body does not work.

Tue Jan 26 22:31:01 2016 philperry [...] hvc.rr.com - Correspondence added

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 <philperry [...] hvc.rr.com>

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'

Thu Feb 18 15:03:37 2016 philperry [...] hvc.rr.com - Correspondence added

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 <philperry [...] hvc.rr.com>

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.