While the integration of all specs to https://jakarta.ee/specifications/ is already very good and in the general the generated HTML & PDF specs are quite familiar there are some differences that should be refactored for the next version:
One point is how java classes and keywords are formatted in the text. The following image shows how classes are formatted in the Java Bean Validation Spec and in the JPA Spec:
Next to this some specs contain images (normally JPG or PNG). Whenever you need to change something is such image the complete image needs to be recreated. Next to this some of the images are not available in a high quality while the complete content of the images (mostly diagrams) could easily be defined as a vector based graphic (like SVG). I assume the HTML / PDF generator support SVG without any problem. https://www.diagrams.net allows to create (technical) diagrams and graphics in a modern web tool. Next to exporting such images as PNG or SVG the basic source file can be saved as an XML and easily committed to the spec repos. By doing so the file can easily be modified (see https://github.com/eclipse-ee4j/servlet-api/pull/348 as an example).
I assume that that we can find more differences between the specs and can improve them in some other points. Maybe it would make sense to collect all this points and do a general review of all the specs once we have a list. @ivargrimstad who would be a good contact to discuss such topics?
While the integration of all specs to https://jakarta.ee/specifications/ is already very good and in the general the generated HTML & PDF specs are quite familiar there are some differences that should be refactored for the next version:
One point is how java classes and keywords are formatted in the text. The following image shows how classes are formatted in the Java Bean Validation Spec and in the JPA Spec:
Next to this some specs contain images (normally JPG or PNG). Whenever you need to change something is such image the complete image needs to be recreated. Next to this some of the images are not available in a high quality while the complete content of the images (mostly diagrams) could easily be defined as a vector based graphic (like SVG). I assume the HTML / PDF generator support SVG without any problem. https://www.diagrams.net allows to create (technical) diagrams and graphics in a modern web tool. Next to exporting such images as PNG or SVG the basic source file can be saved as an XML and easily committed to the spec repos. By doing so the file can easily be modified (see https://github.com/eclipse-ee4j/servlet-api/pull/348 as an example).
I assume that that we can find more differences between the specs and can improve them in some other points. Maybe it would make sense to collect all this points and do a general review of all the specs once we have a list. @ivargrimstad who would be a good contact to discuss such topics?
The issue was originally created in the here: https://github.com/eclipse-ee4j/ee4j/issues/69