Wrapping multi-level elements (Conversion Table)

Report · May 27, 2021

In our unstructured documents, we have multi-level headings, up to 6 levels deep. We are moving to structured documents. Each Heading element is wrapped in its own section, so a Section can consist of a Heading (followed by other elements), followed by another (sub-)Section, etc.

An oddity we have is that, in our unstructured documents, the heading levels are not sequencial and can be followed by any heading of a lower level, i.e Heading Level 1 can be followed by a Heading level 3.

When coverting to a structured document, we need to retain this structure. In our Conversion Table we have rules that successfully wrap the headings in the appropriate, cascasing, sections.

This only works if the respective elements are present. If any of the heading levels are missing, the structure is incorrect. I.e. if, in our unstructure document, we have Heading lvl 1 following by Heading lvl 3, in the structured document, both are wrapped in a Level 1 Section, instead of the Level 3 Section being wrapped in an (empty) Level 2 Section, the (empty) Level 2 Section in turn wrapped in the Level 1 Section.

Is there a way to achieve this without adding the missing Heading levels in our unstructured document?

Report · May 28, 2021

Hi Quintin,

What you describe seems to me like a bit of a paradox. If there is explicit structural hierarchy where one section is subordinate to another, then Level 1 section must always own level 2, level 2 must always own level 3, and so on. And this follows any normal convention for implicit document structure, so I don't think you'll find any easy way for a conversion table to do it. Once in structured FM, though, you could just use the normal hierarchy rules and wrap some sections in extra ancestor Section elements.

But in all of that, I don't understand the purpose of this at all. Somehow, I struggle to believe that you really have level 3 sections under level 1 sections. That would be like parents giving birth to grandchildren... just doesn't really follow any conventional logic. I suspect this is more about formatting specifics... that your level 3 sections are owned by the level 1 parents, but just in some cases you want the heading 3 instead of heading 2. What value is there to that? Heading formats are specifically for the human eye, to let the reader navigate a document effectively. Maybe if you could describe the purpose of this, somebody could speak to it better.

Hope this helps,

Russ

Report · May 28, 2021

Quintin,

If first-level sections can contain both 2nd-level and 3rd-level subsections, can the two levels of subsection occur in any order?

You'll need to indicate the level of each Section. Since you can't do so by counting the number of containing Sections, you'll need to do something like one of the following:

1. Use different element names for Sections at different levels. For example:

Define Section4 to be Heading, (Paragraph | List | Table | Figure)*, (Section5 | Section6)*

Define Section5 to be Heading, (Paragraph | List | Table | Figure)*, Section6*

Define Section6 to be Heading, (Paragraph | List | Table | Figure)*

2. Use an attribute to identify the levels. For example, give Section an attribute named Level. Set this attribute to 1 for highest-level sections, to 2 for second-level, and so forth. This approach allows a higher level Section within a lower level, so that you could put, say, a level-1 section within a level-4.

3. Require all levels, but allow a Section to contain only subsections. Suppose, for instance you want to put a level-3 section within a level-1 section. Create the following hierarchy:

Section

Heading

Section

Heading

Notice that this example has three Section elements but only two Headings. The second-level Section is not visible, but preserves the count of levels.

--Lynne

Report · May 30, 2021

Lynne, the Sections still need to be in sequencial order, i.e. a Section can't contain a Section of higher level. Your third option is what we'll be doing once we start using structured FM. Our easiest option might be to add the missing Headings in our unstructured document and deal with them in the post-structured clean-up.

Report · May 30, 2021

Russ, it's one of those odd guidelines my predecessor put in place whereby screen labels/fields (our documents are software manuals) are always a specific heading, regardless of any preceding heading level. It does keep the aesthetics of our manuals consistentent.

Report · May 30, 2021

Quintin,

What about creating a new element called something like ScreenLabelsAndFields which like a table or figure can occur in a Section? ScreenLabelsAndFields may start with a Heading that is always formatted the same way regardless of its position in the Section hierarchy? That way, you preserve the division of Sections into subsections and also the unique nature of the way you document screen labels and fields. (A slight variation is to have one element called ScreenLabels and another called Fields.)

--Lynne

Report · May 30, 2021

Lynne,

I'd rather not do that as this element would be a section itself, having child elements consisting of itself and/or normal Section elements.

I think we'll just deal with this as part of the post-conversion clean-up.