Appendix A: Support

You’ve made it! Up to this point, you have focused on the description of concepts and features. Now it’s your turn. Start writing and share your successes!

A.1. System Requirements

The minimum system requirements for using adoc Studio are:

  • macOS 13 Ventura

  • iOS 16

A.2. First Aid

Forum

A free forum is available where the team from ProjectWizards is also on hand to offer advice and assistance.

The AsciiDoc Command Reference

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

Personal Experiences with AsciiDoc

On the ProjectWizards website blog, you’ll find a variety of practical articles on AsciiDoc.

Additional Tips on AsciiDoc

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

A.3. Help with Templates and Styles

A partner network is currently being established to assist you with building your templates and designing product styles. You can find the current list of partners online.

Over time, a directory of all styles will also be created there. If you’re interested in actively participating, send a message to: office@projectwizards.net.

A.4. Attributes

We explained the concept and usage in the Attributes chapter. Below is a list of all the attributes used in adoc Studio.

adoc Studio Attributes

ads-compat-mode

When set, compatibility with Asciidoctor is maximised. For example, date and time information is not localised, author names are split differently, and icon directories point to different locations. Other AsciiDoc modernisations are also disabled, such as source-highlighter or stem.

ads-device v3

Contains Mac, iPhone or iPad. Depending on which device you use adoc Studio on.

ads-max-image-resolution v3

Set 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 a width or height is explicitly specified in the source code. To limit the size of images without a predefined width or height in HTML, use the ads-max-image-width attribute.

ads-max-image-width v3

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

ads-pdf-ua v4

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

ads-platform

Contains macOS or iOS. Depending on which platform you use adoc Studio on.

ads-rasterizing-resolution v3

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.

ads-static-stem

By default, STEM equations in HTML exports are created dynamically via JavaScript when you open the exported document in a web browser. If this option is enabled, the equations are exported as static SVG images, so no JavaScript is required to view them.

ads-static-stem → inline

Exports STEM equations as inline SVG elements

ads-static-stem → external

Exports STEM equations as external SVG images.

ads-subtitle

Outputs the subtitle.

Intrinsic Attributes

backend

Always set to html5 for compatibility with Asciidoctor.

backend-html5

Always set for compatibility with Asciidoctor.

basebackend

Always set to html for compatibility with Asciidoctor.

basebackend-html

Always set for compatibility with Asciidoctor.

docdate

Last modification date of the source document without time. Localized according to the language and locale provided via the lang attribute.

docdatetime

Last modification date and time of the source document. Localized according to the language and locale provided via the lang attribute.

docdir

Path to the directory that contains the source document. The path starts with a slash and the root directory of the project.

docfile

Path to the source document. The path starts with a slash and the root directory of the project.

docfilesuffix

File extension of the source document including the leading period.

docname

Name of the source document without file extension.

doctime

Last modification time of the source document. Localized according to the language and locale provided via the lang attribute.

docyear

Year that the source document was last modified. Localized according to the language and locale provided via the lang attribute.

embedded

Can be set as an option for an HTML export. The generated HTML then does not contain head or body tags and can therefore be embedded directly in another HTML page.

filetype

File extension of the main output file of the document, without leading period. The extension depends on the selected output format.

filetype-html

A convenience attribute for checking whether the output filetype is html.

filetype-pdf

A convenience attribute for checking whether the output filetype is pdf.

filetype-rtfd

A convenience attribute for checking whether the output filetype is rtfd (rich text).

filetype-txt

A convenience attribute for checking whether the output filetype is txt (plain text).

htmlsyntax

Currently always html as adoc Studio does not support xhtml output yet.

outfilesuffix

File extension of the actual output file of the document, with leading dot. The value depends on the selected output format.

localdate

Date when the document was converted to the output format.

localdatetime

Date and time when the document was converted to the output format.

localtime

Time when the document was converted to the output format.

localyear

Year when the document was converted to the output format.

Compliance Attributes

attribute-missing

Controls how missing attribute references are handled.

attribute-missing → skip

Leave the unresolved reference in place and create an error.

attribute-missing → drop

Drop the reference.

Localization and numbering attributes

lang

Language tag like en or en-US. Is added to the root element of the HTML output. Controls hyphenation and localization of dates.

nolang

Prevents lang attribute from being added to root element of the HTML output.

appendix-caption

Label added before the title of an appendix.

appendix-number

Sets the seed value for the appendix number sequence.

Callouts

Callout numbers (aka callouts) provide a means to add annotations to lines in a verbatim block.

caution-caption

Text used to label caution admonitions when icons aren’t enabled.

chapter-number

Sets the seed value for the chapter (level 1 section titles) number sequence when using doctype book.

chapter-signifier

Label added to level 1 section titles (chapters) when using doctype book.

example-caption

Text used to label example blocks.

example-number

Sets the start value for the example number sequence. Is only used if the example-caption attribute is set and the example has a title.

figure-caption

Text used to label images and figures.

figure-number

Sets the seed value for the figure number sequence. Is only used if the figure-caption attribute is set and the figure has a title.

important-caption

Text used to label IMPORTANT admonitions when icons aren’t enabled.

last-update-label

Text displayed in the footer before the last modification date.

listing-caption

Text used to label listing blocks.

listing-number

Sets the seed value for the listing number sequence. Is only used if the listing-caption attribute is set and the listing has a title.

note-caption

Text used to label NOTE admonitions when icons aren’t enabled.

table-caption

Text of label prefixed to table titles.

table-number

Sets the seed value for the table number sequence. Is only used if the table-caption attribute is set and the table has a title.

tip-caption

Text used to label TIP admonitions when icons aren’t enabled.

toc-title

Title for table of contents.

untitled-label

Default document title if document doesn’t have a document title.

version-label

The label displayed before the revision number in the document title byline.

warning-caption

Text used to label WARNING admonitions when icons aren’t enabled.

Attributes for Styling & Layout

hyphens

Controls whether and how text is hyphenated in HTML and PDF.

hyphens → none

Words are not broken at line breaks, even if characters inside the words suggest line break points. Lines will only wrap at whitespace.

hyphens → manual

Words are broken for line-wrapping only where characters inside the word suggest line break opportunities.

hyphens → auto

Words are broken automatically at appropriate hyphenation points according to the chosen language in the lang attribute. However, suggested line break opportunities will override automatic break point selection when present.

title-page

Puts a dedicated title page at the start of a PDF document. The title page contains the doctitle, author, date and revision informationen.

pagenums

Enables showing of page numbers in PDF documents.

outline

By default, adoc Studio generates a PDF outline for PDF documents. You can turn it off by unsetting this attribute.

outlinelevels

Adjust the depth of section levels that are displayed in the PDF outline independent of the TOC level depth. By default, it is set to the same value as toclevels.

outline-title

By default, the document title is displayed as the title of the PDF outline. You can customize this using this attribute.

Document metadata attributes

app-name

Value for application-name meta element for mobile devices inside HTML document head.

author

Contains the main author’s name. Can be set automatically via the author info line or explicitly.

authors

Contains a list of author names. Can be set automatically via the author info line or explicitly as a comma-separated value list.

authorinitials

Derived from the author attribute by default. Can also be set explicitly.

email

Extracted from author info line by default. Can be any inline macro, such as a URL. Can also set set explicitly.

firstname

Derived from the author attribute by default. Can also be set explicitly.

middlename

Derived from the author attribute by default. Can also be set explicitly.

lastname

Derived from the author attribute by default. Can also be set explicitly.

doctitle

Set to the level 0 section title by default. Can be set explicitly.

description

Value for description meta element inside HTML document head.

keywords

Value for keywords meta element inside HTML document head.

publisher

Is put into the producer metadata field of PDF documents.

subject

Is put into the subject metadata field of PDF documents.

title

Value of the title element in the HTML head. Used as a fallback when the document title is not specified via either a level 0 section or the doctitle attribute.

revnumber

Extracted from revision info line.

revdate

Extracted from revision info line.

revremark

Extracted from revision info line.

page-background-image

Set this attribute to add a background image to all PDF content pages. For the value you can either specify a simple path to an image or an inline image macro. The latter allows to specify further attributes to control the image scale and position.

page-background-image-recto

Set this attribute to add a background image separately for all recto PDF content pages. For the value you can either specify a simple path to an image or an inline image macro. The latter allows to specify further attributes to control the image size and position.

page-background-image-verso

Set this attribute to add a background image separately for all verso PDF content pages. For the value you can either specify a simple path to an image or an inline image macro. The latter allows to specify further attributes to control the image size and position.

title-page-background-image

Places a logo image in the content area of the title page. The title page needs to be enabled via the title-page attribute. For the value you can either specify a simple path to an image or an inline image macro. The latter allows to specify further attributes to control the image size and position.

front-cover-image

Creates a separate cover PDF page at the very beginning of the document containing only an image. For the value you can either specify a simple path to an image or an inline image macro. The latter allows to specify further attributes to control the image size and position.

back-cover-image

Creates a separate cover PDF page at the very end of the document containing only an image. For the value you can either specify a simple path to an image or an inline image macro. The latter allows to specify further attributes to control the image size and position.

pdf-page-size

Setting this attribute overrides the PDF page size defined in the preview or product options.

pdf-page-layout

Setting this attribute overrides the portrait or landscape PDF page orientation defined in the preview or product options.

pdf-page-margin

Setting this attribute overrides the PDF page margins defined in the preview or product options.

pdf-page-margin-rotated

Define separate PDF page margins for landscape orientation.

text-align

Overrides the default text alignment of the chosen style.

Section title and table of contents attributes

idprefix

By default, auto-generated section IDs begin with an underscore. You can change it by setting this attribute. The value must begin with a valid ID start character and can have any number of additional valid ID characters. If you want to remove the prefix, set the attribute to an empty value.

idseparator

The default section ID word separator is an underscore. You can change it with this attribute. Unless empty, the value must be exactly one valid ID character.

leveloffset

Changes the level depth of all headings by the specified number of steps. The value is relative and begins with + or -. This allows you to publish each chapter as a standalone document, complete with a document title.

partnums

To autogenerate book part numbers, set this attribute in the book header.

sectanchors

When enabled, an anchor (empty link) is added before the section titles. The default stylesheet renders it as a § symbol that floats to the left of the section title.

sectids

Section and discrete headings without an explicitly set identifier receive an auto-generated ID. You can disable this by unsetting this attribute. Elements without an ID cannot be cross-referenced.

sectnums

Sections aren’t numbered by default. However, you can enable this feature by setting this attribute. You can toggle numbering on and off throughout a document.

sectnums → all

Sections that are assigned a built-in special style aren’t numbered by default. To number regular sections as well as special sections, set sectnums and assign it a value of all.

sectnumlevels

When sectnums is set, level 1-3 section titles are numbered by default. You can adjust the level limit to value of 0 through 5.

toc

Turns on table of contents and specifies its location. By default, it is inserted directly below the document title, author, and revision lines.

toc → auto

The table of contents is inserted directly below the document title, author, and revision lines.

toc → left

The table of contents is positioned to the left of the main content column. It is both fixed and scrollable.

toc → right

The table of contents is positioned to the right of the main content column. It is both fixed and scrollable.

toc → preamble

The table of contents is positioned immediately below the preamble, the content between the end of the document header and the first section title.

toc → macro

Place the table of contents in a specific location. Assign the macro value, then enter the table of contents block macro (toc::[]) on the line in your document where you want the table of contents to appear.

toclevels

By default, the table of contents displays level 1 and 2 section titles. Use this attribute to adjusts the depth to a value from 1 through 5.

toc-class

CSS class on the table of contents container HTML element.

media

Enables behavior specific to a PDF media type.

media → print

Shows the URLs for links unless the link text matches the URL.

media → prepress

In addition to print mode also uses double-sided (mirror) page margins and automatic facing pages.

General content and formatting attributes

data-uri

Embeds images and other media in HTML files as data-uri elements. This attribute only comes into effect if you select the value From Attributes in the export settings for resources.

doctype

Document type. Currently supported are article and book.

doctype → article

The default doctype. Unless you are making a book you don’t need to worry about setting the doctype.

doctype → book

Builds on the article doctype with the additional ability to use a top-level title as part titles. There’s also the concept of a multi-part book, but the distinction from a regular book is determined by the content. A book only has chapters and special sections, whereas a multi-part book is divided by parts that each contain one or more chapters or special sections.

doctype-article

A convenience attribute for checking whether the doctype is article.

doctype-book

A convenience attribute for checking whether the doctype is book.

hardbreaks-option

Preserve line breaks in all paragraphs throughout the entire document.

notitle

Hides the document title in a document. Mutually exclusive with the showtitle attribute.

showtitle

Shows the document title in an embedded document. Mutually exclusive with the notitle attribute.

noheader

Turns off document header

nofooter

Turns off document footer

table-frame

Controls default value for frame attribute on tables.

table-grid

Controls default value for grid attribute on tables.

table-stripes

Controls default value for stripes attribute on tables.

Image and icon attributes

icons

Chooses images or font icons instead of text for admonitions. Any other value is assumed to be an icontype and sets the value to empty (image-based icons).

icons → image

Icons resolve to image files in the directory specified by the iconsdir attribute.

icons → font

Icons are loaded from an icon font like Font Awesome.

iconsdir

Location of non-font-based image icons. Defaults to the icons folder under imagesdir if imagesdir is specified and iconsdir is not specified. v3 now uses the media folder as default. If ads-compat.mode is set, the old behavior is active again.

icontype

File type for image icons. Only relevant when using image-based icons.

icon-set

For use with icon macros: Choose a set from which the font-based icons are taken. This attribute only has an effect if you have activated font-based icons via the icons attribute.

icon-set → apple v3

Icon macros display symbols from the SF symbols. The different palettes (multicolor, hierachical, monochrome) are also supported, as are the different font weights.

icon-set → fa

Icon macros show symbols from the deprecated Font Awesome 4 set. In adoc Studio, this is equal to the Regular set. This is the default setting.

icon-set → fas

Icon macros show symbols from the Font Awesome set Solid.

icon-set → fab

Icon macros show symbols from the Font Awesome set Brands.

icon-set → far

Icon macros show symbols from the Font Awesome set Regular.

imagesdir

By default, media files for images or movies are picked based on the path specified in the macro’s target. The text set in imagesdir is automatically added to the beginning of this path.

source-highlighter v4

To enable syntax highlighting, you had to set the attribute in document header via an attribute entry. From version 4 onwards, it is set implicitly in every document.

stem v4

To enable support for equations and formulas, set this attribute in the document header. From version 4 onwards, the attribute is set to asciimath implicitly.

HTML styling attributes

linkcss

Inserts a reference to the stylesheet in HTML files instead of embedding it completely. This attribute is only used if you select the value From Attributes in the export settings for resources.

stylesheet

Normally, you select one of the installed styles to design your documents. If you set this attribute to the name of a CSS file in your project, this stylesheet will be used for the preview and export instead. If the style file is not in the same folder as the document, you can also specify the path to its folder in the stylesdir attribute.

stylesdir

The file path optionally specified here is prefixed to the file name contained in the stylesheet attribute in order to localize the CSS stylesheet file in the project.

A.5. Notes on AsciiDoc Compatibility in adoc Studio

Even though adoc Studio adheres to the AsciiDoc standard, there are some small but notable differences where we have taken our own approach in development. In most cases, we chose not to copy errors in AsciiDoc but to fix them. In some cases, we have expanded features to provide you with a simpler or more comprehensive experience. This section describes these differences.

The App

  • AsciiDoc does not know the concept of collection documents. If you want to switch between different editors and parsers, you should use a folder with an index file instead, in which all files to be used are linked or included.

  • If you need to use an iPad, you will need adoc Studio. Without a hack, you cannot run Asciidoctor on an iPad.

If you have been using Asciidoctor.js to preview .adoc files, you will be aware of the new security developments in current browsers. All includes in AsciiDoc are now no longer loaded. This problem does not exist in adoc Studio.

Attributes

In adoc Studio, we have introduced a set of custom attributes to extend functionality. Each of them starts with ads-.

  • :ads-compat-mode: When set, compatibility with Asciidoctor is maximized, and all other ads- attributes will no longer function. For example, date and time formats will not be localized, author names will be split differently, and icon directories will point to different locations.

  • :ads-platform: Contains macOS or iOS, depending on which platform you are using adoc Studio on.

  • :ads-device: Contains Mac, iPhone, or iPad, depending on which device you are using adoc Studio on.

  • :ads-max-image-resolution: Sets the maximum resolution for images in HTML and PDF exports. Specify 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 code. To limit the size of images without a predefined width or height in HTML, set the attribute ads-max-image-width.

  • :ads-max-image-width: For HTML export, sets the maximum pixel width for images that do not have a width or height specified in the source code.

  • :ads-rasterizing-resolution: If a value is set, PDF and SVG images, as well as STEM equations in HTML exports, will be converted to PNG images. You can specify resolution values in dpi, dpcm, or dppx.

  • :ads-static-stem: By default, STEM equations in HTML exports are dynamically generated via JavaScript when you open the exported document in a web browser. If this option is enabled, equations will be exported as static SVG images, eliminating the need for JavaScript to display them.

  • :ads-static-stem: → inline Exports STEM equations as inline SVG elements.

  • :ads-static-stem: → external Exports STEM equations as external SVG images.

  • :experimental: This attribute is no longer used in adoc Studio and has no effect.

  • :source-highlighter: This attribute has been implicitly set since v3.

  • :stem: This attribute has been implicitly set since v3.

Styles

  • All product types using the same stylesheet.

  • All Styles are collected in one place and can be used, adopted for own styles, extended and modified easily.

Icons

  • Unlike images, the AsciiDoc processor does not support embedding SVG images into the icon macro. In adoc Studio, you can use the inline option. The SVG will then be embedded directly into the exported HTML.

:icons:
icon:tiger.svg[opts=inline]
  • The :iconsdir: attribute in adoc Studio points to the media folder by default.

Macros

  • footnotes appear in PDFs on the same page where they are set.

A.6. Regular Expressions

As the scope of a writing project increases, the search for content also becomes more complex. Instead of searching word by word in each file and possibly replacing them, you can also use a search for a pattern in the text to find relevant text passages. These are then the regular expressions. And because the name is somewhat unwieldy, many people shorten it to RegEx.

A short example clearly shows the power of this grammar:

Search: h*.us replaces the *. with one or more arbitrary characters Finds: House, Haus and even Huus. But not Hans, only words that begin with an h and end with us.

And there are many of these patterns. They can consist of one or more characters, operators or constructs. We will give you an initial overview below.

Regular Expression Meta Characters

The following tables describe the character expressions used by the regular expression to match patterns within a text. The pattern operators specify how many times a pattern is matched and additional matching restrictions. The last table specifies flags that can be included in the regular expression pattern that specify search behavior over multiple lines.

The table Regular Expression Metacharacters describe the character sequences used to match characters within a string.

Table 7. Regular Expression Metacharacters

Character Expression

Description

\a

Match a BELL, \u0007

\A

Match at the beginning of the input. Differs from ^ in that \A will not match after a new line within the input.

\b, outside of a [Set]

Match if the current position is a word boundary. Boundaries occur at the transitions between word (\w) and non-word (\W) characters, with combining marks ignored.

\b, within a [Set]

Match a BACKSPACE, \u0008.

\B

Match if the current position is not a word boundary.

\cX

Match a control-X character

\d

Match any character with the Unicode General Category of Nd (Number, Decimal Digit.)

\D

Match any character that is not a decimal digit.

\e

Match an ESCAPE, \u001B.

\E

Terminates a \Q …​ \E quoted sequence.

\f

Match a FORM FEED, \u000C.

\G

Match if the current position is at the end of the previous match.

\n

Match a LINE FEED, \u000A.

\N{UNICODE CHARACTER NAME}

Match the named character.

\p{UNICODE PROPERTY NAME}

Match any character with the specified Unicode Property.

\P{UNICODE PROPERTY NAME}

Match any character not having the specified Unicode Property.

\Q

Quotes all following characters until \E.

\r

Match a CARRIAGE RETURN, \u000D.

\s

Match a white space character. White space is defined as [\t\n\f\r\p{Z}].

\S

Match a non-white space character.

\t

Match a HORIZONTAL TABULATION, \u0009.

\uhhhh

Match the character with the hex value hhhh.

\Uhhhhhhhh

Match the character with the hex value hhhhhhhh. Exactly eight hex digits must be provided, even though the largest Unicode code point is \U0010ffff.

\w

Match a word character. Word characters are [\p{Ll}\p{Lu}\p<\p{Lo}\p{Nd}].

\W

Match a non-word character.

\x{hhhh}

Match the character with hex value hhhh. From one to six hex digits may be supplied.

\xhh

Match the character with two digit hex value hh.

\X

Match a Grapheme Cluster.

\Z

Match if the current position is at the end of input, but before the final line terminator, if one exists.

\z

Match if the current position is at the end of input.

\n

Back Reference. Match whatever the nth capturing group matched. n must be a number ≥ 1 and ≤ total number of capture groups in the pattern.

\0ooo

Match an Octal character. ooo is from one to three octal digits. 0377 is the largest allowed Octal character. The leading zero is required; it distinguishes Octal constants from back references.

[pattern]

Match any one character from the pattern.

.

Match any character. See dotMatchesLineSeparators and the s character expression in Table 4.

^

Match at the beginning of a line. See anchorsMatchLines and the \m character expression in Table 4.

$

Match at the end of a line. See anchorsMatchLines and the m character expression in Table 4.

\

Quotes the following character. Characters that must be quoted to be treated as literals are * ? + [ ( ) { } ^ $ | \ . /

Regular Expression Operators

The table Regular Expression Operators defines the regular expression operators.

Table 8. Regular Expression Operators

Operator

Description

|

Alternation. A|B matches either A or B.

*

Match 0 or more times. Match as many times as possible.

+

Match 1 or more times. Match as many times as possible.

?

Match zero or one times. Prefer one.

{n}

Match exactly n times.

{n,}

Match at least n times. Match as many times as possible.

{n,m}

Match between n and m times. Match as many times as possible, but not more than m.

*?

Match 0 or more times. Match as few times as possible.

+?

Match 1 or more times. Match as few times as possible.

??

Match zero or one times. Prefer zero.

{n}?

Match exactly n times.

{n,}?

Match at least n times, but no more than required for an overall pattern match.

{n,m}?

Match between n and m times. Match as few times as possible, but not less than n.

*+

Match 0 or more times. Match as many times as possible when first encountered. Do not retry with fewer, even if overall match fails (possessive match).

++

Match 1 or more times (possessive match).

?+

Match zero or one times (possessive match).

{n}+

Match exactly n times.

{n,}+

Match at least n times (possessive match).

{n,m}+

Match between n and m times (possessive match).

(…​)

Capturing parentheses. Range of input that matched the parenthesized subexpression is available after the match.

(?:…​)

Non-capturing parentheses. Groups the included pattern, but does not provide capturing of matching text. Somewhat more efficient than capturing parentheses.

(?>…​)

Atomic-match parentheses. First match of the parenthesized subexpression is the only one tried; if it does not lead to an overall pattern match, back up the search for a match to a position before the "(?>"

(?# …​ )

Free-format comment (?# comment ).

(?= …​ )

Look-ahead assertion. True if the parenthesized pattern matches at the current input position, but does not advance the input position.

(?! …​ )

Negative look-ahead assertion. True if the parenthesized pattern does not match at the current input position. Does not advance the input position.

(?⇐ …​ )

Look-behind assertion. True if the parenthesized pattern matches text preceding the current input position, with the last character of the match being the input character just before the current position. Does not alter the input position. The length of possible strings matched by the look-behind pattern must not be unbounded (no * or + operators.)

(?<! …​ )

Negative Look-behind assertion. True if the parenthesized pattern does not match text preceding the current input position, with the last character of the match being the input character just before the current position. Does not alter the input position. The length of possible strings matched by the look-behind pattern must not be unbounded (no * or + operators.)

(?ismwx-ismwx: …​ )

Flag settings. Evaluate the parenthesized expression with the specified flags enabled or -disabled. The flags are defined in Flag Options.

(?ismwx-ismwx)

Flag settings. Change the flag settings. Changes apply to the portion of the pattern following the setting. For example, (?i) changes to a case insensitive match.The flags are defined in Flag Options.

Template Matching Format

The regular expression provides find-and-replace methods for both immutable and mutable strings using the technique of template matching. Table Template Matching Format describes the syntax.

Table 9. Template Matching Format

Character

Description

$n

The text of capture group n will be substituted for $n. n must be >= 0 and not greater than the number of capture groups. A $ not followed by a digit has no special meaning, and will appear in the substitution text as itself, a $.

\

Treat the following character as a literal, suppressing any special meaning. Backslash escaping in substitution text is only required for '$' and '\', but may be used on any other character without bad effects.

Flag Options

The following flags control various aspects of regular expression matching. These flag values may be specified within the pattern using the (?ismx-ismx) pattern options. Equivalent behaviors can be specified for the entire pattern when a regular expression is initialized.

Table 10. Flag Options

Flag (Pattern)

Description

i

If set, matching will take place in a case-insensitive manner.

x

If set, allow use of white space and #comments within patterns

s

If set, a "." in a pattern will match a line terminator in the input text. By default, it will not. Note that a carriage-return / line-feed pair in text behave as a single line terminator, and will match a single "." in a regular expression pattern

m

Control the behavior of "^" and "$" in a pattern. By default these will only match at the start and end, respectively, of the input text. If this flag is set, "^" and "$" will also match at the start and end of each line within the input text.

w

Controls the behavior of \b in a pattern. If set, word boundaries are found according to the definitions of word found in Unicode UAX 29, Text Boundaries. By default, word boundaries are identified by means of a simple classification of characters as either “word” or “non-word”, which approximates traditional regular expression behavior. The results obtained with the two options can be quite different in runs of spaces and other non-word characters.

A.7. Isn’t something still missing here?

With adoc Studio we still at the beginning of a long journey. You can find the current status of development at the website.

Initially, the focus is on functions that are needed by most users. But it may well be that you are missing that one function. Register for free on the adoc Studio forum and describe us your needs.

Of course, you also have the opportunity to express your own wishes or suggest new functions. Your ideas may also be supported by other users. This will ensure that the functions you need can appear next in adoc Studio.

Look forward to the exciting developments that are yet to come!

A.8. Tips for External Tools

Since adoc Studio is based on the UTF-8 standard for all created texts, UNIX-based tools are particularly helpful. Below is a compiled list that assists us in our daily work. Maybe it does for you too.

  • Git with Tower: A free software for distributed version control of files initiated by Linus Torvalds. Tower is the GUI client for Git on macOS.

  • Make and Makefiles: a build management tool that executes commands based on conditions.

  • Vale: An open-source command-line tool that brings your editorial style guide to life.

Do you also have an idea for an external tool? We look forward to hearing about it in the adoc Studio forum.