XML Tagging?

[BL_N]

Off the cuff question -- I am looking for a way to insert tags in the XML of our help topics. Specifically, to insert DITA tags for concept, task, and reference topics. Thusfar, I'm not finding it possible. So rather than beat my head against the wall, I thought I'd ask -- is this possible (inserting standard tags in XML)?

[BL_N]

Anyone? Bueller?

[NorthEast]

Just to get the full picture, what is it you're actually trying to achieve?

I have only have a pretty vague knowledge of DITA, XML, XHTML, DTD (and other acronyms).
However, if your Flare topics are XHTML, then presumably that means you can only use XHTML tags. What tags are you trying to insert?
Or do you mean you want to mark up the topics in such a way that they can be transformed to XML with the appropriate DITA tags?

[BL_N]

At the moment, Flare does not enforce DITA nor does it provide the means by which to implement DITA tags as part of the authoring process.

I was hoping to find a way to insert DITA tags (e.g., <conbody>, <prolog>, et al, etc, etc, etc.) into the XML for future (and possibly conditional) use.

The goal is to create our help system using only Concept, Task, and Reference topics, to tag them internally with the appropriate DITA tags (even if they are only ballast for now).

I have not been successful in figuring out a way to do this (is it possible?).

[NorthEast]

Ok, I may have completely missed the point with all this, but here goes...

If you're producing content in Flare that's in XHTML, then how you would you include DITA tags, since they aren't valid XHTML?
My rough understanding of a DITA workflow is that you'd write content in some form of DITA XML, which you then use to generate your output in formats such as XHTML (i.e. XHTML is a subset).

So, since you're authoring in XHTML, could you use dummy tags and classes as placeholders for now, so they could be transformed to DITA XML at a later date?

For example, I use classes of the html tag that define different types of topic, and I use DIV classes as containers for different types of content in the topic body. Presumably that would be quite easy to convert to some other form of XML markup.

[BL_N]

Looking at the editor and from all information reviewed, it is not XHTML but XML happening "behind the scenes". If this is the case, there should be some way to get to the code. And if there is, there should also be some way to insert the DITA tags we want. But perhaps I'm missing something?

toolbar.gif

[NorthEast]

If I open a topic in text view, it looks very much like XHTML to me - or is that not what you meant?

[BL_N]

As I understand it, Flare's native (internal) format is XML, not XHTML. The editor says its XML, the doc says it's XML, the help says it's XML.

http://www.madcapsoftware.com/support/w ... Editor.htm

My question is: How do you get to the source using Flare and can you insert your own tags (in this case, DITA tags)?

[LTinker68]

My question is: How do you get to the source using Flare and can you insert your own tags (in this case, DITA tags)?

I also only have a passing knowledge of XML and such, but I believe it's the schema called at the top of the page that determines what tags you can use. I don't know if DITA-specific tags are default tags that are included in every schema, or if web browsers automatically know what they are and the data format they follow, or if you have to specify a schema that defines those DITA tags. If it's the first two options, then the only way you can insert them into a topic is to open the topic in the Internal Text Editor or Notepad and enter them manually. However, I think the third option is the more likely scenario. If that is the case, then I would think you could include reference two schemas in one topic, so long as the tags within the schemas didn't overlap/duplicate. That's just a guess, though -- XML compliance could very well mean that you can only have one schema defined. Either way, you'd have to insert the schema reference and insert the tags into the topic the same way -- manually.

And you'd have to come up with some way to define how those tags are to appear in output, unless you enclosed them in <p> tags or something. I don't know if you can define their styles in a normal stylesheet or if you have to use the XML transform stylesheet or whatever it's called (XLS?).

But, again, that's all based on a vague understanding of XML and such. I could be way off base.

[BL_N]

Blargh. That is pretty much my conclusion as well. I was hoping to be wrong. Thanks for the reply!

[NorthEast]

That was my general understanding too, LTinker. I don't know all the correct terminology, but as I understand it, XML is just a general specification for markup languages, and both the XHTML and DITA specifications are just XML languages (schemas?).

[BL_N]

You could consider XML as the 'parent' and both XHTML and DITA as 'children' or subsets of tags within its specification.

The assumption on my part was that you could choose your schema, reference it accordingly, and utilize tags that are part thereof from within Flare. But it does seem the only way is via an external editor.

No worries, an enhancement request!

[NorthEast]

Yep, I think of XML as the general rules for how you make the languages, and XHTML and DITA as languages (I think DITA actually includes most of what's in XHTML too).

[BL_N]

Yep, I think of XML as the general rules for how you make the languages, and XHTML and DITA as languages (I think DITA actually includes most of what's in XHTML too).

Both XML and HTML are subsets of SGML, the ISO standard markup language (which in turn is a subset of the old IBM GML!).

XML is the Extensible Markup Language. It improves the functionality of the Web by letting you identify your information in a more accurate, flexible, and adaptable way. It is extensible because it is not a fixed format like HTML (which is a single, predefined markup language). Instead, XML is actually a metalanguage—a language for describing other languages—which lets you design your own markup languages for limitless different types of documents. XML can do this because it's written in SGML, the international standard metalanguage for text document markup (ISO 8879). (quoted from http://xml.silmaril.ie/basics/whatisxml/)

XHTML is (more or less) the "XML'd" version of HTML. It is a migration from HTML 4.0 to a version that adheres to the (stricter) XML standard. XHTML is a reformulation of HTML 4 in XML 1.0’. This specification defines HTML as an XML application, and provides three DTDs corresponding to the ones defined by HTML 4. (Strict, Transitional, and Frameset).

DITA, on the other hand, was created by IBM as a content modeling language to be utilized within the framework of XML (This is a quite a synoptical statement. The full history may be read here, and is fascinating as well as insightful). Today, DITA is not so much it's 'own language' as the method by which to model help and support information using XML. IBM donated DITA to OASIS and since that time (2005) it has been incorporated into the XML standard (DTD) as a method for defining online help and support information in XML.

To understand DITA, you really only need to understand that everything in it's 'universe' must fit into one of three categories: A concept, a task, or a reference. A concept explains and establishes context, a task sets forth procedure, and a reference provides granularity to the either of the first two. It's all 'topic-based' which means any of these are discrete pieces of information that can stand alone.

The idea behind DITA is to break down all information to it's base form to allow for truly modular information management; reusability and, of course, the holy grail of single sourcing. The plethora of tags within the architecture are intended to provide options for how finely grained that modularity is (or needs to be).

If you'd like to learn more about DITA without putting knots in your noodle, I recommend "Introduction to DITA: A User Guide to the Darwin Information Typing Architecture" by Jennifer Linton and Kylene Bruski. (http://www.comtech-serv.com/dita2.shtml#book)

[doc_guy]

Sorry I missed this discussion earlier. However, as you know, Flare isn't a general XML editor that allows you to select an XML schema to work with. When you work with Flare, you are working with a customized XML schema that Flare understands and uses. Flare then uses some type of transform to convert the Flare-based XML to XHTML for WebHelp outputs. That is why we get confused when we talk about XML versus XHTML and the Flare interface. Flare is writing in a Flare-based XML which is basically XHTML with specialized Flare tags for conditional text, drop-downs, indexing, etc.

When you look at a Flare source topic, what you see looks a lot like XHTML, but it isn't, because XHTML can't handle any of the tags with the MadCap namespace. (The tags that begin with Madcap: .) Those are specific to the MadCap schema.

I doubt Flare will ever let you select any schema that you want and enforce validation to that schema. After all, Flare isn't a general XML editor, and was never intended to be. The problem is that Flare's transform (the file that knows how to take a native Flare file and convert it into XML, Word, Frame, etc.) has to understand the semantic structure of the source document in order to transform it into the proper output. Sure, Flare could engineer it to work with DITA, Docbook, or some other standard schema (which you may see at some point, I don't know), but it would have to be a closed set because MadCap has to write a new, separate transform for every source document type/output type pairing. So when there is only one source document type (Flare XML) and five output types, then you need five transforms. If there are two source document types (say Flare XML and DITA), and five output types, then MadCap has to produce, test, and support ten output transforms. If there are are three source document types (say Flare XML, DITA, and Docbook), with five output types, then MadCap has to product, test, and support fifteen output transforms. What happens when MadCap adds a new output type (say direct-to-PDF)? They have to create a separate transform for each supported source document type. You can see how this quickly gets unmanageable from an implementation perspective.

If you want a general XML editor that lets you select your schema, then you'll have to pick a general XML editor like XML Spy. But then you're stuck writing your own transforms to get your files from their source XML format to a viewable output type.

I hope this was clear. Let me know if anybody has any questions about it.

PS: I obviously don't speak for MadCap, nor do I have any idea what their development plans are. I just understand the complexities of adding supported input types, so I can understand why MadCap would be hesitant to support a wider range of source document types. As for what they will actually develop and implement, well, you're guess is as good as mine.

[BL_N]

Completely understand what you're saying here. But considering that DITA is *the* reigning XML DTD for online help and support, it would be a bit more than odd if they never supported it.

Here's to hoping.

[doc_guy]

I wonder if they will ever support it as a native, working document type. However, I can see them supporting it as a potential target type.

Who knows? I'd put in a feature suggestion, though, because I wonder if there are people at MadCap who wonder if Flare users want DITA support in Flare. Here's the feature suggestion page, and you should be as detailed as you can about how you'd like to see DITA implemented in Flare:

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

[doc_guy]

To be fair, let me post a slight correction to what I said earlier:

If you were to pick a general XML editor, and you used the DITA schema for validation, you could use a standard DITA transform to get an output type. You wouldn't necessarily need to write your own transform, as I mentioned earlier. You'd only need to write your own transform if you were using a custom XML schema, or if you were wanting to output to a type that doesn't already have a transform for your selected source schema.

Hope that is more clear.

[BL_N]

It would be downright groovy to have Flare either add the DITA tag set to their schema or allow for the use of the DITA schema so one could tag up topics, and have validation in place for which tags are permitted in which topic types.

I like to dream big, especially on a Friday. My biggest, "bestest in da' vurlt" technical authoring dream is to have a H.A.T that not only is DITA aware and compliant, but actually catalogs my modular content and allows me to drag and drop content to create new outputs (with target being one of those nifty drag and drop elements).

Marketing wants a new piece of collateral? Sweeet.... I'll just drop in the latest boilerplace layout, open up the the concepts authored for "Best New Product #1" and "Best New Product #2", drag over the prolog and elements marked with keyword tags 'feature', tell it what order I want them in (also drag and drop), drag over the pre-defined output target for marketing collateral (in this case, print, web, and email), save it, and go have celebratory cup of coffee.

~blinks rapidly a moment~

Ahem. Yes. Well. As I was saying... I like to dream big.

[KevinDAmery]

If nothing else, DITA is the defacto standard for Frame users who work with Structured Frame, so being able to pass DITA compliant files in and out would make working with Frame and Flare in the same doc team a lot more seamless.

Obviously, the true holy grail would be Flare users being able to just assign a DTD or schema for their project and have Flare just make use of that definition... but as Paul points out, that's a whole lot easier to say than to actually implement.

[BL_N]

If nothing else, DITA is the defacto standard for Frame users who work with Structured Frame, so being able to pass DITA compliant files in and out would make working with Frame and Flare in the same doc team a lot more seamless.

Obviously, the true holy grail would be Flare users being able to just assign a DTD or schema for their project and have Flare just make use of that definition... but as Paul points out, that's a whole lot easier to say than to actually implement.

The problem with Frame and DITA is that they insist on using their own, proprietary EDD for managing structure and formatting together. (Just when the rest of the world is finally groking the notion that keeping structure and formatting apart IS the way to go... good job, Adobe! )

I absolutely agree with your second statement, but I'm not so sure it's that difficult for Flare at this point, as they obviously already have the code base in place for validating to a DTD. If anything, it's a matter of codifying the DTD for DITA more than anything. Set against the overall development cycle for Flare, one DTD is rather piecemeal. (Though I'm sure it is a gritty piecemeal!)

In truth, DITA is the XML standard for online help and support. So it stands to reason that it would/should be a core component of Flare at some point.

IMNSHO, the sooner, the better.

edited: misplaced paren!

[doc_guy]

I absolutely agree with your second statement, but I'm not so sure it's that difficult for Flare at this point, as they obviously already have the code base in place for validating to a DTD. If anything, it's a matter of codifying the DTD for DITA more than anything. Set against the overall development cycle for Flare, one DTD is rather piecemeal. (Though I'm sure it is a gritty piecemeal!)

Yes and no. It's not just validating the DITA DTD (actually, isn't DITA a schema, rather than a DTD?). It's also creating transforms to get DITA content into a usable output with all the Flare niceties. You've got to figure out a way to make Flare and DITA do drop-down text, cross reference text, indexes, pop-ups, glossaries, etc. in a way that supports the DITA schema and in a way that Flare understands and can use to create several different output types.

Just making Flare open a DITA document only gets you half there. You still need to be able to create output that does what you want. Unless you are wanting to create non-DITA output, in which case, why start with DITA in the first place?

In truth, DITA is the XML standard for online help and support. So it stands to reason that it would/should be a core component of Flare at some point.

I'm not sure you can make the case that DITA is THE XML standard for online help and support. There IS no standard right now, which is part of the problem.

That said, I think DITA in Flare would be a great addition. I just recognize that its not a trivial affair to add it.

[BL_N]

I understand what you're saying, and wasn't attempting to minimize the amount of design and coding that would be required to do so.

As for standards, I know the WC3 and OASIS both reference DITA as the standard for online help and support and that's no small potatoes. But I am aware that adoption as such (as usual) lags.

[KevinDAmery]

As for standards, I know the WC3 and OASIS both reference DITA as the standard for online help and support and that's no small potatoes. But I am aware that adoption as such (as usual) lags.

Not to mention that there are quite a number of companies using Docbook instead of DITA, although DITA does seem to be more prevalent.

[BL_N]

Indeed. I suspect it will run the same pattern as has Adobe. Market adoption/popularity making things... interesting. But, as we see with Flare, quality outs in the end. The question is -- can DITA be friendly? I figure if anyone can make it so, MadCap can.