Doctype element in Flare source files

zap · Post by **zap** » Thu May 19, 2011 12:42 am

Hi,
we are using Flare and Lingo for writing and sending out our documentation, but our translators are having a hard time importing files from us. At first I thought that their Trados system was - quirky, but then I heard that their import routine works if they add a doctype declaration at the top of every file. now I am trying to find out what to make of this.

I have found that we can enable the doctype tag for generated files in the target in Flare, but what about the source files?

w3.org says:
1 - The document MUST conform to the constraints expressed in the schemas in Appendix D - XHTML 1.1 Schema and Appendix C - XHTML 1.1 Document Type Definition.
2 - The local part of the root element of the document MUST be html.
3 - The start tag of the root element of the document MUST explicitly contain an xmlns declaration for the XHTML namespace [XMLNAMES]. The namespace URI for XHTML is defined to be http://www.w3.org/1999/xhtml.
4 - There MUST be a DOCTYPE declaration in the document prior to the root element.
5 - The start tag MAY also contain a version attribute that declares the version of XHTML in use. The version of this version of XHTML is -//W3C//DTD XHTML 1.1//EN.

madcap source files:

<?xml version="1.0" encoding="utf-8"?>
<html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd" MadCap:lastBlockDepth="4" MadCap:lastHeight="692" MadCap:lastWidth="661">

1 - I guess is OK
2 - OK
3 - OK, but has a reference to MadCap.xsd.
4 - Fail
5 - OK

Regarding number 3:
Should the namespace declaration be a live link? I get 'page not found' trying to reach it. I know it can be found locally, but does xml tools try to reach it?.

Regarding number 4:
Is the doctype declaration not there because of the madcap namespace in #3?

Hope this didn't get to messy and that a bright mind can shed some light on this.

thank you,
jorgen

Post by **RamonS** » Thu May 19, 2011 4:07 am

The source files do not have to necessarily conform to the rules. The output files should. The source files could be flat ASCII or binary or morse code, which is rather irrelevant for the purpose of creating output files that adhere to the standards.

Post by **LTinker68** » Thu May 19, 2011 8:09 am

To add to what RamonS says, the doctype declaration is added to the output when you build it, not as you're authoring it. When you build the output, the first two lines you wrote get changed to something like the following:

Code: Select all

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd" MadCap:lastBlockDepth="2" MadCap:lastHeight="70" MadCap:lastWidth="743" MadCap:disableMasterStylesheet="true" MadCap:tocPath="" MadCap:InPreviewMode="false" MadCap:PreloadImages="false" MadCap:RuntimeFileType="Topic" MadCap:TargetType="WebHelp" lang="en-us" xml:lang="en-us" MadCap:PathToHelpSystem="../" MadCap:HelpSystemFileName="help.xml" MadCap:SearchType="Stem">

Some of the info in the xmlns will be different for your help, but you get the idea. And there is now a doctype declaration before the html tag.

zap · Post by **zap** » Sun May 22, 2011 11:16 pm

Thank you for your comments.

The generation of the output is ok, it is the source files that are the challenge.

We write our stuff in Flare. Whenever we send files for translation, Lingo grabs the files from Flare. It is these files that are missing the docktype declaration... (in the eyes of our translators, using sdl trados)

So it looks like the output is well formed, but not the source files?

Thanks,
j

Post by **RamonS** » Mon May 23, 2011 4:18 am

Looks like it, but I do not see any reason to have well-formed source files as those files are never intended for publication. I am not sure why that ends up to be a problem for the translators.

RiverMonster · Post by **RiverMonster** » Thu May 26, 2011 7:17 am

Hi,

I am wondering if your issue is related to one I posted recently: (http://forums.madcapsoftware.com/viewto ... 40&t=13128)?

We too found that Trados does not recognize Flare source files. However, we observed that it does recognize them if we change the extension of each topic file from htm to xml. Did you try that? Not the ideal solution as the extension needs to be changed back again after exporting from Trados in order to be viewable once more within Flare, but it is perhaps easier/safer than adding a doctype declaration to every file. We found a good renaming tool that can do this easily (http://www.snapfiles.com/php/download.p ... 3134&loc=2)but it would still be better if it was "solved" up front in Flare (if not considered a Flare bug at least have a way to add the necessary declaration that seems to be causing the issue). We dont have Lingo and were wondering if it included a way to handle this but as you are having problems and you DO have Lingo, I guess the answer is no.

Adrian

Post by **Andrew** » Tue May 31, 2011 6:01 am

RamonS wrote:Looks like it, but I do not see any reason to have well-formed source files as those files are never intended for publication. I am not sure why that ends up to be a problem for the translators.

My humble opinion: either it's XML or it's not, and if you are going to use XML source files (which Flare claims to), they must be well-formed -- for exactly the kind of reason that came up in this thread: any other XML-based tool is likely to have problems consuming them.

However, as near as I can tell, Flare's source files are well-formed. A DTD / schema is not required for a document to be well-formed. The problem is the XML is not *valid* xhtml, because it lacks the doctype required by xhtml. In addition to being well-formed, I think Flare's source files should ideally be valid xhtml. They should add the doctype. I'm not sure why they didn't...wonder if there was some technical issue, or just sloppiness.

Post by **RamonS** » Tue May 31, 2011 6:51 am

What I meant with "well formed" was adherence to any (X)HTML standards (sorry for my sloppy use of terminology). The source files are, well, sources. And what constitutes valid XML is a different story. The requirements for being valid XML are rather low compared to (X)HTML. The file needs to contain

Code: Select all

<?xml version="1.0"?>

and at least one element. This means that

Code: Select all

<?xml version="1.0"?><element>Element</element>

is valid XML. By XML rules it is even well-formed and some claim that it is still considered XML when the "xml..." part is not present. A doc type declaration is not mandatory. I think we agree on this and state the same thing.
What I was getting at is that I don't see a point in having a doc type declaration in the source files.

Post by **Andrew** » Tue May 31, 2011 9:09 am

RamonS wrote:What I was getting at is that I don't see a point in having a doc type declaration in the source files.

Because without it, the source is not valid xhtml.

Post by **LTinker68** » Tue May 31, 2011 9:42 am

I think RamonS's point is that the source files aren't the final compiled version anyway. They're not meant to be validated against a doctype declaration because they're not meant to stand alone as they are. It's only after you build the help and bring everything together (e.g., masterpages) that you need a validated (X)HTML file. The translation tools are generally used against finished files, which is why they expect a doctype declaration.

Post by **RamonS** » Tue May 31, 2011 10:03 am

Andrew wrote:
RamonS wrote:What I was getting at is that I don't see a point in having a doc type declaration in the source files.
Because without it, the source is not valid xhtml.

And it does not need to and was never advertised to be as such. That this might cause problems for some 3rd party tool is unfortunate, but not based on the fact that Flare source files are not valid XML or are malformed or any of that. That is why I cannot follow the complaint about the missing doc type declaration. That said, it might make no difference to Flare if that declaration is there or not. So having it added and either stripped or copied / changed properly for output might be easy enough to do for MadCap. And that for the sole reason to play nice with other tools and possibly the competition. Filing an enhancement request would then be the right way to go.

Aside from that, Lisa summed it up better than I could have done it.

Post by **Andrew** » Tue May 31, 2011 10:22 am

I understand RamonS' point; I wasn't suggesting that xhtml validity was a must-have feature. I was speculating as to why they'd leave it out when they seemed to otherwise be so close -- either due to some technical reason (e.g., something in their tools / code has problems with the declaration), or some kind of oversight.

Post by **RamonS** » Tue May 31, 2011 11:12 am

Another option may be intentional design choice. Why add something that Flare does not need and that does not serve any purpose in the given context? That would be more code to maintain, more to parse (and ignore), and so on. I don't know what the reasons are, but it doesn't necessarily have to be negligence.

i-tietz · Post by **i-tietz** » Thu Jun 16, 2011 4:32 am

LTinker68 wrote:I think RamonS's point is that the source files aren't the final compiled version anyway. They're not meant to be validated against a doctype declaration because they're not meant to stand alone as they are. It's only after you build the help and bring everything together (e.g., masterpages) that you need a validated (X)HTML file.

If I edit a topic in the text editor and accidentally delete a ">" from a tag, I cannot save the topic, because in fact IT IS VALIDATED:

invalid_xml.png

So the question why further validations are obviously not executed, must be allowed.

Post by **Andrew** » Thu Jun 16, 2011 5:57 am

i-tietz wrote:
LTinker68 wrote:I think RamonS's point is that the source files aren't the final compiled version anyway. They're not meant to be validated against a doctype declaration because they're not meant to stand alone as they are. It's only after you build the help and bring everything together (e.g., masterpages) that you need a validated (X)HTML file.
If I edit a topic in the text editor and accidentally delete a ">" from a tag, I cannot save the topic, because in fact IT IS VALIDATED:
invalid_xml.png
So the question why further validations are obviously not executed, must be allowed.

Actually, I don't think it is validated. "Validated" has a particular meaning in this context: "valid" XML means XML that is validated against a schema / DTD. To say that "XML is valid" means that it's validated correctly against a schema / DTD. "XML is well-formed" means that the XML follows all the rules of XML. It appears that Flare checks to make sure the XML is well-formed, but not that it is valid.

For example, Flare will let you put plain text inside the <header> element, despite the fact that <header> does not allow mixed content types in xhtml (mixed content types is the ability to mix tags and text, like you can in a <p> element, which can contain both plain text and other tags). However, if you alter the XML so that it is not well-formed -- for example, you remove an end tag, or have invalid tag nesting (like <em><strong>...</em></strong>) -- Flare will show the message you noted. Basically, Flare does not validate the XML against any DTD /schema (even its own MadCap.xsd), but it *does* check to ensure the XML is well-formed.

This makes some sense. XML must be well-formed to be used at all with XML tools (such as .Net's XML classes, which Flare undoubtedly uses extensively). However, you don't need valid(ated) XML for those purposes, and validating XML is a *lot* of programming work (though there may be 3rd party classes available out there that can handle validation for MadCap instead of having to write one or more validators themselves).

MadCap Software Forums

Doctype element in Flare source files

Doctype element in Flare source files

Re: Doctype element in Flare source files

Re: Doctype element in Flare source files

Re: Doctype element in Flare source files

Re: Doctype element in Flare source files

Re: Doctype element in Flare source files

Re: Doctype element in Flare source files

Re: Doctype element in Flare source files

Re: Doctype element in Flare source files

Re: Doctype element in Flare source files

Re: Doctype element in Flare source files

Re: Doctype element in Flare source files

Re: Doctype element in Flare source files

Re: Doctype element in Flare source files

Re: Doctype element in Flare source files