Happy New Year; I'm glad that I was able to start 2021 by being helpful!

Regarding the <keyword> element ... The element certainly can contain PCDATA (text), but in your scenario, where you are using key referencing, that is not necessary. If you were using @conref or @conkeyref, then the referenced element would contain content, for example, <keyword id="accountType">checking</keyword>.

Oxygen is going to create an element with both a start and end tag, if it thinks that you will insert content into the element. The following markup has identical meanings:

<keyword keyref="accountType"/>
<keyword keyref="accountType"></keyword>

Regarding DITA training ... Comtech Services Inc has a course on "Advanced Reuse Strategies". I think LearningDITA also has a course on reuse.

Regarding formatting DITA-OT output to match a company style guide ... You can specify a CSS file as a parameter to an Oxygen transformation scenario. To handle making changes to PDF generated using XSL-FO, you'll need to create a custom DITA-OT plug-in. For this I recommend the following documentation:

• Eliot Kimber, DITA for Practitioners Volume 1 (useful for information about creating DITA-OT plug-ins)
• Leigh White, DITA for Print (useful for information about creating DITA-OT plug-ins for PDF)
• DITA-OT documentation: https://www.dita-ot.org/dev/

Oxygen has ships a PDF transformation that uses CSS, BTW.

Very best of luck with learning DITA and getting a job.

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
OASIS Distinguished Contributor
Principal consultant, Eberlein Consulting LLC
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

On 1/1/2021 10:15 AM, Aaron Mehl via groups.io wrote:

Wow!

Thanks,

I  see that I  need to rethink what I want to accomplish.

But I see now how profiling works.

By formal Dita training, what do you mean? learningdita? OR a paid course?

I am for the most part  doing OK with the basics, but the advanced issues such as profiling and linking are causing me problems. I couldn't find well written concise explanations for when I can, or should do profiling. The tutorials and videos I used, listed the different options and only showed how to do them. I need the rationale for why and also when. Which you also touched on.

Your analysis of what I wanted to accomplish was right on. I understood that I could write one topic and generate two.

One thing I didn't get till I saw it in your example, the keyword tag is one single tag. Oxygen made it a double tag, so I instinctively put text between the opening and closing tag. Must I change this or will it be changed during publishing?

If you have training suggestions I would appreciate them.

I also need to know how to make the output in Oxygen conform to a style guide.

I guess that involves CSS or XSL-Fo, in docbook there was an easy way to do modify the output for html and pdf. 

I think because I am using a gui program I am missing something here.

In docbook I just opened up the xsl or css and made my changes there.

I am currently unemployed and a huge amount of people told me that having Dita knowledge and practical application will help me get employed.

Thanks so much for answering me.

Next week I will apply what you taught me.

:)

Aaron

 

On Friday, January 1, 2021, 07:11:21 AM EST, Kristen James Eberlein <kris@...> wrote:

Hi, Aaron.

If I understand correctly, your requirements are as follows:

Requirements

You want to author a single DITA task topic that you can use to generate two versions of output:

• Creating a checking account
• Creating a savings account

The content in the task topic has the following variations:

• Type of account (checking versus savings)
• Wording in the user interface, leading to different screen captures

DITA mechanisms for handling content reuse

DITA has multiple mechanisms for handling content reuse:

• Content referencing (@conref)
  
• Conditional processing using a DITAVAL file
• Key referencing (@keyref)
• Content key referencing (@conkeyref)
• Key scopes
  
• Branch filtering (using the DITAVALref domain)

Branch filtering and key scopes were designed to address the use case of using DITA topics multiple times within a single publication, with different content in the generated output of the topics. (You don't mention this, but I suspect this is what you want to do.)

Information architecture choices

Getting ROI from DITA always requires sound information design and architecture. Here, I would ask the following questions:

• Do you really need two generated topics? Could this be handled with a single topic ("Creating an account") which could cover both scenarios?
• Do you need a DITA topic for each scenario? This might be the case if you have elaborate metadata requirements or other business requirements.
• Will you be localizing (translating) the DITA source? Remember that inflection in non-English languages can cause differences in articles
  

For the purpose of this exercise, we will assume that you want to author a single DITA topic that can be used to generate two versions of output (and you are not worried about localization). For this goal, you could use either key referencing or conditional processing; I'll show how this can be done using key references.

Reuse using key referencing

Author the content using the following markup for keywords and images:

• <keyword keyref="accountType"/>
• <image keyref="creatingAccount"/>

In a DITA map, create the following key definitions:

<keydef keys="accountType">
  <topicmeta>
    <linktext>checking</linktext>
  </topicmeta>
</keydef>

<keydef keys="creatingAccount" href="creatingCheckingAccount.png" format="png">
  <topicmeta>
    <linktext>Alternate text for the image goes here</linktext>
  </topicmeta>
</keydef>

Obviously, you'd need to modify the key definitions when you process to generate the "Creating a savings account" output.

Reuse using key references and key scopes

If you want both versions of the topics ("Creating a checking account" and "Creating a savings account" in the same publication, you'll need to use key scopes.

Author the content using the (same as above) markup for keywords and images:

• <keyword keyref="accountType"/>
• <image keyref="creatingAccount"/>

In the DITA map where you create the publication navigation, you'll also define key scopes and specify the values for the key references:

      <!-- Generate output for "Creating a checking account" --> 
      <topicgroup keyscope="checkingAccount">
            <keydef keys="accountType">
                <topicmeta>
                    <linktext>checking</linktext>
                </topicmeta>
            </keydef>
            <keydef keys="creatingAccount" format="png" href="creatingCheckingAccount.png">
                <topicmeta>
                    <linktext>Screen capture of the user interface window shown when creating a checking account</linktext>
                </topicmeta>
            </keydef>
            <topicref href="creatingAccount.dita"/>
        </topicgroup>

      <!-- Generate output for "Creating a savings account" --> 
      <topicgroup keyscope="savingsAccount">
            <keydef keys="accountType">
                <topicmeta>
                    <linktext>savings</linktext>
                </topicmeta>
            </keydef>
            <keydef keys="creatingAccount" format="png" href="creatingSavingAccount.png">
                <topicmeta>
                    <linktext>Screen capture of the user interface window shown when creating a savings account</linktext>
                </topicmeta>
            </keydef>
            <topicref href="creatingAccount.dita"/>
        </topicgroup>

I hope that this helps. I'd suggest that getting some formal DITA training might be of benefit.

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
OASIS Distinguished Contributor
Principal consultant, Eberlein Consulting LLC
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

On 12/27/2020 5:26 PM, Aaron Mehl via groups.io wrote:

Hi all, 

I am new to the group, and Dita.

I am documenting KMyMoney and have two similar tasks.

One is creating a checking account and the other is creating a savings account.

The text is nearly the same. I need to make the words checking and savings conditional.

I need a way to also make the screen captures conditional.

That said, and I hope done, I need to know how to generate the two task when publishing/transforming the xml to xhtml and pdf.

I have seen docs provided by my editor (Oxygen) and some videos, but I still can't seem to make heads or tails out of profiling.

This is a draft the Dita task file.

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

<task id="creatingacheckingaccount">

    <title>Creating a <keyword>Checking</keyword> Account</title>

    <shortdesc>A <keyword>Checking</keyword> account in KMyMoney contains the same information as the same account in

        your bank. </shortdesc>

    <taskbody>

        <context>You just created an institution.<p>To create a <keyword>checking</keyword> account in the

                instituion:</p></context>

        <steps>

            <step>

                <cmd>Choose <uicontrol>Accounts</uicontrol> in the <uicontrol>View

                        Selector</uicontrol>pane</cmd>

                <stepresult>The institution you created is listed in the <uicontrol>Account

                        View</uicontrol>pane.</stepresult>

            </step>

            <step>

                <cmd>Click on the <uicontrol>New Account</uicontrol>icon on the

                        <uicontrol>toolbar</uicontrol>.</cmd>

                <stepresult>The <uicontrol>New Account </uicontrol>wizard appears.</stepresult>

            </step>

            <step>

                <cmd>Choose your instituiton from the dropdown list.</cmd>

            </step>

            <step>

                <cmd>Enter your account number.</cmd>

            </step>

            <step>

                <cmd>Click <uicontrol>Next</uicontrol>.</cmd>

                <stepresult>The Account window appears.</stepresult>

            </step>

        </steps>

    </taskbody>

</task>

Thanks

Aaron