SPFE Documentation | Collections > SPFE Development > Creating a topic

Creating a topic

Think
Plan
Do

Think

In common usage, the term topic refers to the subject of a work. Here, we apply the term to a particular work -- a unit of content -- about a particular subject. Using the SPFE Open Toolkit, a topic is an XML document in the structure of a specific topic type.

To be in the output of a content set build, a topic must be included in a topic set sources list (configuration setting /topic-set/sources).

Plan

Which topic type should I use for my topic?

Before creating the document for a topic, consider the document's purpose and select the topic type that best suits it.

The SPFE Open Toolkit provides a set of topic types that may be used as a base for extended topic types in a particular deployment of the toolkit. These base types, called EPPO simple, include the following:

docset-home topic
essay
feature topic
generic topic
think-plan-do topic

Do

Create an XML file using editing software of your choice. Do not use a word processing program such as Microsoft Word. The editor must save output in plain text format.

Several editors provide aids, such as syntax highlighting and schema validation, for editing XML markup. Some cost and some are free. Features and support for XML vary. A short list includes the following:

Oxygen XML is a full-featured XML editor with schema support. In addition to direct text editing, the software provides an "Author" editor that may be easier for those more comfortable in a word-processing environment. The software must be purchased, but is less expensive than most other full-featured XML editors.
Komodo Edit is a free editor with reasonable support for XML and several other code formats. In addition to syntax support, the editor verifies compliance with XML Schemas.

The above list is by no means comprehensive. You may likely find another editor more suitable. Often, the editor that works best is not that with the most features, but is the software you are most practiced and comfortable using. Finger habits are not easily relearned.

Follow the topic type schema

Review the structure diagram or other specification for the topic type.

Example

The XML code below shows the markup for a simple generic topic document.

                
                
<?xml version="1.0" encoding="UTF-8"?>
<generic-topic xmlns="http://spfeopentoolkit.org/ns/spfe-docs"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://spfeopentoolkit.org/ns/spfe-docs 
    http://spfeopentoolkit.org/spfe-docs/topic-types/generic-topic/schemas/generic-topic.xsd">
    
    <head>
        <id>nursery-lessons-in-words-of-one-syllable</id>
            <history>
                <revision>
                    <date>1838-06-06</date>
                    <author>Unknown</author>
                    <comment>Publisher Darton and Harvey, London</comment>
                    <status>In progress</status>
                </revision>
                <revision>
                    <date>2014-11-01</date>
                    <author>jfmacdonald</author>
                    <comment>digital revision</comment>
                    <status>Ready for release review</status>
                </revision>
            </history>
            <index>
                <entry>
                    <type>term</type>
                    <term>nag</term>
                </entry>
                <entry>
                    <type>task</type>
                    <term>reading</term>
                </entry>
            </index>
    </head>
    
    <body>
        <title>Nursery Lessons in Words of One Syllable</title>
        
        <p> See! Here is a find nag. And that is a good boy who rides on it too; 
            for he reads his book so well, and is so neat and clean, that his
            kind aunt gave him this nice horse; and I am sure James takes good
            care of her gift.</p>

        <fig href="../../../graphics/horse.png">
            <title>James on his horse</title>
            <caption>
                <p>See James ride.</p>
            </caption>
        </fig>
        
    </body> 
    
</generic-topic>