Dave Jarvis' Repositories

count/

themes/

quotes/

tex/

spell/

tokens/

* [Gradle 8.5](https://gradle.org/releases)

* [Git 2.43](https://git-scm.com/downloads)

Run the `installer.sh` script to build platform-specific binaries, such as:

    ./installer.sh -V -o linux

The `installer.sh` script:

Run `./installer.sh -h` to see all command-line options.

      <Bug code="EI, EI2, CT, RV, PI" />

    classpath 'org.owasp:dependency-check-gradle:9.0.1'

    classpath "com.github.spotbugs.snom:spotbugs-gradle-plugin:5.2.4"

  id "com.github.spotbugs" version "5.2.4"

  def v_junit = '5.10.1'

  def v_echosvg = '1.0.1'

  implementation 'org.controlsfx:controlsfx:11.2.0'

  implementation 'org.jsoup:jsoup:1.17.1'

  implementation 'org.apache.commons:commons-compress:1.25.0'

  implementation 'org.apache.commons:commons-lang3:3.14.0'

}

/**

 * Mozilla's JavaScript engine, Rhino, is used by the SVG rasterizer.

 * The application does not support animated SVG files (the HTML

 * renderer won't honour them), so we can eliminate the dependency from

 * the binaries.

 */

configurations {

  all*.exclude group: 'org.mozilla', module: 'rhino'

  doFirst { jvmArgs += moduleSecurity }

}

tasks.withType( JavaCompile ).configureEach {

  options.compilerArgs += "--enable-preview"

}

tasks.withType( JavaExec ).configureEach {

  jvmArgs += "--enable-preview"

}

tasks.withType( Test ).configureEach {

  jvmArgs += "--enable-preview"

* [references.md](references.md) -- Captions and cross-references

# Captions and cross-references

Users may define captions and cross-references to tables, figures,

and equations. Unfortunately, at time of writing, the CommonMark

specification is frozen. This means cross-references must be implemented

as an extension to the Markdown specification, leaving the door open for

differing Markdown rendering libraries and applications to diverge on

with respect to syntax.

# Syntax

This section describes how to use captions and cross-references within

Markdown documents. The CommonMark standard details different ways to

add captions to tables and figures. While those are supported, a more

consistent syntax is available.

## Captions

Tables, figures, and equations are captioned using the same syntax. In

general, a line that starts with a double colon after a blank line will

result in a caption added to the item immediately proceding it. The

remainder of this section provides examples.

### Images

An image caption:

```

![kitten](https://placekitten.com/600/350)

:: Figure caption text

```

### Table

A table caption:

```

| a | b | c |

|---|---|---|

| 1 | 2 | 3 |

| 4 | 5 | 6 |

| 7 | 8 | 9 |

:: Table caption text

```

### Equation

An equation caption:

```

$$E | mc^2$$

:: Equation caption

```

# Cross-references

There are two parts to a cross-reference: the anchor name and its references.

An anchor name must be uniquely defined. Any number of references may refer

to an anchor name. Anchor names can be associated with any item in the

document, and are primarily added to captions.

The general syntax for anchor names and references is:

* `{#type-name:label}` (anchor name)

* `[@type-name:label]` (reference)

The `type-name` can be any alphanumeric value, starting with a letter.

Type names user-defined categories for the item type. Labels are user-defined

identifiers that must be unique per item.

Consider the following example:

```

In [@fig:kitten], a cute kitten is shown.

![kitten](https://placekitten.com/600/350)

:: World's cutest kitten {#fig:kitten}

There is no cuter kitten than the one in [@fig:kitten].

```

The anchor name uniquely defines where an item in a document is located. Any

number of references, anywhere in the document, may reference an anchor name.

There are few restrictions placed on the possible type names and labels. Here

are a few more anchor name examples:

```

{#fig:cats}

{#図版:猫}

{#eq:mass-energy}

{#eqn:laplace}

```

## Type names

To avoid duplicating writing the label each time (e.g., Figure, Table,

Equation), there are a number of predefined labels associated with

type names. The following table lists the type names and the label

generated by the typesetting system:

| Type name | English name

|---|---|

| algorithm | Algorithm |

| alg | Algorithm |

| equation | Equation |

| eqn | Equation |

| eq | Equation |

| figure | Figure |

| fig | Figure |

| formula | Formula |

| listing | Listing |

| list | Listing |

| lst | Listing |

| lyric | Lyrics |

| music | Score |

| score | Score |

| source | Listing |

| src | Listing |

| tab | Table |

| table | Table |

| tbl | Table |

These values are defined in the theme's `xhtml/xml-references.tex` file.

1. Visit the [skin](https://gitlab.com/DaveJarvis/KeenWrite/-/tree/main/src/main/resources/com/keenwrite/skins) repository directory

[markdown.css](https://gitlab.com/DaveJarvis/KeenWrite/-/blob/main/src/main/resources/com/keenwrite/editor/markdown.css), which is also in the repository.

The [Java CSS Reference Guide](https://openjfx.io/javadoc/21/javafx.graphics/javafx/scene/doc-files/cssref.html) is exhaustive. In addition to showing many

it along. Either open a new issue in the [issue tracker](https://gitlab.com/DaveJarvis/KeenWrite/-/issues) that contains the CSS file or submit a pull request.

1. Right-click [localpath.bat](https://gitlab.com/DaveJarvis/KeenWrite/-/raw/main/scripts/localpath.bat).

1. Download the <a href="https://gitlab.com/DaveJarvis/keenwrite-themes/-/releases/permalink/latest/downloads/theme-pack.zip">theme-pack.zip</a> archive.

* [What is ConTeXt?](https://www.pragma-ade.com/general/manuals/what-is-context.pdf)

* [A not so short introduction to ConTeXt](https://github.com/contextgarden/not-so-short-introduction-to-context)

* [Dealing with XML in ConTeXt MKIV](https://pragma-ade.com/general/manuals/xml-mkiv.pdf)

* [Typographic Programming](https://www.pragma-ade.com/general/manuals/style.pdf)

[themes](https://gitlab.com/DaveJarvis/keenwrite-themes), and numerous

Follow the steps in the wizard to install the requisite software and

typesetting themes.

-Dprism.order=sw \

--enable-preview \

  -Dprism.order=sw \

  --enable-preview \

readonly APP_NAME_LC=${APP_NAME,,}

readonly PATH_TOKEN="tokens/${APP_NAME_LC}.pat"

readonly URL=$(cat "tokens/publish.url")

readonly FILE_VERSION="version.txt"

# Adds download URLs to a release.

#

# $1 - The system (Linux, WIndows, MacOS, Java)

# ---------------------------------------------------------------------------

release() {

  local -r OS="${1}"

  local ARCH=" (64-bit, x86)"

  local FILE_PREFIX="${APP_NAME_LC}"

  local FILE_SUFFIX="bin"

  case ${OS} in

    MacOS)

      FILE_SUFFIX="app"

    ;;

    Windows)

      FILE_PREFIX="${APP_NAME}"

      FILE_SUFFIX="exe"

    ;;

    Java)

      ARCH=""

      FILE_SUFFIX="jar"

    ;;

    *)

      # Linux, others

    ;;

  esac

  local -r BINARY="${FILE_PREFIX}.${FILE_SUFFIX}"

  upload "${BINARY}"

  glab release upload ${RELEASE} \

    --assets-links="[{

      \"name\":\"${APP_NAME} for ${OS}${ARCH}\",

      \"url\":\"https://${APP_NAME_LC}.com/downloads/${BINARY}\",

      \"link_type\":\"other\"

    }]"

}

# ---------------------------------------------------------------------------

# Uploads a file to the remote host.

upload() {

  local -r FILENAME="${1}"

  if [ -f "${FILENAME}" ]; then

    scp "${FILENAME}" "${URL}"

    echo "Missing ${FILE_BINARY}, continuing."

  release "Windows"

  release "MacOS"

  release "Linux"

  release "Java"

  echo "${RELEASE}" > "${FILE_VERSION}"

  upload "${FILE_VERSION}"

  mv "${FILE_VERSION}" "www/downloads"

import static java.nio.charset.StandardCharsets.UTF_8;

        final var result = outputDoc == null

          ? null

          : writeString( outputPath, outputDoc, UTF_8 );

      return readString( inputPath, UTF_8 );

import static java.nio.charset.StandardCharsets.UTF_8;

    return path == null ? "" : Files.readString( path, UTF_8 );

import com.keenwrite.sigils.PropertyKeyOperator;

import static java.util.regex.Matcher.quoteReplacement;

  /**

   * Creates a new interpolating map using the {@link PropertyKeyOperator}.

   */

  public InterpolatingMap() {

    this( new PropertyKeyOperator() );

  }

  public String interpolate( final String value ) {

    final var sb = new StringBuilder( value.length() << 1 );

        matcher.appendReplacement( sb, quoteReplacement( keyValue ) );

    matcher.appendTail( sb );

    return sb.toString();

    if( this == o ) {

      return true;

    }

    if( o == null || getClass() != o.getClass() ) {

      return false;

    }

    if( !super.equals( o ) ) {

      return false;

    }

import static java.nio.charset.StandardCharsets.UTF_8;

          text.append( readString( file, UTF_8 ) )

/* Copyright 2023 White Magic Software, Ltd. -- All rights reserved.

 *

 * SPDX-License-Identifier: MIT

 */

package com.keenwrite.config;

import com.keenwrite.collections.InterpolatingMap;

import java.io.IOException;

import java.io.Reader;

import java.util.*;

import static java.util.Arrays.*;

/**

 * Responsible for reading and interpolating properties files.

 */

public class PropertiesConfiguration {

  private static final String VALUE_SEPARATOR = ",";

  private final InterpolatingMap mMap = new InterpolatingMap();

  public PropertiesConfiguration() {}

  public void read( final Reader reader ) throws IOException {

    final var properties = new Properties();

    properties.load( reader );

    for( final var name : properties.stringPropertyNames() ) {

      mMap.put( name, properties.getProperty( name ) );

    }

    mMap.interpolate();

  }

  /**

   * Returns the value of a string property.

   *

   * @param property     The property key.

   * @param defaultValue The value to return if no property key has been set.

   * @return The property key value, or defaultValue when no key found.

   */

  public String getString( final String property, final String defaultValue ) {

    assert property != null;

    return mMap.getOrDefault( property, defaultValue );

  }

  /**

   * Returns the value of a string property.

   *

   * @param property     The property key.

   * @param defaultValue The value to return if no property key has been set.

   * @return The property key value, or defaultValue when no key found.

   */

  public int getInt( final String property, final int defaultValue ) {

    assert property != null;

    return parse( mMap.get( property ), defaultValue );

  }

  /**

   * Convert the generic list of property objects into strings.

   *

   * @param property The property value to coerce.

   * @param defaults The values to use should the property be unset.

   * @return The list of properties coerced from objects to strings.

   */

  public List<String> getList(

    final String property, final List<String> defaults ) {

    assert property != null;

    final var value = mMap.get( property );

    return value == null

      ? defaults

      : asList( value.split( VALUE_SEPARATOR ) );

  }

  /**

   * Returns a list of property names that begin with the given prefix.

   * Note that the prefix must be separated from other values with a

   * period.

   *

   * @param prefix The prefix to compare against each property name. When

   *               comparing, the prefix value will have a period appended.

   * @return The list of property names that have the given prefix.

   */

  public Iterator<String> getKeys( final String prefix ) {

    assert prefix != null;

    final var result = new HashMap<String, String>();

    final var prefixDotted = prefix + '.';

    for( final var entry : mMap.entrySet() ) {

      final var key = entry.getKey();

      if( key.startsWith( prefixDotted ) ) {

        final var value = entry.getValue();

        result.put( key, value );

      }

    }

    return result.keySet().iterator();

  }

  private static int parse( final String s, final int defaultValue ) {

    try {

      return s == null || s.isBlank() ? defaultValue : Integer.parseInt( s );

    } catch( final NumberFormatException e ) {

      return defaultValue;

    }

  }

}

import com.keenwrite.processors.markdown.extensions.caret.CaretExtension;

  @SuppressWarnings( "unused" )

  @SuppressWarnings( "unused" )

  private static byte[] compress( final byte[] source ) {

      y += (int) margin.top();

      x += (int) margin.left();

        _ -> fireScrollLockEvent( !mScrollLocked )

import static java.nio.charset.StandardCharsets.UTF_8;

      final var sourcePath = writeString( document, xhtml, UTF_8 );

    final var pdfProcessor = new PdfProcessor( context );

    return createXhtmlProcessor( pdfProcessor, context );

import com.keenwrite.processors.markdown.extensions.captions.CaptionExtension;

import com.keenwrite.processors.markdown.extensions.references.CrossReferenceExtension;

    extensions.add( CrossReferenceExtension.create() );

    extensions.add( CaptionExtension.create() );

import com.keenwrite.processors.markdown.extensions.caret.CaretExtension;

import com.keenwrite.processors.markdown.extensions.images.ImageLinkExtension;

import com.keenwrite.processors.markdown.extensions.outline.DocumentOutlineExtension;

import com.keenwrite.processors.markdown.extensions.tex.TexExtension;

    result.add( TexExtension.create( evaluator, context ) );

/* Copyright 2023 White Magic Software, Ltd. -- All rights reserved.

 *

 * SPDX-License-Identifier: MIT

 */

package com.keenwrite.processors.markdown.extensions.captions;

import com.vladsch.flexmark.html.HtmlWriter;

import com.vladsch.flexmark.parser.InlineParser;

import com.vladsch.flexmark.util.ast.Block;

import com.vladsch.flexmark.util.sequence.BasedSequence;

import org.jetbrains.annotations.NotNull;

/**

 * Responsible for retaining the text node and all child nodes with respect

 * to a caption. The caption can be associated with most items, such as

 * block quotes, tables, math expressions, and images.

 */

class CaptionBlock extends Block {

  private final BasedSequence mCaption;

  CaptionBlock( final BasedSequence caption ) {

    assert caption != null;

    mCaption = caption;

  }

  /**

   * Opens the caption.

   *

   * @param writer Where to write the opening tags.

   */

  void opening( final HtmlWriter writer ) {

    writer.raw( "<span class=\"caption\">" );

  }

  /**

   * Closes the caption.

   *

   * @param writer Where to write the closing tags.

   */

  void closing( final HtmlWriter writer ) {

    writer.raw( "</span>" );

  }

  void parse( final InlineParser inlineParser ) {

    assert inlineParser != null;

    inlineParser.parse( mCaption, this );

  }

  @NotNull

  @Override

  public BasedSequence[] getSegments() {

    return BasedSequence.EMPTY_SEGMENTS;

  }

}

/* Copyright 2023 White Magic Software, Ltd. -- All rights reserved.

 *

 * SPDX-License-Identifier: MIT

 */

package com.keenwrite.processors.markdown.extensions.captions;

import com.vladsch.flexmark.parser.block.AbstractBlockParserFactory;

import com.vladsch.flexmark.parser.block.BlockStart;

import com.vladsch.flexmark.parser.block.MatchedBlockParser;

import com.vladsch.flexmark.parser.block.ParserState;

import com.vladsch.flexmark.util.data.DataHolder;

class CaptionBlockParserFactory extends AbstractBlockParserFactory {

  CaptionBlockParserFactory( final DataHolder options ) {

    super( options );

  }

  @Override

  public BlockStart tryStart(

    final ParserState state,

    final MatchedBlockParser matchedBlockParser ) {

    final var flush = state.getIndent() == 0;

    final var index = state.getNextNonSpaceIndex();

    final var line = state.getLine();

    final var length = line.length();

    final var text = line.subSequence( index, length );

    return flush && CaptionParser.canParse( text )

      ? BlockStart.of( new CaptionParser( text ) ).atIndex( length )

      : BlockStart.none();

  }

}

/* Copyright 2023 White Magic Software, Ltd. -- All rights reserved.

 *

 * SPDX-License-Identifier: MIT

 */

package com.keenwrite.processors.markdown.extensions.captions;

import com.keenwrite.processors.markdown.extensions.common.MarkdownCustomBlockParserFactory;

import com.vladsch.flexmark.parser.block.BlockParserFactory;

import com.vladsch.flexmark.util.data.DataHolder;

class CaptionCustomBlockParserFactory extends MarkdownCustomBlockParserFactory {

  CaptionCustomBlockParserFactory() {}

  @Override

  public BlockParserFactory createBlockParserFactory(

    final DataHolder options ) {

    return new CaptionBlockParserFactory( options );

  }

}

/* Copyright 2023 White Magic Software, Ltd. -- All rights reserved.

 *

 * SPDX-License-Identifier: MIT

 */

package com.keenwrite.processors.markdown.extensions.captions;

import com.keenwrite.processors.markdown.extensions.common.MarkdownRendererExtension;

import com.vladsch.flexmark.html.renderer.NodeRendererFactory;

import com.vladsch.flexmark.parser.Parser.Builder;

/**

 * Responsible for parsing and rendering {@link CaptionBlock} instances.

 */

public final class CaptionExtension extends MarkdownRendererExtension {

  /**

   * Use {@link #create()}.

   */

  private CaptionExtension() {}

  /**

   * Returns a new {@link CaptionExtension}.

   *

   * @return An extension capable of parsing caption syntax.

   */

  public static CaptionExtension create() {

    return new CaptionExtension();

  }

  @Override

  public void extend( final Builder builder ) {

    builder.customBlockParserFactory( new CaptionCustomBlockParserFactory() );

    builder.postProcessorFactory( new CaptionPostProcessorFactory() );

  }

  @Override

  protected NodeRendererFactory createNodeRendererFactory() {

    return new CaptionNodeRendererFactory();

  }

}

/* Copyright 2023 White Magic Software, Ltd. -- All rights reserved.

 *

 * SPDX-License-Identifier: MIT

 */

package com.keenwrite.processors.markdown.extensions.captions;

import com.keenwrite.processors.markdown.extensions.references.CrossReferenceNode;

import com.vladsch.flexmark.html.HtmlWriter;

import com.vladsch.flexmark.html.renderer.CoreNodeRenderer;

import com.vladsch.flexmark.html.renderer.NodeRendererContext;

import com.vladsch.flexmark.html.renderer.NodeRenderingHandler;

import com.vladsch.flexmark.util.ast.Node;

import com.vladsch.flexmark.util.data.DataHolder;

import java.util.HashSet;

import java.util.LinkedList;

import java.util.List;

import java.util.Set;

/**

 * Responsible for rendering {@link CaptionBlock} instances as HTML (via

 * delegation).

 */

class CaptionNodeRenderer extends CoreNodeRenderer {

  CaptionNodeRenderer( final DataHolder options ) {

    super( options );

  }

  @Override

  public Set<NodeRenderingHandler<?>> getNodeRenderingHandlers() {

    return new HashSet<>( List.of(

      new NodeRenderingHandler<>( CaptionBlock.class, this::render )

    ) );

  }

  private void render(

    final CaptionBlock node,

    final NodeRendererContext context,

    final HtmlWriter html ) {

    final var anchors = new LinkedList<Node>();

    html.raw( "<p>" );

    node.opening( html );

    if( node.hasChildren() ) {

      for( final var child : node.getChildren() ) {

        if( !child.isOrDescendantOfType( CrossReferenceNode.class ) ) {

          context.render( child );

        }

        else {

          anchors.add( child );

        }

      }

    }

    node.closing( html );

    for( final var anchor : anchors ) {

      context.render( anchor );

    }

    html.raw( "</p>" );

  }

}

/* Copyright 2023 White Magic Software, Ltd. -- All rights reserved.

 *

 * SPDX-License-Identifier: MIT

 */

package com.keenwrite.processors.markdown.extensions.captions;

import com.keenwrite.processors.markdown.extensions.common.MarkdownNodeRendererFactory;

import com.vladsch.flexmark.html.renderer.NodeRenderer;

import com.vladsch.flexmark.util.data.DataHolder;

class CaptionNodeRendererFactory extends MarkdownNodeRendererFactory {

  @Override

  protected NodeRenderer createNodeRenderer( final DataHolder options ) {

    return new CaptionNodeRenderer( options );

  }

}

package com.keenwrite.processors.markdown.extensions.captions;

import com.vladsch.flexmark.parser.InlineParser;

import com.vladsch.flexmark.parser.block.AbstractBlockParser;

import com.vladsch.flexmark.parser.block.BlockContinue;

import com.vladsch.flexmark.parser.block.ParserState;

import com.vladsch.flexmark.util.ast.Block;

import com.vladsch.flexmark.util.sequence.BasedSequence;

class CaptionParser extends AbstractBlockParser {

  private final CaptionBlock mBlock;

  CaptionParser( final BasedSequence text ) {

    assert text != null;

    assert text.isNotEmpty();

    assert text.length() > 2;

    final var caption = text.subSequence( 2 );

    mBlock = new CaptionBlock( caption.trim() );

  }

  static boolean canParse( final BasedSequence text ) {

    return text.length() > 3 &&

           text.charAt( 0 ) == ':' &&

           text.charAt( 1 ) == ':' &&

           text.charAt( 2 ) != ':';

  }

  @Override

  public Block getBlock() {

    return mBlock;

  }

  @Override

  public BlockContinue tryContinue( final ParserState state ) {

    return BlockContinue.none();

  }

  @Override

  public void parseInlines( final InlineParser inlineParser ) {

    assert inlineParser != null;

    mBlock.parse( inlineParser );

  }

  @Override

  public void closeBlock( final ParserState state ) {}

}

/* Copyright 2023 White Magic Software, Ltd. -- All rights reserved.

 *

 * SPDX-License-Identifier: MIT

 */

package com.keenwrite.processors.markdown.extensions.captions;

import com.keenwrite.processors.markdown.extensions.fences.ClosingDivBlock;

import com.keenwrite.processors.markdown.extensions.fences.OpeningDivBlock;

import com.vladsch.flexmark.parser.block.NodePostProcessor;

import com.vladsch.flexmark.util.ast.Node;

import com.vladsch.flexmark.util.ast.NodeTracker;

import org.jetbrains.annotations.NotNull;

/**

 * Captions are written most naturally <em>after</em>> the element that they

 * apply to, regardless of whether they are figures, tables, code listings,

 * algorithms, or equations. The typesetting software uses event-based parsing

 * of XML elements, meaning the DOM isn't fully loaded into memory. This means

 * that captions must come <em>before</em> the item being captioned.

 * <p>

 * To reconcile this UX conundrum, we swap captions with the previous node.

 */

class CaptionPostProcessor extends NodePostProcessor {

  @Override

  public void process(

    @NotNull final NodeTracker state,

    @NotNull final Node caption ) {

    var previous = caption.getPrevious();

    if( previous != null ) {

      swap( previous, caption );

    }

  }

  private void swap( final Node previous, final Node caption ) {

    assert previous != null;

    assert caption != null;

    var swap = previous;

    boolean found = true;

    if( swap.isOrDescendantOfType( ClosingDivBlock.class ) ) {

      found = false;

      while( !found && swap != null ) {

        if( swap.isOrDescendantOfType( OpeningDivBlock.class ) ) {

          found = true;

        }

        else {

          swap = swap.getPrevious();

        }

      }

    }

    if( found ) {