BITS-enabled JATS reader

[kamoe]

Proposal for development of new BITS reader by expanding the JATS reader.

[kamoe]

@jgm I have updated this PR with all unit tests I needed. They all pass, and all other existing checks pass. Below is the scope of the enhancement to make the JATS reader capable to processing BITS documents:

<title>: two new relevant attributes, @display-as which indicates the Header level at which to display a title; and @suppress, which indicates whether the title should be shown in the document.

<book> and <book-part-wrapper>: the two possible top-level elements of books. These simply set the jatsBook variable to True, then cascade execution to children.

<book-title> and <book-title-group>: These define the structure for <title> elements for books. I created a new getBookTitle function, invoked from parseMeta if document is a book, and renamed getTitle to getArticleTitle, for clarity.

<book-meta>: metadata element for books. Processed via parseMeta, which also invokes a new function called getBookAuthors, if document is a book. Renamed getAuthors to getArticleAuthors, for clarity.

<dedication>, <foreword>, <preface>: Named book sections with assumed titles. Processed via parseBlockWithHeader.

<legend>: New element with title, essential for figures and tables. Processed via parseBlockWithHeader

Index and TOC content elements: book-specific elements, with a title. Processed via parseBlockWithHeader.

Index and TOC title group elements: contain the title for its parent element. Their behaviour is incorporated into wrapWithHeader, therefore, empty output to avoid duplication.

wrapWithHeader: Rewritten to accommodate the new title attributes, named book sections, and index and TOC elements.

The relevant checks have been put in place for <title> and parseMeta when it is necessary to make the distinction between the document as an article, and as a book. Otherwise, given most of the above elements are specific to books, the reader will not have to deal with them if processing an article.

Let me know what you think.

[jgm]

Looks good! I noted one test that doesn't seem right, unless I'm missing something.

[jgm]

Is this what you intended? Shouldn't this test be run with -s so we get the metadata?

[kamoe]

Of course. Just added this, plus a few additional tests for metadata in both book and book-part-wrapper cases. Thanks for pointing out!

[kamoe]

Also separate tests from when we just want to see content, not metadata.

[jgm]

It would be nice to use localized (translated) versions of these names rather than the English.
However, we don't currently have localizations for these, so this will have to wait.

[kamoe]

Good point. The rationale is that, if there are non-English language named sections, then these will probably have a <title>, captured in the case just above. But might still be something to consider in the future.

[jgm]

Thanks for the changes. I thought of a couple other things, regarding the tests.
First, it's not ideal to have a test called book-meta.md (for example); better to add a bits- prefix to all these named tests so we can more easily see what they concern.
Second, if you can reduce the amount of text in these tests, it will reduce the size of the test files (and hence the release tarball).

[kamoe]

How about these?

[jgm]

Perfect!

[jgm]

Questions:

• should we add something to the manual describing BITS support?
• should we allow -f bits (I guess it would just act like -f jats?) Or is BITS considered a dialect of JATS so that -f jats would still be appropriate?

[kamoe]

Uhm, I would say yes, and yes.

BITS it's a very similar but officially different schema, so I think it is appropriate to treat as a separate format, with -bits.

Do you need any particular help wrt wording any docs?

[jgm]

Would -f bits behave any differently from -f jats? Or would it essentially be a synonym? My understanding is that there is no special "setting" for the reader that is needed to parse BITS.

[kamoe]

It would be a complete synonym. No setting needed. It's the top or root element that tells the reader whether it's a jats or bits document.

[jgm]

Great, I'll merge this and add the synonym and manual bits myself.

[kamoe]

Wonderful. I think it would be consistent to add "← BITS" below the XML formats supported in the main page.

[jgm]

Will do