Images

My goal is to not introduce syntax constructs into Novelang for every need, but handling images with paired delimiters quickly becomes a mess. So image: syntax is fine but it collides with what a plain Paragraph can be made of. Let's twist it a bit using a double colon for now.

image::path/file.ext

As with URLs it seems more readable to force image declaration to start at the beginning of a line. The all-on-the-same-line requirement comes with the same advantages: it's easy to add metadata.

image::path/file.ext "title"

There are several ways to reference an image: the image itself for displaying it, or its name. Many document have textual references to images (like Fig. 5). Numbering must be automated, and text must reference images through a symbolic name. It's a clear need for identifiers. Defining identifiers works the same as for Paragraphs:

  \\image-identifier
image::path/file.ext "title"

Referencing the image is done with a new image-ref:: keyword, that should appear at the start of a new line, too:

Have a look at
image-ref::\\image-identifier
.

Ok I'm not happy with the full stop coming on its own line but I'm just trying to be honest so don't hit me. Depending on numbering scheme this should translate to something like:

Have a look at Figure 5-12.

Image display can happen through a reference, too:

image::\\image-identifier

With all that in mind, here is how to use images in big documents. Define one Part file or more with all images, then reference them as needed. The Part files containing images may define Sections with their own absolute identifiers corresponding to some themes or categories, and all images inside the Sections have a relative identifier. Another advantage of having all images in separate files is to get an overview for free.