SPFE Documentation | Collections > SPFE Development > Adding a new structure
Adding a new structure
Think
A structure is a collection of document structure elements that work together to provide some distinct text structure such as a list or a table. A topic type is made up of an appropriate collection of structures. EPPO-simple provides a selection of structures that you can use to create topic types for your content set. In some cases, however, you may want to create a new structure specifically for one or more topic types in your content set.
For example, the SPFE Docs include a demo topic type which is designed to show how various features of SPFE and EPPO-simple are used. Demo topics need to show samples of the output produced by these features. To enable the formatting routines to set these samples apart from ordinary text, it uses an output-sample structure. This structure is not needed in most topic types in the SPFE docs, and is certainly not needed by most content sets unless they describe structured text systems like SPFE.
Plan
- Do I need a custom structure?
-
In many cases, it is possible to use an existing structure that will produce the output effect you are looking for, or something close enough to it. Given this, is it worth creating a custom structure. For instance, the SPFE Docs could have used a generic blockquote element to contain and output sample. Some reasons to create a custom structure are:
Greater clarity - A custom structure more clearly expresses what the content it contain means. This helps authors, editors, and downstream processes to process the structure correctly.
More specific structure - You can express more precise structural requirements with a custom structure. Parts of a generic structure may be optional whereas you want them to be required in your custom structure. You can also require or allow the custom structure at more specific places in your topic type. This also makes it easier to audit and validate your content.
More formatting control - Creating a custom structure makes it easy to specify specific formatting for the structure in different media.
- Why not just use an attribute to modify the handling of an existing structure
-
Many structured text vocabularies use generic structures and then use attributes on the root element of those structures to designate a more specific type. For instance, in DITA, admonitions are indicated with a generic note element with a type elements that indicates the type of admonition: note | tip | fastpath | restriction | important | remember | attention | caution | danger | other. EPPO-simple, on the other hand, supplies different sets of admonition structures for different purposes. For instance, if you add the admonitions.danger-warning-caution-notice structure to your topic type, you will get for separate admonition structures: danger, warning, caution, and notice. There are a number of advantages to this approach:
Easier to author - If an author wants to add a warning to a piece of text is easier to think “Warning” than to think “note with a warning attribute” and it is easier to create a warning element than to create a note element and add a warning attribute.
Better guidance - For any given subject matter, topic type, content set, or company style, only certain sets of admonitions are appropriate. You don't want authors to have to remember which are allowed and which are not allowed from a large set. You only want them to have the appropriate ones available.
- Should I create a custom structure in my content set project or as a SPFE-OT plugin
-
You can define a custom structure within you content project or you can make it a separate plugin. If the structure is unique to a particular content set, create it there. If it is potentially usuable for several content sets, make it a plugin. If you think it is potentially useful to others and you are willing to share, you could submit it to the SPFE Open Toolkit for possible inclusion in the standard structures distributed with the toolkit.
Do
To create a custom structure:
Creating a custom structure
This is the high-level procedure for creating a custom structure.
Step 1: Create the structure directory
Select the appropriate location for your structure and create a structure directory there. If you want to create more than one version of a structure, create a main structure directory for this class of structure and one subdirectory for each specific type of this class. For an example, see the EPPO-simple admonitions structure, which contains a variety of different specific admonitions structures for various collections of admonitions.
Unless it is a parent directory for different variation on the structure, each structure directory contain a config file and three directories: schemas, scripts, and style. (But not every structure needs to define all these things, so you may not need all three directories in each case.)