Page 1 of 1

PDFX4DRV_API.pdf Documentation Woes

Posted: Tue May 01, 2012 11:35 am
by David_Carle
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?

Re: PDFX4DRV_API.pdf Documentation Woes

Posted: Tue May 01, 2012 12:53 pm
by Tracker Supp-Stefan
Thanks for the comments David,

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

Best,
Stefan

Re: PDFX4DRV_API.pdf Documentation Woes

Posted: Wed May 02, 2012 8:42 am
by David_Carle
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.

Re: PDFX4DRV_API.pdf Documentation Woes

Posted: Wed May 02, 2012 10:31 am
by Tracker Supp-Stefan
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

Re: PDFX4DRV_API.pdf Documentation Woes

Posted: Thu May 03, 2012 11:13 am
by David_Carle
Hi Stefan

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

Thanks

Re: PDFX4DRV_API.pdf Documentation Woes

Posted: Thu May 03, 2012 3:09 pm
by Tracker Supp-Stefan
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

Re: PDFX4DRV_API.pdf Documentation Woes

Posted: Fri May 04, 2012 8:30 am
by David_Carle
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"

Re: PDFX4DRV_API.pdf Documentation Woes

Posted: Fri May 04, 2012 9:24 am
by Tracker Supp-Stefan
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

Re: PDFX4DRV_API.pdf Documentation Woes

Posted: Fri May 04, 2012 9:55 am
by David_Carle
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?

Re: PDFX4DRV_API.pdf Documentation Woes

Posted: Fri May 04, 2012 7:02 pm
by Walter-Tracker Supp
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

Re: PDFX4DRV_API.pdf Documentation Woes

Posted: Tue May 08, 2012 8:27 am
by David_Carle
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?

Re: PDFX4DRV_API.pdf Documentation Woes

Posted: Tue May 08, 2012 12:01 pm
by Tracker Supp-Stefan
Hello David,

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

Cheers,
Stefan
Tracker

Re: PDFX4DRV_API.pdf Documentation Woes

Posted: Mon Jun 11, 2012 1:26 pm
by David_Carle
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

Re: PDFX4DRV_API.pdf Documentation Woes

Posted: Mon Jun 11, 2012 2:24 pm
by John - Tracker Supp
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.

Re: PDFX4DRV_API.pdf Documentation Woes

Posted: Mon Jun 11, 2012 3:14 pm
by David_Carle
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

Re: PDFX4DRV_API.pdf Documentation Woes

Posted: Mon Jun 11, 2012 3:25 pm
by John - Tracker Supp
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

Re: PDFX4DRV_API.pdf Documentation Woes

Posted: Mon Jun 11, 2012 3:52 pm
by David_Carle
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?

Re: PDFX4DRV_API.pdf Documentation Woes

Posted: Mon Jun 11, 2012 9:02 pm
by John - Tracker Supp
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

Re: PDFX4DRV_API.pdf Documentation Woes

Posted: Tue Jun 12, 2012 1:53 pm
by David_Carle
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

Re: PDFX4DRV_API.pdf Documentation Woes

Posted: Tue Jun 12, 2012 4:50 pm
by John - Tracker Supp
Thanks David,

A colleague wil review over the coming days as time allows.

Re: PDFX4DRV_API.pdf Documentation Woes

Posted: Wed Jun 13, 2012 2:44 am
by Ivan - Tracker Software
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.

Re: PDFX4DRV_API.pdf Documentation Woes

Posted: Wed Jun 13, 2012 9:12 am
by David_Carle
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

Re: PDFX4DRV_API.pdf Documentation Woes

Posted: Mon Jun 18, 2012 9:48 pm
by Nico - Tracker Supp
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.

Re: PDFX4DRV_API.pdf Documentation Woes

Posted: Tue Jun 19, 2012 10:40 am
by David_Carle
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.

Re: PDFX4DRV_API.pdf Documentation Woes

Posted: Tue Jun 19, 2012 4:51 pm
by Nico - Tracker Supp
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.