Re: [dita] Re: Use of relationship tables

[Michael Priestley <mfcpriestley@gmail.com>]

Iâd agree - well within expected usage, you can even set format and scope as defaults for the column if you wantÂ

On Thu, Dec 21, 2023 at 11:56âAM Eliot Kimber <eliot.kimber@servicenow.com> wrote:

Fundamentally a row in a relationship table does nothing more than relate a set of resources addressed via topicrefs to each other with some semantic imposed by the table.

Given that, I think you are free to impose whatever meaning you want to those relationships, including âpublication-to-supporting-artifactâ.

Â

If your publication is defined by map âroot-01.ditamapâ, you could do something like:

<map><title>Root One</title>

 â

 <mapref keys=âpublicationâ scope=âpeerâ keyscope=âroot-01â href="">  <reltableÂoutputclass="publication-to-supporting-artifact">

  <relheader>
 Â <relcolspec><topicmeta><navtitle>Publication</navtitle></topicmeta></relcolspec>
 Â Â<relcolspec><topicmeta><navtitle>Supporting Docs</navtitle></topicmeta></relcolspec>
 ÂÂ</relheader>

ÂÂÂ<relrow>

ÂÂÂÂÂ <relcell>

ÂÂÂÂÂÂ <topicref keyref=âroot-01.publicationâ>

ÂÂÂÂÂÂ ÂÂÂ<topicmeta><navtitle>Root One</navtitle></topicmeta>

ÂÂÂÂÂÂ </topicref>

ÂÂÂÂ </relcell>

ÂÂÂÂÂ <relcell>

ÂÂÂÂÂÂÂÂÂ <topicref scope=âexternalâ format=âpdfâ href="" href="https://example.com/docs/some-doc.pdf" target="_blank">https://example.com/docs/some-doc.pdf>

ÂÂÂÂÂÂÂÂÂÂÂÂÂ<topicmeta><navtitle>Some Doc</navtitle></topicmeta>

ÂÂÂÂÂÂÂÂÂ </topicref>

ÂÂÂÂÂ </relcell>

ÂÂ </relrow>

 </reltable>

</map>

Â

Here Iâm using a peer mapref with a @keys value to represent the publication as a whole, which I think is legit even though we donât explicitly describe this use of peer maprefs in the spec. But a peer mapref explicitly means âthe target map is a root mapâ, so I think being able to address the root map in this way is clear and meaningful.

Â

So this reltable relates the publication âroot-01â to the PDF document âsome-doc.pdfâ.

Â

It might make more sense for this reltable to be in a root map of its own that does nothing but define these relationships and then use that as input to your custom publication process.

Â

This whole use of reltables assumes that the set of supporting docs will be different over time or in different use contexts for the same publication.

Â

Cheers,

Â

E.

Â

_____________________________________________

Eliot Kimber

Sr Staff Content Engineer

O: 512 554 9368

M: 512 554 9368

servicenow.com

LinkedInÂ|ÂTwitterÂ|ÂYouTubeÂ|ÂFacebook

Â

From: dita@lists.oasis-open.org <dita@lists.oasis-open.org> on behalf of Kristen James Eberlein <kris@eberleinconsulting.com>
Date: Thursday, December 21, 2023 at 10:32âAM
To: DITA Technical Committee (dita@lists.oasis-open.org) <dita@lists.oasis-open.org>
Subject: [dita] FW: Use of relationship tables

[External Email]

Â

---

Hi, DITA TC colleagues.

Â

I am designing information architecture and markup for some Mayo content. Itâs a library of content called âAsk Mayo Expert,â and the targeted audience is clinicians. Some of the simplest content is about particular medical condition, for example, bipolar disorder. Here is a screen capture of how the content is currently presented:

Â

Hereâs an explanation of the areas that Iâve marked:

1. Navigation of the publication, easily handled with a DITA map that references topics such as âSymptoms (adult).â As a user clicks on different nodes in the navigation, what is displayed in the central pane changes â but the top navigation pane (include #2) does not change.
2. Links that are hand-curated by subject matter expert. The items grouped under âGuidelines & Resourcesâ tend to be links to external web sites, and the items grouped under âPatient Educationâ tend to be PDFs developed by Mayo patient education specialists for different branches of the clinical practice at Mayo. These links are applicable to ALL of the âBipolar disorderâ content.

Â

I, of course, immediately thought of expressing these relationships with a <reltable>. But when I looked through the spec, it was pretty clear that all our element-reference topics are written with focus on using relationship tables to define relationships between individual topics, rather than relationships between a publication and external links.

Â

A couple of questions:

• Are we being too old-school in how we define relationship tables in the spec?
• There will be custom processing (of course) for the Mayo DITA source, so from that perspective, I can broaden the usage of a relationship table. But I am urging that all Mayo transformations begin with using base DITA-OT transformations.
• Might I be better off with a specialized DITA map that had specific structures for âGuidelines & Resourceâ and âPatient Education,â rather than using a relationship table?

Â

Thoughts very much welcome.

Â

Kristen James Eberlein

Content Engineer | Health Education & Content Services | 507-293-0006 | eberlein.kristen@mayo.edu

My pronouns are she/her/hers.

Â