OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: RE: [dita] Possible RFE - xref to step


Gershon,
Thank you for your proposal but, as I'm sure Don Day will explain, we're
in the middle of the final definition of the 1.1 specification at
present. 

But I do want to strongly recommend that you not follow the path of
"changing the DITA DTD." The whole idea of specialization is to provide
a mechanism for introducing a new customer requirements without changing
the core DTD. It would be best to review the information available on
the specialization philosophy behind DITA. 

Happy to see you as an observer on the TC. 
JoAnn 


JoAnn T. Hackos, PhD
President
Comtech Services, Inc.
710 Kipling Street, Suite 400
Denver CO 80215
303-232-7586
joann.hackos@comtech-serv.com
 

-----Original Message-----
From: Gershon L Joseph [mailto:gershon@tech-tav.com] 
Sent: Tuesday, January 10, 2006 6:02 AM
To: dita@lists.oasis-open.org
Subject: [dita] Possible RFE - xref to step

I'd like to propose a new feature to support cross-referencing a step in
a procedure. I'll start with the use cases and then address my proposed
DTD modifications.

Use case 1: cross reference another step within the same procedure

This is best shown by example:
1. Do something.
2. Do something else.
3. Do another thing. Details are provided in Step 1.

The 'Step 1' in step 3 would be an <xref> to the first <step> in the
<steps>.

Use case 2: cross reference to step in another procedure.

This is also best shown by example:
1. Do something.
2. Do something else.
3. Do another thing. Details are provided in "name of another task",
Step 1.

Proposed change to the DITA DTD:
Add a new attribute value to the <xref> type attribute, called "step".

In this case, I'd mark up the first example as follows:
<steps>
  <step id="myStep"><cmd>Do something.</cmd></step>
  <step><cmd>Do something else.</cmd></step>
  <step><cmd>Do another thing. Details are provided in <xref type="step"
href="myStep"/>.</cmd></step>
</steps>

The second example, where we reference another procedure, would be
marked up similarly, except that its <xref> would contain the standard
href value needed to reference an element located in a different <task>.

The processing expectations I foresee are as follows:

1. online (HTML-based) outputs:
1a. Xref to same <step>: replace the <xref> element with hyperlink whose
hot text is something like "Step 1", where the number is the number of
the target step.
1b. Xref to <step> in different task: replace <xref> with hyperlink
whose hot text is something like "Step 1 in [task title]" or "[task
title], Step 1"

2. print/PDF outputs
2a. Same as for online.
2b. Same as for online, with addition of page number of the target
<step>.
For example, "[task title], Step 1, on page 33"

Obviously other users may have different output requirements. The ones
I've listed here are based on the current needs of our clients.

All input and comments that can help us refine this requirement will be
greatly appreciated. I need to decide soon whether to specialize for
this or just modify the current DTD. I will also be updating the DITA-OT
accordingly.

Gershon






[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]