Glossary-making-tool

This is a Work-in-progress experiment tool to make living glossaries websites using simple Python, Javascript, and CSS from an Markdown file.

This tool was develop during the process of making: http://tool.attempt.press

What makes it living?

• The glossary structure uses the idea of a ‘gloss’ which means annottation and layer. It makes the glossary a layering of anotations rather than a list of definitions. The pad template uses each word as a card with multiple annotations where you can collect multiple voices for each word.

• Being written in a markdown file makes it permeable to changes, new elements and transformations.

• It also offers the option of add properties to each word in order to find connections and multiple types of organization between them.

• Via Markdown is possible to add hyperlinks. It means that you can easily communicate your annotation to other pieces of information outside the glossary.

PD: This tool is also published as a JupyterLab notebook which makes easier to run. Find here how to install JupyterLab in your computer and here the notebook. Running it through a notebook would simplify the process of writing and modify the Glossary environment.

How to use it?

If you are interested into make a glossary that you can expand and easily manipulate via markdownfile. Follow the next steps:

What do you need?

• python: extract the information from the markdown file or pad and write the content for the website.
• Markdown File: all words for the glossary are gathered here. (It can be written in a pad Instance)
• stylesheet: all CSS rules for the Glossary are collected here (written in CSS)
• html: render the lay out as a HTML (rendered with PyPandoc)

1. Clone this repository

Clone or download….????

2. Write the Markdown File with the Glossary Words and its annotations.

If you are writing the glossary collectively and online, your best option would be using a Etherpad Instance.

• Each word entry has to be inside colons ::: (more than 3) as it is in the example this would create a div when rendered.
• The class for each element is define by adding {.class} next to it. So you can define new properties by adding new classes.

See this pandoc documentation to explore more possibilities with Markdown: https://pandoc.org/MANUAL.html

::::::::::::::::::::::::::::::::::::::::::  {.word .property1 .property2 .property3}

# Word {.title }

⤷ Annotation one

⤷ Annotation two

⤷ Annotation Three

:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

3. (Option 1) Open the Jupyter Notebook and follow the instructions.

glossary-making.ipynb

3. (Option 2) Run the python script to write the Html, Javascript and Css files

Def Glossary content

• Convert the markdown file into html file using pypandoc

*Via API using etherpad

import json, pypandoc
from urllib.request import urlopen
from urllib.parse import urlencode


with open("/opt/etherpad/APIKEY.txt") as f:
    api_key = f.read().strip()

api_url = "https://hub.xpub.nl/soupboat/pad/api/1.2.15/"

# wrap in a convenient function (APICALL)
def ep (api_fn, api_url, api_key, **data):
    data['apikey'] = api_key
    return json.load(urlopen(f"{api_url}{api_fn}", data=urlencode(data).encode()))


glossary = ep("getText", api_url, api_key, padID="camilo_glossary")

text = glossary["data"]["text"]

words = pypandoc.convert_text(text, 'html', format='md')

*Via Local Markdown File

import pypandoc 

text = open(glossary.text, 'w')
words = pypandoc.convert_text(text, 'html', format='md')

Def Glossary properties

• Make a dictionary of the properties

properties = [
	{
		'title':'action',
		'symbol':'AC',
        'color': 'green'
	},
	{
		'title':'situation',
		'symbol':'S',
		'color': 'aqua'
	},
	{
		'title':'logic',
		'symbol':'L',
		'color': 'orange'
	},
]

Writing Website files

• Writing a legend using the properties

legend = ''

i = 0

for title, symbol, color in properties:
    title = properties[i]['title']
    legend += f'''<button id="{title}" class="btn {title}-s" onclick="filterSelection('{title}')">{title}</button>\n'''
    i += 1
    

• Adding property symbols in front of each word generating a Java script code:

script = ''

i = 0 

for title, symbol, color in properties:
    title = properties[i]['title']
    symbol = properties[i]['symbol']
    script += (f"""const {title} = document.getElementsByClassName("{title}");
    for (let i = 0; i < {title}.length; i++)"""'{\n' 
               f"""{title}[i].innerHTML += "<span class='symbol {title}-s'>{symbol}</span>";""" 
    '\n}\n\n')
    i += 1

• Generating a css style using properties values:

style = ''

i = 0 

for title, symbol, color in properties:
    title = properties[i]['title']
    color = properties[i]['color']
    style += f'''.{title}-s''' + '{' + f'''color:{color};''''}'
    i += 1
    

• Writing the Body. Note that here you are using the previous variables style, legend, and script
  
  

body = f'''<!DOCTYPE html>
    <html>
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <link rel="stylesheet" href="style.css"> 
        <title>Attempt to Glossary</title>
    </head>
        <style> {style} </style>
    <body id="glo_body">

    <div class="head">
        <h1> Glossary for a Diffractive Publishing Practice </h1>
        <a href="rss.xml">
            <p>follow what is new (rss)</p>
        </a>
    </div>
    <hr>
    <div class="description">
        <p>This glossary project is an ongoing and ever-transforming experiment that introduces a diffractive methodology inside the publishing practice. It is seen as a mutable and living publication result of collective workshops where participants are invited to think and converse around its words and annotations. During the workshop, diffraction performs a conscious interconnection of practices beyond reflection. The current state of the glossary gathers different annotations on each word instead of a closed definition for each one.</p> 
        <p>Concretly, the glossary as a publication uses questions as triggers and it aims to weave as a conversation the multiple{description}of the current practice, with other vocabularies that come from critical theory, new materialism and others. The final intention is not just to envision our future as publishers but to help to initiate conversations with others.</p>
    </div>
    <hr>
    <div class="question">
        <div id="sptContainer"></div>
    </div>
    <hr>
    <div id="legend" class="legend"> 
        <button class="btn active" onclick="filterSelection('all')">properties</button> {legend}
    </div>
    <hr>
    <div class="words">
        {words} 
    </div>
    </body>
        <script>
            {script}
        </script>
        <script src="main.js"></script>
    </html>'''

• Writing the indel.html file

website = open('index.html','w')

website.write(body)
website.close()

• Open the index.html file in your browser and enjoy

….