You are absolutely right. I was exploring interactively in Oxygen to see what elements I could add, but it turns out that I had disallowed the <desc> element in my grammar so I didnât see it as an option. Iâve updated my FrameMaker-to-DITA
conversion script to preserve our descriptive text in <desc> elements.
Thank you!! Iâll try to RTFM next time.
From: Robert D Anderson <robander@us.ibm.com>
Sent: Tuesday, June 18, 2019 1:34 PM
To: Chris Papademetrious <chrispy@synopsys.com>
Cc: 'dita-comment@lists.oasis-open.org' <dita-comment@lists.oasis-open.org>
Subject: Re: [dita-comment] RE: noting a few limitations in my FrameMaker-to-DITA migration effort
Hi Chris,
If I am understanding the request correctly, I think this is possible with the <desc> element today. That is really the purpose of the <desc> element in a link context, to provide advance disclosure of what a reader will find
by clicking on the link.
In most implementations I've worked with, <desc> is automatically populated with the short description of a linked DITA topic. It can also be specified manually for cases where it can't automatically be retrieved / where the target
isn't DITA, or if something other than the topic's short description is desired.
How that <desc> content gets displayed will vary, but that's up to the processor; the sample below looks like a reasonable display to me. Depending on the output format and context, I've worked with styles that display the description
after the link, below the link, or as hover-help for the link.
Robert D. Anderson
DITA-OT
lead and Co-editor DITA 1.3 specification
Marketing Services Center
|
Chris
Papademetrious ---06/17/2019 04:05:52 PM---I've gotten requests from my writers for the following: *****
From: Chris Papademetrious <Christopher.Papademetrious@synopsys.com>
To: "'dita-comment@lists.oasis-open.org'" <dita-comment@lists.oasis-open.org>
Date: 06/17/2019 04:05 PM
Subject: [EXTERNAL] [dita-comment] RE: noting a few limitations in my FrameMaker-to-DITA migration effort
Iâve gotten requests from my writers for the following:
*****
Item 4: Please allow descriptive text in <related-links> entries.
Our existing FrameMaker documentation allows for text after links to describe why the reader might want to visit that link. For example,
See Also
Â
Multiple Test Mode Examples for more detailed examples
 Physical Layout Challenges for additional considerations when using this feature
Note that this descriptive text should contain only information that is *not* obvious from the link text already shown; it should set the readerâs expectation for what value the reader will findâor look for and take note of--when visiting that link.
From: Chris Papademetrious <Christopher.Papademetrious@synopsys.com>
Sent: Tuesday, April 30, 2019 3:25 PM
To: 'dita-comment@lists.oasis-open.org' <dita-comment@lists.oasis-open.org>
Subject: [dita-comment] RE: noting a few limitations in my FrameMaker-to-DITA migration effort
As a follow-up to my 12/7/2018 post, it *would* actually be nice to have the <bookmap> content model expanded to allow <part> elements within large <appendix> sets. I officially change my position on that from âno action requestedâ to âI want itâ. :)
Adding the following:
*****
Item 3: Please allow <example> elements within <section> elements.
I am specializing the <section> element to represent a particular structure within a topic (such as short description, syntax, arguments, return results, and examples). For example,
<topic id=âfooâ>
<title>My Topic Title</title>
<body>
<description-section>
</description-section>
<syntax-section>
</syntax-section>
<arguments-section>
</arguments-section>
<example-section>
<example>
<title>Single-Phase Example</title>
...figures, tables, or other content...
</example>
<example>
<title>Multi-Phase Example</title>
...figures, tables, or other content...
</example>
</example-section>
<license-section>
</license-section>
</body>
<related-links>...</related-links>
</topic>
However, the <section> element doesnât allow <example> within it, which blocks me from using a proper structure for the examples section. Using nested <topic>s instead of <section>s isnât an option because then the <related-links> must be first in the topic,
then the nested-and-specialized topics which actually contain the information.
For specialization purposes, please allow <example> in <section>!
-----
Chris Papademetrious
Tech Writer, Implementation Group
(610) 628-9718 home office
(570) 460-6078 cell