Proposal to (formally) allow \cat outside footnotes and sidebars

[davidg-sil]

USFM3.0 includes \cat category\cat* for applying special formatting to (extended) footnotes and entire side bars.

I would like to suggest that this is overly restrictive.

In order to differentiate the formatting between, say, the table of contents and some other front-matter tables, PTXprint has (already) extended its application to tables thus:

\tr \cat toc\cat* \tc1 Genesis  \tc2 Gen \tc3 1
\tr \tc1 Exodus \tc2 Exod \tc3 23

We also allow applying \cat to a single paragraph, where there may be some special, distinct purpose for the text, but a full side-bar would be overkill:

\ip A note from the translation team:
\ipi \cat motivation\cat*  We have translated this text not for our own glory or for Earthly riches,
but for the glory of God, taking great care to respect the original text and our own language, 
testing and revising the text many times.  We pray earnestly that our work brings you 
encouragement in your personal daily walk with our saviour, Jesus Christ, and that the Holy 
Spirit uses it to teach you salvation and wisdom. But despite our care, this remains the work 
of (many) human hands; if you find what seems to be a mistake, please do get in contact.

Similarly, it seems to me that there are different contexts for lists, even those enumerating a total, and what is appropriate formatting for the census in Numbers 1 might not be appropriate for contributions to the temple and so on.

I would therefore suggest that the standard also allow \cat ... \cat* to be applied:

• To an individual paragraph or section heading (scope: that paragraph/heading)
• To a table (scope: from the entire table, until non-table paragraph)
• To a list (scope: the entire list, until non-list paragraph)
• To all note types

For each of these, I would suggest that the \cat ... \cat* should appear before any content, immediately after the (first) \p, \tr, \lh or \li as applicable.
(I would not suggest permitting this use inside a sidebar, on the basis that sidebars are complicated enough!)

[KentSpiel]

I think this would be a good for certain use cases. For example it would be a good way to implement NIV 1984 formatting where there are several different list styles. These have been harmonized in the latest NIV.
Questions

• Is \cat category\cat* always implemented as an attr in USX: cat='category' ? I assume so.
• What are the restrictions on category? I would suggest
  • a category consists of alpha numeric characters (\w) plus hyphen and underscore
  • multiple categories separated by spaces are allowed
  • leading and following spaces are not significant and should be deleted in normalized text
• Is a category applied to an entire table or a list that follows? No, the attribute is only applied to the element it immediately follows. Since there is no marked container that corresponds to these structures, it is not feasible to specify here how to calculate and extended the scope of a category to a list or table. That said some some applications may apply some formatting based the category to all similar elements that follow such as the PTXPrint application to tables mentioned above. However, this is an implementation specification not a USFM/USX specification.
• Can category be applied to blank lines (\b \ib)? I would say yes.

Note: One would apply a category to character markup or milestones using word level attributes \zli-s| cat="genealogy"\*

[KentSpiel]

Proposal for a Categories Module

Categories

USFM 3.1 provides a generalized way of adding a category attribute to many paragraph markers. Translation editing and publishing software may format text based on these these categories, for example, to differentiate the formatting between the table of contents and some other front-matter tables.

Categories were originally introduced in USFM 2.1 to support Study Bible publishing to allow a set of study Bible content categories to be defined and inserted into

• Sidebars (\esb)
• Extended Footnotes (\ef)
• Extended endnotes (\efe)
• Extended Cross References (\ex)

The current USFM 3.0 implementation allows their use in all note types

• Footnotes (\f)
• Endnotes, (\fe)
• Cross References) (\x)

USFM 3.1 extends their use to all paragraph styles that fall under these classifications:

• Introductions
• Titles, Headings, and Labels
• Paragraphs
• Poetry
• Lists
• Tables (\tr)

General Syntax

The category attribute takes the form of \cat category\cat* Category content should only include alpha numeric characters and the hyphen and underscore characters. More than one category may be specified separated by spaces.

A category attribute may be added to any of the above types. For note type markers the category field immediately follows the caller specification:

\f + \cat ba st ex\cat*\fr 5:1 \ft Другие варианты в разных рукописях: \fqa гергесинцев\ft /\fqa герасинцев.\f*

For paragraph type markers the category field immediately follows the marker:

\ip A note from the translation team:
\ipi \cat motivation\cat* We have translated this text not for our own glory or for Earthly riches, but for the glory of God, taking great care to respect the original text ...

[jwickberg]

I don't have any problem with this proposal except that I think it would need to be for version 3.2.

I believe this would take a significant effort to implement in Paratext and USFM 3.1 is supposed to only have minimal changes that are related to formulizing the specifications.

[mhosken]

Agreed for 3.2

[mhosken]

How do we add \cat to a table in USFM given there is no overall table structural marker? Likewise for lists?

[davidg-sil]

Not sure I understand the question. currently in ptxprint we specify it after the table row marker.
I notice that at present, (in ptxprint) it seems \cat can be changed from one row to the next, i.e. it's behaving as a row property that automatically overflows onto the next row.

I would suggest that there be a decision made, whether the final value is the one that affects the table as a whole, or if it is preferable to make it the first one.

\tr\cat fee\cat*\thc1-2 A title for the table which should span columns 1--2
\tr\tc1  Shephathiah \tcr2 372 
\tr\cat fie\cat*\tc1  Uzz son of Bildad the Shuhite \tcr2 72
\tr\cat fo\cat*\tc1 \v 4 Hepphathiah \tcr2 272
\tr\tc1 \v 4 Thomas \tcr2 273
\tr\cat fum\cat*\tc1 \v 4 Og \tcr2 27

Unless there's a plan to introduce a specific end-of-table marker, I'd assume that the current category will be continued until the implicit end-of-table that is triggered by encountering a non-table paragraph marker.

For lists, I'd assume a similar pattern, of the first list marker defining the category, with the category ending at the first non-list paragraph marker.

[mhosken]

The natural place in USX would be:

<table><char style="cat">fee</char>
    <tr>...
</table>

But the USFM of \tr\cat fee\cat* would translate to

<table><tr><char  style="cat">fee</char>
...
</table>

So I wonder which way we want to jump on this.

One advantage of cat in the row is that then people could style their rows (e.g. coloured backgrounds) differently from each other. But is that overkill for what is needed?

[KentSpiel]

I would allow \cat in both places, so people can apply a table style or a row style. If you only want only one then I would go with the row. If you wanted a table style you could just apply the style to every row in the table, or your business rules could say the style on the first row is a table style and all other rows are row styles.

[davidg-sil]

I hope Martin's just had a brain glitch... If not, can I point out that \cat isn't a character style, but a layer of styling? If Martin's right about the mapping, then I think it'd be far better, from a usx point of view, if it were:

<table cat="fee">
   <tr>...
</table>

Or

<table>
   <tr  cat="fee">...
</table>

Although I guess you might want to make it its own node type, which would (possibly) simplify the application of multiple cats to one table...

<table>
  <cat style="fee">
    <tr> ...</tr>
    <tr>.... </tr>
 </cat><cat style="fie">
    <tr>... </tr>
 </cat>
</table>