adoc Studio | Working with adoc Studio

2.1. The User Interface

Upon starting adoc Studio, you will see a view like the one shown in the following image. It displays the user manual created with adoc Studio, which can be accessed through the Help menu.

The window layout of adoc Studio is divided into three sections:

Sidebar with:
1. the Project Navigator for all files & directories (keyboard shortcut: ⌘+1)
2. the Section Navigator for the table of contents (⌘+2)
3. the Search Navigator for searching across all files (⌘+3)
4. the Problem Navigator for all warnings & error messages (⌘+4)
The text editor
The preview

At the top of the window is the toolbar with the following functions:

Show/hide the sidebar (keyboard shortcut ⌘+0)
Create a new component (⇧+⌘+N)
Back and forward navigation buttons (⌃+⌘+< and ⌃+⌘+>)
Directory tree as a popup list
Content structure as a popup list
Optionally: List of all products
Show/hide editor (with or keyboard ⇧+⌘+E)
Show/hide preview - (with or keyboard ⇧+⌘+E), including settings

Each section can be individually shown or hidden to optimally adjust to any screen size. The corresponding functions can be found in the menus View, Editor, and Preview.

2.2. The Project Navigator

In adoc Studio, you work in a project-oriented manner. A project includes your text and, if necessary, the associated images. However, as the text length increases, it becomes increasingly difficult to keep track. Therefore, long texts are often divided into smaller sections, which are stored in many individual files along with the images. This often leads to disorder and loss of overview.

To avoid this problem, adoc Studio offer the composite document.

This chapter explains how to handle projects, files, and all associated elements.

Creating a New Project

Create a new project in adoc Studio through the menu File New Project. In the sidebar, you initially see two objects:

A folder for media
A file for the document

Whether the file extension .adoc is displayed as shown in the image can be set in the settings menu of adoc Studio (keyboard shortcut: ⌘+,).

All objects (files and folders) in the sidebar can be moved. They can be nested within each other, restructured, and rearranged.

Media and images can be placed anywhere in the project. However, it is recommended to collect them in the media folders. If the automatically created media folder is not enough, you can create as many additional folders as you need in your project.

Using Standalone Documents

In the next step, expand your project and add a standalone document. Use the menu File New, the keyboard shortcut ⌘+N, or the + in the sidebar. The documents are independent of each other and exist on their own. The process is simple and logical:

Click on a document.
It is displayed in the editor for editing.
The preview shows the current status.

When you click on another document, it will be displayed in the editor.

This means that the contents of the second document Another Document.adoc will not be visible in Document.adoc and vice versa. There are techniques in AsciiDoc to display content from other documents in a document, such as the include macro.

Using Composite Documents

Composite documents offer a structured merging of multiple documents, in contrast to standalone documents. When you compile your documents into a large document, newly created files in the composite document are named as Chapter.adoc instead of Document.adoc.

In a composite document, you can use folders for structuring and nest them as deeply as you like. When you click on a folder, the preview shows all the chapters contained in it as a continuous document. The higher you go in the hierarchy, the more comprehensive the preview display will be.

When the focus in the sidebar is on a folder, the editor remains empty. To edit a chapter, select it specifically. The preview then immediately switches to the display of the text in the editor.

Using Folders for Structuring

With the step-by-step creation of new standalone files, the sidebar might eventually become cluttered. Although using the filter at the bottom of the sidebar can help you quickly find files. It resets after restarting adoc Studio.

For this reason, another solution for structuring presents itself. Similar to the operating system, you also have the option to create folders in adoc Studio. These can be named according to the rules of the operating system and offer space for numerous documents. Additionally, these folders can be created within other folders to allow even finer structuring.

The concept of individual documents remains intact. Even if you have created many folders and stored numerous files within them, they remain independent of each other. However, if you are writing a book with many chapters, you will need the composite document.

Using Media Folders

The media folder serves a special function. You can store all media, such as images, videos, etc., there by default. adoc Studio searches the project for these media in a specified order.

Search Order for Images

The line images::image.jpg[] prompts adoc Studio to search for the image in the following order:

adoc Studio first searches for the file "image.jpg" at the same level as the .adoc file.
If not found there, the app searches in the parent media folder.
If the image is not found there either, the app searches again in the next higher level media folder.
This continues until the root directory of the project is reached.
If the image is still not found, the editor marks the file name in red, and an entry is added to the problem navigator in the sidebar.

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 general, all paths can be specified as in the operating system. The root is always the project directory where your .adocproject file is located.

For AsciiDoc Pros:

In adoc Studio, there is also the concept of imagesdir. If you use this attribute in existing (referencing) projects, it should always precede the images and possible path specifications. Note, however, that it is not set automatically and must be adjusted manually.

Instead of:

image::Folder/image.jpg[]

use:

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

For more details and specific use cases, visit the AsciiDoc website.

You can have many media folders. Here are some examples:

A media folder with general images.
A media folder with images of a specific topic.
A media folder with images of a specific platform.

In this project, for example, the images for the iPad are stored in a subdirectory of the media folder. They are called by the attribute {ads-device} in the products. The values :ads-device: iPad or :ads-device: Mac serve as defaults. Platform-specific images are then included as follows:

image::{ads-device}/new-component.jpeg

This way guides for Mac, iPad, and other platforms are created.

For referencing projects, there are some additional peculiarities. More details can be found there.

Adding a New Component

To add a new component to your project, use the button in the toolbar or the keyboard shortcut ⇧+⌘+N. The dialog adapts according to the selection in the file list as follows:

If you have selected a standalone document, you can either create a new standalone document or a composite document.
However, if you have selected a composite document or a chapter from it, you have the option to add new chapters.

In any case, you have the option to add new folders, media folders, or existing files.

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

Adding Existing Files

In adoc Studio, you cannot only create composite documents with their chapters but also standalone documents.

A standalone document does not inherit attributes from other documents in the file list. All values must be explicitly set in these documents. Also, media folders located in composite documents are not found by a standalone document; only those outside of composite documents are detectable.

It is up to you how you want to integrate these files into your project. Below are some options:

Double-click in Finder

In Finder, you can open any .adoc file in adoc Studio by double-clicking, provided no other application has taken over the .adoc extension after installation. A dialog appears, allowing you to select the target project for the file or create a new project. The file is then copied into the selected project without being moved.

Drag & Drop from Finder

Another method to copy files into a project is by drag and drop. You can simply drag the desired file from Finder and drop it at the desired position in adoc Studio. If the target is a composite document, the file is automatically added as a part of that composite document.

Copy or Move Files in Finder

You can also directly copy or move files into the project directory in Finder. adoc Studio automatically recognizes them, and they appear in the file list of your project within a short time. There is no need to restart the app.

Menu Function

Finally, a menu function is available to add files to your projects. You can open the file selection either through the menu File New Add Files … or the keyboard shortcut ⌥+⌘+A. The selected file(s) are then added below the current selection in the file list. You can then move them to another location with the mouse.

When you drag a file into a composite document, it automatically becomes a chapter of the corresponding composite document.

File Information

In case a file is part of a composite document but should not be output, adoc Studio offers a solution:

By right-clicking on the file in the file directory of the left sidebar, you open the context menu. There, you will find the entry Information …, which opens the dialog shown on the right.

Disable the "Part of the composite document" option to remove the file from the inclusion. If the file should still be used, you must include it via the include command.

More Information

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

For a file:
- Part of a composite document
For a folder:
- Folder
- Composite document
- Media directory

These settings apply exclusively to working in adoc Studio. In macOS Finder (and in all other operating systems), all objects appear merely as folders and files.

2.3. Saving a Project

The old way

In the past, a new project was saved in the first step. You set the storage location where the project would be created. This is done via File Save … or the keyboard shortcut ⌘+S.

You are free to save the files of adoc Studio on your local computer, a server, or in a cloud storage. Using a version control system such as Git or GitHub is also possible.

The new way

An initial save is no longer required to avoid data loss. When you close the last project window, adoc Studio asks if the project should be saved. You then decide whether and where the project will be saved.

In adoc Studio, the app automatically saves the .adoc files at short intervals for you. If desired, you can still use the keyboard shortcut ⌘+S, but automatic saving is faster.

2.4. Opening Additional Windows for a Project

A project can be opened in multiple windows using the menu Window New Window. This is especially helpful in a dual-monitor setup when you want to display the preview in a separate window.

On your Mac, click on the window title while holding the ⌘ key to open a menu with the path of the current project in Finder.

2.5. Referencing Projects

These projects differ from standard projects, in which everything is managed in a separate folder. However, there are cases in which this is not desirable or even possible. For example:

Projects that are created using different writing environments
Projects in which data is distributed

You can create an external project via the menu with the ⌥ key pressed: File New Referencing Project.

Pressing the ⌥ key when calling up a menu is not a special feature of adoc Studio, but a standard feature of macOS. Just take a look at the changes when you press the ⌥ key in the open File or Window menu.

An empty window will open.
Save this project as an .adocproject file in any location.
Now drag files or folders from any location into the project navigator.
This creates a reference to the project in adoc Studio.
You can edit all .adoc documents as usual, but they will be updated in the source folder.

2.6. The Section Navigator

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

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

For individual documents, only the respective table of contents is displayed.

To output a table of contents in the text, use the attribute :toc:, which is described here.

2.7. The Search Navigator

The tab with the magnifying glass is the Search Navigator. Use it to find text throughout the entire project.

In the context menu behind the magnifying glass, you can enable the replace function. Additionally, you can make the following settings here:

Ignore Case,
Ignore Diacritics

In this menu, you also activate the regular expressions for the search.

After the search, the results are grouped by the files in the project. Clicking on a file opens it in the editor and jumps to the desired position.

Special Features

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

Select individual results in the list (multiple selection with the ⇧ key is possible) to perform replacements only for the selected spots.
Select a file in the results list to perform replacements only in that file.

2.8. The Problem Navigator

The concept for AsciiDoc and adoc Studio is to output text regardless of how many AsciiDoc errors are present in the text. The Problem Navigator is not about grammatical or spelling errors.

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

Since not every error is of equal severity, minor issues are displayed as warnings in yellow.

The list itself is sorted by occurrence. Clicking on a message brings the editor to the corresponding position so that you can fix the error.

2.9. Writing and Navigating within the Text

Select a text file from the file list. If the cursor is not already blinking in the editor window, place it in the middle area of the window with a mouse click or by pressing ⌃+TAB, and you can start writing. For information on AsciiDoc, see the next chapter.

The entered text appears in the preview. For longer texts, the position of both windows is synchronized, so you always see the text written on the left at the same height in the preview. The cursor position is synchronized with the position in the preview.

Note that switching to the PDF format preview can be time-consuming for longer texts. Therefore, we recommend staying with the HTML preview as it can be updated faster.

The editor can be customized according to your personal preferences (color perception, diopter strength, etc.). The Editor Styles tab in the Application Settings offers you almost endless design possibilities.

Additional Navigation

The additional navigation bar is located above the editor.

It starts with the navigation arrows to the left and right . The function is similar to navigation in your browser: it allows you to navigate forward and backward.

Next is a graphical block that shows you the current file and its structure.

Reading from left to right, you see where the file you are writing in is located. At the far right, you will find a small table of contents showing the structure, which also shows the overall context. You can also jump to any file with any element.

Line Numbers

A single line number appears at the right edge of the editor for orientation. In most cases, this is sufficient. If you prefer to display all line numbers, change this in the settings.

Clicking on a line number or pressing ⌘+L allows you to jump to a specific line.

Texts are also saved immediately

Changes in the texts are saved just as quickly as the project files. So you don’t have to worry about data loss!

Cursor

While writing, you don’t want to constantly take your hand off the keyboard to position the cursor with the mouse. Therefore, the well-known shortcuts for text editing from macOS and iPadOS have been adopted and integrated into 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. Moving in 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
`⌘`+`→`	Move to the end of the line
`⌘`+`↑`	Move to the beginning of the document
`⌘`+`↓`	Move to the end of the document

Table 3. Selecting in the Document
`⇧`+`←`	Extend selection to the left
`⇧`+`→`	Extend selection to the right
`⇧`+`↑`	Extend selection upwards
`⇧`+`↓`	Extend selection downwards
`⇧`+`⌥`+`←`	Extend selection to the word on the left
`⇧`+`⌥`+`→`	Extend selection to the word on the right
`⇧`+`⌘`+`↑`	Extend selection to the beginning of the document
`⇧`+`⌘`+`↓`	Extend selection to the end of the document

Table 4. Deleting in the Document
`⌘`+`⌫`	Delete the current line to the left of the cursor
`⌥`+`⌫`	Delete the word to the left of the cursor
`⌥`+`⌦`	Delete the word to the right of the cursor

Table 5. Alternative Tastenkürzel im Dokument
`⌃`+`a`	Move to the beginning of the line
`⌃`+`b`	Move one character to the left
`⌃`+`d`	Delete the character to the right
`⌃`+`e`	Move to the end of the line
`⌃`+`f`	Move one character to the right
`⌃`+`h`	Delete the character to the left
`⌃`+`k`	Delete the current line to the right of the cursor
`⌃`+`n`	Move down one line
`⌃`+`o`	Insert a new line after the insertion point
`⌃`+`t`	Swap the characters at the cursor or within a selection

Another keyboard shortcut you might regularly use in adoc Studio is the ESC key. This enters you into the large area of input aids.

2.10. Input Support: The adoc Coach

AsciiDoc has a very extensive range of functions. Even professionals may sometimes forget a command, miss a macro, or not remember a particular syntax. For this reason, adoc Studio has an intelligent input support integrated.

While you are writing, the app continuously searches for ways to assist you. Often, after the second or third character, it recognizes various options and offers these in a completion menu. The goal of adoc Studio is to interrupt your writing flow as little as possible. Therefore, you only receive completion suggestions when you pause your writing.

If needed, you can call up the input aid menu anytime by pressing the ESC key.

Embedding an Image in the Text

Start by typing ima at the beginning of a line.
A short menu appears:
Navigate the list with the keys ↓ or ↑.
Select the desired entry with the ⏎ key.
After selection, another menu appears:

The images are conveniently displayed as small previews.
After selecting the appropriate image with the ⏎ key, the image appears at full width in the preview.
Place the cursor between the square brackets after the image name ([]) to enter the appropriate options for the image.
First, enter the width of the image by typing wi. Now the menu with all available options for images containing wi appears.
Navigate with the arrow keys to width= and press the ⏎ key.
Now you see the following:
Overwrite the placeholder text with a number (e.g., 200) to see the scaling of the image immediately in the preview.
Place the cursor again between the square brackets after the image name ([]) It doesn’t matter whether before or after the width option. It is important that all options are separated by a comma.
Press the ESC key to bring up the completion menu with the other options for the image.
Suppose you want to place the image to the right of a text. You need the float option. Start typing flo, and the completion menu shows all options containing flo:
Select float=right.

Congratulations! You have inserted an image that is scaled and positioned to the right of the text.

In the source text on the left side, it looks like this:

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.

The result on the right side in the preview looks like this:

As shown in the example, the completion menu is available for every AsciiDoc command and all attributes. In case of doubt, a simple press of the ESC key helps to see all macros possible at the current position.

2.11. Spell check

Spell check is enabled by default in many applications on macOS and can be used manually or automatically. This also applies to adoc Studio. Misspelled words are underlined in red. To check spelling, select Edit Spelling and Grammar Check Document Now in an app or press the key combination ⌘+Ü. This will jump to the next error. Right-click on the word to display suggested corrections.

Alternatively, you can add a word you think is misspelled to the system-wide dictionary. This makes it available to all apps on your Mac.

However, since some documentation covers technical topics that are not included in the system-wide dictionary, adoc Studio offers its own dictionaries. These are saved in the project as .adict files. These are alphabetically sorted text files that can also be changed manually.

Any number of dictionaries can be created in the project. They are operated exclusively via the context menu – i.e. by right-clicking with the mouse in the text.

2. adoc Studio

2.1. The User Interface

2.2. The Project Navigator

Creating a New Project

Using Standalone Documents

Using Composite Documents

Using Folders for Structuring

Using Media Folders

Adding a New Component

Adding Existing Files

File Information

2.3. Saving a Project

2.4. Opening Additional Windows for a Project

2.5. Referencing Projects

2.6. The Section Navigator

2.7. The Search Navigator

Special Features

2.8. The Problem Navigator

2.9. Writing and Navigating within the Text

Additional Navigation

Line Numbers

Cursor

2.10. Input Support: The adoc Coach

Embedding an Image in the Text

2.11. Spell check