Date   

Re: Word2Dita?

Chris Brand
 

Did you try copy/paste the Word content (maybe chapter wise) into Oxygen? This way, tables, lists, etc. convert rather nicely to DITA elements. If it's just one doc and not x-numbers, I would do it manually. The effort with 85 pages cannot be that huge.

 

Also, there's a Word to Dita conversion function in Oxygen itself you might wanna try:

 

 

 

Greez,

Chris.

 

Von: main@dita-users.groups.io <main@dita-users.groups.io> Im Auftrag von Nancy Roberts
Gesendet: Mittwoch, 9. Juni 2021 23:37
An: main@dita-users.groups.io
Betreff: Re: [dita-users] Word2Dita?

 

Thanks! All we really need is DITA content that is clean enough for a reasonable import into Ixiasoft. None of us know XSLT, but we don't mind doing a little cleanup once we're in Ixia. It's an 85-pager that's almost all tables. If Word2Dita can get us cleanish tables in DITA, we're good. I'll definitely take you up on your kind offer if we run into any bumps.

Best,
Nancy


Re: Links that are both local and cross-deliverable in shared topics

Chris Papademetrious
 

Thanks Eliot! Excellent summary of the problem and the situation.

Your method #2 (adding a map-level @keyscope) is what I tried, but it doesn't seem to work in Oxygen. It doesn't form the cross-book links properly, and if I create them by hand, they don't resolve.

I will try method #1 tomorrow. However, I'm not sure how well it would work in practice, as the writers want to share entire chapters between books, with a variety of cross-references to both book within the chapters. Trying to create all the local/cross-book flavors of indirection links would be quite maddening!

The good news is, your reply and suggestion for method #2 gives me the confidence that this should be fixable in Oxygen. Thank you so much!

 - Chris


Re: Word2Dita?

ekimber@contrext.com
 

If it's just one doc just contact me offline and I'll convert it for you.

Word2DITA does really well with tables except for one known issue related to a particular row and column spanning use case.

Cheers,

E.

--
Eliot Kimber
http://contrext.com


On 6/9/21, 4:36 PM, "Nancy Roberts" <main@dita-users.groups.io on behalf of nanr93@gmail.com> wrote:

Thanks! All we really need is DITA content that is clean enough for a reasonable import into Ixiasoft. None of us know XSLT, but we don't mind doing a little cleanup once we're in Ixia. It's an 85-pager that's almost all tables. If Word2Dita can get us cleanish tables in DITA, we're good. I'll definitely take you up on your kind offer if we run into any bumps.

Best,
Nancy


Re: Word2Dita?

Nancy Roberts
 

Thanks! All we really need is DITA content that is clean enough for a reasonable import into Ixiasoft. None of us know XSLT, but we don't mind doing a little cleanup once we're in Ixia. It's an 85-pager that's almost all tables. If Word2Dita can get us cleanish tables in DITA, we're good. I'll definitely take you up on your kind offer if we run into any bumps.

Best,
Nancy


Re: Word2Dita?

ekimber@contrext.com
 

Yes, you can use the Word2DITA package by itself--it does not require any other part of the DITA4Publishers project.

It will require some setup to define the mapping from your Word documents to the DITA you want but it is definitely capable of generating DITA with whatever aspects you need and that should definitely be importable to Ixiasoft without issue. For example, you can create both maps and topics from the same set of Word paragraphs, including submaps, as long as you have appropriate paragraph styles (i.e., Heading 1, Heading 2, etc.).

Word2DITA requires a little familiarity with typical XML tools and, often, a little light XSLT work to get going but you can, for example, run it directly on the files inside a DOCX file from OxygenXML using the Archive Viewer and transformation configuration (which is how I almost always run it).

I tried to document Word2DITA well as I could in the time I had but it's not always easy to get going. Feel free to ask questions here or reach out to me directly if you have any difficulty getting it set up.

Beyond simply getting the transform running, the two main challenges are working out how the styles you have in your Word documents (or possibly don't yet have) should map to DITA structures and then expressing that as a Word2DITA style-to-tag map and then, if necessary, doing any post-processing cleanup on the mapping-generated DITA using XSLT through the Word2DITA "final fixup" extension point. Cleanup is usually pretty straightforward XSLT but it's still XSLT....

If your Word documents are consistently styled, even if it's with the built-in generic styles, you should be able to get a pretty good result.

If your Word documents are not consistently styled then it will be a bigger challenge--you will either need to do some cleanup on the Word docs to add the styles or make the styling more consistent (which you can often do with Word's advanced search and replace features) or put more work into Word2DITA preprocessing or post processing extensions. If your Word docs are just not consistent enough you may be better served by one of the commercial conversion services or Word conversion tools.

Word2DITA was designed specifically for environments where there is good control over the Word styling, such as in Publishing workflows where an Editor can ensure that manuscripts are styled appropriately before being converted to DITA. It is not intended to be (and will not work as) an "any Word to good DITA" transform.

That said...

Word2DITA will produce *parseable* DITA topics from any Word document *as long as* the first non-skipped paragraph in the document is mapped to a topic because any non-mapped paragraph in the Word document is automatically mapped to <p>. The result will probably not be that useful but is a result...

Cheers,

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


On 6/9/21, 1:54 PM, "Nancy Roberts" <main@dita-users.groups.io on behalf of nanr93@gmail.com> wrote:

Thank you, Eliot. Can I download and install Word2Dita by itself, or do I need the full dita4publishers project?

Also, once I'm done with the conversion, I want to import the DITA output into the Ixiasoft CMS. I assume there's no conflict there?

Thanks,
Nancy


Re: Word2Dita?

Nancy Roberts
 

Thank you, Eliot. Can I download and install Word2Dita by itself, or do I need the full dita4publishers project?

Also, once I'm done with the conversion, I want to import the DITA output into the Ixiasoft CMS. I assume there's no conflict there?

Thanks,
Nancy


Re: Word2Dita?

ekimber@contrext.com
 

The Word2DITA framework is a general Word-to-DITA conversion framework. It does not require DITA Open Toolkit in any way but because it is often used with DITA content it is packaged as a DITA Open Toolkit plug-in for convenience and you can run it as an OT plugin if it's useful to do so, although most people use it standalone I think.

Word2DITA is part of the larger DITA4Publishers project (dita4publishers.org) but to get the latest version you should go to the Word2DITA project directly:

https://github.com/dita4publishers/org.dita4publishers.word2dita/releases

The documentation for the Word2DITA framework is here:

http://www.dita4publishers.org/d4p-users-guide/user_docs/d4p-users-guide/word2dita/word2dita-intro.html

I do maintain the Word2DITA code (you can see there are some recent bug fixes) but I haven't had the bandwidth to package it as cleanly as I've wanted to, which is why it's a bit scattered about.

Cheers,

E.

--
Eliot Kimber
http://contrext.com


On 6/9/21, 1:38 PM, "Nancy Roberts" <main@dita-users.groups.io on behalf of nanr93@gmail.com> wrote:

Hi all,

For the first time since 2009, I need to convert a Word doc to DITA that is too big to be done manually. What is the Word2Dita plugin? What does it plug in to? The OT? My company uses the Ixiasoft CMS, if that makes a difference. Any advice is much appreciated.

Thanks,
Nancy


Re: Links that are both local and cross-deliverable in shared topics

ekimber@contrext.com
 

DITA 1.3 introduced the ability to author links between two root maps, which is what you want here.

(You can find a small working sample here: https://github.com/dita-community/dita-test-cases/tree/master/cross-deliverable-links)

The basic technique is you define a mapref with a @scope value of "peer" that points to the root map of the target document (the document you are linking to) and a @keyscope value by which you can then refer to keys in the target root map.

So for your example, in the map for Book A you would give Topic 1 the "Topic_01".

Topics used in Book A can refer to Topic one by the unqualified key "Topic_01": <xref keyref="Topic_01"/>

In the map for Book B you would create this keydef to associate a key scope for Book A:

Book B:

<map>
...
<mapref keyscope="book_A" scope="peer" href="..\BookA\book_a.ditamap" format="ditamap"/>
...
</map>

Then in a topic used in Book B you can refer to topic 1 as:

<xref keyref="book_A.Topic_01"/>

Per the rules we defined for scope="peer" in DITA 1.3, this explicitly means "Go to the topic with the key 'Topic_01' as declared in the root map associated with the key scope 'book_A' in this root map."

If you need to be able to have topics that refer to Topic_01 also shared between books A and B, you can enable having all references to Topic_01 be the same in one of two different ways:

1. Use another level of indirection that goes from a global key ("Topic_01") to the appropriately-qualified key in the context of a given map:

Book A:

<topicref keys="Topic_01" href="topics/topic-01.dita"/>

Book B:

Resource-only topicref that points to topic-01 used from Book A:

<keydef keys="Topic_01" keyref="book_a.Subject_of_Topic_01"/>

With this approach, topics can blindly refer to key "Topic_01" without worrying about where the topic is used.

2. Put a key scope name on the Book A map so that a scope-qualified reference to key "book_a.Topic_01" will resolve in the context of Book A as well as in Book B:

Book A:

<map keyscope="book_a" ...>
...
</map>

An unqualified reference to key "Topic_01" from Book A will still work because the key and reference will be in the same scope.

Note that OxygenXML supports resolution of cross-deliverable links in the editor, so you can use it to validate your content as authored.

Cheers,

E.


--
Eliot Kimber
http://contrext.com


On 6/9/21, 11:57 AM, "Chris Papademetrious" <main@dita-users.groups.io on behalf of chrispitude@gmail.com> wrote:

We have two books that share a common topic, called "Shared Topic":

Book A:

* Topic 1
* Topic 2
* Shared Topic

Book B:

* Topic 3
* Topic 4
* Shared Topic

In "Shared Topic", we want to include a cross-reference to "Topic 1", such that it is a local link in Book A and a cross-book link in Book B.

Each book has the other book defined as a peer book, with mapref-level keyscopes:

<bookmap>
<title>Book A</title>
<mapref href="bookB.ditamap" ... scope="peer" keyscope="B"/>
...
</bookmap>


<bookmap>
<title>Book B</title>
<mapref href="bookA.ditamap" ... scope="peer" keyscope="A"/>
...
</bookmap>

If I write <xref keyref="topic1"/>, the link works in book A but not book B.

If I write <xref keyref="A.topic1"/>, the link works in book B but not book A.

So I tried adding local (map-level) keyscopes to each book, which "2.3.4.2 Keyscopes" <http://docs.oasis-open.org/dita/dita/v1.3/errata02/os/complete/part2-tech-content/archSpec/base/keyScopes.html> suggests would allow references to A.* to resolve locally:

<bookmap keyscope="A">
<title>Book A</title>
<mapref href="bookB.ditamap" ... scope="peer" keyscope="B"/>
...
</bookmap>


<bookmap keyscope="B">
<title>Book B</title>
<mapref href="bookA.ditamap" ... scope="peer" keyscope="A"/>
...
</bookmap>

Unfortunately, Oxygen doesn't create cross-book links correctly with this map configuration - it concatenates the mapref-level and map-level keyscopes (for example, B.B.topic1 instead of B.topic1) instead of treating them as a union as described in the spec.

Has anyone run into this situation before, or am I charting new territory here?

- Chris

P.S. On the publishing side, we resolve cross-book links with this DITA-OT plugin <https://github.com/chrispy-snps/DITA-fix-xbook-html-links/>. So mostly, I just need to solve the authoring and DITA-correctness aspects.


Word2Dita?

Nancy Roberts
 

Hi all,

For the first time since 2009, I need to convert a Word doc to DITA that is too big to be done manually. What is the Word2Dita plugin? What does it plug in to? The OT? My company uses the Ixiasoft CMS, if that makes a difference. Any advice is much appreciated.

Thanks,
Nancy


Re: Anyone Using Elasticsearch to Index DITA Content?

Tony Chung
 

Following this conversation. I've seen the ELK stack gaining popularity in dev teams over the past few years and would be interesting to see how DITA analytics could benefit from this open source tool stack.

-Tony


Links that are both local and cross-deliverable in shared topics

Chris Papademetrious
 

We have two books that share a common topic, called "Shared Topic":

Book A:
  • Topic 1
  • Topic 2
  • Shared Topic
Book B:
  • Topic 3
  • Topic 4
  • Shared Topic
In "Shared Topic", we want to include a cross-reference to "Topic 1", such that it is a local link in Book A and a cross-book link in Book B.

Each book has the other book defined as a peer book, with mapref-level keyscopes:

<bookmap>
  <title>Book A</title>
  <mapref href="bookB.ditamap" ... scope="peer" keyscope="B"/>
  ...
</bookmap>

<bookmap>
  <title>Book B</title>
  <mapref href="bookA.ditamap" ... scope="peer" keyscope="A"/>
  ...
</bookmap>

If I write <xref keyref="topic1"/>, the link works in book A but not book B.

If I write <xref keyref="A.topic1"/>, the link works in book B but not book A.

So I tried adding local (map-level) keyscopes to each book, which "2.3.4.2 Keyscopes" suggests would allow references to A.* to resolve locally:

<bookmap keyscope="A">
  <title>Book A</title>
  <mapref href="bookB.ditamap" ... scope="peer" keyscope="B"/>
  ...
</bookmap>

<bookmap keyscope="B">
  <title>Book B</title>
  <mapref href="bookA.ditamap" ... scope="peer" keyscope="A"/>
  ...
</bookmap>

Unfortunately, Oxygen doesn't create cross-book links correctly with this map configuration - it concatenates the mapref-level and map-level keyscopes (for example, B.B.topic1 instead of B.topic1) instead of treating them as a union as described in the spec.

Has anyone run into this situation before, or am I charting new territory here?

 - Chris

P.S. On the publishing side, we resolve cross-book links with this DITA-OT plugin. So mostly, I just need to solve the authoring and DITA-correctness aspects.


Anyone Using Elasticsearch to Index DITA Content?

ekimber@contrext.com
 

In my current job role I'm contributing to an Elasticsearch-based application that is not in any way XML or DITA related. I am new to Elasticsearch but basically it uses the Apache Lucene full-text engine to index JSON data and then provide a bunch of useful search and retrieval services on top of that. It seems very cool.

However, except for the Elasticsearch Logstash tool's generic XML-to-JSON feature (designed primarily for indexing Windows XML logs I believe), there doesn't seem to be a dedicated documentation XML-to-Elasticsearch mechanism (at least I didn't find one in my initial brief searching).

But since the input to Elasticsearch is JSON there's no technical barrier to generating JSON from DITA content, but there would be some art to it.

In the DITA world we'd typically choose something like MarkLogic or XBase to do full-text searching on our content but Elasticsearch is widely used (and is open-source so it's free).

So I'm curious if anyone in the DITA community is using Elasticsearch to index their DITA content and if so, can you talk about it?

Cheers,

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


Generating header and map files in HTMLHelp

Bill Burns
 

Hello,

Developing a CHM plugin for a client. I noticed that the default CHM plugin does not generate mapping or header files from the resourceid values. Is this standard behavior, or is there some trick to getting the OT to generate these files?

Really hoping I don't have to develop that functionality myself.

Thanks,
--
Bill Burns
(737) 242-8678
--
We are [A] 


My recent e-mail

Kristen James Eberlein
 

Please ignore it; I mistakenly sent it here rather than the DITA TC, which was the intended recipient.

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)


Re: Chunking and topic titles

Nancy Roberts
 

I understand. Thanks for trying.

FWIW, this is the first time I've had an issue with it. But usually I only use chunking on the chapter or topic level, not on the map level.


Re: Chunking and topic titles

Michael McLoughlin
 

 I'm not familiar with Ixiasoft CCMS so I don't know if any of the stuff it adds could be to blame. Sorry I've been no help. 


Re: Chunking and topic titles

Nancy Roberts
 

Nothing suspicious that I can see. I can post the map, but without the actual titles for security reasons. 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE bookmap PUBLIC "-//VARONIS//DTD DITA Bookmap//EN" "varonis-bookmap-drm.dtd">
<bookmap chunk="to-content" id="haa1621958012532" xml:lang="en-us"
xmlns:ditaarch="http://dita.oasis-open.org/architecture/2005/">
<booktitle ixia_locid="247">
<mainbooktitle ixia_locid="248">Doc Title</mainbooktitle>
</booktitle>
<bookmeta>
<category ixia_locid="293">activity_new<data datatype="ixia-taxonomy-term"
id="tax1537881104487:tnd1607098826062" ixia_locid="294"
value="Varonis_Taxonomy_5.2/Activity"/></category>
<category ixia_locid="295">external_child<data datatype="ixia-taxonomy-term"
id="tax1537881104487:tnd1537881104602:tnd1620084380942" ixia_locid="296"
value="Varonis_Taxonomy_5.2/External/External"/></category>
<category ixia_locid="297">External<data datatype="ixia-taxonomy-term"
id="tax1537881104487:tnd1537881104602" ixia_locid="298"
value="Varonis_Taxonomy_5.2/External"/></category>
<category ixia_locid="299">product_name<data datatype="ixia-taxonomy-term"
id="tax1537881104487:tnd16070987296911:tnd1621267227331" ixia_locid="300"
value="Varonis_Taxonomy_5.2/Product/DatAdvantage Cloud"/></category>
<category ixia_locid="301">product_new<data datatype="ixia-taxonomy-term"
id="tax1537881104487:tnd16070987296911" ixia_locid="302"
value="Varonis_Taxonomy_5.2/Product"/></category>
<category ixia_locid="303">external_integration_new<data datatype="ixia-taxonomy-term"
id="tax1537881104487:tnd1607098826062:tnd1607098840548" ixia_locid="304"
value="Varonis_Taxonomy_5.2/Activity/External Integration"/></category>
<category ixia_locid="305">product_deployment<data datatype="ixia-taxonomy-term"
id="tax1537881104487:tnd1607098826062:tnd1614633721413" ixia_locid="306"
value="Varonis_Taxonomy_5.2/Activity/Product Deployment"/></category>
</bookmeta>
<frontmatter ixia_locid="54">
 
<booklists ixia_locid="57">
<toc ixia_locid="58"/>
</booklists>
 
</frontmatter>
<chapter ixia_locid="246" keyref="rmk1537989721249" outputclass="subjectscheme"
processing-role="resource-only" scope="external"/>
<containerref href="yos1619187593532.ditamap" ixia_locid="249"/>
 
<chapter ixia_locid="290" keyref="are1621958037792">C1 - Integration Overview</chapter>
 
<chapter ixia_locid="292" keyref="qzj1621958060256">T1 - Deployment Steps</chapter>
</bookmap>


Re: Chunking and topic titles

Michael McLoughlin
 

Is there anything other than text in the T1 topic title - a conkeyref, or a maybe special character?

What output format are you using? 

Maybe you could post your map?


Re: Chunking and topic titles

Nancy Roberts
 

Hi Michael,

Yes - it didn't work.

Thanks,
Nancy


Re: Chunking and topic titles

Michael McLoughlin
 

Did you try an explicit toc="yes" in the T1 topicref?

41 - 60 of 46295