dita-comment message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: Re: [dita-comment] RE: noting a few limitations in my FrameMaker-to-DITA migration effort
- From: "Robert D Anderson" <robander@us.ibm.com>
- To: Chris Papademetrious <Christopher.Papademetrious@synopsys.com>
- Date: Tue, 18 Jun 2019 12:34:07 -0500
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
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
