mapter

Update information

• v0.6 - Addition of spell checker, search and undo/redo

Introduction

mapter is a free tool to assist with planning a piece of writing using the book architecture method. There's an alternative description here

There are many, many writing tools already available but very few that support this sort of grid approach. Of the ones that I found they all had some drawbacks:

• Not available for Linux, e.g. Scrivener
• Had lots of features that I didn't want, e.g. bibisco
• Online only or use web technologies which I didn't want, e.g. Wavemaker

It is not my intention to add word processing features like text markup, grammar checking etc. This is designed as a no-distractions planning and writing tool. However tools like Markdown or LaTeX could be used to format and typeset the export if necessary.

( The name comes from a portmanteau of "mapping" and "chapter" and was created using an online name generator )

Current Status

The current version is a basic minimum viable product ( MVP ) which allows the creation and editing of a full work.

Building

mapter uses the GTK+ 3 library and can be built by simply typing make in the top level directory. Note that the build files and general structure follow that suggested in the rather good set of tutorials at https://prognotes.net/gtk-glade-c-programming/. That page also provides some useful hints as to which GTK related packages are needed for the build to succeed.

The GUI definition is done largely using Glade but some parts are built dynamically within the code.

It's possible to show some debugging information by setting the GTK debug level:

G_MESSAGES_DEBUG=all ./mapter

Operation

Note that the screenshots use the ww1-1916.mapter file from the examples directory.

Command line options

Main Window

Grid tab

The grid tab has four main sections as described below. Double click on any of the cells to edit.

1. The cell at 0,0 doesn't really form part of the grid but is used here to store an optional title for the work ( see Export below ).
2. The column headings are used to describe the series or themes that flow through the work.
3. The row headings are used to define the chapter headings
4. The rest of the grid is for each of the sections mapping the theme/series to the chapter.
5. The currently selected cell is shown with a highlight. The selection can be moved with the arrow keys or by clicking with the mouse. ( "Home", "End", shift up-arrow and shift down-arrow also work ). Hitting Return will bring up the editor for the selected cell.
6. The "Chapter" and "Series" of the selected cell are shown at the bottom. This makes navigation easier when the row and column headers are scrolled off the screen.
7. The background colour of each cell can be changed by right clicking on the cell and selecting the colour. Currently the options are:
   • Clear - no background
   • High - red background
   • Medium - yellow background
   • Low - green background
   • Neutral - blue background

Notes tab

The notes tab is a simple free format text window with a hierarchical tree control. The tree structure can be edited by dragging the elements and by the buttons at the bottom. Text is saved automatically when the tree view changes.

Edit Window

Double clicking on any of the cells or pressing Return on the highlighted cell brings up the edit window:

This has three sections:

1. Text that appears on the front grid
2. Header text for that section in the document export
3. Body text for that section in the document export

Words that fail the automated spell check will be underlined in red. Right clicking on one of these words will present a list of alternatives. Undo/redo ( Ctrl Z / Ctrl-Shift Z ) is also now available in all three text editing sections. The search facility only operates on the "Body" section.

Changing the size of the grid

Important note: at the moment there is no confirmation of any changes and no undo.

Right clicking on any of the cells shows a popup menu with insert/delete commands which can be used to change the size of the grid.

File Loading and Saving

The usual file open, save, save as, new commands can be found under the "File" menu.

File Export

File export is similar to save but exports the data in a more structured way. There are some export options:

Some tools use two consecutive carriage returns as a paragraph marker. However it's sometimes more convenient and a nicer layout in the mapter section editor to write text using just one carriage return. The first option adds an extra carriage return into the export.

The last option specifies whether extra data is added to each line, e.g.

unticked:

February
  The battle of Verdun begins
  Trebizond Campaign.
  Battle of Salaita Hill.

ticked:

February
  Western Front - The battle of Verdun begins
  Caucasian Front - Trebizond Campaign.
  African Theatre - Battle of Salaita Hill.

The included Markdown and LaTeX examples give an idea as to how the output may be typeset. The LaTeX example can be built using the following commands:

Export the document from mapter with a .tex extension
pdflatex export.tex
pdflatex export.tex

Run the second command twice to create the table of contents properly

File formats

mapter File

The .mapter file is a JSON file whose structure is pretty self-explanatory.

Export file

The export file is a simple text format.

Debugging

Trace and debugging information can be show on the standard output by using the following command line:

G_MESSAGES_DEBUG=all ./mapter

Future Developments

Future planned developments include:

• A method of moving or swapping the contents of cells without a lot of cutting & pasting