Documenting Octave scripts with Markdown Notes

In Octave Script Workspace you can attach Markdown Notes to a GNU Octave script: a text document explaining the purpose of the experiment, the units, the assumptions and the meaning of the variables. Notes are read and edited in an editor separate from the code editor.

The screenshots refer to GX-TXT DEV112 with patch P005, Octave Script Workspace module 1.8.3. Interface commands are given in English. The example uses synthetic data; viewing or editing a note does not run the Octave script.

1. Starting from a registered script

To attach notes to a source, you first need a script registered in GX-TXT. Open Octave Scripts, create or select a script and check Scope, Script ID and Name. If the source is still new, register it with File → Save.

Octave Script Workspace showing a registered GNU Octave script and source code before opening Notes.
Figure 1 — Octave script registered in the Workspace, before the notes are opened.

Our example uses two vectors describing synthetic measurements:

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

The code remains the executable content of the script. The Notes do not become instructions and do not change the meaning of the vectors.

2. Opening Edit Notes

Select the tab of the desired source and then Edit → Edit Notes. Another tab opens, recognizable by the — Notes suffix. At first the document is empty: the Markdown Source appears on the left and the Preview on the right.

Newly opened GX-TXT Octave Notes editor with empty Markdown Source on the left and Preview on the right.
Figure 2 — Notes tab just opened, with an empty Markdown editor and the preview area.

The new tab is associated with the selected source. To continue writing there is no need to close the code or open a second Workspace.

3. Writing Markdown and watching the preview

In the editor on the left you write ordinary Markdown. The # character introduces a main heading, ## a subheading, - a list item, while **text** makes text bold.

For example:

# Notes on a synthetic voltage study

## Purpose

Explain the meaning of **voltage_V** without executing it.

## Measurements

- Time: seconds
- Voltage: volts
- Source: synthetic teaching example

The preview on the right interprets the text, showing headings, bold text, paragraphs and lists.

Notes editor showing Markdown headings, paragraphs and lists alongside their formatted preview.
Figure 3 — Markdown Source with headings, text and lists next to its formatted preview.

The formatted view is a reading aid: what you edit is the Markdown Source. No Octave commands or mathematical functions are run through the preview.

4. Giving the whole window to the preview

In the View → Note panes and zoom menu, turn off Source while leaving Rendered preview on. The preview takes up the available area and lets you reread the document without the raw Markdown text.

Markdown Notes in Rendered preview mode, showing the formatted document without the Source pane.
Figure 4 — Rendered preview view on its own, useful for rereading the notes as a document.

To return to the side-by-side layout, simply turn Source back on in the same menu.

5. Writing with the Markdown Source only

You can also do the opposite: turn off Rendered preview while keeping Source. This way the editor space is reserved for the text to be edited.

Notes editor showing only the Markdown Source pane with Rendered preview hidden.
Figure 5 — Source view on its own, suitable for writing and reviewing Markdown.

This is a practical mode for documents with many lines, lists or code fragments. Turning Rendered preview back on brings the preview back without losing the text.

6. Navigating with Outline

The View → Note panes and zoom → Outline command shows the index of the headings in the Markdown. The editor recognizes # and ## level headings and lists them in a tree.

Notes Outline panel showing the hierarchical structure of Markdown document headings.
Figure 6 — Outline shows the structure of the document derived from the Markdown headings.

Select an entry, for example Interpretation, to bring the cursor to the beginning of the corresponding line of the Markdown Source.

Notes Outline with Interpretation selected and the corresponding heading located in Markdown Source.
Figure 7 — Selecting Interpretation in the Outline leads to the corresponding heading in the text.

This function is for navigation: it does not add new headings and does not change the content of the script or of the notes.

7. Looking at Properties and Resources

Also from the Note panes and zoom menu you can show two more sections.

Properties shows information about the document and its save state, including the canonical Dataset, the association with the source and whether there are changes not yet saved.

Notes Properties panel showing document information, unpublished status and Unsaved changes.
Figure 8 — Properties panel with the document not yet published and the Unsaved changes state.

Resources shows the resources of the document, in particular the associated images, with columns for name, size in bytes and dimensions in pixels.

Notes Resources panel with an empty associated-image list and resource management controls.
Figure 9 — Resources panel, still without images, with the resource management tools.

In our example no images were added, so the list is empty. Inserting, replacing and removing resources require a separate workflow, with checks on associations and contents.

8. Hiding and reopening the notes with Show Notes

When you want to go back to the code, open View → Show Notes and turn the entry off. The Notes tab is hidden and the Octave tab becomes available again.

Octave Script Workspace after disabling Show Notes, with the GNU Octave code tab visible again.
Figure 10 — After hiding Notes, the Octave Source is visible again in the Workspace.

Turning Show Notes back on, the same tab reappears with the Markdown you were editing.

Notes tab reopened using Show Notes, with the previously entered Markdown content still available.
Figure 11 — Show Notes reopens the same Markdown draft, without deleting the content being written.

Hiding the tab is not the same as saving it. As long as the document contains unregistered changes, you need to keep the draft deliberately and not confuse this operation with closing it for good.

9. Zoom and layout reset

The View → Note panes and zoom menu includes Zoom in, Zoom out, Reset zoom and Reset note layout. The first two commands change the reading size in the editor and in the preview.

Notes editor showing enlarged Markdown text and preview after using Zoom in.
Figure 12 — The same note displayed with Zoom in, to read the document more comfortably.

Reset zoom restores the initial factor. Reset note layout restores the ordinary layout with Markdown Source and Rendered preview side by side, without changing the lines written.

GX-TXT Notes editor after Reset zoom and Reset note layout, with Markdown Source and Rendered preview side by side again.
Figure 13 — Notes view after resetting the zoom and the standard layout.

10. Telling apart code, draft and registered note

ElementFunction
Octave SourceContains the script instructions.
Notes — SourceContains the Markdown text of the documentation.
Rendered previewShows a formatted representation of the Markdown.
OutlineLets you reach the headings of the document.
PropertiesShows the identity, association and state of the document.
ResourcesLists the associated images and resources.
Show NotesHides or shows the tab, keeping the work in progress in the editor.

The Notes are associated with the identity of the source, but the permanent registration of the document is separate from that of the code. In this procedure we worked on an unpublished draft: the Properties panel does not yet show a canonical Dataset.

When you want to keep them beyond the editing session, you need to use the explicit note save workflow and check the intended association. Managing revisions, images and publishing the document is covered separately.

Notes therefore let you keep explanations and scientific context next to the script, without putting extensive documentation in the executable code and without having to open unnecessary panels while programming.