-
Notifications
You must be signed in to change notification settings - Fork 28
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #938 from robander/conref
Revise conref topics
- Loading branch information
Showing
22 changed files
with
746 additions
and
505 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
47 changes: 47 additions & 0 deletions
47
specification/archSpec/base/example-conref-conaction-pushafter.dita
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,47 @@ | ||
| <?xml version="1.0" encoding="UTF-8"?> | ||
| <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> | ||
| <concept id="example_conaction_pushafter"> | ||
| <title>Example: Using <xmlatt>conaction</xmlatt> to push content after another element</title> | ||
| <shortdesc>In this scenario, a <xmlatt>conref</xmlatt> and <xmlatt>conaction</xmlatt> are used to | ||
| push content after an element in another topic.</shortdesc> | ||
| <conbody> | ||
| <p>Consider the following topic, which is set up to push a step after a step in another topic. | ||
| It needs to use two step elements to set up the reuse. The referencing element itself uses | ||
| <codeph>conaction="mark"</codeph> to mark the referenced element. The element to be pushed | ||
| immediately follows the marking element and uses <codeph>conaction="pushafter"</codeph>: | ||
| <codeblock><steps> | ||
| <step conaction="mark" conref="example.dita#example/b"> | ||
| <cmd/> | ||
| </step> | ||
| <step conaction="pushafter"> | ||
| <cmd>Do this after B</cmd> | ||
| </step> | ||
| </steps></codeblock></p> | ||
| <p>The referenced element is in the file <filepath>example.dita</filepath>, which looks like | ||
| this before a processor resolves the | ||
| reference:<codeblock><task id="example" xml:lang="en"> | ||
| <title>Example topic</title> | ||
| <taskbody> | ||
| <steps> | ||
| <step id="a"><cmd>A</cmd></step> | ||
| <step id="b"><cmd>B</cmd></step> | ||
| <step id="c"><cmd>C</cmd></step> | ||
| </steps> | ||
| </taskbody> | ||
| </task></codeblock></p> | ||
| <p>After the content reference is resolved, the document <filepath>example.dita</filepath> | ||
| includes the pushed <xmlelement>step</xmlelement> element after the step with | ||
| <xmlatt>id</xmlatt> set to | ||
| <keyword>b</keyword>:<codeblock><task id="example" xml:lang="en"> | ||
| <title>Example topic</title> | ||
| <taskbody> | ||
| <steps> | ||
| <step id="a"><cmd>A</cmd></step> | ||
| <step id="b"><cmd>B</cmd></step> | ||
| <step><cmd>Do this after B</cmd></step> | ||
| <step id="c"><cmd>C</cmd></step> | ||
| </steps> | ||
| </taskbody> | ||
| </task></codeblock></p> | ||
| </conbody> | ||
| </concept> |
47 changes: 47 additions & 0 deletions
47
specification/archSpec/base/example-conref-conaction-pushbefore.dita
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,47 @@ | ||
| <?xml version="1.0" encoding="UTF-8"?> | ||
| <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> | ||
| <concept id="example_conaction_pushbefore"> | ||
| <title>Example: Using <xmlatt>conaction</xmlatt> to push content before another element</title> | ||
| <shortdesc>In this scenario, a <xmlatt>conref</xmlatt> and <xmlatt>conaction</xmlatt> are used to | ||
| push content before an element in another topic.</shortdesc> | ||
| <conbody> | ||
| <p>Consider the following topic, which is set up to push a step before a step in another topic. | ||
| It needs to use two step elements to set up the reuse. The referencing element itself uses | ||
| <codeph>conaction="mark"</codeph> to mark the referenced element. The element to be pushed | ||
| immediately preceeds the marking element and uses <codeph>conaction="pushbefore"</codeph>: | ||
| <codeblock><steps> | ||
| <step conaction="pushbefore"> | ||
| <cmd>Do this before B</cmd> | ||
| </step> | ||
| <step conaction="mark" conref="example.dita#example/b"> | ||
| <cmd/> | ||
| </step> | ||
| </steps></codeblock></p> | ||
| <p>The referenced element is in the file <filepath>example.dita</filepath>, which looks like | ||
| this before a processor resolves the | ||
| reference:<codeblock><task id="example" xml:lang="en"> | ||
| <title>Example topic</title> | ||
| <taskbody> | ||
| <steps> | ||
| <step id="a"><cmd>A</cmd></step> | ||
| <step id="b"><cmd>B</cmd></step> | ||
| <step id="c"><cmd>C</cmd></step> | ||
| </steps> | ||
| </taskbody> | ||
| </task></codeblock></p> | ||
| <p>After the content reference is resolved, the document <filepath>example.dita</filepath> | ||
| includes the pushed <xmlelement>step</xmlelement> element before the step with | ||
| <xmlatt>id</xmlatt> set to | ||
| <keyword>b</keyword>:<codeblock><task id="example" xml:lang="en"> | ||
| <title>Example topic</title> | ||
| <taskbody> | ||
| <steps> | ||
| <step id="a"><cmd>A</cmd></step> | ||
| <step><cmd>Do this before B</cmd></step> | ||
| <step id="b"><cmd>B</cmd></step> | ||
| <step id="c"><cmd>C</cmd></step> | ||
| </steps> | ||
| </taskbody> | ||
| </task></codeblock></p> | ||
| </conbody> | ||
| </concept> |
45 changes: 45 additions & 0 deletions
45
specification/archSpec/base/example-conref-conaction-replace.dita
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,45 @@ | ||
| <?xml version="1.0" encoding="UTF-8"?> | ||
| <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> | ||
| <concept id="example_conaction_pushreplace"> | ||
| <title>Example: Using <xmlatt>conaction</xmlatt> to replace content</title> | ||
| <shortdesc>In this scenario, a <xmlatt>conref</xmlatt> and <xmlatt>conaction</xmlatt> are used to | ||
| replace content in another topic.</shortdesc> | ||
| <conbody> | ||
| <p>Consider the following task in <filepath>example.dita</filepath> that has the | ||
| <xmlatt>id</xmlatt> attribute set to <keyword>example</keyword>. The task contains a | ||
| <xmlelement>step</xmlelement> element with the <xmlatt>id</xmlatt> set to | ||
| <keyword>b</keyword>:</p> | ||
| <codeblock id="codeblock_scr_wqh_psb"><task id="example" xml:lang="en"> | ||
| <title>Example topic</title> | ||
| <taskbody> | ||
| <steps> | ||
| <step id="a"><cmd>A</cmd></step> | ||
| <step id="b"><cmd>B</cmd></step> | ||
| <step id="c"><cmd>C</cmd></step> | ||
| </steps> | ||
| </taskbody> | ||
| </task></codeblock> | ||
| <p>In order to replace the step with <codeph>id="b"</codeph>, another topic must combine a | ||
| <xmlatt>conaction</xmlatt> value of <keyword>pushreplace</keyword> with a | ||
| <xmlatt>conref</xmlatt> attribute that references this | ||
| <xmlelement>step</xmlelement>:<codeblock><!-- Steps element within another task --> | ||
| <steps> | ||
| <step conaction="pushreplace" | ||
| conref="example.dita#example/b"> | ||
| <cmd>Updated B</cmd> | ||
| </step> | ||
| </steps> | ||
| </task></codeblock></p> | ||
| <p>The result will be an updated version of <filepath>example.dita</filepath> which contains the | ||
| pushed <xmlelement>step</xmlelement>:<codeblock><task id="example" xml:lang="en"> | ||
| <title>Example topic</title> | ||
| <taskbody> | ||
| <steps> | ||
| <step id="a"><cmd>A</cmd></step> | ||
| <step id="b"><cmd>Updated B</cmd></step> | ||
| <step id="c"><cmd>C</cmd></step> | ||
| </steps> | ||
| </taskbody> | ||
| </task></codeblock></p> | ||
| </conbody> | ||
| </concept> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,62 @@ | ||
| <?xml version="1.0" encoding="UTF-8"?> | ||
| <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> | ||
| <concept id="example_simple_conkeyref"> | ||
| <title>Example: Simple <xmlatt>conkeyref</xmlatt> usage</title> | ||
| <shortdesc>In this scenario, a <xmlatt>conkeyref</xmlatt> attribute is used as an indirect | ||
| reference to pull content from the referenced element in another topic.</shortdesc> | ||
| <conbody> | ||
| <p>Consider the following topic:</p> | ||
| <codeblock><task id="setup-widget" xml:lang="en"> | ||
| <title>Setting up the widget</title> | ||
| <taskbody> | ||
| <steps> | ||
| <step><cmd>Turn the widget on for the first time.</cmd></step> | ||
| <step><cmd>Follow the prompts to select your language and region.</cmd></step> | ||
| <b><step conkeyref="reuselibrary/setup-profile"><cmd></cmd></step></b> | ||
| <step><cmd>Step outside and activate the widget.</cmd></step> | ||
| </steps> | ||
| </taskbody> | ||
| </task></codeblock> | ||
| <p>The key is defined as a reference to a resue library:</p> | ||
| <codeblock><map> | ||
| <title>Key definitions</title> | ||
| <keydef keys="reuselibrary" href="reuse-library.dita"/> | ||
| <!-- ... --> | ||
| </map></codeblock> | ||
| <p>The library topic <filepath>reuse-library.dita</filepath> is set up as follows:</p> | ||
| <codeblock><task id="reuse-library" xml:lang="en"> | ||
| <title>Reuse library topic</title> | ||
| <taskbody> | ||
| <steps> | ||
| <!-- ... other steps used across tasks ... --> | ||
| <step id="setup-profile"> | ||
| <cmd>Follow the prompts to set up your name and contact information.</cmd> | ||
| <info>Contact information is optional, but recommended.</info> | ||
| </step> | ||
| </steps> | ||
| </taskbody> | ||
| </task></codeblock> | ||
| <p>When the <xmlatt>conkeyref</xmlatt> attribute is resolved, the key resolves to the topic | ||
| that contains the referenced ID <codeph>setup-profile</codeph>. The result is the same as if | ||
| the original topic contained | ||
| <codeph>conref="reuse-library.dita#reuse-library/setup-profile"</codeph> instead of | ||
| <codeph>conkeyref="reuselibrary/setup-profile"</codeph>. However, the indirection created by | ||
| using a key allows this reference to resolve differently in other contexts.</p> | ||
| <p>The processed version of the original topic will include content from the referenced | ||
| element:</p> | ||
| <codeblock><task id="setup-widget" xml:lang="en"> | ||
| <title>Setting up the widget</title> | ||
| <taskbody> | ||
| <steps> | ||
| <step><cmd>Turn the widget on for the first time.</cmd></step> | ||
| <step><cmd>Follow the prompts to select your language and region.</cmd></step> | ||
| <b><step> | ||
| <cmd>Follow the prompts to set up your name and contact information.</cmd> | ||
| <info>Contact information is optional, but recommended.</info> | ||
| </step></b> | ||
| <step><cmd>Step outside and activate the widget.</cmd></step> | ||
| </steps> | ||
| </taskbody> | ||
| </task></codeblock> | ||
| </conbody> | ||
| </concept> |
Oops, something went wrong.