Appendix53Appendix S: NanoRC syntax format

Main NanoRC file

A top-level NanoRC file may contain general editor configuration commands as well as syntax-highlighting definitions. In the build environment's shipped configuration, the early part of the main file sets editor options such as autoindent, tabsize, and tabstospaces, and the later part imports the syntax library.

The common structural pattern is:

set option value

set another-option

include "/path/to/default.nanorc"

include "/path/to/language.nanorc"

Within this manual, the syntax-format focus is on the directives which affect syntax selection and colouring. The broader editor configuration vocabulary is part of Nano itself rather than a build-environment-specific extension.

Include organisation

The main syntax library is split into separate files by language or format. The top-level nanorc file includes these in groups such as presentation formats, programming languages, shell syntaxes, data-storage formats, source-control files, and RISC OS-specific file types.

That split matters for maintenance because syntax rules are processed in the order the files are included. Later rules may therefore recolour text which an earlier file already matched.

Directive set used in this environment

The directives most relevant to syntax-highlighting files are:

Syntax selection

Each syntax line creates one named syntax definition. The optional file regular expressions attached to that line are used to match candidate filenames or paths. For example, the shipped Markdown syntax matches .md and .markdown, while the shipped Makefile syntax also matches directory and special-name forms such as Makefile,fe1.

If file-pattern matching is not enough, one or more header rules may be attached to the current syntax. These are tested against the first line of the file, which makes them useful for shebang-based detection and other first-line markers. The shipped Python syntax, for example, attaches this rule so that a script is recognised even without a .py extension:

syntax python "\.py$"

header "^#!.*/(env +)?python[-0-9._]*( |$)"

That pattern matches both a direct shebang such as #!/usr/bin/python3 and an env-wrapped one such as #!/usr/bin/env python3.

The local nano-colour helper follows exactly this two-stage strategy when it tries to identify a syntax automatically.

To check which syntax was actually selected for a given file, run nano-colour --supported <file> <nanorc_dir>. This prints the selected syntax's name and exits successfully if one was found, or exits with a failure status and no output if neither the filename nor header rules matched anything.

Regular-expression details

The file-matching and colouring rules are written as regular expressions inside quoted strings. The shipped syntax files use ordinary regex forms such as anchors, groups, alternation, and character classes.

The build environment's nano-colour support also recognises Nano's word-boundary escapes \< and \> and translates them to the corresponding Perl word boundary expressions before matching.

Colour names

The shipped NanoRC comments and syntax files use the conventional Nano colour names:

• foreground and background colours: black, red, green, yellow, blue, magenta, cyan, white, and normal;
• stronger foreground variants using the bright prefix, such as brightwhite or brightred;
• a foreground-only form, or a foreground-and-background form separated by a comma.

The main NanoRC comments also note that omitting a background colour allows a transparent background where the terminal supports it.

Rule ordering

Colour rules are applied in source order. This means that the effective result is not just a property of one line in isolation: a later color or icolor rule may replace colouring previously applied to overlapping text.

That ordering rule applies across included files as well as within one file, so the sequence of include directives is part of the format's practical behaviour.

Multi-line regions

Range colouring is written using the start="..." end="..." form on a color line. This is commonly used for strings, block comments, or other constructs which may span more than one line.

The highlighter applies the colour from the start match through the matching end expression, inclusive.

Installed syntax families

The default syntax set supplied by the build environment includes definitions for:

• general text and configuration forms such as NanoRC, HTML, Markdown, YAML, XML, JSON, Graphviz, and Jinja2;
• programming languages such as C, Perl, PHP, Python, Groovy, Fortran, Lua, Terraform, Go, JavaScript, and Pascal;
• shell and source-control files such as Bourne shell, Fish, Git commit messages, Git rebase todos, Git tag messages, and CODEOWNERS;
• RISC OS-specific forms such as ARM assembly, BBC BASIC, JFPatch, CMHG, and Obey files.

This is the syntax library used both by Nano itself and by nano-colour when the default environment configuration is supplied as its syntax source.

Maintenance notes

The syntax files live under crosscompile/nano/ in the repository and are copied into the built image as Nano resource files. Changes to those files therefore affect both editor highlighting and any tool which reuses the same syntax definitions for terminal output.

When documenting a new syntax file, it is useful to record both its filename patterns and any header-based detection rules, because those determine whether nano-colour can select it automatically.

Minimal syntax file

This is the smallest useful pattern for a dedicated syntax file.

syntax "example" "\.example$"

comment "#"

color green "^#.*$"

color yellow "\<[[:alnum:]_]+\>"

Top-level include file

This is the common structure used to assemble a syntax library from separate files.

set autoindent

set tabsize 4

include "/riscos-resources/nano/gerph/default.nanorc"

include "/riscos-resources/nano/gerph/nanorc.nanorc"

include "/riscos-resources/nano/gerph/markdown.nanorc"