image-completion-spec.adoc

Image target path auto-completion

Introduction

This feature is designed to help authors quickly find images in their workspace and reference them in their AsciiDoc document.

Scope

Applies to both image:: and image:.

Requirements

Auto-completion should trigger as soon as:

1. ":" is typed and the line is equals to "image:" (i.e., image block macro)

2. ":" is typed and the text before the cursor is equals to "/\bimage/" (i.e., image inline macro). \b stands for word boundary. In other words, auto-completion should not trigger in the following case: "I sent it to the widow along with his primage:".

Context identification

Everywhere where an image block macro or an inline image macro is recognized.

Suggested items

The auto-completion should suggest a list of files that have the following extensions:

• jpeg

• jpe

• jpg

• png

• svg

• bmp

• gif

• ico

• tga

• tif

• tiff

• webp

It should order files based on the folder depth from the current directory.

a.jpeg
b.jpeg
adir/a.jpeg
adir/b.jpeg
bdir/a.jpeg
adir/adir/a.jpeg
adir/bdir/b.jpeg
bdir/adir/a.jpeg

The current directory should take into account the "imagedir" attribute. For instance, if the value of the attribute imagedir is equals to img, it should suggest a list of files from this directory.

It should be possible to move to the parent directory using "..".

Suggested file paths should use forward slashes (which are supported on both Linux and Windows).

If auto-completion is triggered inside the target path if should suggest files from the parent directory.

image::images/france/lyon/traboules.jpeg[]

• If the cursor is anywhere on the path segment "france" then it should suggest images from "images".

• If the cursor is anywhere on the path segment "lyon" then it should suggest images from "images/france".

• If the cursor is anywhere on the path segment "traboules.jpeg" then it should suggest images from "images/france/lyon".

We should not encourage absolute path completion. It the path starts with / or /[a-zA-Z]:/ we should not try to auto-complete the path.

Once an item is selected it should complete the macro if the square brackets are missing []. Otherwise, it should replace the path.

Style guide

We should not encourage using {imagedir} explicitly. The attribute reference completion should not suggest {imagedir} in an image block macro or inline macro.

We should add a quick action to replace {imagedir}/path/to/image.jpeg to path/to/image.jpeg.

Ideally, this list will live in the AsciiDoc WG or AsciiDoc Language project instead of the Asciidoctor project.

That's a good point!
I've created an (almost empty) Antora module in the VS code extension: https://github.com/asciidoctor/asciidoctor-vscode/tree/master/docs/modules/spec/pages.

When we have a substantial amount of specs, we could consider moving them in the AsciiDoc Language project.