Date   

Best way to represent images at the book/cover page level #bookmap #images

snorton@...
 

We are just getting started with our move to DITA and would appreciate some advice.

 

Some of our books are presented with an image on the title page or early in the book, before the frontmatter. What's the best way to represent something like that in DITA?

 

One suggestion was that we might use a <data> element inside the bookmeta, something like: <data name=”coverimage” value=”foo.jpg”/>.  But we would prefer to use the <image> element, so we can easily get things like preview in the editor. 

 

For example, it seems like it would be nice if we could put an <image> inside the <bookmeta> or directly inside <frontmatter>. But it looks like the only similar place images are allowed is inside booktitlealt, which seems a bit weird… The image definitely isn't part of an alternate title.

 

Any recommendations?

 

Thanks,

Stuart


Juniper Business Use Only


Re: Keyref/conkey ref conversion strategy - keyref all the things? #conref

Joe Williams
 

At a previous job, we were doing content management without a CMS, and we relied on simple, consistent practices and enforcement to take care of things like naming files and @id's. Tony Self's book and the IBM DITA Best Practices book suggest a lot of simple things you can do that can save you a lot of effort. The writers might have some ideas about the best way to go about it, too, which might give them a greater sense of ownership over the process. Also, I have heard of organizations that caused themselves problems that could have been avoided because of a lack of clear, consistent practices even with a CMS. As Hackos and Rockley used to say, content management is about processes, not tools.


Re: Keyref/conkey ref conversion strategy - keyref all the things? #conref

Chris Papademetrious
 

Hi Eliot,

Describing it in terms of "conveniences" has helped my thinking along, thank you!

Would a DITA CMS update a map with glossterm keys? Maybe the problem is that I'm expecting CMS-like conveniences from a DITA editor or from DITA itself.

 - Chris


Re: Keyref/conkey ref conversion strategy - keyref all the things? #conref

ekimber@contrext.com
 

The problem I see with the convenience feature you're requesting is that it makes your key references dependent on the particular file (storage) organization of the topics, not on the map structure, which provides a layer of indirection between references from topics to keys and the storage details of the target resources. It would also result in ambiguity about the intended target of the key reference.

That is, a keyref like "my-gloss-group/gloss-entry-one" (where " gloss-entry-one" is the ID of a topic) would only work as long as the target topic (the one with the ID "gloss-entry-one") is a literal child of the topic bound to the key "my-gloss-group".

It would also be ambiguous with a keyref to an element *within* the topic with the ID "gloss-entry-one" (which would be valid per the DITA spec if otherwise ill advised). But there would be no way for a processor to know, from the keyref itself, whether the intended target was a topic with the ID "gloss-entry-one" or a non-topic element with that ID within the topic bound to the "my-gloss-group".

Likewise, if the individual glossary entry topics were broken out to their own XML documents, then the keyref would break, which largely undoes one of the values of keyrefs from topics, namely making the reference insensitive to storage details.

As a contributor to the DITA architecture I think I would have to object to the feature request on these grounds alone: it would violate a basic principle of the key mechanism simply to provide a convenience feature that is largely limited to this particular use case.

I'm sympathetic to the need for convenience but it feels like something better handled in the editor rather than at the DITA addressing level.

Cheers,

E.

--
Eliot Kimber
http://contrext.com


On 2/19/20, 11:26 AM, "Chris Papademetrious" <main@dita-users.groups.io on behalf of chrispitude@gmail.com> wrote:

Hi Eliot,

It's "easy enough" to write a lot of scripts, but we're starting to accumulate a number of such scripts. I'm not trying to be negative, and I understand why the $key/$elt_id reference structure imposes this constraint. But many of my writers are nontechnical; if I switch from the WYSIWYG view to the XML view in Oxygen, you'd think I'm giving them a sneak peek into The Matrix! And as the champion of our move to DITA, I'm responsible for all automation to hide these sorts of details from them.

In my opinion, having keys map to files is handy, but requiring keys for subtopics in those files is a bit limiting. It would be nice to have the option to use a $key/$subtopic_id reference structure as well.

Enough wishful thinking. It's <glossentry> hrefs for now. Back to work!

- Chris


Re: Keyref/conkey ref conversion strategy - keyref all the things? #conref

Chris Papademetrious
 

Hi Eliot,

It's "easy enough" to write a lot of scripts, but we're starting to accumulate a number of such scripts. I'm not trying to be negative, and I understand why the $key/$elt_id reference structure imposes this constraint. But many of my writers are nontechnical; if I switch from the WYSIWYG view to the XML view in Oxygen, you'd think I'm giving them a sneak peek into The Matrix! And as the champion of our move to DITA, I'm responsible for all automation to hide these sorts of details from them.

In my opinion, having keys map to files is handy, but requiring keys for subtopics in those files is a bit limiting. It would be nice to have the option to use a $key/$subtopic_id reference structure as well.

Enough wishful thinking. It's <glossentry> hrefs for now. Back to work!

 - Chris


Re: creating Webhelp Publication TOC from Bookmap #Oxygen #HTML5

Matt Lorenzi <mjlorenzi@...>
 

I am wondering perhaps if part of the problem is my folder structure and hierarchy. Could this play a part in building a successful TOC/Breadcrumb. I will try to mimic what works successfully with the sample projects that ship with Oxygen. If no luck, I will forward on the bookmap. Many thanks! 


Re: Keyref/conkey ref conversion strategy - keyref all the things? #conref

ekimber@contrext.com
 

Iit should be easy enough to generate the necessary map structure if the glossary already exists or have whoever is responsible for the glossary to do it as they add glossary entries.

Once you have created the topicref pattern for pointing to glossary entries, it shouldn't matter whether those glossary entry topics are managed as a standalone files or are subtopics within a larger glossgroup topic--the actual markup creation effort is the same (or at least it should be since the only difference is whether or not the href on the key-defining topicref has a fragment identifier pointing to the specific topic).

It is certainly the case that a lot of DITA design and tool implementation is predicated on managing topics as individual XML documents but that should never be a requirement.

Cheers,

E.

--
Eliot Kimber
http://contrext.com


On 2/19/20, 10:21 AM, "Chris Papademetrious" <main@dita-users.groups.io on behalf of chrispitude@gmail.com> wrote:

I tripped across a complication with the keyref-all-the-things approach. :(

In DITA, a glossary is implemented as a specialized topic (<glossgroup>) that contains terms as nested specialized subtopics (<glossentry>). Unfortunately this means that the map must define @keys values for all glossary terms. :( It's impractical to expect a writer to do this.

I'll ask our writers to use hrefs when referencing glossary terms, but I expect some pushback adding rules about requiring them to remember what kind of links to use where.

I wish DITA allowed ID-based references to subtopic elements nested within a topic, such as

<xref keyref="topic_key/subtopic_id"/>

as this still provides indirection value via the parent's key.

I found some discussion on this topic (hah!) in the comments section of

https://www.oxygenxml.com/dita/styleguide/webhelp-feedback/Artefact/Cross_Referencing/c_Links_to_Glossary_Terms.html

- Chris


Re: Keyref/conkey ref conversion strategy - keyref all the things? #conref

Chris Papademetrious
 

I tripped across a complication with the keyref-all-the-things approach. :(

In DITA, a glossary is implemented as a specialized topic (<glossgroup>) that contains terms as nested specialized subtopics (<glossentry>). Unfortunately this means that the map must define @keys values for all glossary terms. :(  It's impractical to expect a writer to do this.

I'll ask our writers to use hrefs when referencing glossary terms, but I expect some pushback adding rules about requiring them to remember what kind of links to use where.

I wish DITA allowed ID-based references to subtopic elements nested within a topic, such as

<xref keyref="topic_key/subtopic_id"/>

as this still provides indirection value via the parent's key.

I found some discussion on this topic (hah!) in the comments section of


 - Chris


custom ODT styles #DITA-OT #ODT

Vadim V. Balashoff
 

 Hello!

 How I can use custom styles file with org.dita.odt?
 Thank you.


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

John Piechowski
 

Thanks. Exactly what I was looking for.

Appreciate it.
John

On Wed, Feb 19, 2020 at 7:28 AM Chris Brand via Groups.Io <chrizzbee74=yahoo.com@groups.io> wrote:
Hi John

You could control the output of ISO or ANSI icons via the map. I use this technique in my PDF plugin to control for instance the layout (A4/US).

First you need to define a variable in roots-processing.xsl of your plugin:
   <xsl:variable name="ansi" select="(/*/opentopic:map/*[contains(@class, ' map/topicmeta ')]//*[contains(@class, ' topic/othermeta ')][@name='ansi']/@content)[1]"/>

In the Oxygen PDF plugin, you find a template that replaces the note icons. Copy it to your commons.xsl or custom.xsl and modify it to resemble something like this (other note types excluded for the sake of simplicity):
    <!-- Custom Oxygen note images for PDF -->
    <xsl:template match="*[contains(@class,' topic/note ')]" mode="setNoteImagePath">
        <xsl:variable name="noteType" as="xs:string">
            <xsl:choose>
                <xsl:when test="@type">
                    <xsl:value-of select="@type"/>
                </xsl:when>
                <xsl:otherwise>
                    <xsl:value-of select="'note'"/>
                </xsl:otherwise>
            </xsl:choose>
        </xsl:variable>
        <xsl:choose>
            <xsl:when test="$ansi='yes'">
                <xsl:choose>
                    <xsl:when test="$noteType = 'caution'">Customization/OpenTopic/common/artwork/important-ansi.png</xsl:when>
                    <xsl:when test="$noteType = 'danger'">Customization/OpenTopic/common/artwork/danger-ansi.png</xsl:when>
                    <xsl:when test="$noteType = 'warning'">Customization/OpenTopic/common/artwork/warning-ansi.png</xsl:when>
                    <xsl:otherwise>
                        <xsl:call-template name="getVariable">
                            <xsl:with-param name="id" select="concat($noteType, ' Note Image Path')"/>
                        </xsl:call-template>
                    </xsl:otherwise>
                </xsl:choose>           
            </xsl:when>
            <xsl:otherwise>
                <xsl:choose>
                    <xsl:when test="$noteType = 'caution'">Customization/OpenTopic/common/artwork/important-iso.png</xsl:when>
                    <xsl:when test="$noteType = 'danger'">Customization/OpenTopic/common/artwork/danger-iso.png</xsl:when>
                    <xsl:when test="$noteType = 'warning'">Customization/OpenTopic/common/artwork/warning-iso.png</xsl:when>
                    <xsl:otherwise>
                        <xsl:call-template name="getVariable">
                            <xsl:with-param name="id" select="concat($noteType, ' Note Image Path')"/>
                        </xsl:call-template>
                    </xsl:otherwise>
                </xsl:choose>
            </xsl:otherwise>       
        </xsl:choose>
    </xsl:template>

Make sure to copy all your icons to cfg\common\artwork of your plugin (they are probably already there).

In your map, add an <othermeta> element like this (if using a bookmap):
   <bookmeta>
      <othermeta name="ansi" content="yes"/>
   </bookmeta>

Now publish your map with this "switch" enabled and all icons should render in the ANSI style. If you don't set the variable, the ISO icons are taken.


Try it!

Chris.



Re: [Ann] Oxygen XML Suite Version 22.0 Release #Oxygen

cristi_talau@...
 

Hello,

We thought that in the future we may need to add other configuration options to a "prefix-replacement", for example:

  <prefix-replacement prefix="1.">
    <fragment>
      <ol><li></li></ol>
    </fragment>
    <disable-for-parent name="table-cell" namespace="http://something.com"/>
  </prefix-replacement>

The content of it, is the actual replacement. However, if "fragment" is optional to make the files more concise.

Best,
Cristian


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

Chris Brand
 

Hi John

You could control the output of ISO or ANSI icons via the map. I use this technique in my PDF plugin to control for instance the layout (A4/US).

First you need to define a variable in roots-processing.xsl of your plugin:
   <xsl:variable name="ansi" select="(/*/opentopic:map/*[contains(@class, ' map/topicmeta ')]//*[contains(@class, ' topic/othermeta ')][@name='ansi']/@content)[1]"/>

In the Oxygen PDF plugin, you find a template that replaces the note icons. Copy it to your commons.xsl or custom.xsl and modify it to resemble something like this (other note types excluded for the sake of simplicity):
    <!-- Custom Oxygen note images for PDF -->
    <xsl:template match="*[contains(@class,' topic/note ')]" mode="setNoteImagePath">
        <xsl:variable name="noteType" as="xs:string">
            <xsl:choose>
                <xsl:when test="@type">
                    <xsl:value-of select="@type"/>
                </xsl:when>
                <xsl:otherwise>
                    <xsl:value-of select="'note'"/>
                </xsl:otherwise>
            </xsl:choose>
        </xsl:variable>
        <xsl:choose>
            <xsl:when test="$ansi='yes'">
                <xsl:choose>
                    <xsl:when test="$noteType = 'caution'">Customization/OpenTopic/common/artwork/important-ansi.png</xsl:when>
                    <xsl:when test="$noteType = 'danger'">Customization/OpenTopic/common/artwork/danger-ansi.png</xsl:when>
                    <xsl:when test="$noteType = 'warning'">Customization/OpenTopic/common/artwork/warning-ansi.png</xsl:when>
                    <xsl:otherwise>
                        <xsl:call-template name="getVariable">
                            <xsl:with-param name="id" select="concat($noteType, ' Note Image Path')"/>
                        </xsl:call-template>
                    </xsl:otherwise>
                </xsl:choose>           
            </xsl:when>
            <xsl:otherwise>
                <xsl:choose>
                    <xsl:when test="$noteType = 'caution'">Customization/OpenTopic/common/artwork/important-iso.png</xsl:when>
                    <xsl:when test="$noteType = 'danger'">Customization/OpenTopic/common/artwork/danger-iso.png</xsl:when>
                    <xsl:when test="$noteType = 'warning'">Customization/OpenTopic/common/artwork/warning-iso.png</xsl:when>
                    <xsl:otherwise>
                        <xsl:call-template name="getVariable">
                            <xsl:with-param name="id" select="concat($noteType, ' Note Image Path')"/>
                        </xsl:call-template>
                    </xsl:otherwise>
                </xsl:choose>
            </xsl:otherwise>       
        </xsl:choose>
    </xsl:template>

Make sure to copy all your icons to cfg\common\artwork of your plugin (they are probably already there).

In your map, add an <othermeta> element like this (if using a bookmap):
   <bookmeta>
      <othermeta name="ansi" content="yes"/>
   </bookmeta>

Now publish your map with this "switch" enabled and all icons should render in the ANSI style. If you don't set the variable, the ISO icons are taken.


Try it!

Chris.



Re: How to constrain standard DITA topic type? #constraints

Frank Ralf
 

Hi Julio,

Thanks for your feedback. I agree with you in principle. However, the current use case is that images are only allowed within <fig> elements which makes them indeed children of another block element. "Naked" images like icons are currently not used. Therefore I think changing the default behavior for the display of images from "inline" to "block" is a valid solution.

And even if our customer is moving in the direction of using standard DITA instead of their customized DITA, we will have to keep this behavior because of the legacy DITA documentation that would break if we change the default behavior.

Kind regards,
Frank


Re: How to constrain standard DITA topic type? #constraints

Frank Ralf
 

Hi Eliot,

Many thanks for the quick reply and the pointer. Changing the catalog to point the OASIS-defined public IDs to my local shells was the missing link.

Best regards,
Frank


Re: creating Webhelp Publication TOC from Bookmap #Oxygen #HTML5

Radu Pisoi
 

Hi,

I cannot reproduce this issue with a sample bookmap having the following structure:
<bookmap>
<booktitle>...</booktitle>
<bookmeta>
...
</bookmeta>
<frontmatter>
...
</frontmatter>
<chapter>
...
</chapter>
<chapter>
...
</chapter>
<backmatter>
<booklists>
...
</booklists>
</backmatter>
</bookmap>

The build goes ahead, but does not create the Publication TOC on the left sidebar. Same thing with the Breadcrumbs. I have the parameter set to "yes" for both of these, but the TOC and the Breadcrumbs do not appear.
Is there something else that needs to be done if using a bookmap to create a Responsive Webhelp transformation?

The Publication TOC and Breadcrumbs are displayed by default, it is not necessary to set any parameter to display them.

Could you send us a sample bookmap on support@... to reproduce this problem?
-- 
Regards,
Radu
--
Radu Pisoi
<oXygen/>  XML Editor, Schema Editor and XSLT Editor/Debugger
http://www.oxygenxml.com
On 2/18/2020 9:32 PM, Matt Lorenzi via Groups.Io wrote:
So for better or worse, when we first created ditamaps in FrameMaker we created bookmaps - presumably to allow for chapter headings, frontmatter, etc.

Now in Oxygen, I would like to use the same ditamap (bookmap) I used to create a PDF to also create a Webhelp Responsive output. 

The build goes ahead, but does not create the Publication TOC on the left sidebar. Same thing with the Breadcrumbs. I have the parameter set to "yes" for both of these, but the TOC and the Breadcrumbs do not appear.

Is there something else that needs to be done if using a bookmap to create a Responsive Webhelp transformation?



  


creating Webhelp Publication TOC from Bookmap #Oxygen #HTML5

Matt Lorenzi <mjlorenzi@...>
 

So for better or worse, when we first created ditamaps in FrameMaker we created bookmaps - presumably to allow for chapter headings, frontmatter, etc.

Now in Oxygen, I would like to use the same ditamap (bookmap) I used to create a PDF to also create a Webhelp Responsive output. 

The build goes ahead, but does not create the Publication TOC on the left sidebar. Same thing with the Breadcrumbs. I have the parameter set to "yes" for both of these, but the TOC and the Breadcrumbs do not appear.

Is there something else that needs to be done if using a bookmap to create a Responsive Webhelp transformation?


Re: How to constrain standard DITA topic type? #constraints

Julio J Vazquez
 

The question really becomes, is the constraint required? If you have icons within your text, this constraint would break your formatting unless you compensate for it in your XSLT. If your writers are using best practices, images are not children of paragraphs, the constraint is unneeded. 

Julio J. Vazquez


Re: How to constrain standard DITA topic type? #constraints

ekimber@contrext.com
 

You would have to copy and modify the standard shells and/or change your catalog to point the OASIS-defined public IDs to your local shells for the corresponding topic types.

The whole point of local shells is that you control them...

Cheers,

E.

--
Eliot Kimber
http://contrext.com


On 2/18/20, 10:44 AM, "Frank Ralf" <main@dita-users.groups.io on behalf of frank.ralf@parson-europe.com> wrote:

Hello,

I have a constraint module <http://dita4practitioners.github.io/dita-specialization-tutorials/body/part-config-and-extend/tutorials/constraint-module/creating-constraint-module.html> (DTD-based) that sets the default value for the @placement attribute of the <image> tag to "break" instead of "inline" as the DITA standard does. I have integrated this constraint into my custom DITA topic types. But this constraint should also apply to standard DITA topics that are used together with my custom DITA topics. How can I apply the same constraint to standard DITA topics? Can I just copy the relevant topic type shells into the folder of my constraint module and integrate the constraint as described in http://dita4practitioners.github.io/dita-specialization-tutorials/body/part-config-and-extend/tutorials/constraint-module/constraint-domain-dtd-step-4.html?

Any pointers welcome.

Frank


Re: [Ann] Oxygen XML Suite Version 22.0 Release #Oxygen

Chris Papademetrious
 

Thanks Cristian! At the risk of turning this announcement thread into a detailed support case, I'd like to understand what <fragment> means. In the predefined rules, the ordered-list rule has it but the unordered-list rule does not:

  <!-- Ordered lists -->
  <prefix-replacement prefix="1.">
    <fragment>
      <ol><li></li></ol>
    </fragment>
  </prefix-replacement>

  <!-- Unordered lists -->
  <prefix-replacement prefix="-">
    <ul><li></li></ul>
  </prefix-replacement>

What does <fragment> mean/do?

Agreed that with #4, there is some complexity lurking there...

Thanks!

 - Chris


How to constrain standard DITA topic type? #constraints

Frank Ralf
 

Hello,

I have a constraint module (DTD-based) that sets the default value for the @placement attribute of the <image> tag to "break" instead of "inline" as the DITA standard does. I have integrated this constraint into my custom DITA topic types. But this constraint should also apply to standard DITA topics that are used together with my custom DITA topics. How can I apply the same constraint to standard DITA topics? Can I just copy the relevant topic type shells into the folder of my constraint module and integrate the constraint as described in http://dita4practitioners.github.io/dita-specialization-tutorials/body/part-config-and-extend/tutorials/constraint-module/constraint-domain-dtd-step-4.html?

Any pointers welcome.

Frank

1041 - 1060 of 46276