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,

<title>My Topic Title</title>

<body>

<description-section>

</description-section>

<syntax-section>

</syntax-section>

<arguments-section>

</arguments-section>

<example-section>

<title>Single-Phase Example</title>

...figures, tables, or other content...

</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

dita-comment message