Hi Everyone,
Unfortunately it looks like the Spec documents we have received are missing a lot of important formatting. I just went through and fixed up the Servlet spec[1] and looking at other specs I see a lot of similar problems. The main issues are:
- All section headers are Level 2, so there are hundreds of chapters and the original structure is lost.
- All bulleted lists are missing
- All numbered lists are missing
- All tables are not rendered as tables
- All code examples are not rendered correctly
- All monospace names are italics
Fixing the Servlet spec mostly manually took a long time (and it is kinda boring), so I started wondering if maybe we could improve this a bit.
I came up with the idea that maybe we can extract some additional structure from the old spec PDF's, and as a proof of concept I came up with [2], and used it to fix the structure of the JPA spec so all the section numbers now line up with the original spec [3]. Basically I just copied the table of contents into a text file and used that to add the correct section depth.
I think we could expand this approach a bit, and attempt to also match up things like bullet points and numbered lists, and it could end up saving a lot of monotonous grunt work. Unfortunately I don't think we can fix everything this way, but it should be possible to fix some of the more common problems.
I don't have a lot of time to work on this, but I just thought I would put it out there because at the very least the section fixer script could save a lot of time.
Stuart
