DTD declaration

rhofitz · Post by **rhofitz** » Wed Sep 03, 2008 12:08 pm

Can someone explain why MadCap is using a different DTD declaration than the standard?

<html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd">

This is causing a problem with searching our .htm files in Eclipse help. If we change the DTD declaration to:

<html xmlns="http://www.w3.org/1999/xhtml" lang="EN-US">

the problem goes away. However, each time I generate the output, Eclipse changes the DTD back to the Madcap DTD so we'd have to keep replacing this each time we generate. Is there any way to override this?

Post by **RamonS** » Wed Sep 03, 2008 1:18 pm

Eclipse is not the one changing it back to the original, it is Flare itself. I am surprised that a name space declaration throws Eclipse off. Is Eclipse help a particular format? The name space declaration is intended to give each schema its unique name and thus typically points to a URL, which is unique per definition. While I understand the annoyance of that getting changed back, the issue is in Eclipse, not Flare.

pdenchfield · Post by **pdenchfield** » Wed Sep 03, 2008 1:55 pm

I don't use Eclipse but I join the original poster in wondering why MadCap uses a DTD declaration from its website. I am an XML amateur but this proprietary website pointer for the .xsd file raises red flags for me.

Post by **doc_guy** » Wed Sep 03, 2008 3:32 pm

David,

Yes, Eclispe has its own help format. Flare doesn't have an Eclipse output format (as you know). So I can understand the confusion here.

Pamela,

It's not the big mystery you insinuate. Its really not that big of a deal, and it is totally normal for a product that uses a customized version of XML, which Flare does. (See my explanation below)

Rhofitz, et. al.:
Madcap needs to use a proprietary DTD because the markup in Flare's XML is specific to MadCap products. Things like cross references, expanding text, index entries, and the like are all done with XML that isn't part of the XHTML standard. The validity of this markup has to confirmed by a DTD somewhere that lists what valid markup is for the XML variant used by Flare.

The XML is still open. You can still change it, edit it, covert is to whatever format you want. But MadCap has to adhere to some DTD SOMEWHERE, and all the extra code simply isn't valid XHTML. Which is to be expected. XHTML can't do what Flare does. That's why we need Flare. And for Flare to base it's file format in XML, they have to create a DTD of valid markup.

Anyway, what happens if you leave the namespace the way Eclipse changes it? Does the help system work? If so, I'd just let Eclipse change it however it wants and use the output. If it isn't working, then I'm not sure what to tell you... Maybe you should do what I've done and submit a feature request for Eclipse help output:

https://www.madcapsoftware.com/bugs/submit.aspx

Post by **RamonS** » Thu Sep 04, 2008 5:54 am

Interesting stuff...I once tried Eclipse as development environment for PHP and there are many reasons why I no longer use it. I wonder what is so special about Eclipse help and why they didn't go with JavaHelp. After all, Eclipse is designed for Java, which is why it doesn't cut it when shoehorning something else into it, such as PHP. But even then, since Flare doesn't do JavaHelp it wouldn't make much difference.
As Paul pointed out, there is nothing wrong with the DTD and name space declaration that Flare uses, in fact, it has to be that way.

Post by **RamonS** » Thu Sep 04, 2008 6:04 am

Intrigued by this unknown Eclipse help format I came across this page:
http://www.ibm.com/developerworks/opens ... os-echelp/
It explains on how to put Eclipse help together. It should be possible to use the XHTML output files from Flare for the topics and rebuild the Eclipse format. It appears as that the difference is in how the ToC is generated.

rhofitz · Post by **rhofitz** » Thu Sep 04, 2008 8:30 am

Thanks for all your replies.

First, a little bit about Eclipse help. The product we are documenting runs on the Eclipse platform. This is why we need to produce Eclipse help format. We are using Flare to do this by generating WebHelp. We then run a Korn Shell script against the output to rearrange the TOC tags in the TOC that Flare produces. What we actually deliver for our Eclipse help (called Eclipse help plugins) is just the HTML output, images, the CSS, and TOC file. Eclipse help has its own search engine built into it. None of the help authoring tools support Eclipse help format "out of the box", besides the latest version of Epublisher Pro, but our source is already in HTML (we do use Epub Pro for other systems, where our source is in Frame). Before Flare, we were using RoboHTML X5. We didn't like the latest version of Robo so we wanted to move away from it. And, with Flare's ability to import Robo projects, plus the fact that we also need to produce PDF and WebHelp for these systems, we chose Flare, realizing that it would not be a perfect fit. However, I am told that Madcap is looking at supporting DITA in a future release (which would lend itself to producing Eclipse help) and I have put in Eclipse help format as a request.

I have logged a bug with Eclipse about it's problem with the madcap DTD declaration, it is a bug in Eclipse. But won't be fixed until the next release of Eclipse. So, I need a stop gap solution. Since Madcap keeps changing the DTD declaration in the output back to the Madcap one, my plan is to update our korn shell script to change the DTD declaration to the standard one. However, if I do this, will this break the HTML files? We aren't doing anything "fancy" like drop down text, etc. In fact, we don't even ship the scripts with our help plugins since we don't use any of that. The only special functionality I can think of is we are using cross-references, but I gather that these are updated during build time, not after the fact?

Post by **doc_guy** » Thu Sep 04, 2008 8:38 am

It sounds to me like your solution will work.

One of the products I document is also created with Eclipse, but I just ship WebHelp, and we require them to view the help in a browser. It's not the native Eclipse format, obviously, but it is sufficient for us for now (though an Eclipse help output would be ideal).

I'm almost certain that you can change the DTD declaration back to the Eclipse-supported one, and it will work fine. I actually think that the browser doesn't even check the DTD before delivering up the help; it just wants to know that it is there.

Eclipse help is basically XHTML, which is what you get in the output anyway, especially if you aren't including the javascript files.

You might be interested to know that in the pending release of Flare 4 there is an XHTML format that spits out pure XHTML files; this might be a good starting point for creating a script to convert the files to Eclipse help, if you're interested.

pdenchfield · Post by **pdenchfield** » Thu Sep 04, 2008 8:55 am

Hi Paul, thank you for explaining the MadCap .xsd pointer.

Post by **doc_guy** » Thu Sep 04, 2008 8:57 am

No problem. Glad I can help.

rhofitz · Post by **rhofitz** » Thu Sep 04, 2008 8:58 am

Thanks Paul. Yes that XHTML output will probably be a better choice for our Eclipse help in Flare 4. When is Flare 4 coming out? I heard this Fall? Won't help us for this release, but next time.

Also good to know that changing the DTD in the output won't hurt us!

Thanks again,
Rhonda

MadCap Software Forums

DTD declaration

DTD declaration

Re: DTD declaration

Re: DTD declaration

Re: DTD declaration

Re: DTD declaration

Re: DTD declaration

Re: DTD declaration

Re: DTD declaration

Re: DTD declaration

Re: DTD declaration

Re: DTD declaration