Fragment splitting

Fragments are a core concept in PageSeeder; they provide the basic unit for comments, tasks, and editing. Organizing your documents into separate fragments makes them more manageable and helps enforce good practice for creating well-structured documents.

Breaking up long documents into fragments offers several benefits:

• Easier collaboration – Team members can work on different fragments simultaneously without conflicts.
• Focused discussions – Comments and tasks can be attached to specific fragments rather than the entire document.
• Better organization – Each fragment can be edited and managed independently.
• Improved navigation – Readers can jump directly to relevant fragments.

Best practices for splitting

Split at heading levels

Fragment splitting occurs naturally at heading boundaries. This means:

• Headings appear at the start of a fragment, not in the middle.
• Each fragment typically represents a complete topic, including its heading plus the content associated with it.
• The document structure remains clear and logical.

Splitting at other levels

While splitting at heading levels is the most common approach, it's perfectly acceptable to split at a more granular level:

• Paragraph-level splitting – Useful for very detailed documents or when specific paragraphs need individual attention.
• Empty paragraphs as markers – You can insert blank paragraphs to mark your preferred split points.

The key is to split in a way that makes sense for your document's purpose and your team's workflow.

Splitting fragments in PageSeeder

Using the split function

PageSeeder lets you split fragments directly during editing. When you have a lengthy fragment, you can divide it at the following points:

• Any heading within the fragment.
• A blank paragraph you've inserted to mark your split point.

To split a fragment:

1. Open the document for editing.
2. Navigate to the fragment you want to split.
3. Choose where you want to split – either at headings or by inserting a blank paragraph where you want to split.
4. Select Split fragment from the fragment menu.

When you split a fragment, the original fragment remains as the first fragment. This is important because:

• Existing editing history stays with the first fragment.
• Existing comments remain attached to the first fragment.
• Xrefs continue pointing to the first fragment.
• Fragment IDs and URLs remain valid.

Where fragment splitting is used

Fragment splitting isn't only a manual editing feature – it's used throughout PageSeeder in various functions:

• Document import – When converting Word documents or other formats to PSML, content is automatically split into fragments.
• Content migration – When restructuring existing documents.
• Template-based editing – Document templates can define where fragments are to be split.
• Programmatic updates – Developers can use fragment IDs to update specific parts of documents.