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 98550 - cr(vert_offset) change documentation to match code

  • 1 Replies
  • 1078 Views
*

Offline Phil

  • Global Moderator
  • Sr. Member
  • *****
  • 437
    • View Profile
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

[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).

Quote
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).
#
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

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.
#
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'
#
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

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.
#
Thu Feb 18 12:00:43 2016 steve [...] deefs.net - Correspondence added

Yes, that's exactly what a carriage return is supposed to do.  Look it up.  It comes from the days of typewriters.
#
ubject:    [rt.cpan.org #98550]
Date:    Thu, 18 Feb 2016 14:09:56 -0500
To:    bug-PDF-API2 [...] rt.cpan.org
From:    Phil M Perry

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.

The distance() method seems to do what is expected of cr() and nl(), so perhaps both of these should be deprecated?
#
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

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.
Code: [Select]
=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.

*

Offline Phil

  • Global Moderator
  • Sr. Member
  • *****
  • 437
    • View Profile
Re: RT 98550 - cr(vert_offset) change documentation to match code
« Reply #1: November 18, 2016, 09:55:47 PM »
POD updated in 3.001

The current (2.030) code implementation is satisfactory. I have updated the POD to clarify how cr() is supposed to behave. It is merely a "carriage return" with no linefeed, and you supply the amount of vertical feed.