CDATA within a Token

Topics: Developer Forum, User Forum
Mar 25, 2010 at 4:24 PM
Edited Mar 25, 2010 at 4:27 PM

I'm in a time-crunch here, so I'm hoping for a miracle. I'm whipping up some conceptual content - and there is a chunk of web.config configuration that I want to include in several places. However, when I make a token for it, it doesn't like the CDATA. I have this:

<ddue:para>

      <ddue:code lang="xml" title="Sample web.config or app.config">

            <![CDATA[

            <?xml version="1.0" encoding="utf-8" ?>

            <configuration>

                  <sampleConfigStuff goesHere="true"/>

            </configuration>

            ]]>

      </ddue:code>

</ddue:para>

and when I use this token like this:

<token>SampleConfig</token>

It outputs everything within <ddue:code />, including the string-literal for <![CDATA[ and does not format any of the XML. So, the page does create a "code" block, but the code itself is really just a big string literal with no formatting - and it actually prints the CDATA. For example:

CopySample web.config or app.config

    <![CDATA[

<?xml version="1.0" encoding="utf-8" ?>

<configuration>

    <sampleConfigStuff goesHere="true">

</configuration>

    ]]>

 So the question is, how can I use a CDATA within a token? Without it, I think I'm going to have to HTMLencode all of my sample config, right? That isn't ideal. Any ideas?? -Rob

Coordinator
Mar 26, 2010 at 3:11 AM

I haven't tried to use CDATA in a token.  Does it work if you include the token content inline within a topic?  As a workaround, you could move the content to an external file and use the source attribute to pull in the snippet.  The source attribute is an extension supported by the Code Block Component supplied with SHFB.

Eric

 

Mar 26, 2010 at 5:15 AM

Eric,

Thanks for replying. Yes - absolutely, in fact using CDATA's is ideal for XML code comments and for conceptual-content <code/> blocks, because you don't have to HtmlEncode it, you can just copy/paste right in there. For example, in XML code comments, you can do something like this:

    /// <summary>

    /// Summary goes here...

    /// </summary>

    /// <threadsafety static="true" instance="false"/>

    /// <remarks>

    /// <example>

    /// <code lang="xml">

    ///    <![CDATA[

    ///    <?xml version="1.0" encoding="utf-8"?>

    ///    <configuration>

    ///    </configuration>

    ///     ]]>

    /// </code>

    /// </example>

    /// </remarks>

and it works great. In conceptual content, you can do this:

<para>

      <code lang="xml" title="Sample web.config or app.config">

            <![CDATA[

        <?xml version="1.0" encoding="utf-8" ?>

        <configuration>

              <sampleConfigStuff goesHere="true"/>

        </configuration>

        ]]>

      </code>

</para>

and that also works as expected. That is, the CDATA parts aren't shown, and the XML is formatted and color-coded like normal. This is ideal because if you have a change in that sample code later, you can literally just paste it in - you don't have to worry about re-HtmlEncoding it again. So, the only hitch is using this technique in a token.

Within conceptual content, can you point me in the direction to learn more about that source attribute? I searched and coudn't find much. I assume it's similar to how it works for XML code comments, but couldn't find the exact syntax. Thanks again - and by the way, I've been heavily using SHFB I believe since it came out, and I'm a big fan. Thanks for doing what you do, this is a great tool!!

-Rob

Mar 26, 2010 at 1:11 PM

Woops - sorry! I didn't see that link in your reply... yeah, that should work - thanks again!

Mar 26, 2010 at 1:19 PM

WOO HOO!! That worked!!

OK, so a combination of defining the token called "SampleConfig" as:

   <ddue:para>
      <ddue:code lang="xml"
                         title="Sample web.config or app.config"
                         source="Sample.config" />
   </ddue:para>

and then I have a file called sample.config in the same folder. That config file does NOT have a CDATA wrapper. Instead, it looks like a regular web.config/app.config. Then, in my conceptual content, I use the token like this:

     <token>SampleConfig</token>

Just including all the details in case someone else runs across this. Thanks again for the shove in the right direction!

-Rob