You are viewing a plain text version of this content. The canonical link for it is here.

Posted to dev@tomcat.apache.org by bu...@apache.org on 2020/11/18 19:05:16 UTC

[Bug 64931] New: Implement validation of changelog.xml file at build time

https://bz.apache.org/bugzilla/show_bug.cgi?id=64931

            Bug ID: 64931
           Summary: Implement validation of changelog.xml file at build
                    time
           Product: Tomcat 10
           Version: 10.0.0-M10
          Hardware: PC
            Status: NEW
          Severity: enhancement
          Priority: P2
         Component: Documentation
          Assignee: dev@tomcat.apache.org
          Reporter: knst.kolinko@gmail.com
  Target Milestone: ------

I have a fix for this that I will commit shortly. I am filing an issue to
better document the problem and design decisions.


The file "webapps/docs/changelog.xml" sometimes has structural errors. Those
errors are hard to spot. Thus it would be better to have an automated solution
to catch and report them at build time.

For example, in Apache Tomcat 10.0.0-M10 the file has two such errors: at lines
182 and 1550.

https://github.com/apache/tomcat/blob/10.0.0-M10/webapps/docs/changelog.xml#L181


There are the following possibilities to implement the check:

(1) With XSLT, in the tomcat-docs.xsl stylesheet.

It is possible, but it would be an odd choice.

- Reporting an error can be done in XSLT 1.0 with

  <xsl:message terminate = "yes">...</xsl:message>

More recent versions of XSLT specification support validation against an XML
Schema.

- Custom behaviour could be triggered by file name. The tomcat-docs.xsl
stylesheet declared a `<xsl:param name="filename"` parameter.


(2) With an XML Schema.

I tried this way, but failed.

- Validation against an XML Schema is triggered with Apache Ant Task
schemavalidate.

- Running a check against the changelog file with a simple schema fails shortly
with an error:

  Element type "document" must be declared.

- My investigation (running with `ant -verbose` and searching through source
code) found that this message is generated when performing a validation against
a DTD.

(MSG_ELEMENT_NOT_DECLARED, org.apache.xerces.impl.dtd.XMLDTDValidator, in
Apache Xerces 2.12.0)

- I tried running with `<schemavalidate disableDTD="true"`, but it does not
help, as it fails at a `<!DOCTYPE document` declaration at the top of
changelog.xml file.

- I did not found any other setting, any parser feature that could selectively
turn off validation against a DTD.


(3) With a DTD.

I went with this way, and it worked successfully.

Validation against a DTD can be performed with Apache Ant Task xmlvalidate.

- Notes:

1. I defined the DTD inline in the changelog.xml file itself.

It could be moved to an external file, but there is no actual need as I am not
going to validate other files.

2. Any XML element used in changelog.xml and project.xml files must be declared
in the DTD. Any its attributes must be declared as well.

(The project.xml file is included into the changelog as an external entity.)

Thus far the only HTML markup elements that are actually used in Tomcat 10
changelog are <code> and <a>, but we may want to add others in the future.

A useful Tutorial on DTDs:
https://www.w3schools.com/xml/xml_dtd_intro.asp

A simple generic way to declare an element is

 <!ELEMENT elementname ANY>

A simple generic way to declare an attribute of an element is

 <!ATTLIST elementname attributename CDATA #IMPLIED>

-- 
You are receiving this mail because:
You are the assignee for the bug.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org

[Bug 64931] Implement validation of changelog.xml file at build time

Posted by bu...@apache.org.

https://bz.apache.org/bugzilla/show_bug.cgi?id=64931

Konstantin Kolinko <kn...@gmail.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
         Resolution|---                         |FIXED
                 OS|                            |All
             Status|NEW                         |RESOLVED

--- Comment #1 from Konstantin Kolinko <kn...@gmail.com> ---
Fixed in
- Tomcat 10, will be in 10.0.0-M1.
https://github.com/apache/tomcat/commit/d0d773e9691e17251a065d7ca92b1339d8c826ab
https://github.com/apache/tomcat/commit/07607ca50a00e0224510b776023ad7b6a8d6f648
https://github.com/apache/tomcat/commit/b3806e44c52576d867e46d32cc1172f26720e13a
https://github.com/apache/tomcat/commit/3f3150f1a3f949a19f51e857c69e90ba2d362b82

- Tomcat 9, will be in 9.0.41.
https://github.com/apache/tomcat/commit/9c51dc6eff2b67a9c780ad546c99c21f887b0fe0
https://github.com/apache/tomcat/commit/694575d986e60d58b50310326281fe07683c9a0b

- Tomcat 8.5, will be in 8.5.61.
https://github.com/apache/tomcat/commit/4b42204df626ef282a7cdf7307ac6023c6845d72
https://github.com/apache/tomcat/commit/eae0bee4d1092551024ed5ea1f9241a19b96681d

- Tomcat 7, will be in 7.0.108.
https://github.com/apache/tomcat/commit/dd11be50426513f3eeafc1471de520dc833d76b4
https://github.com/apache/tomcat/commit/557c191239d931b1a2345c5cc9ad0fe73a48df56

-- 
You are receiving this mail because:
You are the assignee for the bug.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org