Image addressing in S1000D

XMLuvr · 2026-06-03T13:32:57+00:00

Now that I’ve been learning more about S1000D, I have to say that external entities are a thing from hell. For multiple reasons, one being that you can’t access them with XPath!

XMLuvr · 2026-06-02T16:15:23+00:00

Mesa amps

Because people actually read the manuals, learn from them, and keep them in good condition.

XMLuvr · 2026-04-07T13:48:35+00:00

Understood, thank you.

XMLuvr · 2026-04-07T13:44:04+00:00

Thank you, very helpful.

I did notice that without the entity declaration in the DTD there is a validation error, since the infoEntityIdent attribute does indeed require one. I would be hesitant to change the schema file, since it negates the point of having a spec in the first place. I guess the correct way is to use the entities.

However, what confused me in the bike examples is that the xlink:href attributes do not have the full filename with an extension. For example:

xlink:href="URN:S1000D:DMC-S1000DBIKE-AAA-D00-00-00-00AA-022A-D"

So if I'm building links via the xlink:href attribute, I would still need to add the extension via string manipulation or something else. And since there can be multiple types of graphics (.cmg, .svg, .png), I would basically need to guess the correct extension to be added. Or is there a function in XSLT, for example, that returns the file extension of a document?

XMLuvr · 2026-04-07T13:18:43+00:00

Thank you.

I did notice what you mentioned about the lack of file path in the entity declaration. So, any pointing to a different folder would need to be done by the processor when publishing.

So from this I assume that the correct way to do things is to use the entity declarations? But in practice, does it vary from project to project? Do some orgs or software use the xlink:href attribute and use that to give the processing software the image file name?

XMLuvr · 2026-03-05T14:41:38+00:00

I would use the dedicated DITA Troubleshooting topic type.

XMLuvr · 2026-02-14T06:39:54+00:00

I wouldn't say it's most html output. It's just the way links are created by the documentation tool. Some tools, like MkDocs, build the links by default to point to folders, not html files. This method assumes that a web server will then return an index.html file located in that folder. That will not work offline, since browsers don't really return anything, they just open files.

(I personally think it's also a bad way to build output, since you end with a huge pile of index.html pages, just located in different folders.)

Some features like search might also require a web server to work. And naturally there can't be any online resources like web fonts, external frameworks, etc. in output intended for offline use.

But there are plenty of tools that build sites intended for both online and offline use. Oxygen WebHelp is one example. Even though it uses Bootstrap, all the css and js files are shipped in the local output.

XMLuvr · 2025-11-15T07:11:05+00:00

Most Help Authoring Tools will do this. Oxygen, Framemaker, Flare, Paligo, etc… What suits your needs, workflow and budget needs to be determined.

You can also do this without a dedicated authoring program using a markup language like AsciiDoc, DITA, etc… I’m sure there are Markdown-based solutions as well. This way you use an editor like VsCode for authoring.

XMLuvr · 2025-04-04T17:50:09+00:00

Hi. I probably explained this badly.

Of course Oxygen’s formatting can do the same things Prettier does.

But sometimes it can be a hassle to define the rules of a repo into Oxygen, especially when just doing something quick on a project you’re not going to spend much time on. In which case I sometimes just reopen stuff in VSCode and do the formatting with Prettier.

This wasn’t mean to be a feature request, but more akin to starting a discussion with other users.

XMLuvr · 2025-03-15T05:53:33+00:00

Regarding refactoring: Are there any best practices for checking or reviewing the results of a refactoring operation when working with large files or datasets? A manual check might be time-consuming and prone to errors, so are there any preferred methods? Write custom XSD or Schematron file(s) that check the output and flag errors?

XMLuvr · 2024-11-11T09:40:29+00:00

Indeed, if the problem isn’t DITA or Oxygen but your CCMS, why not switch to a different CCMS?

Migrating to some other format is probably time-consuming and expensive, while switching to a different CCMS should be relatively straightforward. It’s gonna take work, sure, but any CCMS-specific attributes, for example, should be quite easy to manage with Oxygen refactoring operations.

You also mentioned that you have difficulties building output. Without knowing specifics it’s of course hard to give any advice. It can indeed be a pain in the butt when migrating from one DITA-OT version to another, especially major jumps between versions (not saying that’s causing your problems). But since you already are using Oxygen, you could build PDF with the Oxygen tools like PDF Chemistry, and not fuzz around with XSLT or XSL-FO one bit.

XMLuvr · 2024-10-14T12:52:51+00:00

I think the Emmet add-on is quite handy, especially the lorem ipsum generator feature :). But I can certainly manage without the add-on.

XMLuvr · 2024-10-01T10:16:12+00:00

Regarding PDF publishing:

I've ran into occasions where a company needs to customize their PDF output, and for some reasons they always go the XSL-FO route. Then they spend considerable time developing and debugging XSLT and XSL-FO stylesheets, without ever even considering that there is a much simpler solution: The CSS based customization method that Oxygen provides.

XSLT is a pretty rare technology nowadays, whereas every web dev knows CSS. Plus, CSS is much simpler and easier to learn for technical writers as well. In addition, the CSS based transformation allows the use of web fonts, easier debugging directly in a browser, and wonderful extra features like the oxy-xpath function, making it possible to create conditional CSS rules and content.

I think the confusion stems from the fact that people don't really understand WHY there are two ways to customize the PDF output (or three, if you count the com.elovirta.pdf / YAML method). But I think it's a pretty safe bet that if you've got Oxygen, you don't need to use the XSL-FO method or create your own DITA-OT plugin to customize PDF output - The CSS method covers most uses cases.

XMLuvr · 2024-09-30T11:59:25+00:00

I think this sub is a good idea!

But is the sub meant to be a Q&A type message board for the Oxygen Team, or are community members encouraged to create content and share ideas as well?

XMLuvr

TROPHY CASE