Using Example Content From a File

In This Topic

When creating Examples in the Content File Editor, you can choose the Get example source code from a file option in the Example editor to use content from an existing source file. This technique avoids duplicating example content that already exists in a source file (e.g. an example), and ensures that your documentation is up to date with the source file.

Using a specific section of code from a Source File

If your existing source files are fully working examples, you may wish to only use a portion of the file for an example. You can do this using the Section Name field in the example editor together with adding section markup to your source files as outlined below.

Marking up one or more named regions within a Source File

If you are using content from source files, you may wish to only use a portion of the file; for example if the source file is part of a complete sample project and contains code that is outside the scope of a specific example.

To use just a portion of a source file you can mark up regions of the file using specifically formatted marker text to identify the start and end of a region, as well as the region name. By default the start marker should be of the format '#region {Name}#' or '#Region "{Name}"' where {Name} is the name of the region. The end region marker should be '#endregion' or '#End Region'. The start and end region markers can appear anywhere on a line, typically a comment line, so they can be used in any source file regardless of the language.

Here are a few examples of region markup:

/// Retrieves any new RssItem objects for this feed.
public void UpdateFeed() 
{
    if (!string.IsNullOrEmpty(Url))
    {
        XElement RssXml = GetRssXml(Url);

        foreach (XElement Item in RssXml.Descendants("item"))
        {
// #region CreateNewRssItem
            RssItem NewRssItem = new RssItem(Item.Element("title").Value,
                                              Item.Element("description").Value,
                                              Item.Element("link").Value,
                                              DateTime.Parse(Item.Element("pubDate").Value),
                                              RssItemState.New);
// #endregion
            RssItems.Add(NewRssItem);
        }

        _ModifiedOn = DateTime.Parse(RssXml.Element("channel").Element("lastBuildDate").Value);
    }
}

''' Retrieves any new RssItem objects for this feed.
Public Sub UpdateFeed()     
    If (Not String.IsNullOrEmpty(Url)) Then
        Dim RssXml As XElement = GetRssXml(Url)
        For Each Item As XElement In RssXml.Descendants("item")
' #Region "CreateNewRssItem"
            Dim NewRssItem As New RssItem(Item.Element("title").Value,
                                  Item.Element("description").Value,
                                  Item.Element("link").Value,
                                  DateTime.Parse(Item.Element("pubDate").Value),
                                  RssItemState.New)
' #End Region
            RssItems.Add(NewRssItem)
        Next Item
        _ModifiedOn = DateTime.Parse(RssXml.Element("channel").Element("lastBuildDate").Value)
    End If
End Sub

<html>
    <body>
<!-- #Region "Section1" -->
        <h2>Chapter 1</h2>
        <p>An introduction.</p>
<!-- #End Region -->
<!-- #Region "Section2" -->         
        <h2>Chapter 2</h2>
        <p>More information</p>
<!-- #End Region -->
    </body>
</html>

<note>
<!-- #region NoteToAndFrom -->
    <to>John</to>
    <from>Bill</from>
<!-- #endregion -->
    <heading>Reminder</heading>
<!-- #region NoteBody -->
    <body>Don't forget the appointment</body>
<!-- #endregion -->
</note>

The default format of start and end region markers can be customized in the Document! X Options;
i.e. if you have an existing body of code with some other scheme in use to markup named regions of code.

Widgets

Widget Content From a File

Send Feedback