Formatting Markdown Notes and managing images in Octave scripts

The Notes of GX-TXT Octave Script Workspace let you build a scientific document next to the GNU Octave source: headings, formatted text, lists, tables and images can be organized and kept as an associated note. In this chapter we see how to use the formatting commands, recognize the managed PNG resources and verify an actual save.

The command labels are those of the English interface of GX-TXT DEV112 with patch P005, Octave Script Workspace 1.8.3. Only synthetic values are used. Editing the Notes does not run the script and does not create a calculation Job.

1. Preparing the Octave Source

Open a script already registered in the Workspace. For an introductory example, a source containing two numerical vectors is enough:

% Synthetic voltage measurements in volts.
time_s = [0, 1, 2, 3, 4];
voltage_V = [0, 0.2, 0.4, 0.8, 1.0];

Save the code with File → Save before adding the documentation. The Source tab is distinct from the Notes tab.

Octave Script Workspace with a saved GNU Octave script containing two synthetic numerical vectors in the Source editor.
Figure 1 — An Octave script saved in the Workspace, before working on its documentation.

2. Writing a note and telling Source from Preview

With the script tab selected, open Edit → Edit Notes. In the new — Notes tab, the dark box is the editable Markdown text; Preview shows the formatted reading view.

GX-TXT Notes showing Markdown Source on the left and the formatted scientific document preview on the right.
Figure 2 — The Markdown text and the preview of the scientific note side by side.

Markdown syntax can be typed directly. For example, **voltage_V** gives bold text, while ## Measurements introduces a heading. The contents are documentation: no line of the note is interpreted as an Octave instruction.

3. Using Edit → Note format

Select an expression in the Notes editor, then open Edit → Note format. The menu contains Heading with levels 1–3, Bold, Italic, Inline code and other formatting tools. The change is applied to the actual Markdown, not just to the appearance of the Preview.

GX-TXT Notes editor showing Heading, Bold, Italic and Inline code formatting applied to Markdown content.
Figure 3 — Heading, Bold, Italic and Inline code applied to the content of the note with the native commands.

For example:

### Dataset review

A saved *Octave* script contains **five synthetic voltage samples**.
The Notes do not submit a `Run Job`.

Inline code is meant for names of variables, functions and commands; it is not the same as running the marked text.

4. Adding structure with lists, quotes and tables

Note format also offers Bullet list, Numbered list, Insert quote, Insert table, Code block, Insert link and Insert rule. These operations introduce a Markdown structure to be completed with the scientific content you need.

GX-TXT Notes Markdown document containing a table, a quotation and a list displayed in the editor.
Figure 4 — An example with a Markdown table, a quote and a list inserted in the Notes tab.

The table inserted by the command is initially a template with generic headers and values. Replace the placeholders with the names of the quantities, values and units; check how it actually appears in the Preview before considering it ready for publication.

5. Inserting a PNG image into the note

Images are not just arbitrary links to files on disk: the document uses managed resources, identified by a logical name. When an image is added, the Markdown receives a reference like:

![Synthetic voltage plot](assets/o13_voltage_curve.png)
Markdown Notes showing an embedded PNG of a synthetic voltage plot rendered in the document preview.
Figure 5 — An example PNG inserted in the Notes and displayed in the Markdown preview.

The plot shown is a synthetic illustration prepared for the note, not the output of running the Octave script shown at the beginning. Its title, origin, units and any processing should be made clear in the text of the documentation.

6. Examining Resources and the image data

Select View → Note panes and zoom → Resources. The panel lists the resources of the note: name, size in bytes and dimensions in pixels. Selecting an entry shows the logical path assets/..., the SHA-256 and the format.

GX-TXT Resources panel with a selected PNG image showing its logical name, dimensions, format and SHA-256 hash.
Figure 6 — The Resources panel shows the selected managed image, its metadata and the related controls.

This information serves to distinguish the reference written in the Markdown from the binary PNG content that the Preview must be able to load. The logical name must remain consistent with the one used in the document.

7. Replacing an image while keeping the reference

Replace image lets you replace the content of an existing resource. When the same logical name is reused, the Markdown reference does not need to change: it is the PNG content, with its SHA-256, that is updated.

GX-TXT Notes after Replace image, showing an updated PNG resource while preserving the original Markdown reference.
Figure 7 — Replacing the resource updates the image while keeping the same reference in the text.

The Edit → Note images menu offers Insert image…, Replace image… and Remove image. These are the main operations for working on resources without confusing them with editing the text.

GX-TXT Octave Edit → Note images menu showing Insert image, Replace image and Remove image commands.
Figure 8 — The three native operations of the Note images menu, opened over the saved note.

8. Removal, missing references and restoring

Remove image deletes the selected resource from the managed set, but does not automatically delete the Markdown line that refers to it. A reference left without an image may produce the Image unavailable indication in the Preview. Before saving, therefore, check that there are no links to removed resources.

You can reinsert the PNG and restore the same logical name, then check that the Markdown contains only one line referring to the intended image.

Markdown Notes editor after restoring a PNG image and its valid resource reference in the document.
Figure 9 — After the resource is restored, the note again has a valid PNG reference.

Images must be regular PNG files; the manager checks the format, dimensions and resource limits. A file that does not pass these checks must not be considered a valid resource.

9. Saving a note linked to the source

The note can contain text and images without yet being published as a persistent document. Before saving, check that the Octave source is registered in the correct Session. If the source or the association is updated while a draft is open, the application may refuse a save based on an earlier revision: it does not silently overwrite a more recent version. Keep the draft, reopen the current note and review the changes.

GX-TXT Notes showing Markdown text and a PNG resource associated with the current Octave source revision.
Figure 10 — Markdown and PNG associated with the current source before the final save.

Use File → Save with the Notes tab active. The result can be checked from View → Note panes and zoom → Properties: it shows the identity of the Canonical Dataset, the producer of the document, the association with the source and the state Unsaved changes: 0.

Notes Properties panel displaying the Canonical Dataset, source association and Unsaved changes: 0 status.
Figure 11 — Properties confirms the canonical Dataset of the note, the current association and the absence of unsaved changes.

The note Dataset contains Markdown and resources; it is not the .m script and does not represent the result of a numerical Job.

10. Reopening the note and going back to the code

The most important check after saving is to close and reopen the Notes tab of the same source, checking that both the full text and the PNG reappear in the preview.

Markdown Notes reopened after saving, showing the restored text and PNG image in the document preview.
Figure 12 — The note reloaded from the canonical Dataset again shows the Markdown and the associated image.

With View → Show Notes you can hide the documentation tab and return to the normal Octave editor surface, without altering the source.

Octave Script Workspace showing the GNU Octave Source editor again, separate from the saved Markdown documentation.
Figure 13 — Back in the Octave Source, the code is still available and separate from the saved documentation.
OperationWhat changes
Note formatThe Markdown text of the note.
Note images → Insert / Replace / RemoveThe set of managed PNG resources and, when inserting, the Markdown reference.
File → Save in the Notes tabThe associated document, with its resources, in the active Session.
PropertiesShows the identity and save state of the document.
Show NotesThe visibility of the documentation tab, not the executable code.

The recommended practice is to review the Preview, check Resources, save and reopen the note. This way the script documentation remains verifiable, while the code editor can stay essential and readable.