Bug #98550 for PDF-API2: Fwd: cr(vert_offset) change documentation to match code

Tue Sep 02 12:19:03 2014 philperry [...] hvc.rr.com - Ticket created

Subject:	Fwd: cr(vert_offset) change documentation to match code
Date:	Tue, 02 Sep 2014 12:18:56 -0400
To:	bug-PDF-API2 [...] rt.cpan.org
From:	Phil M Perry <philperry [...] hvc.rr.com>

[This may be a duplicate. My mail system says that it failed to deliver it.] Also, I didn't mention that this was in Content.pm (ditto for nl bug report). Show quoted text

-------- Original Message -------- Subject: cr(vert_offset) change documentation to match code Date: Tue, 02 Sep 2014 10:52:19 -0400 From: Phil M Perry <philperry@hvc.rr.com> Reply-To: philperry@hvc.rr.com To: bug-PDF-API2@rt.cpan.org PDF::API2 v2.022 Perl 5.16.3 Windows 7 severity: Important The cr($vert_offset) method behavior does not appear to match its POD. Rather than being a vertical offset from the next line down (the wording is ambiguous), the code appears to place the new line relative to the CURRENT line, with vertical displacement in points. Thus, cr(0) overprints the current line because the current x,y is brought back to the start of the current line. A positive value moves above the current line, and a negative value below it. $self->lead is ignored. I have submitted to the maintainer a suggested change to the POD which documents how the code actually works. It might even be better (more intuitive) to change the code to go down (-y) by $self->lead, and then up by -$vert_offset or down by +$vert_offset (the idea being to go DOWN by leading+offset, rather than swapping signs around).

Sun Jan 24 12:19:24 2016 philperry [...] hvc.rr.com - Correspondence added

Subject:	[rt.cpan.org #98550]
Date:	Sun, 24 Jan 2016 12:19:12 -0500
To:	bug-PDF-API2 [...] rt.cpan.org
From:	Phil M Perry <philperry [...] hvc.rr.com>

Does anyone have any input on how the cr() call is supposed to work? Would any of the proposed extensions break existing code? To have to manually add OBJ->lead as the call's argument seems silly -- to build it in seems to have been the original intent of the call, but it got lost somewhere. cr(0) could stay as "overprint the current line" and cr() could stay as "go DOWN to the next line (by OBJ->lead amount). cr(n) could be understood as "go DOWN to the next line, and down more (or maybe up) by n", but that might break existing uses. Currently it moves UP by n from the CURRENT line. Should an optional second parameter be added to control this, or perhaps an %opts entry? Either way would preserve existing behavior in existing code. To add a comment to this thread, just email bug-PDF-API2 [at] rt.cpan.org with subject line [rt.cpan.org #98550]. 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 of the comment does not work.

Wed Feb 17 18:12:01 2016 steve [...] deefs.net - Correspondence added

cr() works as documented. Calling it without first calling lead() does a carriage return. Calling it with 0 as the argument does a carriage return with no offset, regardless of the lead() value. Calling it with a specific offset does a carriage return and then offsets by the provided $vertical_offset. The existing behavior mimics the X,Y behavior in other calls (positive Y is up, negative Y is down), so I don't think this should be changed.

Wed Feb 17 18:12:01 2016 The RT System itself - Status changed from 'new' to 'open'

Wed Feb 17 18:12:05 2016 steve [...] deefs.net - Status changed from 'open' to 'rejected'

Thu Feb 18 00:32:35 2016 philperry [...] hvc.rr.com - Correspondence added

Subject:	[rt.cpan.org #98550]
Date:	Thu, 18 Feb 2016 00:32:39 -0500
To:	bug-PDF-API2 [...] rt.cpan.org
From:	Phil M Perry <philperry [...] hvc.rr.com>

No, cr(0) does NOT do a carriage return first -- it OVERPRINTS the current line. cr(n) is consistent in the sense that n is the vertical offset from the CURRENT line (+ is up). cr() is the odd man out, moving DOWN (-y) a line by self->lead. If we want to document the cr() method as ignoring self->lead if an explicit value is given, I could live with that, but as things currently stand, its behavior is inconsistent and doesn't match the POD. Something needs to be done, even if it's just clarifying the documentation. If behavior depends on whether the lead() method has already been called, that needs to be documented.

Message body is not shown because sender requested not to inline it.

Download cr.pdf
application/pdf 13.7k

Message body not shown because it is not plain text.

Thu Feb 18 12:00:43 2016 steve [...] deefs.net - Correspondence added

On Thu Feb 18 00:32:35 2016, philperry@hvc.rr.com wrote: Show quoted text

> No, cr(0) does NOT do a carriage return first -- it OVERPRINTS the > current line.

Yes, that's exactly what a carriage return is supposed to do. Look it up. It comes from the days of typewriters.

Thu Feb 18 14:09:51 2016 philperry [...] hvc.rr.com - Correspondence added

Subject:	[rt.cpan.org #98550]
Date:	Thu, 18 Feb 2016 14:09:56 -0500
To:	bug-PDF-API2 [...] rt.cpan.org
From:	Phil M Perry <philperry [...] hvc.rr.com>

Hmm. I never used a typewriter that didn't combine Carriage Return with Line Feed (CRLF). Anyway, that makes cr()'s behavior a bit more understandable, but it still needs to be better documented in the POD. Show quoted text

> Yes, that's exactly what a carriage return is supposed to do. Look it > up. It comes from the days of typewriters.

The distance() method seems to do what is expected of cr() and nl(), so perhaps both of these should be deprecated?

Thu Feb 18 14:39:01 2016 philperry [...] hvc.rr.com - Correspondence added

Subject:	[rt.cpan.org #98550]
Date:	Thu, 18 Feb 2016 14:39:16 -0500
To:	bug-PDF-API2 [...] rt.cpan.org
From:	Phil M Perry <philperry [...] hvc.rr.com>

So this POD entry would make more sense to me. What do you think? BTW, there is already a default leading value -- no need to explicitly set it first. =item $content->cr() =item $content->cr($vertical_offset) When called I<without> an argument, moves the cursor to the start of the line, then down (-y) by the amount of leading in use (moves to the beginning of the next line down). An offset can be passed as an argument to override the current leading value. The cursor will be moved to the start of the line, then a positive offset will move the cursor up, and a negative offset will move the cursor down. An offset of 0 (zero) will only move the cursor to the start of the line, with no vertical adjustment (a simple Carriage Return). This can be used for overprinting a line. The C<distance()> method can be used to go down to the beginning of the next line, and then adjust both vertically and horizontally, if that is needed.