Date   

Shout-out to Oxygen's technical support #Oxygen

Matt Lorenzi <mjlorenzi@...>
 

I was looking for a thread on this, but could not find anything, so here we go.

I recently switched over to Oxygen XML Author and have been very pleased with the level of support I have received.
This includes support within Oxygen's own user forums, here in the DITA group, Write the Docs Slack channel, and through direct email contact.

This has all made the transition from our other authoring tool much more manageable.

Through all of this I do get the sense that the Oxygen team firmly believe in their product and the validity of DITA for structured authoring.

Now to get some further buy-in from management at work so we can expand our docs team from just one ;-)


problem with processing instructions in bookmap #DITA-OT #XSLT

Erik
 

Hi everyone,

I have some DITA content that makes use of processing instructions to add page breaks to PDF output. In some cases, these processing instructions are inside topics, and I have been able to use these to add breaking blocks in the PDF without any issue.

However, some of the page break processing instructions are added directly into the bookmap, and I can't hook in to these. I have tried using custom XSLT with dita.xsl.mapref, dita.xsl.mappull, and inside the plugin itself in root-processing.xsl, but I can't seem to get what I want.

My current understanding of the problem is that these PIs in the map itself don't get processed as topics, and so I can't simply convert them to fo:block elements. They do show up in stage1.xml, but I can't quite figure out how to convert them into formatting objects. I would really just like to know if there is some work-around for this, or if I'm wasting my time.

If anyone can point me in the right direction, I should be able to work it out. Any help would be greatly appreciated. Thanks in advance.


Fixing reference of stylesheet in html5 result #CSS #HTML5

quickvanrijt
 

I have an issue with the css stylesheet references produced by html5 transform (in dita-ot-2.5.4 as well dita-ot-3.4).

Next is my essential folder structure:

+RELNOTES\dita\
      relnotes.ditamap
      COMPONENT\relnotes.dita

+WORKBENCH\
      run.bat
      html.properties
      resources\
          custom.css
     out\

run.bat:
     dita-ot-2.5.4\bin\dita.bat --format=html5 --input=..\RELNOTES\dita\relnotes.ditamap --output=out\html5 --propertyfile=html.properties

html.properties:
    args.csspath=css
    args.css=custom.css
    args.cssroot=abspath/to/WORKBENCH/resources
    args.copycss=yes
    nav-toc=full
    generate.copy.outer=3

 

What is generated using html5 transform:

+WORKBENCH\out\html5\
     css\
        commonltr.css
        commonrtl.css
        custom.css       
     RELNOTES\dita\
         index.html   ==> referring <link rel="stylesheet" type="text/css" href="css/custom.css">
         COMPONENT\relnotes.html     ==> referring <link rel="stylesheet" type="text/css" href="../css/custom.css">

Both CSS references are wrong and only consider the path to the bookmap input.dir and not the args.csspath dir.
In the DITA toolkit i found references to parameter PATH2PROJ which looks like it has to address my problem:

  <xsl:param name="PATH2PROJ">
      <xsl:apply-templates select="/processing-instruction('path2project-uri')[1]" mode="get-path2project"/>
  </xsl:param>


But even in debug mode, i can't figure out which XSLT adds this processing instruction into the header of the temp.dir/topic.html.

Anybody out there who has tackled this problem?

Quick
 

 


Re: Warning statement for both ANSI and ISO #conditional-processing #hazard-statements

John Piechowski
 

Because the safety alert symbol is generated by the note tag and not part of content in the topic.

<Note type='warning'>

Automatically renders the exclamation and 'warning' text in standard Dita. Seemed to make sense not to do warnings completely outside the note tag.



On Mon, Feb 10, 2020, 11:06 AM <lkollar@...> wrote:
If you can use DITAVAL for the hazard icon, why wouldn't that work for the safety alert symbol as well?

As long as you don't have to mix ANSI and ISO in the same book, you could put the right image in a key file and use conkeyref to insert it.


Re: Warning statement for both ANSI and ISO #conditional-processing #hazard-statements

Larry Kollar
 

If you can use DITAVAL for the hazard icon, why wouldn't that work for the safety alert symbol as well?

As long as you don't have to mix ANSI and ISO in the same book, you could put the right image in a key file and use conkeyref to insert it.


Markdown output file structure #markdown

Nicholas Mucks
 

Hi folks,
In OT 3.4 we’d like to create a Markdown output with this structure:

| out
| images
| index.md
| topics

The default output mimics the input file structure, which can be all over the place.

Other than adding new ant targets that manipulate the output structure based on file extension and introducing a new XSLT process to update all the hrefs, is there an elegant way to handle this?


Take care,
- Nick

Sent from mobile


Warning statement for both ANSI and ISO #conditional-processing #hazard-statements

John Piechowski
 

We write manuals using ANSI icons and ISO icons. In many cases, our warning messages are the same except for icons.

Today, we use outputclass='iso' and modified DITA-OT to outputput the correct alert symbol (the exclamation triangle output by in the <note> tag.

<note outputclass="iso" type="warning" id="xxx">

Now we are trying to combine our ANSI and ISO warnings to eliminate duplication. Doing this means that outputclass no longer will work to select safety alert symbol.

We can use DITAVAL to output the correct specific hazard icon, but I am interested in feedback on the best way to handle the safety alert symbol.

I am thinking that we could use the same DITAVAL filter and hardcode in XSL to select the correct ANSI or ISO.
Something like:
<note ansiiso="iso" type="warning" id="xxx">

Then @ansiiso custom filter would select the correct image.

But I don't know if a solution that hardcodes a custom filter in XSL is really the best solution.

Is anyone else using the same warning text with both ANSI and ISO icons? If so, how are you solving this?


Re: Conrefs and key scopes #conref #DITA-OT

Radu Coravu
 

Hi Ozana,

How about if you keep that key definition for "key_doc_titles" in the front matter and also copy it inside both key scopes?

Regards,
Radu

Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

On 2/10/2020 1:56 PM, Ozana Dragomir wrote:
Hi Radu,
Thanks a lot for the tips. I have previously tried with conkeyref and had the same result as with conref. The key defintion for doc_titles.dita was in the <frontmatter> and it seems like this was the deal breaker.
After moving <keydef keys="key_doc_titles" href="conrefs/doc_titles.dita"/> out of the frontmatter and in both keyscopes, I can confirm that the conkeyrefs are resolved using DITA-OT 3.x that comes with Oxygen 21.1, also with 3.3.4 and 3.4.
Now the only problem is that I get this error:
        Description: [DOTJ046E] Conkeyref="key_doc_titles/id_ph_CIG_title" can not be resolved because it does not contain a key or the key is not defined. The build will use the conref attribute for fallback, if one exists.
This means that there will be lots of such errors in the real project, and it will be a pain to sort out which errors are "real" and which can be ignored.
But it's a (big) step forward!
Thanks again,
Ozana


Re: Conrefs and key scopes #conref #DITA-OT

Ozana Dragomir
 

Hi Radu,

Thanks a lot for the tips. I have previously tried with conkeyref and had the same result as with conref. The key defintion for doc_titles.dita was in the <frontmatter> and it seems like this was the deal breaker.

After moving <keydef keys="key_doc_titles" href="conrefs/doc_titles.dita"/> out of the frontmatter and in both keyscopes, I can confirm that the conkeyrefs are resolved using DITA-OT 3.x that comes with Oxygen 21.1, also with 3.3.4 and 3.4.

Now the only problem is that I get this error:
        Description: [DOTJ046E] Conkeyref="key_doc_titles/id_ph_CIG_title" can not be resolved because it does not contain a key or the key is not defined. The build will use the conref attribute for fallback, if one exists.

This means that there will be lots of such errors in the real project, and it will be a pain to sort out which errors are "real" and which can be ignored.
But it's a (big) step forward!

Thanks again,
Ozana



Re: Conrefs and key scopes #conref #DITA-OT

Radu Coravu
 

Hi Ozana,

The situation might look similar with this one:

https://github.com/dita-ot/dita-ot/issues/3259

But I'm not sure, a complete sample small project would have helped.
Some advice:

- Use conkeyref, I would not expect this to work with conref.
- Have a topic reference to the "doc_titles.dita" in both key scope contexts.
- Use DITA OT 3.4

Regards,
Radu

Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

On 2/7/2020 5:03 PM, Ozana Dragomir wrote:
Hi all,
Sorry if this has been asked before.
We have some "reusable content" DITA files where in some places we use keys - for example for product name, etc.
When publishing topics referenced from inside a defined keyscope, the keys in the conref-ed text are not resolved. It seems to be a problem with DITA-OT, as in oXygen Author the keys are resolved  properly.
Is there any combination of command line parameters or anything else that can give me the expected output? I need the keyscopes for publishing to WebHelp - multiple instances of the same document for different variants.
I'm using DITA-OT 3.3.4.
Example:
*Bookmap:*
<chapter href="topics/topic_a.dita" format="dita" type="concept" keyscope="A">
        <ditavalref><ditavalmeta>
                <dvrResourceSuffix>-a</dvrResourceSuffix>
            </ditavalmeta></ditavalref>
        <keydef keys="var_variant_number">
            <topicmeta><keywords>
                    <keyword>AXxxx</keyword>
                </keywords></topicmeta>
        </keydef>
        <topicref href="topics/topic_b.dita" />
</chapter>
*topic_b.dita contains:*
<p>For <keyword keyref="var_variant_number"/>, see <ph conref="../conrefs/doc_titles.dita#doc_titles/id_ph_TRM_title"/> for details.</p>
*Note:* using conkeyref here doesn't change anything, the output is the same.
*doc_title.dita contains:*
<ph id="id_ph_TRM_title"><keyword keyref="var_variant_number"/> Technical Reference Manual</ph>
*The output will be:*
        For AXxxx, see Technical Reference Manual for details.
*Desired output:*
       For AXxxx, see AXxxxTechnical Reference Manual for details.
Many thanks
Best regards,
Ozana


Re: Using Lightweight DITA's HTML5 format? #HTML5 #LwDITA

Mark Giffin
 

The XML format of Lightweight DITA (XDITA) is pretty much what Chris describes, it is only topic and map with only a few elements compared to full DITA:

https://docs.oasis-open.org/dita/LwDITA/v1.0/cn02/LwDITA-v1.0-cn02.html#what-is-xdita

Mica, you could also mix XDITA and MDITA (markdown) and HDITA in the same map, if some topics required more control than others. This works with the DITA OT right now (except for HDITA, which I'm not sure about).

Mark Giffin
Mark Giffin Consulting, Inc.
http://markgiffin.com/


On 2/7/2020 2:24 AM, despopoulos_chriss via Groups.Io wrote:
There's no reason that you can't just use a subset of DITA that almost completely resembles HTML.  Just use topic, and pretty much all that needs to be different it topic and title.  Just ignore all the other stuff.  With very little effort you can have people producing this minimal DITA in text editors. 

That's pretty much what we do...  We use conref and maybe a few other things, but we're effectively using a self-imposed LW DITA.  And then we just transform to HTML in the browser. 

Another approach could be to use XHTML, and then for translation set up a transform to DITA...  And back to XHTML again.  You just have to be a bit rigorous about the acceptable structure in your XHTML...  No nesting heading levels too deeply in a single file. 

Just a couple of thoughts...


Re: modifying multiple instances of a topic in the same map?

Ron Wheeler
 

You might want to explain your use case a bit in terms of what you want to customize and what you need to produce.

audience might be helpful.
It pushes the customization into the topic a bit.

In order to create bilingual documents, I have used audience to select the content in the topic that will be output.

    <shortdesc>
        <ph audience="en">This unit has 2 bedrooms and 1 bathroom in the interior of the building.</ph>
        <ph audience="fr">Cette unité dispose de 2 chambres et 1 salle de bain à l'intérieur du bâtiment.</ph>
    </shortdesc>

In my case this does the job very well and I like having the 2 languages in the same topic so that the text has a better chance of staying in synch.

If your case is more complex you may also have to think about using keyref/conkeyrefs as well.

Ron

On 2020-02-06 6:51 p.m., Chris Papademetrious wrote:
If I reuse the same topic in multiple bookmaps, and those bookmaps have a difference in profiling attributes (let's say, @product), then I can customize the topic for each bookmap:

<topic id="mytopic">
  <title>My Topic</title>
  <body>
    <p product="p1">This is customized for Product P1.</p>
    <p product="p2">This is customized for Product P2.</p>
  </body>
</topic>

But let's say I reuse a topic multiple times in the *same book*:

<bookmap>
  <chapter ...>
    <topicref href="mytopic.dita" keys="my1"/>
  </chapter>
  ...
  <chapter ...>
    <topicref href="mytopic.dita" keys="my2"/>
  </chapter>
</bookmap>

What mechanisms are available to customize each instance of that topic in the same book?

Is there a way to push a profiling attribute down into a referenced topic from the map?

 - Chris


Re: Using Lightweight DITA's HTML5 format? #HTML5 #LwDITA

Jonathan Hanna
 

Hi Mica,

The DITA Open Toolkit also supports Markdown with some extensions:
https://www.dita-ot.org/dev/topics/markdown-dita-syntax-reference.html

If you need something that's more expressive, you can also apply `outputclass` attributes to headers.

Jonathan


Conrefs and key scopes #conref #DITA-OT

Ozana Dragomir
 

Hi all,

Sorry if this has been asked before.

We have some "reusable content" DITA files where in some places we use keys - for example for product name, etc.

When publishing topics referenced from inside a defined keyscope, the keys in the conref-ed text are not resolved. It seems to be a problem with DITA-OT, as in oXygen Author the keys are resolved  properly.
Is there any combination of command line parameters or anything else that can give me the expected output? I need the keyscopes for publishing to WebHelp - multiple instances of the same document for different variants.
I'm using DITA-OT 3.3.4.

Example:

Bookmap:
<chapter href="topics/topic_a.dita" format="dita" type="concept" keyscope="A">
        <ditavalref><ditavalmeta>
                <dvrResourceSuffix>-a</dvrResourceSuffix>
            </ditavalmeta></ditavalref>
       
        <keydef keys="var_variant_number">
            <topicmeta><keywords>
                    <keyword>AXxxx</keyword>
                </keywords></topicmeta>
        </keydef>
        <topicref href="topics/topic_b.dita" />
</chapter>

topic_b.dita contains:
<p>For <keyword keyref="var_variant_number"/>, see <ph conref="../conrefs/doc_titles.dita#doc_titles/id_ph_TRM_title"/> for details.</p>
Note: using conkeyref here doesn't change anything, the output is the same.

doc_title.dita contains:
<ph id="id_ph_TRM_title"><keyword keyref="var_variant_number"/> Technical Reference Manual</ph>


The output will be:
        For AXxxx, see Technical Reference Manual for details.

Desired output:
       For AXxxx, see AXxxxTechnical Reference Manual for details.

Many thanks

Best regards,
Ozana


Re: Using Lightweight DITA's HTML5 format? #HTML5 #LwDITA

despopoulos_chriss
 

There's no reason that you can't just use a subset of DITA that almost completely resembles HTML.  Just use topic, and pretty much all that needs to be different it topic and title.  Just ignore all the other stuff.  With very little effort you can have people producing this minimal DITA in text editors. 

That's pretty much what we do...  We use conref and maybe a few other things, but we're effectively using a self-imposed LW DITA.  And then we just transform to HTML in the browser. 

Another approach could be to use XHTML, and then for translation set up a transform to DITA...  And back to XHTML again.  You just have to be a bit rigorous about the acceptable structure in your XHTML...  No nesting heading levels too deeply in a single file. 

Just a couple of thoughts...


Re: modifying multiple instances of a topic in the same map?

Radu Coravu
 

Hi Chris,

If you want to have the same topic in multiple places of the DITA Map with slightly different content in each of those places you can use either key scopes or branch filtering:

https://oxygenxmlblog.netlify.com/presentation-reuse/reuse_keyscopes.html

https://oxygenxmlblog.netlify.com/presentation-reuse/reuse_branch.html

For example if you use key scopes inside the topic you can use conkeyref to refer to the paragraph and the conkeyref would be resolved to different paragraphs depending on the context.

Regards,
Radu

Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

On 2/7/2020 1:51 AM, Chris Papademetrious wrote:
If I reuse the same topic in multiple bookmaps, and those bookmaps have a difference in profiling attributes (let's say, @product), then I can customize the topic for each bookmap:
<topic id="mytopic">
  <title>My Topic</title>
  <body>
    <p product="p1">This is customized for Product P1.</p>
    <p product="p2">This is customized for Product P2.</p>
  </body>
</topic>
But let's say I reuse a topic multiple times in the **same book**:
<bookmap>
  <chapter ...>
    <topicref href="mytopic.dita" keys="my1"/>
  </chapter>
  ...
  <chapter ...>
    <topicref href="mytopic.dita" keys="my2"/>
  </chapter>
</bookmap>
What mechanisms are available to customize each instance of that topic in the same book?
Is there a way to push a profiling attribute *down into* a referenced topic from the map?
 - Chris


Re: keys and scoped keys #conref

Radu Coravu
 

Hi Matt,

After you define these keys in different key scopes you can explicitly refer to any of them like:

<ph keyref="3000.inverter"/>
Or as other use cases you can refer to the same DITA topics in various key scopes and have them published with different content in each key scope:

https://oxygenxmlblog.netlify.com/presentation-reuse/reuse_keyscopes.html

Regards,
Radu

Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

On 2/7/2020 1:35 AM, Matt Lorenzi via Groups.Io wrote:
I am going to add to this thread rather than start a new one. I am looking to use a keyspace or map to house reusable content such as product names, document numbers, etc. I learned that before keyscope you would need a unique keyname for each keyword entry. But with the introduction to keyscope you can reuse the keyword, but further differentiate it using keyscope. Do I have this right?
Given all of that, is this correct markup for use of keyscope? This is a dummy example of my keyspace:
<map id="keydefs">
    <!-- product name -->
    <title>Key Definitions</title>
    <keydef keys="inverter" keyscope="1000">
        <topicmeta>
            <keywords>
                <keyword>Inverter 1000</keyword>
            </keywords>
        </topicmeta>
    </keydef>
    <keydef keys="inverter" keyscope="2000">
        <topicmeta>
            <keywords>
                <keyword>Inverter 2000</keyword>
            </keywords>
        </topicmeta>
    </keydef>
    <keydef keys="inverter" keyscope="3000">
        <topicmeta>
            <keywords>
                <keyword>Inverter 3000</keyword>
            </keywords>
        </topicmeta>
    </keydef>
</map>


Re: Using Lightweight DITA's HTML5 format? #HTML5 #LwDITA

Mica Semrick
 

Thank you for the replies Kris & Mark. The original request was for the docs to go into markdown, and I'm still considering MDITA for that, however I have reservations that markdown is expressive enough to capture the necessary information for this documentation set. I also worry about the translation pipeline, which for the current docbook workflow uses GNU get text and PO files. I don't want to hang all the translators out to dry, and I haven't seen great tooling around markdown and translation.

I think vanilla dita is too complicated here, as most seem to be authoring in a text editor. Since it is a Free Software project, many will balk at using a proprietary editor.

I'll continue to think about it; meanwhile I'm open to any suggestions.

-m


On February 6, 2020 3:14:36 PM PST, Mark Giffin <mark@...> wrote:
Hi Mica,

Your observation is correct. There are not a lot of details and examples
available about the HTML5 format of Lightweight DITA (HDITA), outside of
the committee note on it. I'm on the LWDITA subcommittee and there is no
DTD or other schema for HDITA. I think that was largely because it was
hard to figure out what to use for it. There is no DTD for HTML5 itself,
because they have officially cut ties with SGML (which is where DTDs
came from).

Oxygen has good support for MDITA and XDITA (some other tools do also),
but not much (none?) for HDITA. In my personal experience, most of the
interest is in Markdown/MDITA.

HDITA is basically standard HTML5. It does not violate the HTML5 specs.
There is a validator for HTML5:

https://about.validator.nu/
https://github.com/validator/validator/wiki/Service-%C2%BB-HTTP-interface

I think that Oxygen now implements this validator but I have not tested
it yet. But that doesn't help you validate HDITA.

By the way, there is also no official validation mechanism for the
Markdown format of Lightweight DITA (MDITA). Although the Oxygen
Markdown editor may help with this, I'm not certain. And there's no
official way to validate ordinary non-LWDITA Markdown either (and there
are many flavors of it). I believe most people use their static site
generator to "validate" their markdown content. But some people are
trying on this.

Mark Giffin
Mark Giffin Consulting, Inc.
http://markgiffin.com/


On 2/6/2020 9:37 AM, Mica Semrick wrote:
I've been looking at migrating the docs for one of my favorite photo
editing applications from docbook to something else. I had thought
that HDITA would be a great fit for this content, but I can't seem to
find much on the format, other than the examples in the spec. I can't
create an HDITA topic in Oxygen, I can't find a DTD. Forgive my
ignorance, but can someone shed some light on this?

Best,
Mica




Groups.io Links: You receive all messages sent to this group.

View/Reply Online (#45175): https://dita-users.groups.io/g/main/message/45175
Mute This Topic: https://groups.io/mt/71028148/2985651
Mute #lwdita: https://groups.io/mk?hashtag=lwdita&subid=5779837
Mute #html5: https://groups.io/mk?hashtag=html5&subid=5779837
Group Owner: main+owner@dita-users.groups.io
Unsubscribe: https://dita-users.groups.io/g/main/leave/defanged [mica@...]


modifying multiple instances of a topic in the same map?

Chris Papademetrious
 

If I reuse the same topic in multiple bookmaps, and those bookmaps have a difference in profiling attributes (let's say, @product), then I can customize the topic for each bookmap:

<topic id="mytopic">
  <title>My Topic</title>
  <body>
    <p product="p1">This is customized for Product P1.</p>
    <p product="p2">This is customized for Product P2.</p>
  </body>
</topic>

But let's say I reuse a topic multiple times in the *same book*:

<bookmap>
  <chapter ...>
    <topicref href="mytopic.dita" keys="my1"/>
  </chapter>
  ...
  <chapter ...>
    <topicref href="mytopic.dita" keys="my2"/>
  </chapter>
</bookmap>

What mechanisms are available to customize each instance of that topic in the same book?

Is there a way to push a profiling attribute down into a referenced topic from the map?

 - Chris


Re: keys and scoped keys #conref

Matt Lorenzi <mjlorenzi@...>
 

I am going to add to this thread rather than start a new one. I am looking to use a keyspace or map to house reusable content such as product names, document numbers, etc. I learned that before keyscope you would need a unique keyname for each keyword entry. But with the introduction to keyscope you can reuse the keyword, but further differentiate it using keyscope. Do I have this right? 

Given all of that, is this correct markup for use of keyscope? This is a dummy example of my keyspace:

<map id="keydefs">

    <!-- product name -->

    <title>Key Definitions</title>

    <keydef keys="inverter" keyscope="1000">

        <topicmeta>

            <keywords>

                <keyword>Inverter 1000</keyword>

            </keywords>

        </topicmeta>

    </keydef>

    <keydef keys="inverter" keyscope="2000">

        <topicmeta>

            <keywords>

                <keyword>Inverter 2000</keyword>

            </keywords>

        </topicmeta>

    </keydef>    

    <keydef keys="inverter" keyscope="3000">

        <topicmeta>

            <keywords>

                <keyword>Inverter 3000</keyword>

            </keywords>

        </topicmeta>

    </keydef>

 

</map>

1041 - 1060 of 46224