LOOPS ⋅ Frequently Asked Questions

On this page, you’ll find information about single-source publishing, (machine) translation, and LOOPS; the Lightweight Object-Oriented Publishing System by 9to5 Media Services.

1. Technology

“What is your technology stack?”

We have a low-tech / high-efficiency approach to digital publishing. This is the LOOPS technology stack:

1. Content is marked up using a lightweight markup language called Markdown.
   You have probably seen Markdown markup (or documents created using Markdown) many times without even realizing that this is a document format with a proper name (and interesting history). Markdown has been around for more than two decades, making it easy to learn and apply. It is both intuitive for humans and easily convertible into more complex formats by applications.

2. Markdown content is converted to HTML, the lingua franca of the web.

3. HTML templates are used to place metadata and the actual content.

4. Content is styled using Cascading Style Sheets, just like any other published web content. Modern CSS styling ensures responsive display of content based on device properties (smartphone, tablet, computer) and viewport adjustments (window size, device orientation).

5. Images can be hosted on any web server and are linked from the Markdown documents. Where required, CSS classes are applied to resize and position images. Video and audio file players (both local content and popular streaming content) can also be integrated.

6. Our custom JavaScript library is used to add user-side navigation features such as a table of contents, bookmarkable anchors, and in-document “previous element” / “next element” links to the published documents.

7. Product literature can be hosted on the Specs and Docs site, using a subdomain such as yourbrand.specs-and-docs.online, or made available for download and hosting on your own site. As all documents are static HTML files that do not require a content management system or database backend, they are highly portable.

That’s all.

Our web documents can also be converted to PDFs both on the server and by end-users.

“What are the basic concepts behind your technology stack?”

In one sentence: Avoid all unnecessary complexity

These are the principles we followed when developing our workflow:

1. No opaque file formats
   Use the simplest / transparent format for any task.
2. No overly complex toolchain
   Reduce the number of necessary components.
3. No use of commercial, expensive software (components) unless absolutely necessary
   Don’t (make clients) invest in proprietary technology unless it cannot be avoided.
4. No unnecessary dependencies
   No use of complex frameworks that are maintained (and possibly abandoned) by third parties.

“Why are you using Markdown?”

Markdown is the world’s most popular lightweight markup language.

Markdown is one of the world’s most popular “file formats” / markup languages. Describing its many uses, but also its restrictions, is beyond the scope of this document. Here are just the basic considerations:

• Markdown allows for simple text-only markup
  “#”, “-” and a few other characters are used to generate structural markup (headings, lists), emphasis (bold, strong), tables, links, footnotes, etc.
• Markdown is easy to read for humans.
  Even without knowing what it is, most people can look at Markdown “source” and understand their structure and semantics.
• Markdown is easy to process for computers.
  Writing a basic Markdown parser / converter that will convert a Markdown-formatted source to HTML is fairly easy. A talented developer will not need more than a few hours to implement this in any modern programming language, and such converters can run on servers, in dedicated conversion applications, and even in web browsers.
• Markdown is easy to write.
  Core concepts can be learned and applied by anyone who has ever used a text editor or word processor in about ten minutes.
• There is no “coding”, no binary file format, no (required) tools, and nothing has to be licensed or installed.
  Any text editor on any operating system will do. Many online tools for writing and processing Markdown documents are available.

It is important to note that there isn’t one unified, “canonical” version of Markdown.

A variety of Markdown “flavors” exist.

Many of these “flavors” / variations are extensions of the core concept. They are better suited for technical and scientific publishing, as they support document sections, math, citations, and other features.

For more information, see:

• “Comparison of features in various Markdown flavors”

For more information on Markdown, see:

• Markdown Guide – Getting started
• “Human technology: Text files” (Boris Marinov)
• Markdown @ Wikipedia
• “Markdown everywhere!”
• 9to5 Media Services Basic Markdown Guide

“Why are you using Pandoc?”

Pandoc is an extremely versatile, stable and popular document conversion engine. Pandoc is starred by more than 35000 users on GitHub, making it one of the 400 most prominent projects on the platform.

Markdown itself is a set of formatting conventions / a markup language – but to actually use it in a publishing workflow, a conversion engine is required that will convert the “loose” human markup into a well-formed, machine-readable XML/HTML format.

Hundreds of these converters exist – with and without visual frontends and support for extensions.

When developing LOOPS, we decided early on not to reinvent the wheel, but use Pandoc for the following reasons:

• Pandoc is free software.
• Pandoc is open source software under the GNU General Public License.
• Pandoc has an active development team with more than 400 contributors – see https://github.com/jgm/pandoc/graphs/contributors.
• Pandoc has an active, friendly support community – see the Pandoc User Group on Github.
• Pandoc is available for many operating systems and platforms – including Windows, macOS, Linux, and Docker.
  See https://pandoc.org/installing.html.
  Pandoc can also be compiled from source.
• Pandoc can be used to convert documents from Markdown to HTML and vice versa. Pandoc also supports conversion from and to many other formats – including, but not limited to, LaTeX, EPUB, and Word – see the project homepage.
• Pandoc offers many useful extensions of the original Markdown syntax. From the project’s homepage:
  • Pandoc supports templates for HTML and other formats.
  • Pandoc supports variables that can be used in document templates.
  • Variables can be set in so-called Pandoc default files – see https://pandoc.org/MANUAL.html#defaults-files.
    These are YAML files that can be edited with any text editor.
    Multiple default files can be aggregated when running a project, and options from one file can be overridden in the next.

From the Pandoc documentation:

Pandoc supports a number of useful markdown syntax extensions, including…

• document metadata (title, author, date),
• footnotes,
• tables,
• definition lists,
• superscript and subscript,
• strikeout,
• enhanced ordered lists (user-set start number and numbering styles are considered),
• running example lists,
• delimited code blocks with syntax highlighting,
• smart quotes, dashes, and ellipses,
• markdown inside HTML blocks, and
• inline LaTeX.

If strict Markdown compatibility is required for whatever reason, all of these extensions can be turned off.

“Will we be tied to your service and document formats?”

Or, put differently: “What happens if 9to5 Media Services / Specs and Docs goes belly-up?”

We perfectly understand that brands want to avoid vendor lock-in, especially in an ever-changing technology landscape.

As we keep our stack as simple as possible and use no complex database technology for creating or publishing content, you can easily take back your content: It’s just a set of plain text (Markdown) files with references to images hosted on a run-of-the-mill web server. It doesn’t get more portable than this.

2. Single-source publishing / semantic publishing

“What is single-source publishing?”

Single-Source Publishing is a content creation, management, and publishing strategy where a single, centralized source of content is used to produce multiple output formats.

The core concept is that the content is authored once in a neutral, flexible format and then automatically or semi-automatically transformed into various formats, such as HTML, PDF, eBooks, and more. This approach minimizes the need for duplicate content creation and maintenance, ensuring consistency across all published formats.

“What are the advantages of Single-Source Publishing?”

1. Consistency: Since all output formats are derived from the same source, consistency across all target formats is ensured.

2. Efficiency: Single-source publishing reduces the time and effort required to produce multiple versions of the same content (for example, printed and web versions of a manual, or quick guide and FAQ content). The content is authored once and then converted to different formats.

3. Reduced Maintenance: If errors are found or content is updated, changes need to be made only in the source document, which then propagates to all output formats, reducing the risk of discrepancies.

4. Cost Savings: Single-source publishing streamlines the publishing process, which can lead to significant cost reductions in content production and maintenance.

5. Scalability: Scaling a single-source publishing workflow is fairly straightforward. New formats can usually be added in a short time, either by developing a dedicated output module or confirming one of the more popular output formats to another format (example: Markdown → HTML → PDF).

“How is content created, stored, processed, and styled in a single-source publishing workflow?”

Here’s an example workflow starting with a lightweight markup language like Markdown, with other formats such as HTML and PDF derived from it.

Step 1: Authoring content

Content is authored in a lightweight markup language. Markdown is the preferred source format in our workflow, chosen because it is easy to read and write, and it can be converted to many other formats.

Tools: Text editors like VS Code, Atom, or a dedicated Markdown editor like Typora can be used. Such editors are available for all major platforms (both traditional and mobile operating systems).

Step 2: Storing content

In a single-source publishing workflow, source documents are either saved as plain text files on a file server, which can be accessed by SFTP, or in a version control system (VCS) such as Git.

Version control systems allow for tracking changes over time, but introduce various complexities and “silos”: Content is stored in a system that requires meticulous setup and regular maintenance by a qualified operator, and a user interface for “mere mortals” who only want to author content.

We currently offer simple, straightforward storage in a file-based system. We may introduce a versioning system later.

Step 3: Rendering content

Markdown documents are converted to the relevant target formats, either individually (e.g., the French manual for a new product) or in batches (all documents for a specific product).

In our workflow, conversion is so fast that it is possible to convert all product manuals for a typical consumer brand in one pass – this will usually not take longer than a few minutes, even for large document sets.

Step 4: Customizing output through templates

In a modern single-source publishing workflow such as LOOPS / Specs and Docs, it is possible to customize output both for a specific target format and specific uses by using templates. Examples:

• A Markdown source with YAML metadata is rendered in full for the HTML target format.
• Only the section tagged “For Intranet” is rendered in Microsoft Word format.
• A subsection of the source document marked as “print” is rendered through a second HTML target template that will only show content intended for printing. These HTML documents, when styled correctly, can be rendered as PDFs from LOOPS, a web browser running in headless mode, or a dedicated HTML-to-PDF rendering engine.

Step 5: Styling output through style sheets

In a single-source publishing workflow, content can be styled using the respective target format’s styling mechanism. Examples:

• A Markdown source is output in HTML format, and the HTML document (template) is linked to one or multiple Cascading Style Sheets.
• The same Markdown source could be sent through another HTML template that is linked to different style sheets.
• A Markdown source is rendered in DOCX (Office Open XML) format. When rendering the DOCX output, a reference Microsoft Word document guides the creation of the document by applying the corporate design-compliant paragraph styles.

Step 6: Publishing

The documents created in a single-source publishing workflow can be published in various ways. Examples:

• HTML pages can be deployed to a web server using SFTP or Dropbox upload.
• “Headless” HTML pages (without html and body tags) can be imported into a content management system.
• Microsoft Word (.docx) documents can be distributed on an intranet.
• PDFs can be distributed via e-mail, uploaded to a website, or printed as needed.

Step 7: Updating

To update content with new information or correct errors, only the original Markdown documents need to be changed. All formats derived from the Markdown source are updated when the content is rendered next time.

“What is semantic publishing?”

Semantic publishing is about adding meaning to published information. This is achieved through the use of semantic markup. Semantic markup is achieved by adding tags that describe the content rather than just how it should be presented.

Think about it like this (and inspect this page’s source code, if you are interested):

Bold text may seem visually different from regular text, but to a computer program it’s all just text.

Semantic markup goes beyond visual cues and tells browsers, search engines, and other applications:

• “This is a heading” or
• “this is important.” or
• “This is the name of a function or user element.”

“What are the advantages of semantic publishing?”

• Search engines and other applications, such as large language models trained on web content, can understand the structure and even the meaning of the information. This makes search and data integration much more efficient.
• Search engines can better understand the context of semantically tagged content, potentially giving it a ranking boost in search results. Google’s “Rich snippets” are a well-known example of how semantic markup can extract and present relevant information.
• Semantic markup allows you to create richer, more informative content. For example, you can use semantic markup to highlight definitions or figures.
• Unambiguous semantic markup allows users to navigate and interact with information more easily.

“What is information granularity in digital publishing?”

Information granularity in digital publishing refers to the level of detail or depth at which content is segmented and presented.

From an author’s perspective, granularity involves breaking down information into smaller, more manageable units or components. Granularity allows publishers to control the level of detail provided to audiences and provides flexibility in accessing and manipulating content. Think of granularity as having a bucket of Lego bricks that can be assembled into anything you can imagine, rather than just owning one monolithic model.

In the context of digital publishing, information granularity can manifest in various ways, including:

Content Units

Breaking down content into smaller units, such as paragraphs, sections, or chapters, allows for more granular control over the presentation of information and navigation tools made available to the reader. “Monolithic” documents (where presentation and content are predefined and inseparable) are hard to repurpose – think of clay tablets and handwritten documents. Granular content, on the other hand, can easily be taken out of the original context, reformatted, and reused as required.

Multimedia Elements

Granularity can involve the inclusion of multimedia elements like images, videos, and interactive components, and these elements may also have granular characteristics. These multimedia elements can be independently manipulated and accessed, providing a more detailed and engaging user experience.

Metadata

Information about the content, such as tags, categories, and keywords, contributes to granularity. This metadata helps in organizing and categorizing content, making it easier for users to discover and navigate through digital publications.

Responsive Design

Granularity is essential in designing responsive layouts for different devices and screen sizes. Content may be adapted and restructured to suit the specific requirements of various target devices, ensuring a consistent and optimal user experience.

User Interactivity

Granularity enables interactive features, such as hyperlinks, pop-ups, or tooltips, allowing users to explore additional details or related content with a click or tap.

Adaptive Content

Granular content can be adapted to suit different user preferences, such as language, reading level, or topic of interest. This adaptability enhances the user experience and makes digital publications more accessible.

In summary, information granularity in digital publishing allows publishers to customize the presentation of content, cater to diverse audience preferences, and enhance the overall user experience. It plays a crucial role in the effective communication of information in the digital realm.

“What are smart documents?”

A smart document is more than just a series of sentences (and images). A smart document contains structural information that allows software to access, manipulate, and extend its elements.

Smart document features in LOOPS include:

Index builders

Documents and templates can be configured to generate and display internal hyperlinked lists of arbitrary elements such as headings (this will create a classical table of contents), images, tables, etc.

Anchors

Document templates can be configured to expose unique IDs of document elements such as headings, tables, or images for bookmarking purposes. This enables support staff to refer users not only to a specific document, but also to a specific section or element within that document, so that they can find the information they need more quickly, while still retaining the context.

Navigation tools

In-document hyperlinks can be used to navigate directly to the previous or next element of a specific type (heading, table, or illustration).

Style switchers

Style sheet switchers allow users to adjust the display of a document to their preference, for example, by switching to a higher contrast or font size.

Filtering

Widgets allow users to hide information they currently don’t want to see, leaving only the relevant parts. Popular applications include “Only show illustrations” and “Only show specifications” controls.

Transclusion

Transclusion is a feature that allows users to access an information source (a secondary document such as a glossary entry) within the current document, avoiding a “lost in hyperspace situation”.

3. Translation

“What is machine translation?”

Machine translation refers to the use of software to translate text or speech from one language to another automatically. The goal of machine translation is to enable communication between people who speak different languages by automatically generating accurate and coherent translations.

The most recent and powerful approach to machine translation is Neural Machine Translation (NMT). NMT uses artificial neural networks, particularly recurrent neural networks (RNNs) or transformer models. These models learn to map input sentences in one language to output sentences in another. NMT has achieved significant success and is known for its ability to capture context and produce more fluent translations.

“How good is machine translation in 2025?”

While machine translation systems have made considerable progress, achieving human-level translation accuracy remains a challenging task due to the complexities of language, cultural nuances, and the inherent ambiguity of certain expressions. However, for some industries, topics, and language pairs, it is definitely possible to publish machine-translated content without any post-editing by a human editor. Well-written and translation-friendly product literature (especially manuals for consumer products) is a strong candidate for machine translations that can be published without human post-editing.

“What is “translation-friendly writing?”

Translation-friendly writing refers to the practice of creating content in a way that makes it easier to translate into other languages while maintaining its accuracy and clarity. Principles and techniques for writing translation-friendly content include clarity, simplicity, consistency, and conciseness.

Translation tiers

Please note that the following is not a generally accepted and used classification, but a simplified model of content translation.

Tier 1 – human translation

Tier 1 expert human translation refers to a translation process where a document or document set is translated in full by a human translator to another language. Variations within this tier would include…

• Translator skills: Content may be translated by professional full-time translators, subject matter experts, or lesser qualified individuals.
• Review: Translations may be reviewed/proofread by one or more reviewers proficient in the source and target language. In an ideal setup, these reviewers are also subject-matter experts.

While full human translation by a professional translator usually produces the highest quality, it also entails the highest costs, especially if the translations also need to be reviewed.

Tier 2 – post-edited machine translation

Tier 2 – post-edited machine translation refers to a translation process where a document is translated using a machine translation engine, and a human translator or reviewer will review and edit this machine translation as necessary before publishing. This process is called translation post-editing.

Tier 2 translations are more cost-effective than tier 1, as the basic translation work is done automatically. When a high-quality machine translation engine is used, the majority of translation units (sentences) will require little or no editing.

Tier 3 – user-side machine translation

Tier 3 – user-side machine translation refers to a translation process where an end user will initiate machine translation of the currently displayed document (usually an HTML document rendered by a web browser) using a machine translation engine. The machine translation will then replace the original document with the unedited (”raw”) machine translation.

Tier 3 translations are the most cost-effective approach because the translations are essentially free. In other words: The cost of the machine translation is covered by an agreement between the browser vendor and the machine translation engine provider. However, as there is no human subject matter expert or reviewer involved, errors and ambiguities in the translation are more likely.

4. Accessibility

“Why is accessibility relevant?”

Product literature accessibility is relevant for several important reasons:

Inclusivity

Accessibility ensures that everyone, including people with disabilities, can access and use websites, removing barriers that might otherwise prevent individuals from fully engaging with digital content.

Legal compliance

Many countries have laws and regulations that require user-facing sources such as websites, support databases, and other published product information to be accessible to people with disabilities. Failure to comply with such laws and regulations on accessibility can result in legal consequences and penalties.

Improved user experience

Accessibility features often improve the overall user experience for everyone, not just people with disabilities. For example, closed captioning on videos benefits not only people who are hard of hearing, but also users in noisy environments who can’t hear the audio.

Search Engine Optimization (SEO)

Search engines increasingly consider accessibility as a ranking factor. Accessible websites are more likely to be indexed and rank higher in search results, resulting in increased visibility and traffic.

Technological advances

As technology evolves, new devices and platforms emerge. By designing for accessibility from the outset, your company can ensure the long-term success and relevance of your website. At the same time, you increase the likelihood that your content will be accessible on as many current and future devices and technologies as possible.

Brand Reputation

A commitment to accessibility can enhance your brand reputation. People value organizations that prioritize inclusivity and take steps to make their products and services accessible to everyone.

Financial benefits

When manuals and support content are accessible to a broad audience, this can increase the number of satisfied customers and motivate them to continue using the provider’s products and services in the future.

“What disabilities should be considered when creating accessible product literature?”

Cognitive Disabilities

Cognitive disabilities refer to conditions that affect cognitive functions such as memory, attention, problem-solving, and comprehension. Examples include dyslexia, attention deficit hyperactivity disorder (ADHD), and intellectual disabilities.

According to the World Health Organization (WHO), approximately 15 % of the world’s population lives with some form of cognitive disability.

Sensory Disabilities

Sensory disabilities involve impairments in one or more of the senses, including sight, hearing, touch, taste, and smell. Typical examples are blindness, deafness, and tactile sensitivities.

According to the World Health Organization, an estimated 2.2 billion people globally have vision impairment or blindness, and over 5 % of the world’s population (466 million people) has disabling hearing loss.

Motor Disabilities

Motor disabilities affect a person’s physical movement or coordination. Conditions such as paralysis, muscular dystrophy, and cerebral palsy fall under this category.

The prevalence of motor disabilities varies, but according to the World Health Organization, around 15 % of the world’s population experiences some form of disability, and a significant portion of this includes motor disabilities.

“How many potential users of our products and product information are affected by disabilities?”

The World Health Organization estimates that approximately 15 % of the global population (1.3 billion people) has some form of disability.

In the United States, the Centers for Disease Control and Prevention (CDC) reports that about 26 % of adults in the country have some type of disability.

According to the World Bank, people with disabilities are often more likely to experience poverty and face barriers to education and employment.

World Health Organization Disability Fact sheet

“How can your semantic publishing solution(s) save us money?”

Put shortly: Using a modern workflow for publishing product literature will save brands money by reducing or eliminating all kinds of transformation processes:

• Using an open format (HTML) means that content (prose) can easily be translated from one language (usually English) to another, using either server-side machine translation (with or without post-editing) or user-side machine translation in a web browser.
• The use of well-formatted, semantic HTML also improves the accessibility of published documents, making life easier for everyone and significantly improving the experience of users with motor, cognitive, or sensory impairments.
• Our workflow supports adding product information as key-value pairs in YAML format. This allows authors or product managers to enter product data and have it transformed into both human- and machine-readable output formats. Better product information data increases visibility / search engine optimization.

5. Artificial Intelligence

“How and where does artificial intelligence come into play?”

Popular large language models can be accessed either via a public web interface or using APIs. If you want to use artificial intelligence to create, modify, extend, or translate product literature, you can use both approaches. Markdown-formatted content can simply be pasted into the frontends of popular LLMs for extending and polishing content. For more information, see our article “Markdown and Large Language Models: a perfect combination”.

Appendix: General terminology

Product literature

Product literature usually refers to printed or digital materials that provide information about a particular product. This can include brochures, user manuals, spec sheets, data sheets, product catalogs, and other documents that detail the features, specifications, usage instructions, and benefits of the product. Product literature is used for marketing and informational purposes to help consumers make informed purchasing decisions and to assist them in using the product effectively. It may also include technical information for those involved in product development, distribution, or maintenance. Product literature is usually, but not always, available on or linked to product web pages on manufacturer or distributor sites.

Semantic HTML

Semantic HTML refers to the use of HTML elements to convey the meaning or structure of the content they enclose, rather than just dictating its appearance. In other words, properly used semantic HTML tags describe the purpose or role of the content they are assigned to. Semantic HTML improves the readability and maintainability of the code and provides benefits for accessibility, search engine optimization (SEO), and interoperability with other web technologies. Screen readers, search engine crawlers, and other tools can better “understand” the structure and meaning of the content when semantic HTML is used, leading to improved user experiences and better search engine rankings.

↻ 2025-08-21