Feature Documentation

[rmartinbops]

Hello, I'm coming from the Python wrapper (treepoem), and I was reviewing the features that treepoem supports and comparing them with the official documentation. I found a few minor inconsistencies, so I came here to ask about them:

There's the "industrial2of5" encoder, which doesn't appear directly in the documentation. The closest thing is code2of5, which generates this encoder by default, since the other options were deprecated by specific constructors. I wanted to know if the "industrial2of5" encoder has been deprecated, and if not, simply to point out that it's not mentioned in the documentation.

There's also the "rectangularmicroqrcode" encoder, which in #110 is indicated as having preliminary support, but there's no documentation mentioning it. If it's not present due to its non-final state, I think a section mentioning it but indicating its experimental status would be helpful.

The "jabcode" encoder, as I saw in #96 , has already been discarded because it's apparently not feasible in a PostScript environment. In that case, should it be ruled out as a valid generation option? Or is BWIPP capable of generating it, but considering its drawbacks?

I've only been reviewing the documentation for a couple of days, but are there any other features similar to the rectangular micro QR code that BWIPP can generate but aren't mentioned in the documentation?

[terryburton]

There's the "industrial2of5" encoder, which doesn't appear directly in the documentation. The closest thing is code2of5, which generates this encoder by default, since the other options were deprecated by specific constructors. I wanted to know if the "industrial2of5" encoder has been deprecated, and if not, simply to point out that it's not mentioned in the documentation.

Industrial 2 of 5 is a synonym for "standard" Code 2 of 5, i.e. what most people think of as 2 of 5 rather than some industry variant such as IATA.

I think there's enough references to that in the documentation, but l welcome any suggest for where to put additional references.

There's also the "rectangularmicroqrcode" encoder, which in #110 is indicated as having preliminary support, but there's no documentation mentioning it. If it's not present due to its non-final state, I think a section mentioning it but indicating its experimental status would be helpful.

It's actually final. The standard wasn't complete at the time that the encoder was written and it was expected that there may have been additional changes required when in fact there was not.

It needs documenting. I've created issue #297 for this.

The "jabcode" encoder, as I saw in #96 , has already been discarded because it's apparently not feasible in a PostScript environment. In that case, should it be ruled out as a valid generation option? Or is BWIPP capable of generating it, but considering its drawbacks?

The code in BWIPP is based on the original specification. The reference code that accompanied the standard never in fact matched the standard, and therefore there was never any real compatibility.

The in-feasibility is due to the excessive runtime cost of symbol generation due to the ECC algorithm requiring upwards of 100,000,000 iterations.

Alternative (more practical) error correction schemes were discussed during the International Standardisation process, but where not implemented. Instead, other significant changes were made. Since this encoder could only ever be "academic" for BWIPP I have not made any effort to realign with those changes.

So notionally BWIPP aligns with the original standard from a German national body (BSI) and not the ISO standard. But since that standard has been withdrawn and there was never a compatible reference implementation, the BWIPP code does nothing useful.

(The implementation did find a number of significant issues with the DIN standard, most of which were addressed in the ISO standard. So the effort wasn't for nothing. But most users cannot benefit from the existence of the BWIPP implementation.)

[terryburton]

It's actually final. The standard wasn't complete at the time that the encoder was written and it was expected that there may have been additional changes required when in fact there was not.

It needs documenting. I've created issue #297 for this.

Done: https://github.com/bwipp/postscriptbarcode/wiki/Rectangular-Micro-QR-Code

[rmartinbops]

I think there's enough references to that in the documentation, but l welcome any suggest for where to put additional references.

Yes, you're right about that, it's well documented in that part, but my question was more about the "keyword" to tell bwipp which code to generate. I know this project is separate from Treepoem, but in this project, "industrial2of5" and "code2of5" appear as keyword options, and after reading the documentation, they're the same thing. That's why I wanted to know if bwipp generates the requested code using either of these two, or if "industrial2of5" isn't a valid keyword.

So notionally BWIPP aligns with the original standard from a German national body (BSI) and not the ISO standard. But since that standard has been withdrawn and there was never a compatible reference implementation, the BWIPP code does nothing useful.

(The implementation did find a number of significant issues with the DIN standard, most of which were addressed in the ISO standard. So the effort wasn't for nothing. But most users cannot benefit from the existence of the BWIPP implementation.)

It was progress with a certain level of usefulness, which was good, but because of that case, I suppose I'll set up a pull request on Treepoem to rule out that option, since it has no real use at the moment.