helidon-io / helidon

Java libraries for writing microservices
https://helidon.io
Apache License 2.0
3.5k stars 565 forks source link

Trailing whitespace needs to be removed in Persistence Guide properties snippets #9350

Closed ljnelson closed 3 days ago

ljnelson commented 4 days ago

https://github.com/helidon-io/helidon/blob/ed6cf6544616ba44c264a3d4ab7053b8025a981c/docs/src/main/asciidoc/mp/persistence.adoc?plain=1#L437

Note the trailing space at the end of the line before the pound sign (#), which exists only for the Asciidoc callout. I am not sure if this whitespace can be removed while preserving the callout but I need to look to see if it can.

Without a fix, a user who copies text from the persistence guide's rendered output will get the trailing space as part of the copy, and then the UCP won't be able to load the supplied class, because there is whitespace as part of the name.

It is possible as well that something like String.trim() should be applied selectively, but that means that our data source integration stuff will now "know" about certain "special" properties that need to be trimmed (at the moment it is entirely and deliberately agnostic). Of course one could also argue that the UCP or the data source or the driver should do this and I'm sure a strong case could be made for or against any or all of this.

To start with I will see if I can somehow eliminate the trailing space from the documentation.

ljnelson commented 4 days ago

Not going to be zero-effort straightforward: https://docs.asciidoctor.org/asciidoc/latest/verbatim/callouts/#copy-and-paste-friendly-callouts

ljnelson commented 4 days ago

Hmm; we can do a callout like this, and there will be no trailing whitespace after, e.g., OracleDataSource:

javax.sql.DataSource.main.connectionFactoryClassName = oracle.jdbc.pool.OracleDataSource# <1>

but that results in the callout glyph getting smushed up against the end of the line:

Screenshot 2024-10-09 at 2 56 29 PM