Creating an AsciiDoc table with multiple AsciiDoc snippets

[ronaldtse]

Suppose we have this table:

[cols="a,a"]
|===
| Name | Description

| {file1.name} | {file1.content} 
| {file2.name} | {file2.content} 
| {file3.name} | {file3.content} 
...

|===

Each file{n} is a content like this:

[format=asciidoc]
= title

[lang=en]
== content
This is where English content goes.

// a comment

image::xyz.png[]

[lang=jp]
== content
ここから日本語のテキストが始まります

// a comment

image::xyz.png[]

Clearly, we cannot naively include the inner content in the cell because the result will become invalid AsciiDoc.

There are two options we can process this table:

1. Parse the inner file contents in Coradoc, and generate proper asciidoc that can be embedded properly in a table cell (which requires transformation)
2. Generate the entire table using Coradoc, so that the output is proper AsciiDoc.

The questions:

1. How should the first content access the individual table cell contents?
2. How should the table cell contents files be formatted in syntax?

[ReesePlews]

hi @ronaldtse thank you for initiating this discussion. i think i am following the logic here on your idea, but these are just my comments, so please provide feedback and correct my comments if they are wrong.

in the content ( file1.content ) of the file, i believe that some limitations need to be set on what asciidoc constructs can be used.

for example, do we want to allow a "table" within the cell? that would seem overly complex and not something regularly needed. i would say a table should not be allowed. the same goes with "headings" in a cell, we dont want those because it just does not make sense structurally, but i think we do want to support a cross-reference link to those "clauses/sub-clauses" in the same document. if we dont allow headers, then should we allow simple "bolding" of text to give the impression of a header? i am not sure, that would probably default back to how/if simple "bolding" is handled in metanorma.

i think the following "supported subset" of asciidoc constructs that must be available for embedding within a cell:

• code level comments
• single lines of text
• paragraphs of text
• ordered and unordered lists
• examples
• notes
• forumlae
• code block (formatting of some "source code" within the cell)
• character styling (at least bold and italics), possibly some others
• "background color" of the cell (related to "style") added 20240905
• embedding of figures (images) with support for an image title. (uncertain about support for image numbers or keys)
• cross references (links to other "things" in the same document - like a link to a different clause/sub-clause, a table, a figure, a modspec formatted provision, a bibliography reference, etc)

the following constructs should also be considered but may not be possible (meaning i am not certain of my understanding of their support currently in metanorma) to support

• asciidoc "include" such as pulling content from a common file (one managed file's contents used across multiple sections of a document using the "include" construct) - but the contents of that managed file must conform to the constructs in the "supported subset" list shown above.
• cross references (links to other "things" in another document - like a link to a different clause/sub-clause, a table, a figure, a modspec formatted provision, a bibliography reference, etc)

i look forward to continuing this discussion. thank you.

[ronaldtse]

Thank you @ReesePlews , this is indeed the correct approach, which is to limit the features available as a subset through a defined "profile", which is a definition created through the task:

• Create DSL framework for content rule checks #116

In a profile, we need to define the following:

• What elements are allowed
• What commands, like include are allowed
• Behavior of commands, such as cross-references, do they resolve to the outermost context? Or do they have to be contained?

Would like to have the opinion of @opoudjis @hmdne @webdev778 @xyz65535

[opoudjis]

I have had a long history in Metanorma of ruling out possibilities as absurd, only for some SDO or other to shove them in there, and for me to be told that I have to support it. In fact, that is issue metanorma/mn-samples-itu#159 : I declined to model blocks as containing other blocks, on the grounds that it is absurd to do so, and impossible to reference them coherently, only for it to turn out that SDOs routinely did so.

So:

for example, do we want to allow a "table" within the cell? that would seem overly complex and not something regularly needed. i would say a table should not be allowed.

metanorma/metanorma-standoc#790, from PDFA-ISO-32000

PDFA disagree with you, and tables within tables are on our to-do list.

I think any attempt to constrain content in tables is pointless. So long as the customer is always right, the customer will always find an exception they want represented in tables. For coradoc to prevent that is simply going to mean that coradoc will be called upon to unprevent it in a year later. The only content you can assume won't go into table cells is entire clauses, and I wouldn't even be too sure of that. (Bilingual documents, realising parallel columns as tables: that is in fact a sticking point in the current implementation.)

Recall that Asciidoctor initially assumed you would never put a footnote inside a table cell either, when they processed each cell as separate documents. Which is why we can't deduplicate table footnotes.

You certainly can't assume includes won't be invoked within table cells; if anything, implementing a master document model is one of the reasons you're reimplementing Asciidoctor from scratch, since that is one of its more obvious shortcomings.

If you want to implement these not as absolute blocks, but as SDO-specific profiles, you're pretty much outsourcing what Metanorma currently does in flavour-specific validation as XPath queries, into the document object model. You can do that, I suppose, but again, experience has shown that document authors and editors are indifferent to the style rules SDOs proclaim, and find our validation of them a nuisance.

Cross-references, if I understand the question, should resolve outermost. The chopping up of a document into tiny little included bits is an editorial artifice; readers read the whole thing as a single document, and they would I assume expect the references to act that way too. (That is of course the thinking behind Asciidoctor's document model, and its lack of master document processing.)

[ronaldtse]

Cross-references, if I understand the question, should resolve outermost. The chopping up of a document into tiny little included bits is an editorial artifice

Remember the embed command? The inner document needs to be self-sufficient as well in that case.

[opoudjis]

Cross-references, if I understand the question, should resolve outermost. The chopping up of a document into tiny little included bits is an editorial artifice

Remember the embed command? The inner document needs to be self-sufficient as well in that case.

Not that me pointing this out is going to matter, but there is a difference in how people deal with a table cell and an entire standard, which is the subject of embed.

The fact that you aren't seeing such a difference confirms that there is no point at all in constraining the contents of table cells, except as a validation exercise.

[ReesePlews]

thanks @ronaldtse and @opoudjis for the comments. there is a lot of deep asciidoc tech i am not familiar with. but i would think that without a set of guidelines, it would be too difficult to implement... but maybe it is implemented already and its just "putting that content" into the cell. i wont say much because i dont want to muddle up the discussion.

i will make an edit to my initial list above, that adding "background color" of the cell (related to "style") would be a helpful feature.