dita — archive

[Kristen Eberlein]

We talked a bit about this at last week’s TC meeting, and Robert and I talked about this at our spec editors’ meeting yesterday and made decisions. The question (raised by Tammy Crowley) concerned the following code sample for <troubleSolution>, and the question was whether it would be better shown in the context of the <troublebody> element: Original code sample <troubleSolution> <cause>The <msgnum>E247</msgnum> error message is generated due to a transient memory fault. </cause> <remedy> <steps> <step><cmd>Reset the alarm. </cmd></step> <step><cmd>Monitor the system periodically to see whether the alarm recurs. </cmd></step> </steps> </remedy> </troubleSolution> Robert and I agree that the following would be better: <troubleshooting id="e247"> <title>E247: Memory fault has occurred</title> <troublebody> <troubleSolution> <cause>The <msgnum>E247</msgnum> error message is generated due to a transient memory fault. </cause> <remedy> <steps> <step><cmd>Reset the alarm. </cmd></step> <step><cmd>Monitor the system periodically to see whether the alarm recurs. </cmd></step> </steps> </remedy> </troubleSolution> </troublebody> </troubleshooting> Note that this is a pattern ONLY for elements that are components of structural specializations, not base constructions or domain elements. Also, the following considerations apply: Snip the code as necessary to make the code sample not otherwhelmingly long Scrap this pattern if following it makes the code sample too involved or ;ong. Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Owner, Eberlein Consulting LLC kris@eberleinconsulting.com Skype: kriseberlein; voice: +1 (919) 622-1501