Date   

Re: Reuse - best practices #reuse

ekimber@contrext.com
 

I agree that avoiding having topics specific to publication A directly reuse topics specific to (or organized as part of) publication B is a bad idea, just as doing conrefs to content in topics that are not explicitly warehouse topics is a good idea.

For that reason I'm partial to the common folder approach.

Beyond that I find that having one folder per organizing structure (i.e., part, chapter, etc.) works well. With that structure it then makes sense to have a map per directory.

That establishes a pattern where each directory in your document structure is represented by a map and the resources specific to that structure. Depending on the volume of data I find it then makes sense to have subdirectories for topics, media, etc., so that your structure starts to look like:

Pub-01.ditamap
Pub-01/
Chapter-01/
Chapter-01.ditamap
topics/
media/
Chapter-02/
Chapter-02.ditamap
topics/
media/
common/
...

Within a common directory it usually makes sense to organize either by topic type (concepts, reference, tasks, etc.) or by subject area, basically, what will be most general and make most sense to users trying to find things.

Note that in the structure above the root maps for each publication are above the directories for each publication's content, in order to avoid issues with having references from root maps to files that are not directly beneath the map in the file system.

Cheers,

Eliot
--
Eliot Kimber
http://contrext.com


On 2/28/20, 4:13 PM, "Matt Lorenzi via Groups.Io" <main@dita-users.groups.io on behalf of mjlorenzi=yahoo.com@groups.io> wrote:

I know this thread is a can of worms, but here we go anyway. How does one best organize content for maximum content reuse?

I know ideally you would do some serious information architecture to strategize where to put everything. But in some cases you inherit a folder structure and it's too far along to backtrack.

Is there a resource for a high-level overview of folder/file structure for content reuse?

I want to try and avoid referencing topics from Document A into Document B, C, D, etc....then topics from Document B into Document A, C, D. You see where I am going with this.
Is it best to put all imaginable common content into COMMON folder and go from there? OR, should I not even worry about it and leave it up to the ditamap? Ditamap does not care where the files reside, but as a content author you want to know where the most commonly used topics reside.

My next question would be on profiling and how to best address that, but let's stick to folder structure for now.


Reuse - best practices #reuse

Matt Lorenzi
 

I know this thread is a can of worms, but here we go anyway. How does one best organize content for maximum content reuse?

I know ideally you would do some serious information architecture to strategize where to put everything. But in some cases you inherit a folder structure and it's too far along to backtrack.

Is there a resource for a high-level overview of folder/file structure for content reuse?

I want to try and avoid referencing topics from Document A into Document B, C, D, etc....then topics from Document B into Document A, C, D. You see where I am going with this. 
Is it best to put all imaginable common content into COMMON folder and go from there? OR, should I not even worry about it and leave it up to the ditamap? Ditamap does not care where the files reside, but as a content author you want to know where the most commonly used topics reside. 

My next question would be on profiling and how to best address that, but let's stick to folder structure for now.


[ANN] Release of XMLmind XSL-FO Converter v6.2 #XMLmind

Hussein Shafie
 

Release of XMLmind XSL-FO Converter v6.2. Highlights:

- XMLmind XSL-FO Converter engine: element fo:block-container with a reference-orientation attribute equal to 90, 270, -90 or -270 may be used to temporarily switch the page orientation from portrait to landscape. This feature is typically used to help MS-Word or OpenOffice/LibreOffice display a wide table or a wide figure.

- XMLmind XSL-FO Converter engine for .NET: upgraded the .NET implementation of the Java™ runtime needed to run XMLmind XSL-FO Converter to IKVM.NET 8.1.5717.0 (which corresponds to Java 1.8.0_45).

- Updated several software components in XMLmind XSL Utility and XMLmind XSL Server, and most notably XMLmind Web Help Compiler. Thanks to XMLmind Web Help Compiler v3.x, the generated Web Help gets a fresh new look, among several other useful enhancements. For example, the Web Help is now “responsive” by default.

More information in https://www.xmlmind.com/foconverter/changes.html

---------------------------------
What is XMLmind XSL-FO Converter?
---------------------------------

XMLmind XSL-FO Converter is an XSL-FO processor similar to Apache FOP, RenderX XEP or Antenna House XSL Formatter, except that it generates RTF, WML, ODT and DOCX file formats rather than PDF.

More importantly, this commercial product comes with a handy desktop application called "XMLmind XSL Utility" (https://www.xmlmind.com/foconverter/xsl_utility.html) which makes it easy converting DITA, DocBook, XHTML and XSL-FO documents to a variety of formats (PDF, RTF, WML, ODT, DOCX, HTML, EPUB, Web Help, etc).

XMLmind XSL Utility also makes it easy customizing the deliverables it generates (PDF, DOCX, EPUB, Web Help, etc) and this, without modifying configuration files by hand and without prior knowledge of XSLT. See https://www.xmlmind.com/foconverter/_distrib/xslutil/doc/help/com.xmlmind.xslutil.ConversionEditor.html#customizing_xslt

Home page: https://www.xmlmind.com/foconverter/


Re: DITA XML to JSON conversion #JSON

patrick.wright73@...
 

Thank you for the comments and feedback.  Chris - what you describe is what we hope to accomplish. Provide microcontent (of a sort) to an application as XML and reuse that content in the future in other forms and more formal technical documents. The application prefers JSON, but was willing to convert from DITA XML if needed. The first type of DITA was simple glossary entries with nothing aside from term and definition.

Could I contact you off list? I'm at patrick.wright73@gmail and can use almost any video conference. Much appreciated.

Pat


New path #consulting

Bill Burns
 

Greetings,

 

My position at Healthwise has ended, and I’m available for XML/DITA/CCMS consulting engagements or positions. I can be reached at wdburns63@....

 

Regards,

Bill Burns

wdburns63@...

+1.208.794.5709

 


Re: Adjusting the Oxygen Responsive Webhelp plugin - I need help #Oxygen

Matt Lorenzi
 

Hi Pieterjan,
Thanks for this! Great little hack. 


Re: Word wrapping in tables for PDF #PDF #tables

Zoë Lawson
 

Sorry, I wasn’t clear, I am doing this in the XSLT. I probably found Elliot’s suggestion back when I started this 2-4 months ago.

I’m just trying to figure out which template to work with next. I can see advantages and disadvantages for each approach and was looking for a second opinion.

Thanks,
Zoë

Zoë Lawson


From: main@dita-users.groups.io <main@dita-users.groups.io> on behalf of Radu Coravu <radu_coravu@...>
Sent: Wednesday, February 26, 2020 1:59:05 AM
To: main@dita-users.groups.io <main@dita-users.groups.io>; dita-users@groups.io <dita-users@groups.io>
Subject: Re: [dita-users] Word wrapping in tables for PDF
 
Hi Zoë,

Doing this kind of fix directly in the DITA content does not seem very
scalable.
In older threads Eliot Kimber suggested doing this in the XSLT code:

https://dita-users.groups.io/g/main/topic/48666312

Something like:

>     <xsl:template match="*[contains(@class, ' topic/entry ')]/text()">
>         <xsl:value-of select="local:addBreakPointsToString(.)"/>
>     </xsl:template>
>     <xsl:function name="local:addBreakPointsToString" as="xs:string">
>         <xsl:param name="text" as="xs:string"/>
>         <xsl:variable name="result" as="xs:string" select="local:insertBreakPoints($text, ())"/>
>         <xsl:sequence select="$result"/>
>     </xsl:function>
>     <xsl:function name="local:insertBreakPoints" as="xs:string">
>         <xsl:param name="text" as="xs:string?"/>
>         <xsl:param name="resultString" as="xs:string?"/>
>         <xsl:choose>
>             <xsl:when test="not($text)">
>                 <xsl:sequence select="$resultString"/>
>             </xsl:when>
>             <xsl:otherwise>
>                 <xsl:variable name="pre" select="substring($text, 1, 5)" as="xs:string"/>
>                 <xsl:variable name="rest" select="substring($text, 6)" as="xs:string?"/>
>                 <xsl:sequence
>                     select="local:insertBreakPoints($rest, concat($resultString, '&#x200b;’, $pre)"
>                 />
>             </xsl:otherwise>
>         </xsl:choose>
>     </xsl:function>

In our custom DITA to PDF using CSS output there are various properties
which can be set to help with this:

https://www.oxygenxml.com/doc/ug-pdf-css/topics/dcpp_tables.html#ariaid-title4

Regards,
Radu

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

On 2/25/2020 5:11 PM, Zoë Lawson wrote:
> Greetings!
>
> Somewhere I found the fun and exciting workaround for word wrapping in
> tables where you insert zero width spaces between camel-case letters,
> before _ . , : etc.
> I did this for “code” type elements, since that’s where most of the
> “non-traditional hyphenation” stuff comes in. It’s working reasonably well.
>
> Of course, now I have a xref to a topic with a camel-cased word in the
> title, and it’s not word-wrapping. The camel-cased word is in a
> paramname, which has the zero space shenanigans, but the paramname is
> not getting carried along to the xref text.
>
> What’s the best way to approach this?
> Add word wrapping shenanigans to all xref?
> Try to get the paramname pulled along in the xref?
>
> Thanks,
> Zoë
>
>
>
> Zoë Lawson
>







Re: Adjusting the Oxygen Responsive Webhelp plugin - I need help #Oxygen

Pieterjan Vandenweghe
 

Hi Matt,

I usely do the following when I don't want to see the default footer in the webhelp.
  1. I open my Webhelp transformation scenario in OxygenXML.
  2. In the Parameters I search for the parameter webhelp.fragment.footer.
  3. I double click on the parameter and simply add a space in the Value: field.
You will not have the default footer anymore when you run the transformation scenario again.

Kind regards,
Pieterjan


Re: Word wrapping in tables for PDF #PDF #tables

Radu Coravu
 

Hi Zoë,

Doing this kind of fix directly in the DITA content does not seem very scalable.
In older threads Eliot Kimber suggested doing this in the XSLT code:

https://dita-users.groups.io/g/main/topic/48666312

Something like:

<xsl:template match="*[contains(@class, ' topic/entry ')]/text()">
<xsl:value-of select="local:addBreakPointsToString(.)"/>
</xsl:template>
<xsl:function name="local:addBreakPointsToString" as="xs:string">
<xsl:param name="text" as="xs:string"/>
<xsl:variable name="result" as="xs:string" select="local:insertBreakPoints($text, ())"/>
<xsl:sequence select="$result"/>
</xsl:function>
<xsl:function name="local:insertBreakPoints" as="xs:string">
<xsl:param name="text" as="xs:string?"/>
<xsl:param name="resultString" as="xs:string?"/>
<xsl:choose>
<xsl:when test="not($text)">
<xsl:sequence select="$resultString"/>
</xsl:when>
<xsl:otherwise>
<xsl:variable name="pre" select="substring($text, 1, 5)" as="xs:string"/>
<xsl:variable name="rest" select="substring($text, 6)" as="xs:string?"/>
<xsl:sequence
select="local:insertBreakPoints($rest, concat($resultString, '&#x200b;’, $pre)"
/>
</xsl:otherwise>
</xsl:choose>
</xsl:function>
In our custom DITA to PDF using CSS output there are various properties which can be set to help with this:

https://www.oxygenxml.com/doc/ug-pdf-css/topics/dcpp_tables.html#ariaid-title4

Regards,
Radu

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

On 2/25/2020 5:11 PM, Zoë Lawson wrote:
Greetings!
Somewhere I found the fun and exciting workaround for word wrapping in tables where you insert zero width spaces between camel-case letters, before _ . , : etc.
I did this for “code” type elements, since that’s where most of the “non-traditional hyphenation” stuff comes in. It’s working reasonably well.
Of course, now I have a xref to a topic with a camel-cased word in the title, and it’s not word-wrapping. The camel-cased word is in a paramname, which has the zero space shenanigans, but the paramname is not getting carried along to the xref text.
What’s the best way to approach this?
Add word wrapping shenanigans to all xref?
Try to get the paramname pulled along in the xref?
Thanks,
Zoë
Zoë Lawson


Re: Adjusting the Oxygen Responsive Webhelp plugin - I need help #Oxygen

Matt Lorenzi
 

Rather than start a new thread I will see if I can add my simple question here. I would like to disable the default footer text on my Webhelp Responsive transformation.  I know I can point to a new HTML file to override the Generated by <oXygen/> XML WebHelp blurb that shows by default.

Is this a parameter that has a true/false argument that can be toggled? I'd be happy just deleting the content of the default blurb for now.


Word wrapping in tables for PDF #PDF #tables

Zoë Lawson
 

Greetings!

Somewhere I found the fun and exciting workaround for word wrapping in tables where you insert zero width spaces between camel-case letters, before _ . , : etc. 
I did this for “code” type elements, since that’s where most of the “non-traditional hyphenation” stuff comes in. It’s working reasonably well. 

Of course, now I have a xref to a topic with a camel-cased word in the title, and it’s not word-wrapping. The camel-cased word is in a paramname, which has the zero space shenanigans, but the paramname is not getting carried along to the xref text. 

What’s the best way to approach this?
Add word wrapping shenanigans to all xref?
Try to get the paramname pulled along in the xref?

Thanks,
Zoë 



Zoë Lawson


Re: DITA XML to JSON conversion #JSON

despopoulos_chriss
 

@Zoë  Interesting...  That's exactly what we're doing.  We have a transform service that is part of our GUI app, and we give it a topic file and an XSLT file.  In the case of tours (we also customized them) we transform a task to JSON, where the intro section is the first tour panel, and then each task step is a specific tour panel.  We give metadata to the DITA that describes the HTML page the tour panel points to, and includes the CSS selector on that page to specifically point to a GUI item. 

What's neat is that we can single-source our docs not only as PDF and online help, but now micro-content.  We use the same transform service to give content to other embedded help panels that are tied to specific GUI widgets.  Because we pass the XSLT to the service, that means we can transform our content to whatever the display widget needs...  Be it XML, HTML, or JSON.  And we do it real-time, so we can use keyrefs and filter by audience, depending on the product flavor or brand that's currently running. 

Anyway, while it would be way specific, if you wanted to see our transforms we could share them...  It's nothing proprietary AFIK.  Like Zoë, we use a very limited subset of the DITA standard, and we do very specific things with it.  I think the first thing you would need to state is the scope of your problem.  How specific is the JSON you want, and how much of the DITA standard do you need to support?


Re: DITA XML to JSON conversion #JSON

Nicholas Mucks
 

We convert dita to json so that a ditamap structure can feed a python app. It’s a lot like creating a text output.

What’s your json data structure?


Take care,
- Nick

Sent from mobile

On Feb 24, 2020, at 12:15 PM, "ekimber@..." <ekimber@...> wrote:

Note that XSLT 3 (supported by recent Saxon versions, so including latest OT 2.x and 3.x versions) has features for reading and writing JSON, so if you know what the JSON should look like it shouldn't be too hard to generate it. There's also a generic JSON serialization option but it's unlikely it would provide satisfactory results due to the inherent difficulty in mapping from XML to JSON.

I think the larger challenge is probably knowing what the JSON should look like--that's going to be very specific to the consumer of the JSON.

Cheers,

Eliot
--
Eliot Kimber
http://contrext.com


On 2/24/20, 11:43 AM, "main@dita-users.groups.io on behalf of patrick.wright73@..." <main@dita-users.groups.io on behalf of patrick.wright73@...> wrote:

Is anyone converting DITA to JSON format? I've seen OT plugins to convert JSON to DITA topics, and Oxygen (and other) single-file converters for JSON to DITA. But I'm curious if there is either a bulk conversion tool available (for DITA->JSON) or a toolkit plugin to convert a map's worth of topics.

Thank you.
Pat








Re: Normalized DITA and keys #keys

Dawn.Bunting@...
 

Thanks Radu.  As always, you are correct.

I can see now that I was expecting the resolved topic to just have text in place, and not still contain the keyref element, because that is what the conrefs do., and so I did not note that the text had been put in. 

What I really want as an end is just text, but I see now that after I normalize the dita, ( using your example code)  I can just use LXML in a script to remove the <ph keyref="abc"> and the </ph> and I will be left with the simple text I am looking for.

Many thanks!


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

Stuart Norton
 

Thanks all for your input!

FWIW, we discovered that the image element is actually permitted inside of <data>, as well, so it looks like we will probably go with that:
<data name="cover-image"><image href="cover-image1.png"/></data>

Thanks again,
Stuart


Juniper Business Use Only

-----Original Message-----
From: main@dita-users.groups.io <main@dita-users.groups.io> On Behalf Of Radu Coravu
Sent: Sunday, February 23, 2020 10:35 PM
To: main@dita-users.groups.io
Subject: Re: [dita-users] Best way to represent images at the book/cover page level

Hi,

In Oxygen XML Editor if the DITA Map is opened in the main editing area in the Author editing mode you can get the <data> image reference to appear as an image with a small CSS customization:

data[href]{
content: attr(href, url);
}
https://urldefense.com/v3/__https://blog.oxygenxml.com/topics/customizeDITACSS.html__;!!NEt6yMaO-gk!UXJiiGY6HqOqA1xkbW__B7PMJeXU93Kr1koYCmYQLAgS67SRMvwLfRJqf5cVrMk$

Regards,
Radu

Radu Coravu
<oXygen/> XML Editor
https://urldefense.com/v3/__http://www.oxygenxml.com__;!!NEt6yMaO-gk!UXJiiGY6HqOqA1xkbW__B7PMJeXU93Kr1koYCmYQLAgS67SRMvwLfRJqmzwUgTE$

On 2/22/2020 6:41 PM, Tom Magliery wrote:
Some editors can be customized (relatively easily, and by you) to
recognize any element as an image to be displayed while editing.
XMetaL can do this. I don't know about oXygen.

In XMetaL's case, with DITA maps, this would only apply to the "XML
view" of the map (as opposed the usual side-panel "map editor"). Note
that the "XML view" is a slight misnomer as this is a WYSIWYG-like view.

mag
--
Tom Magliery
I worked at XMetaL for a year or 17


Re: DITA XML to JSON conversion #JSON

ekimber@contrext.com
 

Note that XSLT 3 (supported by recent Saxon versions, so including latest OT 2.x and 3.x versions) has features for reading and writing JSON, so if you know what the JSON should look like it shouldn't be too hard to generate it. There's also a generic JSON serialization option but it's unlikely it would provide satisfactory results due to the inherent difficulty in mapping from XML to JSON.

I think the larger challenge is probably knowing what the JSON should look like--that's going to be very specific to the consumer of the JSON.

Cheers,

Eliot
--
Eliot Kimber
http://contrext.com


On 2/24/20, 11:43 AM, "main@dita-users.groups.io on behalf of patrick.wright73@..." <main@dita-users.groups.io on behalf of patrick.wright73@...> wrote:

Is anyone converting DITA to JSON format? I've seen OT plugins to convert JSON to DITA topics, and Oxygen (and other) single-file converters for JSON to DITA. But I'm curious if there is either a bulk conversion tool available (for DITA->JSON) or a toolkit plugin to convert a map's worth of topics.

Thank you.
Pat


Re: DITA XML to JSON conversion #JSON

Zoë Lawson
 

Sorry, bad link. Try http://metadita.org/toolkit/morse.html

Zoë Lawson


From: main@dita-users.groups.io <main@dita-users.groups.io> on behalf of Zoë Lawson <zoelawson17@...>
Sent: Monday, February 24, 2020 3:08:54 PM
To: main@dita-users.groups.io <main@dita-users.groups.io>
Subject: Re: [dita-users] DITA XML to JSON conversion
 
Technically I am, but I’m doing something extremely specific.
We’re using a tour js (like hopscotch or bootstrap.js, but customized for our environment), so I’m only converting task topics and I’m really limiting what elements I’m using.

I don’t have anything really shareable. I think I started with a DITA to text transform, based on Robert Anderson’s http://metadita.org/toolkit/Morse.html

Zoë

Zoë Lawson

From: main@dita-users.groups.io <main@dita-users.groups.io> on behalf of patrick.wright73@... <patrick.wright73@...>
Sent: Monday, February 24, 2020 12:43:55 PM
To: main@dita-users.groups.io <main@dita-users.groups.io>
Subject: [dita-users] DITA XML to JSON conversion
 
Is anyone converting DITA to JSON format? I've seen OT plugins to convert JSON to DITA topics, and Oxygen (and other) single-file converters for JSON to DITA. But I'm curious if there is either a bulk conversion tool available (for DITA->JSON) or a toolkit plugin to convert a map's worth of topics. 

Thank you.
Pat


Re: DITA XML to JSON conversion #JSON

Zoë Lawson
 

Technically I am, but I’m doing something extremely specific.
We’re using a tour js (like hopscotch or bootstrap.js, but customized for our environment), so I’m only converting task topics and I’m really limiting what elements I’m using.

I don’t have anything really shareable. I think I started with a DITA to text transform, based on Robert Anderson’s http://metadita.org/toolkit/Morse.html

Zoë

Zoë Lawson


From: main@dita-users.groups.io <main@dita-users.groups.io> on behalf of patrick.wright73@... <patrick.wright73@...>
Sent: Monday, February 24, 2020 12:43:55 PM
To: main@dita-users.groups.io <main@dita-users.groups.io>
Subject: [dita-users] DITA XML to JSON conversion
 
Is anyone converting DITA to JSON format? I've seen OT plugins to convert JSON to DITA topics, and Oxygen (and other) single-file converters for JSON to DITA. But I'm curious if there is either a bulk conversion tool available (for DITA->JSON) or a toolkit plugin to convert a map's worth of topics. 

Thank you.
Pat


DITA XML to JSON conversion #JSON

patrick.wright73@...
 

Is anyone converting DITA to JSON format? I've seen OT plugins to convert JSON to DITA topics, and Oxygen (and other) single-file converters for JSON to DITA. But I'm curious if there is either a bulk conversion tool available (for DITA->JSON) or a toolkit plugin to convert a map's worth of topics. 

Thank you.
Pat


Re: Closing void elements in HTML5 (writing HTML5 serialized as XML) #HTML5

Radu Coravu
 

Hi Chris,

Indeed probably a simple DITA OT customization plugin cannot override this setting.
You would need a DITA OT plugin which adds a custom XHTML5 transtype which has its own top-level XSLT stylesheet importing the HTML5 one:

<xsl:import ref="plugin:org.dita.html5:xsl/dita2html5Impl.xsl"/>
and then declaring the xsl:output. That's how we do things for our WebHelp responsive output.

Or in the tool which consumes the HTML5 output add some pre-processing stage using an HTML to XHTML convertor like HTMLTidy or Neko HTML.

Regards,
Radu

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

On 2/23/2020 3:15 AM, Chris Papademetrious wrote:
I don't think xsl:output can be overridden from a plugin. According to the precedence description in section 26 at
https://www.w3.org/TR/xslt-30/#serialization
and the import precedence rules at
https://www.w3.org/TR/xslt-30/#import
the top-level module will always win over the imported modules (I think).
 - Chris