PDFX4DRV_API.pdf Documentation Woes

PDF-XChange Drivers API (only) V4/V5
This Forum is for the use of Software Developers requiring help and assistance for Tracker Software's PDF-XChange Printer Drivers SDK (only) - VERSION 4 & 5 - Please use the PDF-Tools SDK Forum for Library DLL assistance.

Moderators: TrackerSupp-Daniel, Tracker Support, Vasyl-Tracker Dev Team, Sean - Tracker, Chris - Tracker Supp, Tracker Supp-Stefan

Post Reply
David_Carle
User
Posts: 36
Joined: Fri Apr 20, 2012 2:43 pm

PDFX4DRV_API.pdf Documentation Woes

Post by David_Carle » Tue May 01, 2012 11:35 am

I have been reviewing the latest (?) PDFX4DRV_API.pdf documentation kindly supplied by Stefan in this post
http://www.tracker-software.com/forum3/ ... 43&t=13212
and noticed that it still seems to contain numerous mistakes.

Here are the mistakes and discrepancies that I'm aware of (but I've only been using the Watermark features and looking at the forums) ...

1. The internal links (that I tried) are incorrect, eg on Page 29 the hyperlinks for AddTextWatermark or
AddlmageWatermark don't link to a relevant place.

2. On Page 29, Section Watermarks, you will find this line of misleading gibberish:
"A comma to separate the list of watermark names should be added to the document."
I would suggest that this should be reworded, eg
"A semi-colon separated list of the watermark names that are to be added to the document"
This was reported in June 2010 in http://www.tracker-software.com/forum3/ ... =43&t=8274
but hasn't been corrected in nearly two years?

3. Within AddTextWatermark, nFontSize says "Font size is specified in tenths of a point (1 pt = 1/72 inch)"
In my experience, nFontSize is the actual font size eg 10 or 12
Can you clarify?

4. Also Within AddTextWatermark, dwOpacity "must be in the range of 0 (fully transparent) to 100 (fully opaque)"
However, various examples in the forum posts show values above 100
What is correct?

5. Still Within AddTextWatermark, the table for dwFlags is wrong. This was described in this post
http://www.tracker-software.com/forum3/ ... 43&t=13212

6. According to http://www.tracker-software.com/forum3/ ... 43&t=12221
there are 2 undocumented flags for AddImageWatermark. Will you include them in the manual?

7. According to http://www.tracker-software.com/forum3/ ... 887#p49552 from May 2011 there is a PDFPrinter.Option("DevMode.DPI") option, but this is not yet in the manual

8. In http://www.tracker-software.com/forum3/ ... =43&t=9349 from Nov 2010
it suggests that the property Perms40.AllowComment should be Perms40.AllowComments
If so the manual is still incorrect (Pg 24)

Minor Typo, In the C++ example for AddTextWatermark, dwAlign should probably be on a separate line

I also noticed that you have a method called AddBookmakrkItem. I realise that changing this would break existing code but would it not be a good idea to have a correctly named method AddBookmarkItem as well? I get nervous when I encounter sloppy code like this - if the programmer can't be bothered to correct a basic spelling mistake, what other shortcuts are they taking?

Hopefully you can check these points soon and release a new manual in the near future. If not, would you consider encouraging users to post any mistakes that they find so that all users can benefit.

I would also like to suggest that you make the documentation available for download separately, without having to download and install the exe (I would be reluctant to do that in case it broke my existing installation) and use some kind of published version number per manual (so that people know they're on the latest release).

I realise that updating documentation is not fun, but it must be better than dealing with potentially irate users who have wasted hours of their time due to incorrect documentation?

User avatar
Tracker Supp-Stefan
Site Admin
Posts: 13548
Joined: Mon Jan 12, 2009 8:07 am
Location: London
Contact:

Re: PDFX4DRV_API.pdf Documentation Woes

Post by Tracker Supp-Stefan » Tue May 01, 2012 12:53 pm

Thanks for the comments David,

Some of them are already being worked on and all will be reviewed.

Best,
Stefan

David_Carle
User
Posts: 36
Joined: Fri Apr 20, 2012 2:43 pm

Re: PDFX4DRV_API.pdf Documentation Woes

Post by David_Carle » Wed May 02, 2012 8:42 am

Just found another possible problem ...

In AddTextWatermark, page 43, in the table for dwAlign, bit 6 refers to bit 4, but bit 4 is not defined.

User avatar
Tracker Supp-Stefan
Site Admin
Posts: 13548
Joined: Mon Jan 12, 2009 8:07 am
Location: London
Contact:

Re: PDFX4DRV_API.pdf Documentation Woes

Post by Tracker Supp-Stefan » Wed May 02, 2012 10:31 am

Hi David,

Those were bits 4 (8) and 5(16) in the older version of the manual - and the "Meaning" text seems to have not been updated and refers to them as such .

Included in the list of things that need to be corrected.

Best,
Stefan

David_Carle
User
Posts: 36
Joined: Fri Apr 20, 2012 2:43 pm

Re: PDFX4DRV_API.pdf Documentation Woes

Post by David_Carle » Thu May 03, 2012 11:13 am

Hi Stefan

In the meantime, can you please give a response to points 3 and 4?

Thanks

User avatar
Tracker Supp-Stefan
Site Admin
Posts: 13548
Joined: Mon Jan 12, 2009 8:07 am
Location: London
Contact:

Re: PDFX4DRV_API.pdf Documentation Woes

Post by Tracker Supp-Stefan » Thu May 03, 2012 3:09 pm

Hi David,

For 3) - 1 point is 1/72 of an inch - and you can specify font sizes with a precision of a tenth of a point - e.g. 8.0 , 8.1 etc.

and for 4) - One of my colleagues confirmed it should be in the range 0...100.

Best,
Stefan

David_Carle
User
Posts: 36
Joined: Fri Apr 20, 2012 2:43 pm

Re: PDFX4DRV_API.pdf Documentation Woes

Post by David_Carle » Fri May 04, 2012 8:30 am

OK, Thanks. The way the font size is worded "Font size is specified in tenths of a point" made me think that 120 would be 12 point. Perhaps it could be reworded as "Font size is specified in points, with up to 1 decimal place eg 12 or 12.5"

User avatar
Tracker Supp-Stefan
Site Admin
Posts: 13548
Joined: Mon Jan 12, 2009 8:07 am
Location: London
Contact:

Re: PDFX4DRV_API.pdf Documentation Woes

Post by Tracker Supp-Stefan » Fri May 04, 2012 9:24 am

Thanks David,

yes this could definitely use a bit of a rewording.
I am thinking of something like this will be much clearer and straight forward to understand:
"Font sizes can be specified with a precision of one tenth of a point e.g. 8.2, 8.3 (1 pt = 1/72 inch)"

Best,
Stefan

David_Carle
User
Posts: 36
Joined: Fri Apr 20, 2012 2:43 pm

Re: PDFX4DRV_API.pdf Documentation Woes

Post by David_Carle » Fri May 04, 2012 9:55 am

Hi Stefan

Another confusing point (pardon the pun) is the FontSize in Section HeaderFooters.
This has a similar description "Specifies font size for the text. Font size is specified in tenth of point" but also states "Default value: 100"

Is the default really 100 point or is that another mistake?

Walter-Tracker Supp
User
Posts: 383
Joined: Mon Jun 13, 2011 5:10 pm

Re: PDFX4DRV_API.pdf Documentation Woes

Post by Walter-Tracker Supp » Fri May 04, 2012 7:02 pm

David_Carle wrote:Hi Stefan

Another confusing point (pardon the pun) is the FontSize in Section HeaderFooters.
This has a similar description "Specifies font size for the text. Font size is specified in tenth of point" but also states "Default value: 100"

Is the default really 100 point or is that another mistake?
If it is specified in tenths of a point, a value of 100 (tenths) would be 10.0 points.

-Walter

David_Carle
User
Posts: 36
Joined: Fri Apr 20, 2012 2:43 pm

Re: PDFX4DRV_API.pdf Documentation Woes

Post by David_Carle » Tue May 08, 2012 8:27 am

Hi Walter

The problem here is that there are 2 pieces of information required, but only one specified, and it's not clear which it is (and they seem to be used interchangeably, which is incorrect)

The information required is
a) Unit of Measure
b) Precision

The term "is specified in tenth of point" sounds like a unit of measure, which would tie in with your suggestion that 100 relates to 10 point. However, this differs from Stefan's comments earlier (and the results of my testing) which suggest that "is specified in tenth of point" means the precision eg 8.2 or 8.3

I would suggest that Tracker Software should review and correct the manual as a matter of urgency.

You have a great product, but your documentation (and the delays in updating it) is shockingly bad. Do you really care?

User avatar
Tracker Supp-Stefan
Site Admin
Posts: 13548
Joined: Mon Jan 12, 2009 8:07 am
Location: London
Contact:

Re: PDFX4DRV_API.pdf Documentation Woes

Post by Tracker Supp-Stefan » Tue May 08, 2012 12:01 pm

Hello David,

Yes - we do care! And will be fixing all things commented in this topic as soon as possible!

Cheers,
Stefan
Tracker

David_Carle
User
Posts: 36
Joined: Fri Apr 20, 2012 2:43 pm

Re: PDFX4DRV_API.pdf Documentation Woes

Post by David_Carle » Mon Jun 11, 2012 1:26 pm

Hello Stefan

Well, it's over a month now since your last comment (and over 2 years since item 2 was first reported).

Are we any closer to having accurate documentation?

If not, can you give a target date for this?

Regards, David

John - Tracker Supp
Site Admin
Posts: 8202
Joined: Tue Jun 29, 2004 10:34 am
Location: Vancouver Island - Canada
Contact:

Re: PDFX4DRV_API.pdf Documentation Woes

Post by John - Tracker Supp » Mon Jun 11, 2012 2:24 pm

Hi David,

We have not been idle I promise you - but have been busy both updating the product releases and the doc's - moving them online so that changes made can be reflected immeadiatley - please see here ;

http://help.tracker-software.com/develo ... tWatermark

I am not sure if this is corrected or explained better - but if you could advise - if not, now we can effect an immeadiate change to do so (e.g. withing 24 hours)

Thanks for your patience and understanding.
If posting files to this forum - you must archive the files to a ZIP, RAR or 7z file or they will not be uploaded - thank you.

Best regards
Tracker Support
http://www.tracker-software.com

David_Carle
User
Posts: 36
Joined: Fri Apr 20, 2012 2:43 pm

Re: PDFX4DRV_API.pdf Documentation Woes

Post by David_Carle » Mon Jun 11, 2012 3:14 pm

Hi John

I think that having searchable documentation with hyperlinks online is a great idea, but I personally think it should be available as a document as well.

Whatever format(s) you use, it has to be correct. I've just had a quick look at the online documentation, and it appears to be an exact copy of the previous documentation, with none of the above fixes applied?

Are you planning to apply the reported corrections in the near future?

Regards, David

John - Tracker Supp
Site Admin
Posts: 8202
Joined: Tue Jun 29, 2004 10:34 am
Location: Vancouver Island - Canada
Contact:

Re: PDFX4DRV_API.pdf Documentation Woes

Post by John - Tracker Supp » Mon Jun 11, 2012 3:25 pm

Hi David - I will ask that these be reveiwed asap and corrected in the next day or so.

Also - you can generate a PDF of the online Doc's yourself at anytime - see the 'Print/Export' option to the left in the links pane.

HTH
If posting files to this forum - you must archive the files to a ZIP, RAR or 7z file or they will not be uploaded - thank you.

Best regards
Tracker Support
http://www.tracker-software.com

David_Carle
User
Posts: 36
Joined: Fri Apr 20, 2012 2:43 pm

Re: PDFX4DRV_API.pdf Documentation Woes

Post by David_Carle » Mon Jun 11, 2012 3:52 pm

That's great. Let me know if you'd like me to review it.

Also, have you considered allowing public (or registered user) comments to be added to the developer wiki (similar to php.net)?

When you refer to the "Links pane" is this the one with links to Main Page, Community Portal, Current events, etc?
(because I don't see any option for 'Print/Export'. Am I looking in the wrong place?

John - Tracker Supp
Site Admin
Posts: 8202
Joined: Tue Jun 29, 2004 10:34 am
Location: Vancouver Island - Canada
Contact:

Re: PDFX4DRV_API.pdf Documentation Woes

Post by John - Tracker Supp » Mon Jun 11, 2012 9:02 pm

Hi David,

the doc's have been updated online and on checking the PDF creation was only available to our own staff - so the option to download has now been added here ;

http://help.tracker-software.com/develo ... ory:Driver

Below the logo and above the topic Index on the main page body.

cheers
If posting files to this forum - you must archive the files to a ZIP, RAR or 7z file or they will not be uploaded - thank you.

Best regards
Tracker Support
http://www.tracker-software.com

David_Carle
User
Posts: 36
Joined: Fri Apr 20, 2012 2:43 pm

Re: PDFX4DRV_API.pdf Documentation Woes

Post by David_Carle » Tue Jun 12, 2012 1:53 pm

Hi John

Thanks for that. I've had a look at the pdf that you linked to and it does seem that some of the mistakes have been corrected, but unfortunately many still remain.

Here are my findings ...

1. OK - The links that I tried seemed fine.
2. OK - Much better description for Watermarks.Watermarks
3. Method AddTextWatermark - nFontSize - Useful to add typical values such as 12 and 12.5
4. OK
5. Method AddTextWatermark - dFlags - STILL INCORRECT?
6. Additional flags not added
7. Still no mention of DevMode.DPI
8. OK - Perms40.AllowComments looks correct

Also,
FontSize is still misleading or incorrect. (See posts on 8th May)
The FontSize for HeadersFooters is described differently from AddTextWatermark. Surely that's not correct?
Page 25 including the examples suggests that 120 = 12 point, but for AddTextWatermark 12 = 12 point
I suspect that the entries on page 25 are wrong, but it would really benefit from a better explanation.


Bear in mind that all my comments are only based on the subset of methods that I actually used, so I would suggest that you have a developer proof-read the remainder of the documentation.

One thing I did wonder about is that some of your your lists (eg Fonts) use comma as separators while others (eg Watermarks) use semi colons while others (eg sRange) will accept either. Is this correct? (If so, it might be a useful enhancement to support either separator for all lists).

Finally, would you consider adding a Last Updated date and/or version to the documentation so that users know whether they are using the latest version?

Minor typo on page 3: "Creating arguable" should be "Creating arguably"

Regards, David

John - Tracker Supp
Site Admin
Posts: 8202
Joined: Tue Jun 29, 2004 10:34 am
Location: Vancouver Island - Canada
Contact:

Re: PDFX4DRV_API.pdf Documentation Woes

Post by John - Tracker Supp » Tue Jun 12, 2012 4:50 pm

Thanks David,

A colleague wil review over the coming days as time allows.
If posting files to this forum - you must archive the files to a ZIP, RAR or 7z file or they will not be uploaded - thank you.

Best regards
Tracker Support
http://www.tracker-software.com

Ivan - Tracker Software
Site Admin
Posts: 3609
Joined: Thu Jul 08, 2004 10:36 pm
Location: Vancouver Island - Canada
Contact:

Re: PDFX4DRV_API.pdf Documentation Woes

Post by Ivan - Tracker Software » Wed Jun 13, 2012 2:44 am

Thanks for your comments and help with making our documentation a bit better.

In regards of your notes:
3. Method AddTextWatermark - nFontSize - Useful to add typical values such as 12 and 12.5
I have changes the code in V5 and now the font size should be specified in tenth of points. V4 will not be changed as it may affect many developers. The online documentation is updated.
5. Method AddTextWatermark - dFlags - STILL INCORRECT?
No, it is absolutely correct.

Code: Select all

6. Additional flags not added
Not exactly. As these flags are used only by AddImageWatermark method, they are described in this function (http://help.tracker-software.com/develo ... eWatermark).
7. Still no mention of DevMode.DPI
Yes, this section not yet described. Description for DPI and other items from this section will be added a bit later.
One thing I did wonder about is that some of your your lists (eg Fonts) use comma as separators while others (eg Watermarks) use semi colons while others (eg sRange) will accept either. Is this correct? (If so, it might be a useful enhancement to support either separator for all lists).
Sometimes it is not so easy to use common separators for all lists and I see no benefits doing that.
Finally, would you consider adding a Last Updated date and/or version to the documentation so that users know whether they are using the latest version?
We will try to implement it. Thanks for the good idea.
Minor typo on page 3: "Creating arguable" should be "Creating arguably".
Corrected.
Tracker Software (Project Director)

When attaching files to any message - please ensure they are archived and posted as a .ZIP, .RAR or .7z format - or they will not be posted - thanks.

David_Carle
User
Posts: 36
Joined: Fri Apr 20, 2012 2:43 pm

Re: PDFX4DRV_API.pdf Documentation Woes

Post by David_Carle » Wed Jun 13, 2012 9:12 am

Hi Ivan

Thanks for your comments.

With regard to FontSize, I feel that the phrase "should be specified in tenth of points" is ambiguous. Does this mean that a value of 105 represents 10.5 point, or that the font size can include one decimal place eg 12.5 ?

Can you clarify this in the documentation, ideally with an example?

Secondly, unless you have changed the flags for version 5, I think that the AddTextWatermark table for dwFlags is still incorrect as it shows bit 1 (value 2) as background, but according to Walter's post on April 19 in http://www.tracker-software.com/forum3/ ... 43&t=13212 this should be bit 0 (value 1). Walter stated: "I just noticed there's an error in the documentation (flags offset by one)"

Regards, David

Nico - Tracker Supp
User
Posts: 220
Joined: Fri May 18, 2012 8:41 pm

Re: PDFX4DRV_API.pdf Documentation Woes

Post by Nico - Tracker Supp » Mon Jun 18, 2012 9:48 pm

Hi David,

Thank you for your feedback. Regarding your questions:
With regard to FontSize, I feel that the phrase "should be specified in tenth of points" is ambiguous. Does this mean that a value of 105 represents 10.5 point, or that the font size can include one decimal place eg 12.5 ?

Can you clarify this in the documentation, ideally with an example?
An example has been added to make it clear that 125 should be specified for a font size of 12.5 points. In other words, multiply by ten the desired font size for nFontSize parameter (http://help.tracker-software.com/develo ... tWatermark)
Secondly, unless you have changed the flags for version 5, I think that the AddTextWatermark table for dwFlags is still incorrect as it shows bit 1 (value 2) as background, but according to Walter's post on April 19 in viewtopic.php?f=43&t=13212 this should be bit 0 (value 1). Walter stated: "I just noticed there's an error in the documentation (flags offset by one)"

Bit 0 is not used in dwFlags. An entry for this bit has been added to the table at the wiki. To clarify our previous post, there isn't an offset by one in the flag bits values. Values on table are still correct. Bits start from bit 0. I.e.: to set the watermark as a background on the page, you should provide binary value '10' (decimal 2).

Thanks.

David_Carle
User
Posts: 36
Joined: Fri Apr 20, 2012 2:43 pm

Re: PDFX4DRV_API.pdf Documentation Woes

Post by David_Carle » Tue Jun 19, 2012 10:40 am

Hi Nico

Thanks for your response. The comment for FontSize makes it much clearer.

However, I'm still confused about dwFlags. Has this changed for version 5?

If not, it seems to contradict the post by Walter on April 19th which stated "Set flags to decimal 14 (binary 1110) to set all bits except background. The flags are binary 1 for placement in background, 10 for viewer, 100 for export visibility, and 1000 for printing visibility..."

The updated manual now suggests that it should be 28, not 14.

My code was written based on Walter's advice to use Flags of 14, but I need to know whether it was correct (but it does seem to work and print with this value, so perhaps it was correct for version 4?)

Your clarification would be appreciated.

Nico - Tracker Supp
User
Posts: 220
Joined: Fri May 18, 2012 8:41 pm

Re: PDFX4DRV_API.pdf Documentation Woes

Post by Nico - Tracker Supp » Tue Jun 19, 2012 4:51 pm

Hi David,

Confirmed, the only parameter for that function that has changed from version 4 to version 5 is nFontSize, dwFlags remains the same. Therefore, the value you should use is decimal 28 not decimal 14. In the documentation, the least significant bit is Bit 0 which is not used, and Bit 1 sets the watermark as a background or in the foreground on the page.

Post Reply