Convert the specification to asciidoc

Description

Besides the conversion of the content, there is an integration to be considered for the purpose of verification of having tests in the TCK to cover it all.

As explained informally by Gunnar:

as you know there is a TCK
and there is a "TCK coverage report" which gives us an indication of which parts from the spec are covered in the TCK
"covered" here means there is at least one test method in the TCK which has an annotation such as @SpecSection(1.2.3)
(so if the test itself is bogus, this doesnt help of course)
in addition there is an XML file which contains all the TCK-relevant sections/phrases from the spec
that TCK coverage report generator then takes that XML and checks how many of its contents are reflected in @SpecAssertion annotations in the TCK
and that XML file in turn is generated from the spec DocBook itself - which is why i bring that up
so there is an XSLT sheet which takes specific docbook parts and copies them into that XML file for the TCK report
for that purpose, we used the docbook feature of "roles" to mark specific phrases as "tck-relevant"
so we'd need a similar mechanism for asciidoc,
that all "relevant" spec statements are covered by the TCK
iirc we also had a rendering mode where the rendered doc html highlighted the phrases marked as tck relevant
just some CSS i suppose
that way you could skim over the spec and see whether it lacked any TCK phrases for relevant parts
in a first step I'd check what's the equivalent of "roles" in asciidoc and how we can extract that information to create the TCK file
the actual reporting will not change
it's just the first part of the pipeline I am talking about here
extraction of marked phrases from the spec into that XML file; from there it should continue to work as is
BTW. another issue with the tool used by hardy for docbook -> asciidoc conversion was that it lost markup such as classname, methodname etc.
would be interesting to see whether we can retain these for the BV spec

Environment

None

Activity

Show:
Emmanuel Bernard
February 12, 2016, 7:09 PM
Emmanuel Bernard
February 12, 2016, 2:40 PM

I've added as a potential follow up

Emmanuel Bernard
February 12, 2016, 2:39 PM

About the file names, we should have bean-validation-specification.pdf and index.html

What to name the initial file, I don't care much: master.adoc, index.adoc, bean-validation-specification.adoc are all fine by me.

Emmanuel Bernard
February 12, 2016, 2:37 PM

About the book-docinfo.xml, I'd like the Spec to mention:

  • the version number (e.g. 1.1 final)

  • the publication date

  • the copyright of Red Hat

  • The author as Bean Validation Expert Group and Emmanuel Bernard

These might not all be metadata that asciidoctor support but we could have a first section of sort with that if necessary, maybe add the version in the title.

Sanne Grinovero
February 11, 2016, 1:23 PM

Good job!

Thanks, I needed that as I was feeling very bad about the time it took. Many dead ending roads, and yet not all goals hit.

do you make use of book-docinfo.xml in the rendering?

No. You mentioned it was missing some time ago so I added it, but I forgot to ask you about its purpose.

should we do foo.asciidoc or foo.adoc?

Now that sounds like something I might be able to do without hitting too many traps I'll change it. Let me know also about the final document name.. it's called "master" now which I like from a point of view of the guy editing the sources as it easily identifies the main entry point, but it seems the outputs get the same name.. I have the impression I can override that by actually renaming the artifact in ANT.

Fixed

Assignee

Sanne Grinovero

Reporter

Sanne Grinovero

Labels