Parsing Madcap tags in XML

[johnWatson]

Hello everyone,

I am running into a unique situation. In one of our latest projects, we are working out a system to keep both the styling and layout as dynamic as possible. To achieve this, we have created a set of Master Pages in our project that contain the different base layouts, with each section of the layout having a different style applied to it. We then have a javascript file that pulls data from an XML file (with each topic getting its own XML file) and loads the data into the appropriate sections of the topic. This way, the sections of the topic can be changed from both a styling (through CSS) and layout (through Master Pages) point.

The issue we are running into is that any Madcap tags (such as the keyword tag) are not recognized as valid XML in the Jquery script we are running, and causes the scrip to halt. Has anyone else encountered this type of scenario, or have a work around/alternate layout for this type of problem?

[kwag_myers]

The only way I know to get valid XML files from Flare is to use the DITA output.

[NorthEast]

I'm familiar with using the jQuery load function to load content from one HTML file into another - but that's for HTML, not generic XML.

I don't really follow what you're doing though:
- How is the jQuery loading the 'XML data'?
- How are you parsing/converting the XML to HTML?
- What actually is the 'XML data' ?
- Why does the XML data contain keyword tags? MadCap:keyword tags are only in topic source files, and would be converted to a (anchor) tags in the built output.

[johnWatson]

I apologize for the delay on this one, I did find a solution to this but have been without internet connectivity for the past couple of days. In order to explain the solution (and another problem that I'm running into), let me give a better description of the project's background and what I am trying to do.

I work for a software company that has develops and maintains a programming language used to program educational robotics. My job is to document the individual commands, functions, and internal variables that are used in the language, as well as set up "getting started" guides, etc (mainly, support documentation). We are currently overhauling the support documentation from a rough, non-standard format (with a lot of inline formatting and no set standards on fonts, layout, etc...*shudder*) to a standardized, HTML5 compliant, easily maintainable format.

Specifically, we are looking for ways to make sweeping changes to the 300+ function/variable pages without having to manually edit each one, while maintaining the ability to make changes to each individual page if needed. The method I have developed to do this (as of right now) is as follows:

• Create a Flare template for the function pages, and another template for the variable pages (different styling on each)
  Each template page follows a specific layout with each section of the page (function/variable name, description, sample code, etc) getting its own unique ID tag
  For each individual page, create a JSON/XML file that contains the actual data that will be populated in each of the page sections
  In Flare, create a new Topic for each command/variable with the only unique item being an ID tag for the HTML field
  Create a Javascript function that checks each HTML ID tag on a Topic, opens the appropriate XML and JSON files for that Topic, and populates the individual sections of the page appropriately.

I went with a JSON/XML mix because JSON supports the inline Flare tags, while XML supports linebreaks (required for one section of the page which uses <pre> tags). The process works (JSON and XML scripts I've created are linked below, for future reference), but now I'm running into the issue of not being able to easily add Flare tags to the JSON files.

The core issue that I'm running into is trying to find a way that I can make a bunch of topics with unique content but using a set layout, then later change the layout in one place (Master Page/Template) and have those changes reflected across all of the individual topics that use that layout. Am I trying to script my way out of an unnecessarily complex issue, and is there an easier way to do this that anyone is aware of? I appreciate any and all feedback/constructive criticism as I'm still learning both HTML-based coding and the best practices that go with it.

XML Parsing:

Code: Select all

function loadXMLDoc()
{
	//Grab ID from HTML tag
	var tagName = $("html").attr("id");
	
	//Use it to find the appropriate xml file
	//currently hardcoded into loadXML.js
	var xmlLoc = "/../xml_files/" + tagName + ".xml";
	
	if (window.XMLHttpRequest)
  	{
		xhttp=new XMLHttpRequest();
 	}
	else // code for IE5 and IE6
 	{
		xhttp=new ActiveXObject("Microsoft.XMLHTTP");
  	}
	
	xhttp.open("GET", xmlLoc, false);
	xhttp.send();
	return xhttp.responseXML;
} 

function parseXML(){

	//Open XML file
	//Import data from XML	
  	var xmlDoc=loadXMLDoc();
		
	//Parse the data
	//"sampleCode" to sh_c
	var x = xmlDoc.getElementsByTagName("sampleCode")[0].childNodes[0];
	var txt = x.nodeValue;
	$(".sh_c").text(txt);
}

JSON Parsing:

Code: Select all

//Script to load and parse the JSON data
function parseJSON(){
	$.ajaxSetup({
		async:false
	});
	
	//Grab ID from HTML tag
	var tagName = $("html").attr("id");
	
	//Use it to find the appropriate json file
	var jsonLoc = "/../json_files/" + tagName + ".json";

	//Open JSON file
	//Import data from JSON
$.getJSON(jsonLoc, function(jData)
 {
	 //Assign Title, Syntax, and Explanation values
	 $(".func-Title").text(jData.title);
	 $(".func-Syntax").text(jData.syntax);
	 $(".func-ExplanationList").html(jData.explanation);
	 
	//Create and populate an additional row (blue) for each parameter/data set

	for(var i = 1; i < jData.funcParams.length; i++)
	 {
		//Add a new row (with "blank" text in each cell)
	 	$(".func-Table tr:last").after("<tr>" + $(jData.rowPlaceHolder).html() + "</tr>");
	
	 }
	 
	 //Create variable (array) for each instance of the class names	 
	var paramElems = document.getElementsByClassName("func-Param");
	var expElems   = document.getElementsByClassName("func-Exp");	
	var typeElems  = document.getElementsByClassName("func-Data");
	
	 //Assign top row (yellow) with data
	 $(paramElems[0]).text(jData.funcParams[0].name);
	 $(expElems[0]).text(jData.funcParams[0].explanation);
	 $(typeElems[0]).text(jData.funcParams[0].type);

	//Create and populate an additional row (blue) for each parameter/data set
	for(var i = 0; i < jData.funcParams.length; i++)
	 {
	 	//Fill the Parameter, Explanation, and Data Type cells
	 	$(paramElems[i]).text(jData.funcParams[i].name);
	 	$(expElems[i]).text(jData.funcParams[i].explanation);
	 	$(typeElems[i]).text(jData.funcParams[i].type);
	 }
 }
);
}

[MattyQ]

Hi, john,

I've run in to some similar issues trying to parse data into topics once they're generated. In the end, I found it was easier to script a parser that takes our files and converts them into Flare topics, which are then automatically added to the project (which allows them to be controlled by the master pages, and makes them editable within the Flare UI).

That said, it worked for us because we're trying to move to working completely within Flare, so a conversion was ideal. From what you've described, it sounds like that may not be the case for you, so this may not be helpful.

I can commiserate with the validation though -- I ran in to the same issue using MadCap Lingo, also, where not all the XML was valid (although it worked in Lingo), and forced me to create a utility to parse the code there, too.

If you come up with a good solution, I'd be really interested in hearing about it.

Thanks!

[Gary Taylor]

Hi John,

Did you ever get this resolved?

If not, it sounds like you may have a "GIGO" problem and Dave Lee may be pointing you in the right direction:
- Are your source files HTML, XHTML, or XML?
- If they're XML, are they well-formed and valid?
- If they are well-formed and valid XML, is the total number of schemas (or DTDs) referenced in all your source files small enough for you to consider using XSLT transforms?

Regards,
Gary Taylor