• ArgView: Argument Maps in YAML
  • Installation
    • Dependencies
  • Getting Started
  • How to represent Argument Maps in YAML
    • Markdown Formatting
    • Unique Identifiers
    • Empty Lists
    • Keys and Quotation
    • Notes, Labels, and Strength
  • argmap2mup.lua
  • mup2argmap.lua
  • argmap2tikz.lua
  • pandoc-argmap.lua
    • Default Google Folder
    • Embedding Maps in Markdown
    • Converting Maps Embedded in Markdown
    • HTML5 Output
    • Displaying Argmaps with mapjs
    • Uploading Maps to Google Drive
    • Generating PDFs
    • LaTeX and PDF output
    • Output in All Other Formats
  • Generating Interactive Argument Maps mapjs
    • Installing mapjs
    • Creating html pages containing mapjs with Pandoc
    • Using mapjs in your own projects
  • Troubleshooting
  • License
  • Contributing
  • Relationships to Other Projects

See CHANGELOG.md for change notes.

This has been tested on Debian only. I believe the Lua code should be portable, but I'm not familiar enough with Lua to know for sure. Some of the supporting code e.g. makefile and contents of /scripts may work on other Linux distros or even MacOS, but will not work on Windows.

1. Set env variable PATH_ARGMAP_ROOT to app installation root folder.

2. If you wish, customise the values in the environment-[X]-default.yaml files in config and mapjs/config folder, removing -default from the filenames.

3. You can place argmap2mup.lua, argmap2tikz.lua, and mup2argmap.lua somewhere in your PATH e.g. ~/bin.

   Or you leave them in place and put symbolic links to them into your PATH, as has been done in makefile. This script also removes the .lua extension from the links to reduce command line typing, however the examples below keep the .lua extension for clarity.

4. Place pandoc-argmap.lua in the filters folder inside your pandoc data directory, e.g. $HOME/.local/share/pandoc/filters/pandoc-argmap.lua (The makefile also sets up this symlink).

5. For additional functionality, see Dependencies section.

Note that makefile does not yet do a full install of argview, some of the install is in the form of notes and useful commands. However, it does do enough to install it to netlify (when combined with netlify.toml) to provide maps online. The symlink generation and cleanup has been moved to the makefile which can be run with make all.

Tested with:

• Lua 5.3.4
• LuaRocks 3.7.0
• Pandoc 2.9.2.1-0; 2.6

argmap2mup.lua, argmap2tikz.lua, and mup2argmap.lua require:

• penlight (for command line option parsing)
• lyaml (for parsing YAML)
• json (for encoding JSON)
• LuaLogging: A simple API to use logging features in Lua.

1. To install these dependencies, you can use the included rockspec file. Navigate to the package directory and run luarocks make --only-deps argmap-[version number].rockspec depending on latest version.

2. For lyaml, you may need to install libyaml-dev or yaml (conda).

3. argmap2mup.lua and mup2argmap.lua also depend on the command line utility gdrive for Google Drive integration. Follow the link for installation instructions. (Note that on linux the 386 version is more likely to work: see prasmussen/gdrive#597).

4. Converting the tikz code generated by argmap2tikz.lua to PDF requires several TeX packages, some of which you may need to install if they are not already available on your system. e.g. texlive-latex-extra and texlive-luatex from apt-get.

5. pandoc-argmap.lua depends on Pandoc(tested with v2.9.2.1 and v2.6), and on argmap2lua and argmap2tikz.lua. It also depends on pdf2svg for conversion to svg, and ImageMagick's convert for conversion to png.

6. To display MindMup JSON files on a web page as an interactive mindmap, without using the MindMup website, see Installing mapjs.

7. The various scripts and the mapjs code also rely on yaml configuration files, some parts of which need to be processed to expand config variables. This processing requires both pandoc and the yq binary mikefarah/yq: yq is a portable command-line YAML, JSON, XML, CSV and properties processor, and is carried out by running the scripts/init_read_config.sh bash script.

Files with config in the name should be left as is, as these can change without warning in new releases.

However, you should make copies of the various environment-default files and remove -default from the name. You can then customise aspects of the app and these should be reflected in the rest of the app.

See config/environment-conda-argmap.yaml for conda environment export of non-lua dependencies and version numbers.

Each claim key is processed by Pandoc. This means that you should be able to get away with using simple markdown inside the claim keys.

"Brunellus is *probably* 90% H~2~O":

Keep in mind that MindMup offers very limited support for formatted text. So, for MindMup maps, formatting will be converted to Pandoc's "plain" output:

Brunellus is _probably_ 90% H₂O

For TikZ maps, formatting will be converted to latex:

Brunellus is \emph{probably} 90\% H\textsubscript{2}O

Note that the reasons for a given claim cannot share the same identifier.

Something like this will lead to unpredictable behaviour:

"Brunellus is irrational":
  reason: {}
  reason: {}

The resulting map will only display a single reason, and which one it will choose in unpredictable.

Instead, you need to ensure that the keys are distinct:

"Brunellus is irrational.":
  reason1: {}
  reason2: {}

Reasons for distinct claims can have the same identifier. So this is okay:

"Brunellus is a donkey.": 
  reason1: {}
"All donkeys are irrational.":
  reason1: {}

The same holds for claims: each of the claims that make up a given reason must have distinct keys. So don't write something like this:

"Brunellus is irrational":
  r1:
    "Brunellus is a donkey.": {}
    "Brunellus is a donkey.": {}

Since the key is the content of the claim, this restriction makes sense: you would not want to represent the same premise twice as part of a single reason. But, of course, the same premise can occur as part of two distinct reasons:

"Brunellus is irrational":
  r1:
    "Brunellus is a donkey.": {}
    "All donkeys are irrational.": {}
  r2:
    "Brunellus is a donkey.": {}
    "Most donkeys I've met have been irrational.": {}

Note that every claim is represented as key-value pair, where the value is a list of reasons. If there are no reasons offered for or against a claim, that means that the value is an empty list. You can represent this empty list explicitly if you like:

    "Brunellus is a donkey.": {}

Or you can leave it implicit, omitting the '{}'. But you still must put the colon (':') after the claim:

    "Brunellus is a donkey.": 

In practice, the implicit empty list notation is preferred, because it means you don't have to delete the braces before adding reasons in support of a claim.

YAML allows just about any string to be a key, but you do have to be careful about quotes and line-wrapping. If your key has no special characters, like ':', you get away with omitting the quotes:

    Brunellus is a donkey.: 

Multiline keys are also possible, but the format is a bit complicated (1, 2)

?
 "Brunellus is a donkey who wanted a longer tail, and he went to Paris
 to study, but he couldn't remember the city's name."
:
  r1:
    ?
     "The wikipedia says that Brunellus is a donkey who wanted a longer
     tail, and he went to Paris to study, but he couldn't remember the
     city's name."
    :
    ?
     "The wikipedia is a reliable source for information about donkeys
     in medieval literature."
    :

(Currently, notes are only supported for MindMup input and output, and do not appear in TikZ output.)

You can attach one note to any claim (if you attach more than one note, only one of them will be processed). A note is represented by a key-value pair, where the key is the string "note" and the value is the content of the note. To attach a note to a claim, add it to the list of reasons:

Brunellus is irrational:
  r1:
    Brunellus is a donkey.: 
      note: |
        Brunellus means "brown one" in Latin, and was the name of a stock character in medieval logic texts.
    All donkeys are irrational.: 
  note: |
    Although donkeys *are* notoriously stubborn, it seems a bit much to suppose that irrationality is the defining feature of a donkey.

Notes are also processed by Pandoc, allowing the use of simple markdown.

You can attach a label or strength to any reason. A label is a key-value pair, where the key is the string "label" and the value is the content of the label. A strength is a key-value pair, where the key is "strength" and the value is a number between 1 (weak) and 5 (strong). Labels and strengths are added to the list of a reason's claims:

Brunellus is irrational:
  r1:
    Brunellus is a donkey.: 
    All donkeys are irrational.:
    label: argumentum ad asinum
    strength: 4
  o1:                                            
    Brunellus studied in Paris.: 
    -Most who study in Paris are rational.:
    label: argumentum ad parisiensis
    strength: 2

pandoc-argmap.lua is a Pandoc Lua filter for converting YAML argument maps embedded in a Pandoc document, using argmap2mup.lua and argmap2tikz.lua.

If you're not familiar with Pandoc, see the official: Pandoc - Getting started with pandoc.

I put a line like this at the top of my personal copy of pandoc-argmap.lua:

local gdriveFolder = "11w-foIj3p_FWSUROEX0VJg1KsslhJR0m"

This tells Pandoc to upload all the maps it generates to a specific folder on my Google Drive.

Embedded argument maps are represented as code blocks with the class argmap.

    ``` {.argmap}
    "Brunellus is irrational":
      r1:
        "Brunellus is a donkey.":
        "All donkeys are irrational.":
      o1:
        "Brunellus studied in Paris.":
        "-Most who study in Paris are rational.":
    ```

As per Pandoc's markdown format for Fenced code blocks, you can use:

• # for an id
• . for classes
• attribute="value" for assigning values.

If you want your argmap to be converted into mapjs format, then add the attribute to="js". See section Generating mapjs Interactive Argument Maps for more details.

A name and Google Drive ID can also be specified as attributes of the code block:

    ``` {.argmap name="A Donkey Argument" gid="1X6uD8KyrSawW2qSqhmPaNtuSy-6eEK6g"}
    "Brunellus is irrational":
      r1:
        "Brunellus is a donkey.":
        "All donkeys are irrational.": 
      o1:
        "Brunellus studied in Paris.":
        "-Most who study in Paris are rational.":
    ```

To convert a markdown document containing argument maps, use the --lua-filter option with Pandoc:

pandoc examples/example.md -o test/output/example.html --lua-filter pandoc-argmap.lua

By default, this will generate a png image representing the argmap.

Alternatively, the next two sections describe how to generate an svg image or a mapjs interactive map.

If the output format is html5, and you are not using the mapjs output format, then the filter generates individual pdf files for each map, and uses pdf2svg to convert them to svg, which are embedded directly into the html file.

You can display MindMup JSON files on a web page as an interactive mindmap without using the MindMup website, by using a customised version of mapjs.

Here is an example:

mapjs is an earlier, open source version of MindMup, and while it does not look as attractive, it provides similar functionality.

See Generating Interactive Argument Maps mapjs for details of how to use it.

By default, pandoc-argmap.lua does the following:

1. Replaces each embedded YAML map with a TikZ generated image of the map;
2. Generates a MindMup map;
3. Uploads it to Google Drive, and links the image to the MindMup url.

It will not do this when displaying in argmapjs format.

Alternatively, if your output format is markdown and you add the code block attribute "tidy=true", the filter will skip step '1. Replacing the map with a TikZ image' above, and will just do steps 2 and 3.

e.g.

    ``` {.argmap tidy=true}
    "Brunellus is irrational":
    ```

In addition, if the Google Drive gid attribute for the file is added to the code block, it will associate the map in your markdown file with a specific map on your Google Drive. This will ensure that future conversions will update that map, rather than cluttering your Google Drive with a new map every time.

If you want to generate a PDF file using LaTeX, you will also need to use the --pdf-engine=lualatex option, and use a custom template with the --template:

pandoc examples/example.md -o output/examples/example.pdf --lua-filter pandoc-argmap.lua --pdf-engine lualatex --template examples example-template.latex

If you prefer, you could use the --include-in-header option instead of a custom template:

argmap2tikz.lua -i > output/header.tex
pandoc examples/example.md -o output/example.pdf --lua-filter pandoc-argmap.lua --pdf-engine lualatex --include-in-header output/header.tex

If the output format is latex, the filter directly embeds the TikZ image code into the latex file as raw latex. So if you want to use Pandoc to directly produce a PDF using one of its latex engines, you will need to specify --pdf-engine lualatex and use a custom template or the --include-in-header option.

pandoc examples/example.md -o output/example.pdf --lua-filter pandoc-argmap.lua --template custom.latex --pdf-engine lualatex

For all other formats, it uploads the MindMup file to Google Drive and generates individual pdf files for each map, and then converts them to png using ImageMagick's convert command. It replaces the code block with a paragraph containing the generated image, linked to the MindMup file.

This interactive mindmap format is an alternative way to display your argument maps in html pages.

I have added a custom branch of repo s6mike/mapjs-webpack-example at custom to a sub-folder, map-js.

To set this up, you will need to:

1. Install node.js and then run npm --prefix [path to mapjs folder] install to grab the dependencies.

2. Call npm run --prefix [path to mapjs folder] pack to build the app with webpack.

This builds the client side JavaScript file which activates the maps: mapjs/public/js/main.bundle.js. This needs to be added to any page displaying the map using mapjs .json data.

See mapjs/README.md for more details about mapjs.

You can convert an argmap inside a markdown file into html containing mapjs by doing the following:

1a ) Either adding attribute to="js" to the code block:

  ``` {.argmap name="An argument about a donkey" to="js"}
  "Brunellus is irrational":
    r1:
      "Brunellus is a donkey.":
      "All donkeys are irrational.":
    o1:
      "Brunellus studied in Paris.":
      "-Most who study in Paris are rational.":
  ```

b) Or you can set a default value to: value for all argmap blocks in the document by adding this to the document metadata:

argmap:
  to: js

e.g.

    ---
    title: An Example
    argmaps: true
    argmap:
      to: js
    ---

    This is an example of an argument about a donkey!

    ``` {.argmap name="An argument about a donkey"}
    "Brunellus is irrational":
      r1:
        "Brunellus is a donkey.":
        "All donkeys are irrational.":
      o1:
        "Brunellus studied in Paris.":
        "-Most who study in Paris are rational.":
    ```

2 ) The simplest way to convert your argmap code block into the mapjs format is to use the pandoc-argmap.lua filter and provided Pandoc template to convert the markdown document into html containing mapjs.

e.g.

pandoc input/example-updated.md --template src/layouts/templates/pandoc-mapjs-main-html5.html --metadata=mapjs-output-js:/mapjs-example/public/main.js --metadata=css:mapjs-default-styles.css --lua-filter=/src/pandoc-argmap.lua > output.html

3 ) Open output.html in a browser to see the map.

If you can see the map controls but not the map, check the console for errors.

If you get a CORS origin error, you can fix it easily in Chrome by opening it with the command line option --allow-file-access-from-files. Other browser should have similar solutions.

Note that this disables a security feature, so best to use this option only when viewing mapjs files.

You can adapt the above for your own DIY approach:

1 ) Create a JSON file using src/argmap2mup, and put it somewhere accessible from your web page.

2 ) Embed it into an html page using html like this, replacing [JSON file path] with the path:

<div id="container-argmap1" class="container-argmapjs">
  <script type="application/json" class="argmap-json" src="[JSON file path]"></script>
</div>

The container and script classes must be as above unless you customise mapjs/config/config-mapjs.yaml. However, app updates can change this file without warning, so this is not recommended. The container div id can be as you wish.

3 ) Add the mapjs script built from webpack: <script src="/mapjs-example/public/main.js"></script>

4 ) Add the included stylesheet to ensure the mapjs is formatted properly: <link rel="stylesheet" href="mapjs-default-styles.css" />

I have written scripts to help with this workflow, you may be able to adapt them for your purposes. See scripts/bash-aliases-argmap.sh.

See mapjs README.md for a customised version of the original (and brief) mapjs documentation.

For more information about the structure of the mapjs output format (.json/.mup), see: Data Format · MindMup/mapjs Wiki.

See Displaying Argmaps with mapjs for other ways to use mapjs with argmap.