LOOPS documentation

Martin Post

1 Introduction

1.1 LOOPS History

Target group for this section: 9to5 Media Services customers / buyers

LOOPS is a software / platform project under active development since Spring / Summer 2022. We have soft-launched a platform using LOOPS – Specs and Docs – in Summer 2024.

Concept: Martin Post
Coding: Jonas Trippler

1.2 Concepts and use

In essence, LOOPS is a static site generator and single-source publishing engine with a web frontend created in PHP.

LOOPS is currently piggybacking on / using the free and open-source document converter Pandoc for content conversion, but we may implement our own conversion engine at a later point.

1.3 LOOPS features

Customizable ⋅ Add your own style sheets and templates or (let us) adapt ours.
Effective ⋅ A single source publishing solution where all target formats (HTML, PDF etc.) are created from one source.
Efficient ⋅ We’re not trying to reinvent the wheel. Sources are used efficiently.
Fast ⋅ Batch-convert of hundreds of files in seconds.
Flexible ⋅ Use for hundreds of support files, a few manuals or your Great American novel. The concept is always the same.
Intuitive ⋅ Folder-based system. All documents and configuration files in one location.
Lightweight ⋅ Our source format is Markdown, the world’s most popular lightweight markup language.
No-nonsense ⋅ Built-in lightweight file manager: upload, delete, rename. That’s it.
Open ⋅ No vendor or technology lock-in. Create Markdown files that can be used anywhere. Check out your data any time.
Portable ⋅ Bring your own editor: Markdown files can be edited on any device, using any text editing software.

1.4 About this documentation

This documentation will only describe LOOPS as such, not the underlying technologies and products. We expect the reader to know (or learn) about…

Technology	Category
Markdown	Lightweight Markup Language
PHP	Programming language
Pandoc	File converter
Single-source publishing	Concept
Static site generators	Concept

2 LOOPS Usage

Target group for this section: Technical writers; marketing specialists, support specialists writing, editing or working with product information (manuals, quick guides, support articles etc.)

This section describes using LOOPS after setup has been completed.

2.1 LOOPS Philosophy

2.1.1 Semantic, agnostic (“unopinionated”) format

In many publishing applications, word processors and content management systems,…

content (what you want to say),
semantics (what it means in a given context)
and styling (how it is presented to the reader)

…are “glued together”. A format that designates a content segment’s meaning also defines the visual presentation. Examples: Adobe InDesign, Apple Pages, Microsoft Word.

In a modern single source publishing workflow, content is formative using neutral / semantic markup. The way that semantic tags are presented is separated from the writing stage and the applied tags. Examples: Markdown formatting converted to HTML or another XML-based language, which is styles using CSS.

LOOPS is based on Markdown and supports a semantic approach to creating and publishing content. The principles applied here are:

Write first, think about structure later.
Apply structure, think about presentation later.

2.1.2 “One to many” principles

LOOPS follows a basic “one to many” philosophy. In typical use,…

one source file can be converted to many target formats.
This is a well-established concept usually referred to as single-source publishing.
one source file can be split into multiple target files.
This is helpful for creating a long-form source document and then splitting it into multiple, connected chapters that can be read sequentially or individually.

With LOOPS, both approaches can be combined as in the following scenarios:

A technical writer creates a long-form source document called “reference.md”.
“reference.md” is converted to three target formats:
1. “reference.epub” (an “encapsulated” EPUB file) and
2. “reference.docx” (an “encapsulated” Microsoft Word file) and
3. “reference.htm” (a single, large HTML file referencing image files and style sheets)

This is a “single format to multiple formats” approach.

“reference.md” is converted to two target formats:
1. “reference.htm” (a single, large HTML file referencing image files and style sheets)
2. a set of linked files:
  1. “reference-chapter-1.htm”
  2. “reference-chapter-2.htm”
  3. etc.

This is a “granular” publishing format, where a single source is split into chapter-sized chunks.

2.2 Accessing you LOOPS project

The following section assumes that a project has already been set up for you or your company / organization, and that you have a valid project passkey.

In your web browser, type or select the URL of your LOOPS server. Example:
https://loops.specs-and-docs.online
You will be prompted for your project’s passkey.
Enter the project passkey into the passkey field. Example: 9g5i4y8o2w7g9r0d6g6t4c8g2d1v4qd
You can also store a full login to your project concatenated from the LOOPS server URL and passkey. Example:
https://loops.specs-and-docs.online?token=9g5i4y8o2w7g9r0d6g6t4c8g2d1v4qd
Warning: Anyone with access to a project URL with a qualified token will have access to your project, including rights to modify and delete all data. Make sure you have an external “single source of truth” document set for all mission-critical data.

You will now see the dashboard for your project, giving you access to the functions described below.

2.3 Logging off / logging out of a project

To log off, click the Log out button in the top command bar.

2.4 Creating a new source document

Click the New button.
The LOOPS Markdown Editor will open.
Enter text in the Editor pane on the left. Use Markdown markup to format your content.
The text you enter or paste into the Editor Pane will be shown in the Preview Pane on the left.
To save the new file, enter a file name and suffix (for example “documentation.md”) in the text entry field above the Editor pane and click the Save button.
You will be returned to the Project Dashboard, and the new file will be added to the Input Files list.

2.5 Uploading a source, configuration or media file

To upload one or multiple source, configuration or media files to the current LOOPS project, click the Upload button in the top command bar.
Your browser’s standard file dialog will open.
Navigate to the folder containing the files you want to upload. Select the file or files you want to upload and click the Upload button. The selected file or files will be uploaded and shown in the respective parts of the dashboard.

2.6 Editing a source or configuration file

To edit a source or a configuration file, click the name of the source or configuration file in the Input Files list.
The selected source or configuration file will be opened in the editor.
Edit the source or configuration file in the Editor Pane on the left.
For sources, the Preview Pane in the right half of the window will update when you stop typing.
To save your changes, click the Save button.
To discard your changes, use your browser’s back button to return to the dashboard.

2.7 Converting one or multiple source documents

To convert one or multiple source documents, click the checkboxes in the rows of these source documents.
Optionally, selected one or more configuration files that should be applied to the selected source documents. If you select multiple source documents, they will be applied successively.
If a parameter is defined in two or more configuration files, the definition in the (alphabetically) last configuration file is used.
When you have selected all source documents and configuration files, click the Run button in the top command bar.
The selected files will be converted.

2.8 Deleting a single source, configuration, rendered or asset file

To delete a source, configuration, rendered or asset file, click the Delete button in the row of the file.
The file will be deleted immediately.

2.9 Deleting multiple files

To delete multiple files, click the checkboxes in the rows of these files. Then click the Delete Selected button in the top command bar.
The selected files will be deleted immediately.

2.10 Renaming a source or configuration file

To rename a source or configuration file, click the Rename button in the row of the source or configuration file.
A dialog box will be shown allowing you to rename the source or configuration file.
Click OK after entering the new source or configuration file name.
If you enter the name of another, existing source or configuration file, it will be overwitten immediately.

2.11 Previewing a source, configuration file or rendered document

To preview a source, configuration file or rendered document, click the Rename button in the row of the source, configuration file or rendered document.
The selected source, configuration file or rendered document will be opened in a new browser tab. This preview is not editable. When you are done, just close the browser tab with the previewed file.

2.12 Filtering the Dashboard

To show only source documents, configuration files, rendered documents and assets with specific names, enter the string you want to filter for into the text entry box in the top command bar.
All sections of the dashboard will be filtered immediately.
To remove the filter, click the x widget in the text entry box in the top command bar.
The full list view for all sections of the dashboard will be restored.

3 Troubleshooting

3.1 Log file

If the conversion of one or multiple files to a target format failed, you can review the log file. The log file for your project is called log.txt and can be accessed using the dashboard like any other files by simply clicking on it.

4 A Guide to creating and maintaining complex document sets using Markdown and LOOPS

Target group for this section: Technical writers

This section of the LOOPS documentation is a “best practices” guide to creating long-form documents using the lightweight markup language Markdown and LOOPS as the main environment for maintaining and converting content sets.

For more information on the basic concepts of LOOPS as a static site / documentation generator, see the “Philosophy” section of this document.

4.1 Use whatever content editor you have (and enjoy using)

LOOPS documents are Markdown documents. And Markdown content can be edited in any text editor on any platform.

Google Docs, the TextPad editor in Microsoft Windows, Apple’s TextEdit: You can use any text editor, note taking app or layout application there is, as long as it is possible to save / export / copy plain text from this application.

However, you should keep the following in mind:

You will need to save your documents in plain text format. Plain text documents only contain UTF-8 text characters as seen on screen / in your editor.
If your text editor has visual formatting tools for character and paragraph styling, the visual formatting you apply in this editor will not “carry over” to the LOOPS editor. So if you have a sentence with ten words, three of them highlighted and an embedded hyperlink, only the content (the ten words) will be used.

4.2 Copy and paste to your heart’s content

While LOOPS provides an editor that allows you to enter and edit text directly, there’s nothing wrong with copying and pasting long-form content from another application or content management system directly into an empty or populated document.

Go wild.

↻ 2024-08-27