developerHowToDocument : Why this do not work?

Topics: Developer Forum, User Forum
Jun 28, 2012 at 3:26 PM

Example:

    <developerHowToDocument
      xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
      xmlns:xlink="http://www.w3.org/1999/xlink">

.

.

.

        <procedure>
            <title>How To use</title>
            <steps class="ordered">
                <step>
                    <content>

                        <para>
                            Installation
                                <markup>

                                    <code language="sql" source="CreateAssembly.sql" title="Create Assembly">    </code>
                                </markup>

 

 

content of CreateAssembly.sql

USE [master]
GO

CREATE ASSEMBLY [Functions]
FROM 'c:\Functions.dll'
WITH PERMISSION_SET = UNSAFE

GO

 

Generated result

@@_SHFB_1

Why?

Coordinator
Jun 28, 2012 at 7:24 PM

There are a couple of issues:

1. The <markup> element is unnecessary.  It has very limited uses for very specific cases where you want to pass something through unmodified (i.e. literal HTML).  It should never contain other MAML elements and should be avoided unless absolutely necessary.

2. The <code> element is a block level element and shouldn't be nested within a paragraph.  Sandcastle won't complain but it might not render as you want it to.

So, to fix it, it should look like this:

<para>Installation</para>

<code language="sql" source="CreateAssembly.sql" title="Create Assembly" />

<para>Other info here if needed</para>

Eric