7. Exporting

When exporting documents, adoc Studio offers a new method that is particularly useful for large projects. You can choose between the regular export of a document and the output of products. But first, let’s look at the preview.

7.1. The Preview

To the right of the editor, you will find the preview. If it is not displayed, click on the icon or use the keyboard shortcut ⇧+⌘+P to show it.

The preview adapts to the set output format. Sometimes it appears like a browser displaying an HTML page, sometimes like a PDF preview, or an RTF display. You select the output format in the dialog behind the icon next to the eye icon . There you can also make further settings that vary depending on the output format.

HTML Preview and Settings

previewoptions

When you set the output format to HTML, the document in the editor is displayed as a long HTML document.

  • Style: Choose the desired product style for your document’s preview.

  • Appearance: Decide whether the display should be light or dark. This is often referred to as Darkmode and Brightmode. In automatic mode, adoc Studio follows your operating system’s control panel settings.

  • Attributes: Manage the document attributes. In addition to the attributes defined in the document, you can set additional attributes through a dialog. More details can be found in the description of the products.

Text Preview and Settings

In addition to the options for style, appearance, and attributes, you can also choose:

  • Text format: Choose whether the text should be formatted (as RTF) or plain text. When output as plain text, styles are not applied and images are not displayed.

PDF Preview and Settings

pdfpreviewoptions

The PDF preview shows the document as it will be written to a file upon export. The settings in the dropdown menu behind the icon include not only the style, appearance, and attributes but also:

  • Paper: You can set the printer, paper size, and margins. More details about these settings can be found in the chapter on styles.

  • Orientation: Set whether the document should be displayed in portrait mode or landscape mode.

In the menu Preview, you will find entries to optimize the display for your screen size when the PDF format is active.

  • Single page

  • Double page

  • Single page scrolling

  • Double page scrolling

The PDF shown in the preview is not PDF/UA-compliant! This can be integrated when you export the PDF.

7.2. Features for Editor and Preview

Linking Preview with the Editor

By default, the preview scrolls to the same line as the editor, so the corresponding text in the preview is always at the same height as the current line in the editor.

However, if you want to copy text from another preview and paste it into the editor, you can disable this function in the menu Preview  Link with Editor  Reading Position.

Linking Fold State with Editor

If the option Buttons to Collapse Sections is activated in the settings, you can disable this linkage separately here.

The fold state affects the sections, i.e., the headings from 2x == to 6x ======, but not the document title.

When you collapse a section in the editor, it is also collapsed in the preview. Even if the editor is hidden, the collapse triangles are shown in the preview, allowing you to continue to expand or collapse the text.

Linking Content with Editor

Through the menu Preview  Link with Editor  Content, you can set whether a file is automatically displayed in both the editor and the preview. When this option is activated, everything you select in the sidebar is shown in both the editor and the preview.

If you hold the ⌥ key and click on a file in the sidebar, the selected file is unlinked from the editor and displayed only in the preview. This way, you can quickly view a file in the preview while editing another in the editor.

7.3. Exporting

To export a file, you can either use the menu File  Export  Selection or the keyboard shortcut ⌥+⌘+E. Alternatively, you can use the icon in the toolbar on the right.

export

If you are satisfied with the display in the preview, simply check the Like Preview box and press ⏎.

Otherwise, the dialog offers the same output options as explained in the Preview section:

  • Format: Choose the desired target format for the file (Text, HTML, or PDF).

  • Style: Define the appearance of the file. More details can be found here.

  • Appearance: Decide whether the document should be displayed in light or dark mode, or let the system decide.

  • Attributes: Set predefined or custom attributes for the output. An introduction can be found here.

  • Specific output settings: Adjust additional settings according to the output format.

  • Action: Choose what should be done with the exported file. The default is "Export," which you can execute by clicking "Export." Alternatively, you can send the file directly by email, share it via Apple AirDrop, or share it with others in different ways.

When exporting in HTML format, you can also set the output of the HTML file’s resources. HTML file resources include media and style files. Here are some possible options:

  • Separate: Resources are saved as separate files in a folder next to the HTML file.

  • Inline: Resources are embedded in the HTML file.

  • None: Resources are not exported.

  • From Attributes: Resources are not exported, but the attributes :stylesheet: and :stylesdir: are respected. If these attributes are not set, the resources will be exported.

In the settings, you will find a list where you can set specific attributes for a document. Open the list to see a small dialog where you can create new attributes or select existing ones.

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

Exporting images

Images are an important topic for the documentation. The challenge here is often the size. The product team usually sends images in the maximum resolution. And that’s a good thing. But the reader of a documentation, e.g. on the iPhone, cannot use images with hundreds of megabytes.

That’s why adoc Studio has various attributes for handling images in the export.

ads-max-image-resolution

Specify the maximum resolution for images in HTML and PDF exports. Specify the resolution values in dpi, dpcm or dppx. For HTML, this setting only affects images for which you have explicitly specified a width or height in the source text. To limit the size of images without a specified width or height in HTML, set the attribute ads-max-image-width.

Example:

  • :ads-max-image-resolution: 72dpi
    Limits images in the output to 72dpi

ads-max-image-width

Set the maximum pixel width for HTML export for those images for which you have not specified a width or height in the source text.

Example:

  • :ads-max-image-width: 200px
    Limits the width of images to 200 pixels.

ads-rasterizing-resolution

If you set a value, PDF and SVG images as well as STEM equations in HTML exports are converted to PNG images. You can specify resolution values in dpi, dpcm or dppx.

Example:

  • :ads-rasterizing-resolution: 72dpi
    Limits images in the output to 72dpi.

PDF/UA-Conformity

PDF/UA stands for "Universal Accessibility" and is an international ISO standard (ISO 14289) for accessible PDF documents. The aim is to make documents accessible to everyone, including people with disabilities. PDF/UA is not a separate file format, but rather a method of structuring the existing PDF format in such a way that it is accessible. More at Wikipedia.

ads-pdf-ua

When set, PDF exports add accessibility information according to the PDF/UA standard. This attribute is deactivated by default.

If you wish to disable PDF/UA compliance for a document, activate the attribute:

  • :ads-pdf-ua:

That is all that folks.

7.4. Products

For documents created with adoc Studio, long-term maintenance and output are common. Therefore, a tool is needed that efficiently manages complex export configurations as well as frequent switches between different settings and special attributes, making them quickly accessible. This task is handled by products.

products

You can open the dialog box for configuring products via the menu File  Export  Products … or with the keyboard shortcut ⌘+⌃+E.

If you access the products for the first time, the list on the left side will still be empty. By clicking on the + symbol, you can access a list of all documents. Select the desired document or master document here.

On the right side, you will now find various options:

  • Product Name: Here you can optionally specify a name for your product.

  • Source: Here you select the source for your product. You can change this selection at any time.

  • Languages: Decide which language the output should be in.

  • Filename: Enter the name for the exported file here. If this field remains empty, either the product name or, if not available, the file name of the source with the corresponding file extension will be used.

  • Subfolder: You can optionally specify a subdirectory where the product should be exported.

You can now set the same export parameters as in the previous section, Exporting.

Products in the Toolbar

productslist

Once you have created a first product, the product name appears in the toolbar to the left of the . All further products will be added to this list.

Set up a product for output in HTML format and another for PDF format. This way, you can easily switch between the quick HTML preview and the somewhat slower PDF preview in the toolbar.

Exporting Products

To export a product, select the desired target in the products dialog and then click either Export … or Share, depending on what you want to do.

Alternatively, you can also export multiple products at the same time. To do this, go to the context menu in the products dialog or click on and select the Export  Multiple Products entry. This will display checkboxes next to each product. Check the products you want to export and then click Export … or Share.

If you perform multiple HTML exports, the products share the resources. This means that after the export, you will have a separate .html file for each product, but only one folder with shared images, CSS files, etc.

7.5. Websites

Pro

Description forthcoming.

7.6. Command Line Tool

In many cases, documentation is generated automatically. For adoc Studio we have added in the Pro version a command line tool that can be accessed directly in the Terminal and also via Apple Shortcuts.

Installation

cmdline install

On the Mac, start the installer via the menu entry adoc Studio  Install Command Line Tool…. This is necessary because apps from the App Store are not allowed to access the system level directly.

If the tool is already installed, the menu entry will instead be: adoc Studio  Update Command Line Tool….

After launching, follow the on-screen instructions and enter your user password when prompted. This allows the installer to place the adocstudio tool on your Mac in the /usr/local/bin/ directory.

After installation, you can start directly in the Terminal.

Invocation and Options

If you type only adocstudio in the Terminal, you will see the following output:

OVERVIEW: Export content from an adoc Studio project in HTML, PDF or text format.

USAGE: adocstudio export <subcommand>

OPTIONS:
  -h, --help              Show help information.

SUBCOMMANDS:
  products                Export products from an adoc Studio project using their 
                          pre-defined configuration.
  documents               Export documents from an adoc Studio project with custom 
                          configuration

  See 'adocstudio help export <subcommand>' for detailed help.

This means the command line tool is split into two subcommands:

  • export products

  • export documents

Both require different parameters, but they have one thing in common: An export must always come from a project. Exporting a single file that is not part of a project is not possible.

Exporting Documents

Let’s first look at the help for documents. By typing adocstudio help export documents you will get:

OVERVIEW: Export documents from an adoc Studio project with custom configuration

USAGE: adocstudio export documents --project <project> --document <document> ... [--language <language> ...] [--format <format>] [--style <style>] [--appearance <appearance>] [--attribute <attribute> ...] [--paper-size <paper-size>] [--paper-margins <paper-margins>] [--text-format <text-format>] <output-folder> [<output-filename>]

ARGUMENTS:
  <output-folder>         Path to the folder to which the specified document should be exported. 
                          A path containing spaces should be enclosed in quotes.
  <output-filename>       An optional filename for the main export file.
                          If it does not contain an extension, a default file extension matching the format is
                          used.

OPTIONS:
  -p, --project <project> Path to an adoc Studio project file
  -d, --document <document>
                          A document to be exported by name, relative path or ID. 
                          A name containing spaces should be enclosed in quotes.
  -l, --language <language>
                          The project language to be exported, given as a BCP 47 identifier 
                          (like en, en-US, de-DE etc.). Needs to be one of the project
                          languages. If none is specified, all project languages are exported.
  -f, --format <format>   The export format. (values: html, pdf, text; default: html)
  -s, --style <style>     The style for formatting the exported document by name or ID. 
                          If none is specified, the default style is used. A name containing
                          spaces should be enclosed in quotes.
  -A, --appearance <appearance>
                          The appearance of the exported document. 
                          (values: automatic, light, dark; default: light)
  -a, --attribute <attribute>
                          A document attribute to set in the form of name, name!, 
                          or name=value pair. Values containing spaces should be enclosed in quotes.
                          The attribute takes precedence over the same attribute defined in a document 
                          unless the name ends in @ (i.e., name@=value). name!
                          unassigns the same attributed defined in a document.
  -P, --paper-size <paper-size>
                          Only for pdf. CSS page size like: a4, letter, a4 portrait, 
                          10cm 20cm (width x height), 10in 20in. If not specified, the default paper
                          size defined in the chosen style is used.
  -M, --paper-margins <paper-margins>
                          Only for pdf. CSS margin string like: 1cm 2cm 3cm 4cm. 
                          When one value is specified, it applies the same margin to all four sides.
                          When two values are specified, the first margin applies to the top and bottom, 
                          the second to the left and right. When four values are
                          specified, the margins apply to the top, right, bottom, 
                          and left in that order (clockwise). If not specified, the default margins
                          defined in the chosen style are used.
  -F, --text-format <text-format>
                          Only for text. Determines the format of the exported text: 
                          rich, plain (values: plain, rich; default: rich)
  -h, --help              Show help information.

An example export from the manual project could look like this:

adocstudio export documents --project Manual.adocproject --document colophon.adoc --format PDF --style Optima ~/Desktop/

Exporting Products

The output for a product via adocstudio help export products is more concise:

OVERVIEW: Export products from an adoc Studio project using their pre-defined configuration.

USAGE: adocstudio export products --project <project> [--product <product> ...] <output-folder>

ARGUMENTS:
  <output-folder>         Path to the folder to which the specified products 
                          should be exported.

OPTIONS:
  -p, --project <project> Path to an adoc Studio project file
  -P, --product <product> Specify one or more products by name or ID. 
                          If no products are specified, all products will be exported.
  -h, --help              Show help information.

An example product export from the manual project could look like this:

adocstudio export products --project Manual.adocproject --product ‘PDF for Mac‘ ~/Desktop/

If the product or project name contains no umlauts or spaces, you can omit the single quotes.

7.7. Apple Shortcuts

Unlike the Terminal tool, you do not need to install support for the Shortcuts app first. As soon as v3 or a later version is installed, you can start right away if adoc Studio is on your device.

To add adoc Studio to a shortcut, search for adoc in the action selector. As a result, two commands will appear:

  • Export Documents

  • Export Products

Both offer a range of options that you can enter automatically within a shortcut or directly in the editor.

More details about Shortcuts and their usage can be found on the Apple website.