platform-is-the-problem/README.md

*Platform is the Problem* is an open source publication produced
with free / open source software and fonts. Use has been made of the
ConTeXt typesetting system due to its precision.

# The short version

``` fish
$ fish install-context.fish
$ fish install-fonts.sh
$ fish compile.fish
$ open src/platform-is-the-problem.pdf
```

The remainder of this document outlines how to contribute to the
publication and make your own version.

# How to contribute to this publication

There are many ways to contribute to this publication. The following
protocol details one way amongst many to create your own version of *The
Platform is the Problem*.

## Download and install ConTeXt luametatex

ConTeXt luametatex is required to typeset the pdf version of *The
Platform is the Problem*. To download and install ConTeXt luametatex
visit <https://wiki.contextgarden.net/Installation>. Alternatively, if
you are a Linux user, you can run the script install-context.sh which is
included in this repository. This will install Context luametatex and
its modules within \~/Applications/. Ensure to add the executables to
your fish path. This can be done by appending the following line to
\~/.config/fish/config.fish

``` fish
set -p PATH $PATH /home/USERNAME/Applications/context/tex/texmf-linux-64/bin
```

replacing USERNAME with your username.

## Installing fonts: Bitter and Compagnon Light

Bitter and Compagnon Light are libre fonts which we have used throughout
the publication. In order to typeset in these fonts, and assuming you
are a Linux user, run the script install-fonts.sh. You will need to have
installed ConTeXt luametatex, wget and git to execute the script
successfully. If you are not running Linux, you may need to follow the
script manually. In which case, to enable these fonts it is necessary
to:

1.  Create appropriate subdirectories within your ConTeXt distribution.
2.  Copy fonts/type-imp-bitter.mkxl and fonts/type-imp-compagnon.mkxl to
    the appropriate location in your ConTeXt distribution.
3.  Download the libre fonts from the web and install them into your
    system for use with LibreOffice Draw
4.  Make it possible to use the fonts in ConTeXt by passing various
    arguments to mtxrun.

## Copying the ConTeXt template

The template for a feature page can be found in the contrib directory.
The file, named template.mkxl, is comprised of macros specific to the
ConTeXt luametatex typesetting software. Each feature page in the src
subdirectories are based upon this template. You might like to edit one
of the examples in contrib/examples. If not, determine the name and page
number of the feature you would like to contribute. For example, the
feature might be \'Privacy Policy\' and the page number might be 24.
Inside the contrib directory create a subdirectory called, for instance,
\'24-privacy-policy\'. Copy the template.mkxl to that subdirectory and
call it, for example, \'24-privacy-policy.mkxl\'. The reason for placing
.mkxl files inside folders is largely due to neatness. ConTeXt generates
auxiliary files when compiling .pdf documents and, if these files are
not purged, this can quickly become messy.

## Typesetting your contribution

Each entry in *The Platform is the Problem* is composed of three parts:

-   Feature
-   Implications
-   Alternatives / Anecdote

It is suggested write no more than 123 words for each part. Otherwise,
there is the possibility that the copy may not fit inside the frame.
Replace the placeholder text in the copy of template.mkxl with the
appropriate information. The following table outlines on which lines
placeholder text appears and what it should be replaced with.

```
 Placeholder        Line(s)      Replace with
 -----------------------------------------------------------------------------
 PAGENUMBER         41, 46, 52   The page number
 TITLE              73           The name of the feature
 FEATURECOPY        79           A description of the feature
 IMPLICATIONSCOPY   86           A discussion of implications of the feature
 ALTERNATIVESCOPY   93           Some alternatives to this feature
```

### Ensuring copy fits within the frame

As each page is physically cut into thirds it\'s worth double checking
that your copy will fit in the available space. Here is an excerpt from
template.mkxl (lines 75 to 88).

``` context
\definelayer[head]
         [x=30mm,y=10mm,width=99mm,height=60mm]
\setlayer[head]
{\switchtobodyfont[bitter,9pt] \framed[width=99mm,height=60mm,frame=off,align={tolerant,width,hz,hanging}]{\kerncharacters[0.03125]{
FEATURECOPY
}}}

\definelayer[torso]
        [x=30mm,y=80mm,width=99mm,height=60mm]
\setlayer[torso]
{\switchtobodyfont[bitter,9pt] \framed[width=99mm,height=60mm,frame=off,align={tolerant,width,hz,hanging}]{\kerncharacters[0.03125]{
IMPLICATIONSCOPY
}}}
```

To ensure that copy will fit on the page when it is cut, activate the
\"bottomframe\" for the head and torso layers. In other words, change
lines 78 and 85 so that they read as follows:

``` context
{\switchtobodyfont[bitter,9pt] \framed[width=99mm,height=60mm,frame=off,bottomframe=on,align={tolerant,width,hz,hanging}]{\kerncharacters[0.03125]{
```

Save the mkxl file and run context on it. Check the output pdf document.
If the copy fits within the frame, remove the \"bottomframe=on\" option,
save the file and recompile. Otherwise, edit the copy and recompile
until it fits.

## Adding your contribution to platform-is-the-problem.mkxl

platform-is-the-problem.mkxl is a file which collates pages from
different .pdf documents and assembles them into one file. It lives in
the src directory. Here is some sample code from
platform-is-the-problem.mkxl.

``` context
\externalfigure[{./21-blocking-content/21-blocking-content.pdf}]
\externalfigure[{./22-curating-content/22-curating-content.pdf}]

\externalfigure[{../maps/maps.pdf}][page=22]
\externalfigure[{../maps/maps.pdf}][page=21]

\externalfigure[{./23-customisation-of-profile/23-customisation-of-profile.pdf}]

\pagebreak[+2]

\externalfigure[{../maps/maps.pdf}][page=23]
```

What is this code doing? The first two \'`\externalfigure`\'
commands instruct ConTeXt to insert into the main typesetting area two
feature pages: 21 - Blocking Content and 22 - Curating Content. These
features are single-page pdf documents. The next two
\'`\externalfigure`\' commands instruct ConTeXt to typeset two
further images: page 22 and page 21 of maps.pdf. Note the order of the
pages across the first four \'`\externalfigure`\' commands: 21,
22, 22, 21. This micro-structure is required to ensure that the map
printed on the reverse of the feature page corresponds to the feature
itself. You might like to experiment with this layout for a different
reading experience or keep it as is.

The third \'`\externalfigure`\' command instructs ConTeXt to
typeset feature 23. As this is the last page and it is an odd number,
it\'s necessary to add two blank pages in between the feature and the
corresponding map. This ensures that the map is on the reverse side of
the feature when the document is printed.

Suppose you have written a contribution and would like to add the
feature to the publication. The following code snippet expands on the
above example to illustrates how that can be done.

``` context
\externalfigure[{./23-customisation-of-profile/23-customisation-of-profile.pdf}]
\externalfigure[{../contrib/24-privacy-policy/24-privacy-policy.pdf}]

\externalfigure[{../maps/maps.pdf}][page=24]
\externalfigure[{../maps/maps.pdf}][page=23]
```

## Making a map

Complementing each feature is a map which is printed on the reverse of
the page. Short-side flipping should be enabled when it comes to
printing the document. This is to ensure that the map which appears on
the reverse side of the feature corresponds to that feature. The maps
have been made with Libreoffice Draw and a map-framework.odg file is
included to assist with making your own maps. The idea behind the maps
is that the \"cross-points\" align on every page. This entails that,
when the document is cut and bound, the maps line up with each other to
produce many possible variations. Throughout the publication rounded
rectangles and curved connectors have been put to use. You may like to
follow this aesthetic for consistency or mix it up for a different
effect. If you installed the libre fonts correctly, it should be
possible to select these from within Libreoffice Draw. To create your
own map, open the map-framework.odg file. Select all the elements on the
page and copy them to the clipboard. Next, open maps.odg and navigate to
the last page. This can be done via the menu bar through Page \>
Navigate \> To Last Page. Create a new page via the menu bar with Page
\> New Page. Paste the contents of the clipboard onto the new page and
design your map. When you have finished you may like to rename your page
to the name of your feature. This can be done through the menu bar (Page
\> Rename Page). Once you are satisfied with your design, you may like
to delete the framework objects; the two horizontal lines traversing the
page. Do you prefer more organic curves? If so, you might like to rotate
the four short vertical lines by 90 degrees and align the connectors
before deleting the four, short (now horizontal) lines. After the
framework lines have been deleted, export the odg drawing as a pdf
document.