This document guides you directly and as simply as possible in using adoc Studio. You’ll learn about the app’s structure, get to know the most important commands, and receive many hints on where to delve deeper into the documentation with adoc Studio. Additionally, the source code of this documentation provides an example of how to structure a project in adoc Studio. Access it from the main menu under Help  User Manual.

This documentation is based on the beta version of adoc Studio. Please inform us of any errors and issues in the forum.

Notation in this document

You will find some notes in the text that will give you special help.

Additional notes are displayed as a note.
Whenever there is an opportunity for a special hint, you will receive a tip.
The bell appears to alert you to special features.
Whenever you need to take special care before performing an action, this warning will appear.
Attention, here we try to draw your attention to existing dangers, damage or consequences.

You can recognize menu commands by the structure of the menu: File  Export  Products…​. If there is a keyboard shortcut, you can recognize it by this representation ++E.

Please note that operating instructions, manuals and software are protected by copyright. Copying, duplicating, translating or converting into any electronic medium or machine-readable form in whole or in part is not permitted without the prior written consent of ProjectWizards. All other rights to the software are set out in the supplied license terms. The rights to other trademarks and product names mentioned in this manual belong to their owners and are hereby acknowledged. The naming of products that are not from ProjectWizards is for information purposes only and does not constitute advertising. ProjectWizards assumes no liability with regard to the selection, performance or usability of these products.

adocstudio

2. What is adoc Studio?

When we talk about adoc Studio, we’re referring to an integrated writing environment that generates documents in HTML, PDF, and later, additional formats like ePub, based on the markup language AsciiDoc. With this, we already have a few terms that need explanation because they might not be familiar to everyone.

Markup Language

Most people are familiar with Microsoft Word or other WYSIWYG editors. In contrast, in recent years, several markup languages like Markdown have gained significant popularity. These no longer display the result in a print-like preview (as MS Word or Apple’s Pages does) but need to be translated - sometimes with more effort, sometimes with less.

AsciiDoc

The foundation of adoc Studio is AsciiDoc, which is one of the older representatives of markup languages. Notably, the fact that the Eclipse Foundation aims to standardize the scope of AsciiDoc is a guarantee of a future-proof decision for you. However, we primarily chose AsciiDoc because it’s very easy for beginners to learn while providing a comprehensive set of commands for professionals.

Integrated Writing Environment

To make everything easy to operate, you need a program that includes all the necessary functions. Here, you enter text, organize them in projects, use the preview for an initial overview, and finally, export the documents individually or as finished products.

Of course, adoc Studio can be configured as an integrated writing environment according to your preferences. You determine the appearance of the editor and select an output style. We provide some styles and regularly release more on our website.

In adoc Studio, you focus exclusively on the structure and content of your document. Naturally, you will make bold statements and emphasize what requires special emphasis. And, of course, emojis are also available in our app 😀.

2.1. What is a Markup Language?

Historically, the term markup comes from typography. Printers - the people of the printing trade - used the term to refer to the highlighting of text parts, such as using font variants different from the base font, like italic and bold typefaces or small capitals, using uppercase letters (capital letters), using letter spacing, underlining, or coloring of text, as well as different font sizes and styles. This also included (handwritten) marking of corresponding sections in the associated manuscript (from Wikipedia). And this concept was adapted into the computer era and software. This is where our markup language comes in.

You may have already heard of the language Markdown or a phrase like "the text is written in Markdown." You are on the right track. On one hand, we have plain text - letters without formatting. On the other hand, we have notations that highlight the text: what is a heading, what is bold, italic, or a link, and so on.

There are many markup languages, not to be confused with word processors like MS Word. The three most well-known representatives of markup languages are:

  • HTML, the language of the Internet, but also quite verbose.

  • TeX or LaTeX, probably the most popular typesetting system for scientific articles, but relatively rare and difficult to learn in the business world.

  • Markdown, very simple - perhaps too simple, lacking many features for technical documentation. Here is a detailed comparison of Markdown and AsciiDoc.

Due to the disadvantages of the languages mentioned above, we have chosen AsciiDoc as the markup language. At ProjectWizards, we have been writing all our manuals and public documents in this format since 2007.

AsciiDoc is a mature, lightweight, and semantic markup language that was primarily developed for creating technical documentation. Of course, it is ideal for all kinds of structured texts. And let’s be honest, with over 10 million downloads (Source: Asciidoctor History), there is always someone who can help. This honor naturally goes to Asciidoctor, the first parser of AsciiDoc texts.

2.2. What about Word, Pages, or Google Docs?

There are many reasons why you might choose adoc Studio over WYSIWYG word processors like Microsoft Word, Apple Pages, or Google Docs:

The abbreviation has been in common use since the 90s: WYSIWYG – or in full form: "What you see is what you get." This describes the output of documents, which should be as displayed on the screen. In other words, "What you see is what you get."
  1. Separation of Content and Presentation: Text-based markup languages allow you to separate content from presentation. This enables consistent formatting across different documents and makes it easier to change the appearance of documents all at once. A document written in a markup language can be opened on any computer without special software.

  2. Portability: Text-based markup languages are universal and cross-platform. They can be opened and edited on any device and operating system. Word files can look very different on different computers.

  3. Version Control: Markup languages are compatible with version control systems like Git, making collaboration and tracking changes in large documents easier. Even though Word has now introduced an XML format, many administrators still refuse to check these files into a Git.

  4. Reusability: You can create a document in a markup language and then convert it into various formats, such as HTML for a website, PDF for printing, EPUB for e-books, and so on.

  5. Flexibility: Text-based markup languages allow for high levels of customization. You can customize the appearance and behavior of your documents in ways that are often not possible in standard word processing programs.

  6. Automation: You can use automated scripts and tools to generate, process, and manipulate documents in text-based markup languages. This can save time and reduce errors, especially with large documents.

  7. Stability and Longevity: Text-based markup languages are typically stable and enduring, unlike proprietary file formats that may change over time.

2.3. Installation

The beta version of adoc Studio is exclusively distributed via TestFlight. Visit our website and download the latest TestFlight version for free.

System Requirements

The minimum system requirements for adoc Studio are:

  • On Mac: macOS 13 (Ventura)

  • On iPad: iPadOS 16

  • On iPhone: iOS 16

3. Getting to Know adoc Studio

In this chapter, you will discover the app and the concepts that make using it easier.

3.1. The User Interface

After launching adoc Studio, you will see a screen similar to this one. Here, we have accessed the user manual - which was, of course, created with adoc Studio - from the Help menu.

100%

The window layout in adoc Studio is divided into three parts:

At the top of the window, there is, of course, the obligatory toolbar with these functions:

  • Show/hide the sidebar (keyboard shortcut: +0)

  • Create a new component (or via: ++N)

  • Navigation backward and forward buttons (also via ++< and ++>)

  • Directory tree as a popup list

  • Content structure as a popup list

  • Optionally, a list of all products

  • Show/hide the editor (with pencil or ++E)

  • Show/hide the preview - (with eye or ++E) including the settings

Each section can be individually shown or hidden, allowing for a perfect setup for every screen size. You can find the corresponding functions in the menus View, Editor, and Preview.

3.2. The Project Navigator

In adoc Studio, you work in a project-oriented manner, but what does that mean? In the simplest case, this includes your text and, if used, also the images in the text. However, the longer a text becomes, the more problematic it becomes to maintain an overview. Therefore, it’s common to split a text into smaller sections. These sections are stored in many individual files, interspersed with images. This inevitably leads to chaos, as maintaining an overview becomes challenging. To prevent this from happening, we offer the composite document in adoc Studio.

This chapter covers how to work with projects, files, and everything related.

Creating a New Project

When you create a new project in adoc Studio (via the menu File  New  Project), you will find two items in the sidebar:

new project
  • A folder for media

  • A file for the document

Whether the file extension is .adoc as shown in the image on the right depends on the settings in the adoc Studio menu (+,).

Of course, all items (files and folders) in the sidebar can be moved around. You can nest them within each other, restructure them, or rearrange them as needed.

Media and images can be placed anywhere in the project. We recommend organizing them in media folders. If the automatically created media folder is not sufficient, you can create as many as you need in your project.

Standalone Documents

new project 2

Next, we expand our project by adding a standalone document. You can use the menu File  New, +N, or the + button at the top of the sidebar to achieve this. These are independent documents that exist on their own. The process is as simple as it is logical:

  1. You click on a document.

  2. It is displayed in the editor for editing.

  3. In the preview, you see the most up-to-date version.

Clicking on another document will display it in the editor, and so on.

This means that you won’t see the contents of the second document more.adoc in Document.adoc. Of course, in AsciiDoc, there are techniques to display contents from other documents; the Includes. But we’ll get to that later.

Composite Documents

Composite documents contrast with standalone documents. The term describes it; you collect your documents into one large document. As a result, the newly created files in a composite document are no longer named Document.adoc but rather Chapter.adoc.

In a composite document, you can also use folders for structuring, nested to any depth. However, when you click on a folder, all the chapters contained within it are displayed cohesively in the preview. The further up the hierarchy you go in the sidebar, the more extensive the displayed contents become. Since the focus in the sidebar is now on a folder, nothing is displayed in the editor. To edit a chapter, select it specifically, and the preview immediately switches to display the text in the editor.

Folders for Structuring

If you create new independent files gradually, the sidebar will eventually become cluttered. Of course, you can use the filter at the bottom of the sidebar for quick file retrieval. However, it is temporary and will be empty again after restarting adoc Studio.

Therefore, the next structural tool comes into play; folders. Just like in an operating system, you can create folders in adoc Studio. Name them according to the rules of the operating system. In a folder, you can store many documents. You can also create folders within other folders.

However, the concept of individual documents remains. Even if you have created many folders and placed many files inside them, they all remain separate from each other. If this is what you want, then you’re done here. But if you are writing a book with many chapters, you need another document; the composite document.

Media Folders

The media folder has a special purpose. By default, you can store all media (images, videos, etc.) in this folder. adoc Studio searches for media in the project in a predetermined order.

Search Order for Images

The line images::image.jpg[]

  1. searches for the file image.jpg first at the same level where the .adoc file is located.

  2. Then, it goes up one level and searches for the image there.

  3. If it is not found, the media folders are searched from top to bottom.

  4. If a picture is still not found, the editor will mark the filename in red, and an entry will be added to the problem navigator in the sidebar.

error image
Images with Path Specifications
  • The line images::/image.jpg[] searches for the image in the project directory (where the .adocproject is located).

  • The line images::/Folder/image.jpg[] searches for the image in the subdirectory Folder, starting from the project directory.

  • The line images::../image.jpg[] searches for the image one level above the text file in which it is referenced.

In essence, you can specify all paths as you would in an operating system. The root is always the project directory, where your .adocproject is located.

For AsciiDoc experts: The concept of imagesdir also exists in adoc Studio. If you use the attribute in existing (external) projects, it always appears in front of images and possible path references. However, it is not set automatically!

Thus:

image::Folder/image.jpg[]

becomes:

image::{imagesdir}/Folder/image.jpg[]

There are many more details about this on the AsciiDoc website.

You can have many media folders. Here are a few examples:

  • A folder for general images

  • A folder for images in a specific language

  • A folder for images on a specific platform

In this project, for example, we placed the images for the iPad in a separate media folder and controlled their use in the products via the iPad attribute.

There are some more peculiarities when it comes to external projects. You can find the details there.

Adding a New Component

new component

You can add a new component to your project using the plus button in the toolbar or the keyboard shortcut ++N. The dialog will respond based on your selection in the file list:

If a standalone document is selected, you can create a new standalone document or a composite document. If a composite document or one of its chapters is selected, you can create new chapters. In any case, you can add new folders, media folders, or existing files.

You can also simply drag and drop existing files from Finder into the file list to add them to your project.

Adding Existing Files

In adoc Studio, there are not only composite documents with their chapters but also standalone documents.

A standalone document does not inherit attributes from other documents in the file list. You need to explicitly set all values in these documents. Additionally, media folders located within composite documents are not accessible from standalone documents; only media folders located outside of composite documents are accessible.

Now it’s up to your creativity to decide how to incorporate these documents into your project. Here are the possibilities:

Double-click in Finder

You can double-click any .adoc file in Finder. If no other program has registered for the .adoc file extension after installation, adoc Studio will handle these files. The dialog shown below will appear, allowing you to select the destination project for the file or create a new project. This file will then be copied to the selected project—no movement!

NeuesDokument
Drag & Drop from Finder

Another way to copy files into a project is the familiar drag and drop method. Drag the desired file directly to the desired position. adoc Studio will automatically include it as part of a composite document if the target is one.

File Operations Directly in Finder

Of course, files can also be copied or moved directly to the project directory in Finder. adoc Studio will automatically recognize them, and after a short moment, they will appear directly in the file list in your project. The app does not need to be restarted.

Menu Function

Finally, there is a menu function to add files to your projects. Use File  New  Add Files… or the shortcut ++A to open the file selection dialog. The selected file(s) will be inserted below the selection in the file list. You can then use the mouse to move them to another location.

When you drag a file into a composite document, it will automatically become a chapter of the respective composite document.

File Information

Sometimes, a file should be in a composite document but not displayed. We have an elegant solution for that:

file inspector

With a right-click on the file in the file directory on the left sidebar, you can access the context menu. Here, you’ll find the Information… option, which opens the dialog shown on the right.

Simply deactivate the "Part of the composite document" switch, and the file will no longer be included. If you still want to use it, you must include it using the include command.

More Information

Most files and all folders in the sidebar can be modified via the Information…. In addition to renaming a file or folder, there are the following options:

For files: Part of a composite document For folders: Composite document Media directory Folder

3.3. Saving a Project

saveProject
The Traditional Way

In the past, it was always a good idea to save a new project in the first step. You actively specify where the project is created. This is done through the menu File  Save… or the keyboard shortcut +S.

You can choose whether to save the files from adoc Studio on your local computer or place them on a server or cloud storage. You can also use version control systems like Git or Github.

The New Way

But even without initial saving, you don’t have to worry about data loss. If you close the last project window, adoc Studio will ask if you want to save the project. You can decide whether and where to save the project.

Even though it may feel unusual at first, in adoc Studio, you no longer need to worry about regularly saving .adoc files. The app does this for you at very short intervals. For peace of mind, you can always press the familiar shortcut +S. But rest assured, the computer is faster.

3.4. Opening Additional Windows for a Project

You can open a project in multiple windows using the menu Window  New Window. This can be particularly helpful in a two-monitor setup if you want to view the preview in a separate window.

On your Mac, clicking on the window title with the mouse while holding down will show you a menu with the path to the current project in Finder.

4. Externe Projekte

The externen Projekte are not yet described. We are working on making up for this as soon as possible.

The second tab in the sidebar displays the structure of headings as an outline.

For composite documents, the entire table of contents is always displayed, regardless of which chapter you are currently working on.

For standalone documents, only their own table of contents is displayed.

If you want to generate a table of contents within your text, you can use the :toc: attribute, which is explained here.
search context menu

To find texts in the entire project, use the third tab in the sidebar; the Find Navigator.

In the context menu behind the magnifying glass, switch on Replace. If you do not want to search for

  • upper/lower case or

  • accents/umlauts

you will also find the switches here as well. The hits are grouped according to the files in the project.

Special features

If you also want to replace found text, adoc Studio offers some practical additions:

  • If you select individual hits in the list (multiple selection is possible using the key), the replacements will only be made for the selected positions.

  • If you select a file in the hit list, the replacements will only be made in this file.

The concept for AsciiDoc and adoc Studio is to always generate a text, regardless of whether or how many AsciiDoc errors are present in the text. This is not about grammatical and orthographic errors.

If there is a problem with an AsciiDoc command in the text, the error list icon appears in red: errorlist

Since not every error carries the same weight, minor issues, i.e., warnings, are displayed in yellow.

The list itself is sorted by occurrence. Clicking on an error message will take the editor to the corresponding location so that you can resolve the error.

4.4. Writing Text and Navigating Within

Now, select a text file from the file list. If the cursor is not blinking in the editor window, you can place the cursor there with a confident click in the middle area of the window (or press +TAB), and you’re ready to go. You start writing your text. You’ll find information about AsciiDoc in the next chapter.

The text you enter appears immediately in the preview. For longer texts, the positions of both windows are synchronized. This means that on the right, you always see the text written on the left at the same level. More precisely, the cursor’s position is synchronized with the position in the preview.

Even though the temptation to switch to PDF preview may be great, we recommend sticking with HTML preview for long texts. Generating a complete PDF document can be slow in practice for large documents. In contrast, the HTML preview can be updated step by step, which is much faster.

You can customize the editor itself according to your preferences (color perception, diopter strength, etc.). The Tab Editor Styles in the Program Settings offers you almost endless design possibilities.

Additional Navigation

Above the editor, you’ll find a special control element: the Additional Navigation.

This starts with navigation arrows pointing left arrow left and right arrow right . The function is similar to your web browser - navigating forward and backward.

Next, there’s a graphical block:

zusatz navigation

This element is particularly valuable on small screens - but not only there. When reading from left to right, you can see where the file you’re currently writing is located. On the far right, you have a small table of contents of the structure, which also shows the overall context. Moreover, you can jump to any file with any element.

Line Numbers

A single line number appears on the right edge of the editor for personal orientation. In most cases, this is sufficient if you don’t need to communicate with others about a text position. If you prefer to display all line numbers, you can configure that in the settings.

Clicking on a line number (or +L) gives you the option to jump to a specific line.
  1. Texts are immediately saved too

Just like the project files, changes in the texts are immediately saved. So, you don’t have to worry about data loss here!

Moving the Cursor

Of course, when writing, you don’t want to take your hand off the keyboard too often to position the cursor with the mouse. Therefore, we’ve adopted the familiar shortcuts (to use the English term) for text editing from macOS and iPadOS and offer them exactly the same way in adoc Studio.

Table 1. Modifier keys used

Command key

Option key

Control key

Shift key

Enter key

Return key

Delete key

Forward delete key (only on extended keyboards)

Table 2. Movement within the document

Move one character to the left

Move one character to the right

Move one line up

Move one line down

+

Move one word to the left

+

Move one word to the right

+

Move to the beginning of the line

+A

Move to the beginning of the line

+

Move to the end of the line

+E

Move to the end of the line

+

Move to the beginning of the document

+

Move to the end of the document

Table 3. Selections within the document

+

Expand selection to the left

+

Expand selection to the right

+

Expand selection upwards

+

Expand selection downwards

++

Expand selection to the word on the left

++

Expand selection to the word on the right

++

Expand selection to the beginning of the document

++

Expand selection to the end of the document

Table 4. Deleting within the document

+K

Delete the current line to the right of the cursor

+

Delete the current line to the left of the cursor

+

Delete the word to the left of the cursor

+

Delete the word to the left of the cursor

But there’s another shortcut in adoc Studio that you’ll want to use regularly: the ESC key. And with that, we enter the realm of input aids.

4.5. Input Aids

The scope of AsciiDoc is very extensive. Therefore, even professionals can forget a command, overlook a macro, or simply not remember a specific syntax. That’s why adoc Studio has an intelligent input aid built-in.

While you write, the app is always looking for ways to help you. Often, after the second or third character, it recognizes various possibilities and offers them in a completion menu. adoc Studio tries to disturb your writing flow as little as possible.

If needed, you can access the input aid menu anytime using the ESC key.

completion images

How to Embed an Image in Text

  1. Start typing at the beginning of a line: ima

  2. A short menu appears:

    completion image

  3. Use the or keys to navigate the list.

  4. Select the desired entry with the key (here, whether it should be an image as a block or in the text line).

  5. After the selection, another menu appears immediately:

    completion image adoc

    Conveniently, the images are displayed as small previews.

  6. And it continues. After selecting the appropriate image with the key, the image appears in the preview at full width.

  7. Place the cursor between the two square brackets after the image name ([]) to enter the appropriate options for the image.

  8. First, let’s adjust the width of the image, so type wi, and at this point, the menu appears again. Now, all available image options containing wi are listed.

  9. Use the cursor keys to select width=, then press the key.

  10. Now you’ll see this: completion image placeholder

  11. Overwrite the placeholder text with a number (e.g., 200), and you’ll immediately see the image scaling in the preview.

  12. Now, place the cursor again between the two square brackets after the image name ([]) - it doesn’t matter whether it’s before or after the width option. What’s important is that all options are separated by a comma.

  13. Now, press the ESC key to bring up the completion menu with additional options for the image. Suppose we want to position the image to the right of some text.

  14. For that, we need the float option. So start typing flo, and the completion menu shrinks to the terms containing flo:

    completion image float

  15. Now, select float=right.

Now you’ve inserted an image, it’s scaled, and positioned to the right of the text. Congratulations! Here’s the resulting text (including some "lorem ipsum" placeholder text):

image::adocstudio.png[width=200, float=right]

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

And here’s the result:

completion image example
Just like in the example where an image (image::) was used, a completion menu is available for every AsciiDoc command and all attributes. When in doubt, simply press the ESC key.

5. Program Settings

In adoc Studio, many areas can be customized.

5.1. General

You can open the settings window via the main menu adoc Studio  Settings … or the keyboard shortcut ⌘+,.

Here, you will find the most important settings for your editor under the General tab:

settings general
Line Numbers

Here, you define whether all line numbers or only the current line should be displayed.

Section Collapse Buttons

Activate the triangles here to expand and collapse sections in the text.

Show File Extensions

Do you want all file extensions to be displayed in the Project Navigator in the sidebar? If this is deactivated, the file extension will only appear for the currently selected file.

Line Width

Specify the number of characters that can be entered into a line of the editor before it wraps. If the displayed area is too small, wrapping will occur in any case.

Section Indentation

You specify how much space should remain free for the left indentation of the equal signs of headings. You determine the left margin with a value between 0 and 6. This allows you to achieve a nice left alignment for the body text. Only the = characters extend further to the left.

Tab Width

Your setting for the width of a tab in the text. Here, you specify the character width of a tab with a value between 1 and 100. In practice, values between 3 and 5 have proven to be effective.

Indent With

How would you like to fill the space when indenting? With tabs or spaces.

5.2. File Access

settings fileaccess

A major concern with modern operating systems like macOS and iOS is security. The goal is to keep malicious programs away from the depths of the operating system. For this reason, Apple introduced the concept of the sandbox for macOS and iOS.

Every app has its own sandbox and is only allowed to work within it. This means that on your computer, there are many apps, each of which can only run within its own sandbox. If an app wants to work outside of the sandbox, it must obtain permission from the user.

This also applies to adoc Studio on macOS and iOS. Since adoc Studio needs to access all the included text and media files to process projects, it requires explicit permission from you.

All allowed file accesses are recorded in a list that can be viewed on this tab in the settings and managed using the + and - buttons. When you open a new project that is not yet listed here, the app will ask for permission and automatically add it.

For convenience, you can also include folders at a higher level in the file structure. This way, you won’t be asked as often.

5.3. Editor Styles

settings editorstyles

Here, you define the appearance of the editor. Click through the list of named styles on the left side with the mouse. Most styles are available for both the Light Mode (marked with ○ at the end) and the Dark Mode (marked with ● at the end). Choose a style that you like or that best suits your taste. Then proceed.

The middle list provides all the elements, attributes, and function names used in the text. Follow a simple rule here: Start with the "General" entry and set the font, size, and other desired attributes there.

If your system is set to automatically switch between Light and Dark modes, adoc Studio will remember the last selected style so that the app can follow the system’s automatic mode change.

5.4. Product Styles

Also found in adoc Studio  Settings … (Shortcut: ⌘+), you can find Product Styles on the fourth tab.

As described earlier in adoc Studio, text and design are separated. Every design comes from a style file: the Product Styles. adoc Studio includes a variety of Product Styles, but you can also create your own. The special charm of these Product Styles lies in the technology used. Whether you choose to output as text, HTML, or PDF, the styling is done using Cascading Style Sheets (CSS).

Yes, you read that correctly; you can format all documents, even for PDF, using a CSS style!

In this Settings tab, you manage your Product Styles.

settings productstyles

On the left side, your custom Product Styles are listed first, followed by the included Product Styles after a separator. On the right side, examples are displayed in the previously selected Product Style. Under the preview, you can choose different examples (left) and the output format (right).

Installing Custom Product Styles

Product Styles are files with the extension .adocstyle. New Product Styles can be installed in the Finder by double-clicking the file. Alternatively, you can simply drag them into the list on the left side of the Settings. Finally, under the list of existing Product Styles, you’ll find a +-Button that allows you to add new ones.

Removing Product Styles

Only custom Product Styles can be removed. Right-click on the desired Product Style, and select the Delete option from the context menu.

Creating Custom Product Styles

To create or modify Product Styles, you need CSS knowledge. Here, we describe how to create a Product Style based on an existing one in the simplest way possible:

  • To create a custom style, select the Product Style you want to use as a base.

  • Next, right-click on the Product Style name, and select the "Duplicate" option from the context menu. Alternatively, you can also access the context menu directly on the Product Style name.

  • The duplicated style will then appear as a new style at the top of the list.

  • After double-clicking on the name, you can make changes to it.

Editing a Style

To edit the Product Style, you will need a text editor. In our case, we like to use BBEdit. You can use any text editor that can save CSS files in UTF-8 format.

  • Select the newly created Product Style.

  • In the ellipsis.circle - menu or the context menu, you will now find the "Edit in" option.

  • Choose your preferred editor from the list.

  • The chosen app will start, and the Product Style will be opened in the app.

  • Now you can make all the desired changes to the Product Style.

Make sure that adoc Studio is running in the background and that the style you are editing is also set for preview. This way, the preview in adoc Studio will be updated immediately, and your changes will be saved in the external editor.

6. The Markup Language AsciiDoc

As previously explained, adoc Studio uses the markup language AsciiDoc as its foundation. In this chapter, we provide beginners with an initial overview of the AsciiDoc command set. Afterwards, you will find links to the corresponding pages in the official documentation.

AsciiDoc experts are welcome to skip this chapter. Instead, we have a request: On the Roadmap for adoc Studio, you will find a list of AsciiDoc features that are not yet implemented. Please prioritize your personal needs there. In our forum, we invite you to discuss these needs with us and others.

6.1. What is AsciiDoc?

AsciiDoc is a simplified markup language used for publishing texts in various document formats. AsciiDoc files can be converted into different formats, such as HTML, PDF, ePub, and others. Compared to XML-based document formats like DocBook, lightweight markup languages like AsciiDoc, which are based on plain text, have the advantage of being easy to learn. Additionally, they are very readable in their raw (source code) form. Learn more on Wikipedia.

6.2. Writing Text

You write your text as you are used to. Write everything directly in a row, just like you do in other programs - often called plain text. However, you can also write the text line by line. So, every sentence on a new line. It’s your choice. The formatted text always looks the same.

A new paragraph is created by a blank line between paragraphs.

It’s that simple.

The Preamble

The first paragraph of a document is called the preamble or sometimes abstract. This paragraph is automatically set slightly larger than the normal text. It is often used as an introduction to the document.

You can also make any other paragraphs larger by prefixing [.lead].

Example 1. Embedding an Abstract or Preamble in the Middle of Text
[.lead]
This paragraph will be displayed slightly larger than all other paragraphs. 
And with the "Optima" product style, the paragraph even gets an initial (i.e., a capital letter as a decorative element).
Result:

This paragraph will be displayed slightly larger than all other paragraphs. And with the "Optima" product style, the paragraph even gets an initial (i.e., a capital letter as a decorative element.

If you don’t want to use this effect in the first paragraph and want your text to start immediately in the regular font size, use [.nolead] prefix.

You can find more information about paragraphs on the AsciiDoc website.

6.3. Formatting

Just like in any markup language, you can also make individual words bold, italic, or otherwise styled in AsciiDoc. So, the transition is very easy. The Editor menu in adoc Studio provides you with all the important formatting options for quick access using the mouse or keyboard.

Table 5. Direct Formatting in the Editor Menu
Command Keyboard Shortcut Markup in Text Result in Preview

Bold

+B

*bold*

bold

Italic

+I

_italic_

italic

Marked

+#

#marked#

marked

Fixed Width

++#

`fixed width`

fixed width

Underlined

+U

[.underline]#underlined#

underlined

Strikethrough

++X

[.line-through]#strikethrough#

strikethrough

Overlined

+++X

[.overline]#overlined#

overlined

Superscript

++⌘+

^superscript^

superscript

Subscript

++⌘-

~subscript~

subscript

But AsciiDoc can do much more. You can combine various styles as you like. The text:

**##Super##cali[underline]##fragilist__isch##[red]##expialige__tic##** 😀

becomes:

Supercalifragilistischexpialigetic 😀

You can find more information about text formatting on the AsciiDoc website.

6.4. Headings

Headings – or more precisely – heading levels can be set using a number of = or # characters. The latter makes it easier for you to transition from Markdown to AsciiDoc. But it’s better to get used to the = character from the start because it offers much more functionality.

Here are all the headings in the source text:

= Document Title
== Heading 1
=== Heading 2
==== Heading 3
===== Heading 4
====== Heading 5
Additional Headings

If the six levels plus the document title are not sufficient, you can set a . in front of a line as a paragraph heading:

.Additional Headings
You can find more information about heading levels on the AsciiDoc website.

6.5. Table of Contents

When you define headings – or also known as Section Titles in AsciiDoc language – you automatically think of a table of contents. And automatically is the key!

If you add :toc: to the document header, the document will automatically have a table of contents. This table of contents includes two heading levels and is positioned above the document. It is updated automatically.

However, the :toc: attribute can also accept parameters:

  • left: The table of contents is positioned to the left of the text.

  • right: The table of contents is positioned to the right of the text.

  • preamble: The table of contents is positioned after the preamble.

  • macro: The table of contents is inserted at the desired location using the macro toc::[].

  • auto: The same function as without parameters.

In this context, another attribute is interesting: :toclevels: 3. By specifying the number after the toclevels attribute, you determine the number of levels that appear in the table of contents. The attribute must be set in the document header. By default, two levels are specified.

You can find more information about table of contents on the AsciiDoc website.

When it comes to linking, we distinguish between:

  • Hyperlinks to the internet

  • Cross-references within the document

The simplest link is a fully written-out address that immediately becomes a clickable URL in the preview. The corresponding page opens in the browser: https://adoc-studio.app. This works for the most important URL schemes:

  • http

  • https

  • ftp

  • irc

  • mailto

However, each link can also be output as a macro: https://www.adoc-studio.app[]. Between the brackets, you can optionally enter text that should be displayed instead of the URL:

https://www.adoc-studio.app[adoc Studio website] becomes adoc Studio website.

You can find more information about Hyperlinks on the AsciiDoc website.

Cross-references within the Document

To jump to other positions in the same document (standalone document and collection document), insert a cross-reference.

<<Reference>>

The reference is an automatic ID of a heading or an anchor.

Use automatic IDs as sparingly as possible because if you change a heading to which you have cross-referenced, it will immediately break.

It is always better to set an anchor before a heading.

[#my_anchor]
== My Heading

Now you can set the cross-reference in the text as:

<<my_anchor>>

In the rendered document, the heading will appear. Optionally, you can also set text that will be displayed instead of the heading:

<<my_anchor, Jump here>>
You can find more information about Cross-references on the AsciiDoc website.

Footnotes

Footnotes are automatically generated when using the footnote:[] macro.1 The text of the footnote is placed between square brackets:

footnote:[Here is the text of the footnote]
AsciiDoc can currently only generate footnotes displayed as endnotes. That’s why we have implemented both footnote and endnote. For compatibility with existing documents, you can use the :footnotes-position: attribute.
You can find more information about Footnotes on the AsciiDoc website.

6.7. Images

In the introduction, we briefly touched on the topic of images and their paths. Now, let’s focus on embedding images in AsciiDoc text.

There are two ways to arrange images: as block images and as inline images.

Block Images

The basic syntax is:

image::image.png[]

The text must be on a separate line. The bracket can contain many options. adoc Studio’s auto-completion menu, as shown in the "How to Embed an Image in Text" example, can be helpful. The three most important options are:

  • width: The width of the image.

  • align: The alignment of an image.

  • float: The text flow around an image.

Inline Images

The syntax for inline images is very similar to block images, except that a : is omitted:

image:image.png[]

It inserts an image into the text flow. For example:

Please press image:reload.svg[] to reload the page.

Results in:
Please press reload to reload the page.

Inline images also allow you to easily place images side by side:

hello hello hello hello hello

You can find more information about Images on the AsciiDoc website.

6.8. Lists

Let’s start with unordered lists:

  • A list begins with an *.

    • You can use ** to indent items one level deeper.

      • And with each additional asterisk,

        • you go one level deeper again.

      • or

    • back up.

If you’re coming from Markdown, the following also works:

  • Markdown lists start with a -.

  • It works

  • just as well.

Ordered lists are equally simple:

  1. one

  2. two

  3. three

But you can also specify a number:

  1. one

  2. two

  3. three

  4. Incorrect numbering (here) is ignored, so it doesn’t become 7. (as in the editor) but 4. is displayed.

adoc Studio always generates automatic numbering!

If you want to make lists more complex, the concept is the same as with unordered lists.

  1. Step 1

    1. Step 1a

    2. Step 1b

  2. Step 2

  3. Step 3

You can even create checklists:

  • to do

  • done

  • also done

  • and even combined with other entries.

You can find more information about Lists on the AsciiDoc website.

6.9. Block Elements

A block element (also called a block) is the Swiss Army knife in AsciiDoc. There are countless ways to display and use them.

It’s important to know that blocks—unless they’re like, for example, the Admonitions that are represented on a single line—always have two delimiters: the block start and end. There are many different characters for this purpose, as seen in the following quote example:

Two things are infinite: the universe and human stupidity; and I’m not sure about the universe.

— Albert Einstein
You can find more information about Text and other blocks on the AsciiDoc website.

6.10. Admonitions

In particular, this area is worth examining in different styles. We put a lot of effort into the little icons.

Make sure that at the beginning of your document, the attribute :icons: font is set. Otherwise, instead of symbols, only text will appear.

NOTE provides additional information to the reader.
TIP suggests a trick or special tip to the reader.
WARNING alerts the reader to a danger.
CAUTION warns the reader of a pitfall.
IMPORTANT draws the reader’s attention to an important point.

And here’s a practical tip:

You can find more information about Admonitions on the AsciiDoc website.

6.11. Tables

Tables are as extensive as blocks. It starts with simple tabular representations like this:

One

Two

Three

Next comes a table header, which is simply highlighted by an empty line:

Title 1 Title 2 Title 3

One

Two

Three

Four

Five

Six

But complex examples (from the [AsciiDoc website](https://docs.asciidoctor.org/asciidoc/latest/tables/format-cell-content/)) are also possible:

Column 1 Column 2

This content is duplicated across two columns (2*) and aligned to the right edge of the cell (>).

It is rendered with a monospaced font (m).

This cell spans 3 rows (3+). The content is horizontally centered (+^+), vertically aligned at the bottom of the cell (.>) and displayed as strong formatting (s).

This content is rendered in italics (e).

This content is displayed with a monospaced font (m).

This content is bold (s), except for the word content.

End.

You can find more information about Tables on the AsciiDoc website.

6.12. User Interface

In technical documentation, descriptions of the Graphical User Interface (GUI) or simply the UI (User Interface) are commonplace. There are three important areas in this context:

Keyboard Shortcuts

Use the kbd:[] macro to create keycaps in your documentation. For example, +S quickly saves the document.

A special feature of the kbd:[] macros is demonstrated in the cursor keys in this document.

Menus

The menu:[] macro assists in describing menu entries. For example, you can initiate product export via File  Export  Products ….

Buttons

The  macro is responsible for outputting all types of buttons. This way, you always have a OK button at your disposal.

You can find more information about UI Macros on the AsciiDoc website.

6.13. Comments

Especially when viewing this document as source code in adoc Studio, it’s worth looking at the editor. After all, comments are only displayed here.

At the beginning of a line, you can mark the following text as a comment using //.

// This text is a comment and will not be output in the document.

Of course, entire sections can also be defined as comments. In that case, you just need to define a comment block using //// at the beginning and end of the block.

In this context, the question may also arise as to why someone would want to insert comments in a text that are not output in the document. Here’s a small collection of ideas:

  • The obvious // TODO: for tasks that still need to be done for the text: optimizations, improvements, corrections, etc.

  • Instructions for formatting.

  • Explanations of why a content is the way it is.

  • Internal version notes that should not be made public.

  • Notes for proofreaders.

  • and so on

You can find more information about Comments on the AsciiDoc website.

6.14. Attributes

Now we come to the area that we internally consider an absolute game-changer. With attributes, you elevate your documentation to a completely new level!

The term "attributes" is used differently in adoc Studio. Essentially, you can use them to:

  • Define values and then use them in the text.

  • Make settings in the document.

Using Attributes as Variables

Certain words, URLs, and other information are constantly and repeatedly used. Some terms change for each version of a document. And some terms, such as a URL, are so long that you only want to type them once – just to avoid mistakes. Simply set them in an attribute. You can then use them anywhere in a document as many times as you like.

Example 2. Using an Attribute as a Variable
Definition
:app-version: 1.2.3.4
Input
This document is based on version {app-version}.
Output
This document is based on version 1.2.3.4.

With this alone, you already have very extensive possibilities. In this documentation, every time the name adoc Studio appears, we use the attribute {app-name}. Here are some attributes used in this document by us:

:app-name: adoc Studio
:lang: de
:url-website: https://www.adoc-studio.app
:url-roadmap: https://adoc-studio.canny.io 
:url-styles: https://styles.adoc-studio.app 
:url-forum: https://forum.adoc-studio.app

In adoc Studio, there are a number of standard attributes that are already prepared because they appear in (almost) every document. However, these must be entered at the beginning of your document – in the document header:

  • Author information (:author:)

  • Version attributes (:revnumber:, :revdate:, and :revmark:)

  • Metadata (:description:, :keywords:)

An example for this document could look like this:

:author: Frank Blome
:revnumber: 1.0
:revdate: {docdate}
:description: This document introduces you to working with {app-name}.
:keyword: {app-name}, AsciiDoc, Technical Documentation, Manuals, and more

You can even abbreviate a standard title as follows:

= The Manual for {app-name}
Frank Blome <frank@projectwizards.net>
1.0, {docdate}

In this case, the information for :author:, :email:, :revnumber:, and :revdate: is automatically extracted from the context following the document title (=) and can later be output as an attribute with {}.

Attributes as Document Settings

The next use of attributes serves the settings of your document. Each document contains a set of name-value pairs called document attributes. These attributes allow you to configure the backend processor, declare document metadata, and you can use built-in attributes or define your own.

Document attributes must always be set at the beginning of a line!
Built-in Attributes

Built-in attributes help configure and control the document. Many built-in attributes only take effect when defined in a line at the beginning of the document.

Attributes can:

  • Provide access to document information.

  • Define document metadata.

  • Enable or disable integrated functions.

  • Configure integrated functions.

  • Specify the location of assets, such as images.

  • Store content for reuse in a document.

Examples
  • Attributes are either set by the entry alone: :beta:.

  • Attributes are set with additions: :beta-version: 23.

  • Attributes are toggled or disabled with an exclamation mark: :!beta: or :beta!:.

In adoc Studio, calling all built-in attributes works elegantly. Simply press the ESC key at the beginning of the line and select :Attribute: in the text completion menu. In the subsequent menu, you will find all built-in attributes.

text menu text menu attributes

You can find more information about built-in attributes on the AsciiDoc website.
User-Defined Attributes

A user-defined attribute is any attribute set by the author that is not reserved by the AsciiDoc language or an extension. User-defined attributes are mostly used for text replacement. These attributes allow the author to define named and reusable content. Instead of repeating text throughout the document, such as a product name, this text can be defined in an attribute and referenced by its name instead. This technique helps keep the document DRY, which stands for "Don’t Repeat Yourself."

An example that we regularly use in the documentation for mp 32 Merlin Project:

:mp-mpe-features: https://www.projectwizards.net/merlin-project/features
:not-in-mpe: CAUTION: This feature is not included in Merlin Project Express. +
             Please compare your requirements with the {mp-mpe-features}[feature comparison] table.

Then becomes:

This feature is not included in Merlin Project Express. Please compare your requirements with the feature comparison table.

This is a great work facilitation because the text does not need to be repeated with each copy and paste. Also, a change to this text only needs to be made once in the document!

You can find more information about document attributes on the AsciiDoc website.

6.15. Conditional Statements

A conditional statement is a control structure in programming. A program section is executed only under a specific condition. This applies similarly to our texts in adoc Studio. With the following conditional statements, you can include or exclude lines of text in your document:

  • ifdef: The content is included only if the specified attribute is set.

  • ifndef: The content is included only if the specified attribute is not set.

  • ifeval: The content is included only if the expression within the square brackets of the ifeval directive evaluates to true.

When the processor encounters one of these conditions, it evaluates the specified condition. The condition is based on the presence or value of one or more document attributes. If the condition is evaluated as true, the lines enclosed by the condition are included. Otherwise, the lines are skipped.

You can find more information about conditional statements on the AsciiDoc website.

6.16. Includes

One of the core features of AsciiDoc is dealing with split files. Instead of writing one endlessly long file, you split the text into many individual files and then assemble them according to certain rules.

In adoc Studio, we have already introduced our own concept for this in the The Project Navigator section.

For example, if you work with authors who cannot use adoc Studio, we recommend using the include command. With these commands, you can sequentially include the chapters that are also available in AsciiDoc format:

The file “chapter-1.adoc” couldn’t be opened because there is no such file.
The file “chapter-2.adoc” couldn’t be opened because there is no such file.
The file “chapter-3.adoc” couldn’t be opened because there is no such file.
Includes in adoc Studio

But include can also be useful within our app. Suppose you know that not everything can be documented all at once for your product. In that case, you need a placeholder.

In this project, we have defined such a placeholder in the file list: comingSoon.adoc. To prevent this file from being output in the combined document, the checkbox was deactivated in the file information (for more details, see here). Whenever a feature is not yet described, you can place the following text:

The file “comingSoon.adoc” couldn’t be opened because there is no such file.

This will be output as follows:

The important features are not yet described. We are working on making up for this as soon as possible.

The trick lies in the content of the file comingSoon.adoc:

  1. When this file is called via the include command, a text is assigned to the feature attribute - in this case, "important features".

  2. The file comingSoon.adoc is now included at the current position.

  3. The feature is checked first to see if there is any text in the attribute.

  4. If so, the warning is issued.

  5. Then the attribute is cleared.

You can find more information about Includes on the AsciiDoc website.

7. Outputting Documents

When exporting our documents, we have come up with something new that will particularly support you in extensive projects. We distinguish between the normal export of a document and the output of products. But first, let’s talk about an important intermediate step in the output: the preview.

7.1. The Preview

To the right of the Editor, you will find the preview. If it’s not displayed, click on the eye icon or use the keyboard shortcut ++P to show it.

The preview behaves differently depending on the set output format. Sometimes it’s like a browser displaying an HTML page, sometimes it’s like the PDF preview, and sometimes it’s displayed in RTF format. You can find the output format in the dialog behind the chevron.down icon next to the eye . You will also find additional switches there to make further settings, which may vary depending on the output format.

HTML Preview & Settings

previewOptions

When you set the output format to HTML, the document is output in the editor as a long HTML document. We jokingly refer to this as "a long piece."

  • The style, or more precisely, in which Product Style you want to view the document in the preview.

  • The appearance refers to the light or dark display (often also referred to as Dark mode and Bright mode). When set to automatic, adoc Studio uses the setting predetermined by your operating system’s system preferences.

  • The attributes, with which you control the document. The special thing here is that, in addition to the attributes assigned in the document, additional attributes can be assigned in a dialog. You can find more details in the description of products.

Text Preview & Settings

In addition to the settings for style, appearance, and attributes, you also decide here on:

  • The text format, which is formatted (as RTF) or output as plain text. In the latter case, styles are no longer applied, and images are not displayed.

PDF Preview & Settings

pdfPreviewOptions

In this preview, you see the document as it would be written to a file during export. The settings behind the chevron.down icon include not only style, appearance, and attributes but also:

  • Paper, where you can set the paper size, printer, and margins. Later, in the chapter on styles, we will go into more detail about the specifics and relationships.

  • Orientation, where you decide whether the document is displayed in portrait or landscape.

In the menu, you will now find some entries when PDF is the active output format, which are also known in Apple’s preview.app. This allows you to optimize the required space for the screen size you are using:

  • Single page

  • Double page

  • Single page scrolling

  • Double page scrolling

7.2. Features for Editor and Preview

Linking Preview with the Editor

By default, the preview always scrolls so that it is at the same height as the current line in the editor. This way, your eye only needs to move to the right to find the text in the preview.

This behavior can be disabled in the menu by selecting "Link with Editor > Reading Position." This is helpful when you want to copy texts from the preview of another document and paste them into the editor.

Linking Collapse State with the Editor

If the buttons to collapse sections are enabled in the settings, this linking can also be separated in the same way.

The collapse state affects the sections (i.e., headings 2 x == to 6 x ======, but not the document title). If you collapse a section in the editor, the corresponding section is also collapsed in the preview.

If the editor is hidden, the collapse triangles are also visible in the preview, allowing you to toggle text visibility in the preview.

Linking Content with the Editor

Using the menu, you can decide whether a file is automatically displayed in both the editor and the preview at the same time. Everything you select in the sidebar is displayed in both the editor and the preview simultaneously.

Click on a file in the sidebar while holding down the key, and the selected file will be displayed separately from the editor in the preview. This allows you to quickly view one file in the preview and edit another in the editor.

7.3. Exportieren

Whenever you want to export a file, go to the menu Ablage  Export  Auswahl – or use the shortcut ++E – that’s what you’re looking for. Additionally, you can find the share symbol in the right toolbar. Both ways open the export dialog.

export

If you are already satisfied with the preview, mark the checkbox Wie Vorschau (Like Preview) and press .

Otherwise, in this dialog, you have the same output options as explained in the Vorschau section:

  • Format: The target format of the file (Text, HTML, or PDF).

  • Stil: The styling of the document. Details can be found here.

  • Aussehen: Selection of light or dark mode, or automatic adoption from the system.

  • Attribute: Specification of existing or custom attributes. An introduction can be found here.

  • And the output-specific settings.

  • Aktion: Your decision on what to do with the output. By default, Exportieren (Export) is always preselected, which you can choose after clicking "Export." However, you can also share the export directly via email, Apple AirDrop, or another method.

When exporting in HTML format, you can additionally specify the output of the HTML file’s resources. Resources in an HTML file include media and style files. The following options are available:

  • Separieren: The resources are placed as separate files in a folder next to the HTML file.

  • Eingliedern: The resources are encoded and embedded within the HTML file.

  • Ohne: The resources are not exported.

  • Aus Attributen: In this mode, resources are not exported, but the :stylesheet: and :stylender: attributes are considered. If the attributes are not assigned, the resources will be exported.

If you need special attributes for a document, you have a dedicated attribute list available in the settings. Expand the list to reveal a small dialog where you can create new attributes or select existing ones.

All entries in this list will override the attributes entered in the text and therefore have the highest priority.

7.4. Products

We assume that the documents created in adoc Studio will have a long life and, as a result, will need to be maintained and outputted permanently. Therefore, whenever you work with complex export configurations or frequently switch between different export settings and special attributes, you need a tool that can capture, manage, and quickly retrieve all these different settings. This is where the "Produkte" (products) come into play.

products

You can access the product configuration dialog by going to the menu Ablage  Export  Produkte … or using the shortcut ++E.

When you access the products for the first time, the list on the left side will be empty. Clicking the + symbol will display a list of all your documents. Here, you can select the desired document or composite document.

Now, on the right side, various options are available:

  • Product Name: An optional name for your product.

  • Source: The source you have selected for the product. You can change it here as well.

  • Filename: The finished product will be generated with this filename. If this field is left empty, the product name or, if it’s not assigned, the source filename with the extension of the chosen format will be used.

  • Subfolder: An optional subdirectory in which the product will be exported.

Now you can assign the same export parameters as explained in the previous section, Export.

Products in the Toolbar

productsList

Once you’ve created your first product, the product name will appear in the toolbar to the left of the pencil . All additional products will be added to this list.

Create one product with the HTML output format and another with PDF. This way, you can easily switch between lightning-fast HTML and somewhat slower PDF generation in the toolbar.

Exporting Products

To output a product, select the desired destination in the product dialog and click either Export… or Share depending on your goal.

You can also export multiple products at once. To do this, select the context menu or the ellipsis.circle in the product dialog, and then choose the Export  Multiple Products option. This will display checkboxes next to all the products. Now, when you click Export… or Share, all the selected products will be exported.

In HTML exports, the individual products share resources. So, after exporting, you will have a .html file for each product, but only one resource folder containing images, CSS files, and so on.

8. There’s Still Something Missing…​

We are at the beginning of a long journey with adoc Studio. For the initial version that you have in front of you, we have selected features that we are confident 80% of users will definitely need. Of course, it’s highly likely that you are missing that one feature.

Whether it’s AsciiDoc or adoc Studio where you feel something is lacking, we have provided an online system where you can actively support us. Please sign up for free on this system and vote for missing features. The features with the most votes will be prioritized by us for earlier implementation. Of course, you can also express your own wishes or suggest features. Perhaps they are also needed by other users. In this way, we aim to ensure that the features you need most will be the next ones to appear in adoc Studio.

Join us in looking forward to what’s yet to come!

Appendix A: Support

You’ve made it! Up to this point, we’ve focused on describing the concepts and features. Now it’s your turn. Write and share your successes with us. We look forward to hearing from you!

A.1. System Requirements

The minimum system requirements for adoc Studio on your operating system are:

  • macOS 13 Ventura

  • iOS 16

A.2. First Aid

Forum

We’ve set up a free forum where the ProjectWizards team is also available to assist you.

adoc Studio Roadmap

We’re still at the very beginning of our journey and have many ideas ahead. To ensure that you not only see but also have an influence on the further development, we’ve created a public roadmap. If you’re missing a feature, please add it here or vote for an existing request that’s important to you.

The AsciiDoc Command Reference

You can find the always up-to-date AsciiDoc Command Reference here.

Hands-On Experience with AsciiDoc

The ProjectWizards website's blog has a series of practical articles on AsciiDoc.

More AsciiDoc Tips

Visit Awesome Asciidoc(tor) for an extensive collection of various tips and tricks on AsciiDoc.

A.3. Help with Templates & Styles

We are currently building a partner network that will be happy to assist you with setting up your templates and designing product styles. You can always find the current list of partners on our website.

Over time, we will also create a directory of all styles there. However, since we are just at the beginning of the product strategy for adoc Studio, this is all still evolving. If you’re interested in actively participating, please feel free to contact us at: office@projectwizards.net.

Appendix B: Glossary

Many terms in adoc Studio are derived from the AsciiDoc vocabulary and are therefore in English. However, since we release our app in languages other than English, we have decided to translate some terms. This results in a colorful mix of English and German terms. The following glossary should help you navigate through the language chaos smoothly.

In case of doubt, always refer to the (currently still) preliminary specification of AsciiDoc.

B.1. Inhalt

[ A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z ]


A

Abstract

An abstract is a brief overview or summary of a document. Sometimes it is used synonymously with a preamble.

Admonition

Admonitions are used to draw attention to specific statements by taking the block or paragraph out of the content flow. They are defined with one of five types (NOTE, TIP, IMPORTANT, CAUTION, WARNING) that determine their appearance. An admonition can be defined as a paragraph or a block.

adoc

The abbreviation for this app and the file extension for AsciiDoc text files.

adoc Studio

The name of this app.

Anchor

A jump target defined by the ID attribute.

Appendix

The appendix section style can be used in books and articles and can have additional subsections. Although the AsciiDoc structure allows for appendices to be placed anywhere, it is customary to include them at the end of a document.

Article

The standard doctype in adoc Studio. This includes optional sections such as Appendix, Abstract, Bibliography, Glossary, and Index.

ASCII

An acronym for American Standard Code for Information Interchange. This standard defines 128 characters, consisting of 33 non-printable and 95 printable characters, including spaces. In AsciiDoc, however, ASCII stands for "everything is text - even emojis." AsciiDoc uses the full Unicode character set.

AsciiDoc

A mature, lightweight, and semantic markup language mainly designed for structured document creation. You can convert AsciiDoc files to HTML or PDF using programs like adoc Studio or Asciidoctor. The AsciiDoc language was created by Stuart Rackham in 2002. A reimplementation is Asciidoctor, which has been developed by Dan Allen since 2013. Since 2020, the Eclipse Foundation, along with the AsciiDoc Working Group, has been working on standardizing AsciiDoc.

Asciidoctor

A command-line tool for parsing AsciiDoc files and converting them to output formats such as HTML, PDF, etc. Essentially, it is a similar program to adoc Studio, but without the project integration, editor, text completion, and preview features. Asciidoctor is open source and has been developed and maintained by Dan Allen since 2013.

Attribute

Used in AsciiDoc to configure documents and store variables. A document attribute is available from the point it is defined in the document. However, some attributes must appear at the beginning of a document. Attribute entries are also frequently used to toggle features. An attribute entry consists of two parts: an attribute name and an attribute value.

Attribute List (or attrlist)

The definition of attributes used for an element is called an attrlist. An attribute list is always enclosed in a pair of square brackets. This applies to both element attributes and attributes in a block or inline macro.

Author

The writer of a document. In AsciiDoc documents, the author can be specified below the title and is automatically stored in the :author: attribute. Additional attributes related to the author are also possible.

B

Bibliography

An independent listing of references or the act or process of creating such a listing. In adoc Studio, it can be used in books and articles.

Block

In an AsciiDoc document, blocks define the structure of the document. Some blocks can contain other blocks, making the document structure inherently hierarchical (i.e., a tree structure). You can view this block structure in the preview, for example, by enabling the automatic table of contents. Examples of blocks include paragraphs, sections, lists, delimited blocks, tables, and admonitions.

Block Name

Refers to custom blocks that can associate any name with one or more contexts. It serves a similar function to the style for a built-in block, such as an admonition block.

Block Style

Additional information that specializes the context of a block. For example, a source block can be additionally annotated with the language of the source code used.

Bold

In bold text, the weight of the text is increased by using a thicker and/or darker font compared to regular text. The formatting character for bold is an asterisk (*) before and after the word (keyboard: ++).

Boolean Attribute

A built-in attribute that functions as a toggle. It can only specify two states: true or falseon or off. The purpose is to activate a function or behavior.

Book

Builds on the doctype of article and additionally provides the option to use a top-level title as a sub-title. It includes the appendix, dedication, preface, bibliography, glossary, index, and colophon. A book can contain either only chapters or, additionally, various parts, which in turn can contain one or more chapters.

Bounded Blocks

A bounded block is a section of content enclosed by a pair of congruent line-level boundary markers on both sides. A bounded block is used either to encapsulate other blocks (e.g., multiple paragraphs) or to define the content model of the content (e.g., a literal block).

Built-in Attribute

Is a document attribute used for processing the AsciiDoc document. It can control integration, styling, localization, and more.

C

Chapter

Is a content-separating subdivision in texts. In adoc Studio we speak of chapters for the files in collective documents.

CLI

Is the abbreviation for command-line interface. It is often also referred to as the command line, console or terminal. It refers to an input area for controlling software. This typically takes place in text mode.

Composite Document

In adoc Studio, a composite document is a distinct document type and contrasts with standalone documents. It collects many chapters into a single large document. Within a composite document, many folders and media folders can be created for further structuring. All folders can be selected to combine the underlying chapters in the preview. Attributes defined anywhere in the composite document can be used in any chapter within the composite document.

Colophon (also subscription)

Is an element of a book and is usually at the end. It contains information about the content, author, place, time, producer, publisher and production details of the publication.

Content model

The content model of a block determines what type of content the block can have and how this content is processed (e.g., simple, compound, literal, raw, etc.).

Converter

Is a software component that an AsciiDoc processor calls to convert a AsciiDoc document to a specific output format.

CSS (Cascading Style Sheets)

Is a set of instructions or a template with settings for designing a document. A document or website with the same content can be displayed completely differently using different CSS. In adoc Studio, both HTML and PDF are designed with CSS. In addition, custom .css files can be transferred to a project and integrated using :stylesheet:.

Custom Attribute

A document attribute defined by the author used for storing reusable content and controlling conditional inclusion.

D

Dedication

Used to express gratitude to third parties. In AsciiDoc the dedication is a separate block type, which is preferably used in books.

DocBook

Is a document format defined in a Document Type Definition (DTD) for SGML and XML. It is suitable for creating books, articles, and documentation in technical fields (hardware or software). DocBook is an open standard maintained by the Organization for the Advancement of Structured Information Standards (OASIS).

Document (or standalone document)

A file in adoc Studio is referred to as a document. It is in plain text format. A document can consist of a single sentence (or even a single character, to be academic).

Document Attribute

Used to configure behavior in the processor or convey information about the document and its environment. An addition to document attributes is element attributes. There are built-in and custom attributes.

Docs as Code

Refers to the philosophy that documentation should be written using the same methods as software code. This means following the same workflows as development teams and integrating into the product team. It enables a culture where both authors and developers take responsibility for documentation and work together to make it as good as possible.

Document Header

An AsciiDoc document begins with a document header. The document header can contain the document title, author and revision information, document-wide attributes, and other document metadata. Furthermore, all document attributes must be defined in the document header.

Document Type (Doctype)

Specifies the expected structure of an AsciiDoc document. adoc Studio offers articles (as the default) and books.

E

Editor

Is a program or component for creating and modifying text. In adoc Studio, the editor is located in the middle window area. It provides special features such as intelligent text completion to assist while writing. The editor’s behavior can be customized in adoc Studio through a program setting.

Element

Is an identifiable part of the content in a document. An AsciiDoc document is always a composition of all elements contained within it.

Element Attribute

Define integrated and user-defined settings and metadata. They can be applied to an individual block element or inline element in a document (including macros).

Encoding

Most AsciiDoc processors, including adoc Studio, assume that the text in the file uses UTF-8 encoding. UTF-16 encodings are only supported if the file begins with a BOM.

Environment attribute

An environment attribute is a dynamic document attribute that refers to or provides information about the runtime environment.

Export

The output of an adoc file is in a format such as HTML or PDF. An export can have its own styles and attributes, which can be assigned either in the AsciiDoc document or in the export dialog. The output can be saved to a file and optionally shared directly with other programs.

F

Fixed line breaks

Since adjacent text lines in AsciiDoc are merged into a paragraph during conversion, you can place each sentence or phrase on its own line. Line breaks are not displayed in the output. To separate paragraphs from each other, simply use an additional empty line. This method is often used in the Docs as Code workflow. However, if you want to preserve line breaks within a paragraph, you can use a space followed by a plus sign (+) or set the "Hard Breaks" option for the paragraph.

Folder

Is a directory within a data structure. Any number of folders can be created in adoc Studio - even nested. A folder can be selected in collective documents to display the chapter contained therein in the preview combined.

Formatting mark and pairs

A formatting mark is a symbolic character such as *, _, or ~ that indicates the inline style the AsciiDoc converter should apply to the text. Formatting characters always come in pairs. A formatting pair consists of identical opening and closing characters that enclose the text to be formatted. The formatted text (i.e., the text enclosed by a formatting pair) can span multiple consecutive lines. The opening mark indicates where the formatting should begin, and the closing mark indicates where the formatting should end.

G

GIT

Git is free software for distributed version control of files, initiated by Linus Torvalds in 2005. All texts and media from adoc Studio can be versioned in a Git repository.

Glossary

A glossary is a list of words with accompanying explanations or translations. When included as an appendix in a work, it is also referred to as a word list, and as a standalone glossary, it is known as a dictionary. By the way, you are currently reading the glossary of adoc Studio.

H

Header Attribute

A header attribute is a document attribute defined in the document header of a document. It is visible to all nodes in the document and is often used for global attributes, e.g., for the icon mode: :icons: font.

HTML

Hypertext Markup Language (HTML) is a text-based markup language for structuring electronic documents, including text with hyperlinks, images, and other content. HTML documents form the foundation of the World Wide Web and are rendered by web browsers.

I

ID Attribute or Anchor

With an anchor, you can assign a unique name (i.e., identifier) to a block or inline element. It is used to identify the element for linking purposes or styling.

Index

You can explicitly mark index terms in AsciiDoc content. Index terms form a controlled vocabulary that allows you to navigate the document based on an index.

Inline

The inline doctype allows the AsciiDoc processor to cover the entire range of applications, from unstructured (inline) text to complete standalone documents.

Inline Element

An inline element is a phrase (i.e., a span of content) within a block element or one of its attributes in an AsciiDoc document. They are used for text formatting and performing various types of text substitutions. Inline elements and the syntax for inline elements are defined in configuration files. Conversion of inline documents is not yet implemented in adoc Studio.

Italic

Text is often italicized to emphasize a word or phrase, quote a speaker, or introduce a concept. Italic type is slanted slightly to the right and, depending on the font, may have italic swashes and flourishes. The formatting character for italic is an underscore (+-).

Integrated Writing Environment (IWE for short)

Is software that provides comprehensive writing and knowledge management functions for authors and information workers. So does adoc Studio. IWEs allow authors and information workers to perform a variety of tasks related to the document in the IWE in a single environment. In the best case, principles such as Docs as Code are also supported. This ensures a distraction-free workspace and an optimized writing environment.

J

K

Keywords

The :keywords: attribute contains a list of comma-separated values that are assigned to the HTML <meta> element.

L

Line

AsciiDoc is a line-oriented language, so the line is an important construct. A line is defined as text that is separated on both sides either by a line break or by the boundary of the document. Many aspects of the syntax must take up an entire line. When working according to Docs as Code, the single line is particularly important as it is easier to recognize changes in a Git.

M

Macro

Is a syntax for representing non-text elements or a syntax that transforms into text using the provided metadata. See Macro to learn more about the significance of this term.

Macro Attribute

Is an attribute associated with a block or inline macro. These attributes can influence the processing of the macro but cannot be referenced via an attribute reference.

Manual page

A man page, short for "manual page," is a text-oriented form of software documentation commonly accompanying software on UNIX and Unix-like operating systems. Its formalized structure allows the man command to display a formatted document in a terminal. Writing a man page in AsciiDoc has the advantage of being convertible into various formats, including HTML and PDF, making the source of the man page reusable. Conversion to "man pages" is not yet implemented in adoc Studio.

Markdown

A simplified markup language released in December 2004 by John Gruber and Aaron Swartz.

Markup Language

A markup language is a machine-readable language for structuring and formatting text and other data. The most well-known example is Hypertext Markup Language (HTML), the core language of the World Wide Web.

Marking

Another way to draw attention to text is to highlight it with a marker. This semantic style is used for referencing or notational purposes or to emphasize the significance of an important topic or point. The formatting character for Marking is a hash # (#).

Media Folder

In adoc Studio, the media folder has some special functions. When selected, all contained media items are displayed as previews. You can create as many media folders as needed.

Metadata

Are structured data containing overarching information about a resource, such as books, web documents, videos, or images. Regarding a document, it can include a description of the document, keywords, and custom information that can be assigned as attributes in the document header. When converted to HTML, the values of these attributes correspond to the elements found in the <head> section of an HTML document.

Monospace

In technical content, text often needs to be styled to indicate a command or source code. Such text is typically highlighted using a fixed-width font (i.e., Monospace). The formatting character for Monospace is a backtick ` (+´).

N

O

Outline

An outline is the division of a whole into several structural parts or sections that are largely self-contained but cannot be removed from the whole without making it incomplete. adoc Studio contains multiple outlines: the file navigator and section navigator in the sidebar, the heading structure above the editor, and more.

P

Paragraph

In most documents, the paragraph is the most important block type. Therefore, you don’t need to use special markings or attributes to create paragraphs. You can simply start typing sentences. Whether you use a separate line for each sentence or write them one after the other, the content will always form a paragraph. A blank line separates paragraphs.

Parser

A parser is a computer program in computer science responsible for parsing and converting input into a more suitable format for further processing. For the technically inclined: The parser in adoc Studio is written in Swift, inspired by AsciiDoc. It is a migration, not a direct copy or port.

Part

In the context of a multipart book, a part is an additional subdivision. A part can contain its own chapters or appendices.

PDF (Portable Document Format)

Is a platform-independent file format developed and published by Adobe Inc. in 1992. Electronic documents in this file format can be faithfully reproduced independent of the original application, operating system, or hardware platform.

Plaintext

In IT, plaintext refers to data that is human-readable without any formatting and can be directly converted into text using characters. The AsciiDoc documents in adoc Studio use plaintext.

Preamble

Is the content between the end of the document header and the first section title in the document body. A preamble is optional in AsciiDoc.

Predefined attribute

A predefined attribute is a document attribute that has been defined for reasons of convenience. It is often used to insert special characters for the content.

Preview

In the preview, adoc Studio displays all content from the editor in various formats. HTML, PDF and RTF text are available. Each output format can be formatted with a style.

Preface

A preface is a special section that precedes the first chapter of a book or part of a book. In AsciiDoc, the preface is a separate block type, which is preferably used in books.

Preprocessor Directive

Is a function that controls the lines input into the parser. A conditional preprocessor directive can configure lines to be included or excluded based on the presence of an attribute (ifdef, ifndef) or any other condition (ifeval). An include directive can add additional lines from another document to the document.

Preprocessor Directive

see Präprozessoranweisung

Products

Are a logical grouping of many exports. Within a product, many exports can be created, each of which can have its own styles and attributes and output formats.

Product Styles

In adoc Studio, text is separated from styling. Therefore, a technique is needed to combine both. This task is accomplished using product styles. A product style is a file bundle that includes at least an information file and the style file in CSS format. Optionally, additional resources such as media or fonts can be included.

Project

In adoc Studio, a project is a summary of all AsciiDoc files and folders, including media folders. Additionally, projects can also contain other files such as CSS files and others. It is organized and managed in adoc Studio through the project navigator. Additionally, continuous synchronization with the operating system’s directory takes place, allowing the project to be modified in the Finder.

Q

Quote, quoted text

Text surrounded by special punctuation to quote other authors, or to give the text a special meaning.

R

Role

blocks and most other inline elements can be assigned one or more roles with the attribute role. A role adds additional semantics to an element, for example to assign an additional style (via a CSS selector).

RTF (Rich Text Format)

Is a proprietary file format for texts that was introduced by Microsoft in 1987. It can be used as an exchange format between word processing programs from different manufacturers on different operating systems. In adoc Studio, the preview can be set to text, which corresponds to the Rich Text Format. This format can also be selected for the export and within the products.

S

Section

Divides an AsciiDoc document into a hierarchy of content. A section is defined by a section title prefixed with one or more equals signs. The section encompasses all content that follows the section title until the next sibling or parent section title or until the end of the document.

Section Title

Marks the beginning of a section and simultaneously serves as a heading for that section. The section level is determined by the prefixed section marker (equals signs). In adoc Studio, the equals signs can be displayed in the left margin of the editor.

Source code

Is a human-readable text of a computer program written in a programming language. In the Docs as Code working principle, the AsciiDoc text is also often referred to as source code.

Stylesheet

Most closely resembles a template. The fundamental idea is to separate text from presentation. The program that evaluates the stylesheet interprets the assigned data (text, tables, graphics, etc.) and formats them according to predefined rules. Cascading Stylesheets are perhaps the most well-known example of a stylesheet. In adoc Studio, custom stylesheets can be placed in the project as .css files and used with the attribute :stylesheet:.

Subscript (English)

Subscript text is often used in mathematical expressions and chemical formulas. The formatting character for subscript is a tilde ~ (+n).

Superscript

Superscript text is often used in mathematical expressions and chemical formulas. The formatting character for superscript is a caret (^).

Syntax

In general, it refers to a rule system for combining different characters into natural or artificial systems. The rules of syntax contrast with the interpretation rules of semantics. The command set of a language, such as AsciiDoc, is often referred to as its syntax.

T

Text

Enclosed by markers, delimiters, and metadata lines, text is the core of a document and the reason why AsciiDoc syntax gives it so much breathing room. Text is most commonly found within the lines of a block (e.g., a paragraph), in the block title (e.g., section title), and in list items, among other places. Text is subject to substitutions. Substitutions interpret markup as text formatting, replace macros with text or non-text elements, expand attribute references, and perform other types of text replacements. By default, normal text is subject to all substitutions unless otherwise specified. Literal text is subject to a minimal set of substitutions to ensure it is displayed in the output as it appears in the source. It is also possible to disable all substitutions to pass the text through unchanged (i.e., as unprocessed) to the output. Parsing the text involves a mixture of inline elements and other forms of transformations.

Text Completion (intelligent or automatic)

A technique that, after entering two to three letters in the editor, recognizes that contextually relevant attributes, macros, or other possibilities are available at the current typing position. The key is that it doesn’t block the writer’s flow but rather provides support. It is often used to save time.

Text Formatting

AsciiDoc provides a set of formatting characters that allow you to visually emphasize your document and use typographic punctuation. You can build on these basic formatting characters using built-in and custom roles. Examples include: bold, italic, highlighting, etc.

U

UTF-8

see Encoding

V

Version management

Version management is used to manage multiple versions of a document in a space-saving manner. With most version management systems, only the changes that are necessary to create a specific version are saved alongside the original document. In addition, version management makes it possible to work together on the same document.

W

X

Y

Z


1. Here is the text of the footnote