Commit 312f9c1c authored by Paul Asmuth's avatar Paul Asmuth
Browse files

update the documentation 

- Add a logo
- Improve the page layout slightly and change link colours
- Update the favicon
- Update the readme demo chart
parent e2cdac08

README.md

+54 −70
Original line number Diff line number Diff line 
# clip

<div align="center"><img src="./doc/logo.svg" alt="clip" width="160" /></div>

<h3>clip – The command line illustration processor</h3>



clip (the _command line illustration processor_) is an open-source command line

program and software library for creating charts and other data-driven

illustrations.



In essence, clip consists of a library of drawing commands. This command library

includes high-level building blocks for creating common chart types as well as

lower-level drawing primitives such as markers, arrows and lines.



When called from the command line, clip reads input data in text and CSV format

and produces the output chart as a SVG or PNG file. Additionaly, clip is available

as the libclip software library which can be embedded into any application that

supports a C FFI.



program and software library for creating charts and other programmatic

illustrations. In essence, clip consists of a library of drawing commands. This

command library includes high-level building blocks for creating common chart

types as well as lower-level drawing primitives such as markers, arrows and lines.



<h4>

  <a href="https://clip-lang.org/getting-started">Getting Started</a> &middot;
@@ -21,71 +14,61 @@ supports a C FFI. 
</h4>





Example

-------

Introduction

------------



Being a highly visual tool, clip is best explained by example. So here is how to

draw a simple line chart using clip:

draw a simple line chart using clip):



    $ clip --export example_chart.svg example_chart.clp



Output File (`example_chart.svg`):

[![A simple scatterplot](/doc/demo_timeseries.svg)](https://clip-lang.org/examples/charts-basic/demo_timeseries)



Input File (`example_chart.clp`):

The command reads an input file (`example_chart.clp`) and produces an output SVG

file from it. This is the input file:



    (figure/plot

        limit-x (1404278100 1404299700)

        limit-y (6000000 10000000)

        axes (

            position (bottom left)

            label-format-y (scientific)

            label-format-x (datetime "%H:%M:%S")

            label-placement-x (linear-align 1800))

        limit-x (0 7200)

        limit-y (0 100)

        lines (

            data-x (csv "test/testdata/measurement.csv" time)

            data-y (csv "test/testdata/measurement.csv" value1)

            color #06c)

        legend (

            position (top right)

            item (label "Random Data" color #06c)))



            data-x (csv "measurement.csv" time)

            data-y (csv "measurement.csv" value)

            stroke-width 0.8pt)

        grid (

            stroke-color #333

            stroke-style dashed))



Note that this example is only intended to give you an idea of what the syntax

looks like and to get you started quickly; for an in-depth description of all

parameters, please refer to [the documentation](https://clip-lang.org).

The resulting SVG file looks like this:



More examples can be found on [the examples page](https://clip-lang.org/examples).

<div align="center">

  <a href="https://clip-lang.org/examples/charts-scientific/vectorfield">

    <img src="/doc/demo.svg" width="80%" alt="Demo Chart" />

  </a>

</div>



If you have any questions please don't hesitate to reach out via [GitHub issues](https://github.com/asmuth/clip).

Note that this example is only intended to give you an idea of what the syntax

looks like; for an in-depth description of all parameters, please refer to

[the documentation](https://clip-lang.org). More examples can be found on

[the examples page](https://clip-lang.org/examples).





Documentation

-------------



You can find the full documentation at https://clip-lang.org/





Example Gallery

---------------



A list of examples can be found on the [Examples](https://clip-lang.org/examples)

page.

You can find the full documentation and more examples at [clip-lang.org](https://clip-lang.org/).





Installation

------------



### Using homebrew (macOS)

#### Using homebrew (macOS)



To install clip using homebrew, run the following command:



    $ brew install clip



### From source

#### Compile from source



To build clip, you need an up-to-date C++ compiler, cmake, fmtlib, libharfbuzz,

libfreetype and cairo. Run:

libfreetype and cairo. Then run:



    $ cmake .

    $ make
@@ -103,37 +86,24 @@ For detailed installation instructions, have a look at the [Installation](https: 
page.





Acknowledgements

----------------



  - Text rendering is based on the libre [freetype](https://www.freetype.org/)

    and [harfbuzz](https://harfbuzz.org) stack.



  - The structure of the plot elements is based on ideas from [The Grammar of

    Graphics](https://www.springer.com/gp/book/9780387245447) and the

    [ggplot2](https://ggplot2.tidyverse.org/) library.



  - A number of concepts in clip are modelled after the

    [CSS specification](https://www.w3.org/TR/CSS2/)



FAQ

---



### I'm getting build errors when compiling the code

#### I'm getting build errors when compiling the code



clip is written in C++17 and needs a reasonably modern C++ compiler and standard

clip is written in C++17 and requires a reasonably modern C++ compiler and standard

library. In most cases where the code doesn't build it's due to some problem with

the local build environment. We always appreciate bug reports so that we can

improve our build system on GitHub Issues.

the local build environment. Still, we always appreciate bug reports via Github

Issues so that we can improve our build system.



### The test suite fails on my machine because text placement is slightly offset

#### The test suite fails on my machine because text placement is slightly offset



The test suite requires that you have the original Microsoft Arial TTF files

installed on your machine. To verify that this is the case, run `fc-match

'Arial,Helvetica,Helvetica Neue:style=Regular,Roman'` and check that it returns

the correct 'arial.ttf' file.



### What happened to the project name?

#### What happened to the project name?



The project was started in 2011 and was initially called "FnordMetric". The

first version from 8 years ago also included facilities for storing and
@@ -145,13 +115,27 @@ situation. The best solution seemed to be to rename the project and so it was 
renamed to "clip".





Acknowledgements

----------------



  - Text rendering is based on the libre [freetype](https://www.freetype.org/)

    and [harfbuzz](https://harfbuzz.org) stack.



  - The structure of the plot elements is based on ideas from [The Grammar of

    Graphics](https://www.springer.com/gp/book/9780387245447) and the

    [ggplot2](https://ggplot2.tidyverse.org/) library.



  - A number of concepts in clip are modelled after the

    [CSS specification](https://www.w3.org/TR/CSS2/)





License

-------



    clip -- The command line illustration processor

    https://clip-lang.org



    Copyright (c) 2018, Paul Asmuth, Laura Schlimmer

    Copyright (c) 2020, Paul Asmuth, Laura Schlimmer

    All rights reserved.



    Licensed under the Apache License, Version 2.0 (the "License");

doc/demo.clp

0 → 100644
+18 −0
Original line number Diff line number Diff line 
(layer/resize 2048px 768px)

(layer/set-dpi 240)

(layer/set-font "Latin Modern Roman")



(figure/plot

    limit-x (0 7200)

    limit-y (0 100)

    axes (

        label-format-x (datetime "%H:%M:%S")

        label-placement-x (linear-interval 900 900 7000))

    grid (

        stroke-color (rgba 0 0 0 0.2)

        stroke-style dashed

        tick-placement-x (none))

    lines (

        data-x (csv "test/testdata/timeseries.csv" time)

        data-y (csv "test/testdata/timeseries.csv" value)

        stroke-width 0.8pt))

doc/demo.svg

0 → 100644
+257 −0

File added.

Preview size limit exceeded, changes collapsed.

doc/demo_timeseries.svg

deleted100644 → 0
+0 −56
Original line number Diff line number Diff line 
<?xml version="1.0" encoding="UTF-8" ?>

<!-- Generated by clip v0.7.0 (clip-lang.org) -->

<svg xmlns="http://www.w3.org/2000/svg" width="2048.000000" height="512.000000">

  <rect width="2048.000000" height="512.000000" fill="#ffffff" fill-opacity="1.000000"/>

  <path d="M154.547 431.5 L2020.5 431.5 " fill="none" stroke-width="2.500000" stroke="#000000ff"/>

  <path d="M232.295 431.5 L232.295 421.5 " fill="none" stroke-width="2.500000" stroke="#000000ff"/>

  <path d="M387.791 431.5 L387.791 421.5 " fill="none" stroke-width="2.500000" stroke="#000000ff"/>

  <path d="M543.287 431.5 L543.287 421.5 " fill="none" stroke-width="2.500000" stroke="#000000ff"/>

  <path d="M698.783 431.5 L698.783 421.5 " fill="none" stroke-width="2.500000" stroke="#000000ff"/>

  <path d="M854.279 431.5 L854.279 421.5 " fill="none" stroke-width="2.500000" stroke="#000000ff"/>

  <path d="M1009.78 431.5 L1009.78 421.5 " fill="none" stroke-width="2.500000" stroke="#000000ff"/>

  <path d="M1165.27 431.5 L1165.27 421.5 " fill="none" stroke-width="2.500000" stroke="#000000ff"/>

  <path d="M1320.77 431.5 L1320.77 421.5 " fill="none" stroke-width="2.500000" stroke="#000000ff"/>

  <path d="M1476.26 431.5 L1476.26 421.5 " fill="none" stroke-width="2.500000" stroke="#000000ff"/>

  <path d="M1631.76 431.5 L1631.76 421.5 " fill="none" stroke-width="2.500000" stroke="#000000ff"/>

  <path d="M1787.26 431.5 L1787.26 421.5 " fill="none" stroke-width="2.500000" stroke="#000000ff"/>

  <path d="M1942.75 431.5 L1942.75 421.5 " fill="none" stroke-width="2.500000" stroke="#000000ff"/>

  <text x="178.763672" y="478.500000" fill="#000000ff" font-size="27.500000" font-family="Arial,Helvetica,'Helvetica Neue',sans-serif" font-weight="500.000000">05:30:00</text>

  <text x="334.259766" y="478.500000" fill="#000000ff" font-size="27.500000" font-family="Arial,Helvetica,'Helvetica Neue',sans-serif" font-weight="500.000000">06:00:00</text>

  <text x="489.755859" y="478.500000" fill="#000000ff" font-size="27.500000" font-family="Arial,Helvetica,'Helvetica Neue',sans-serif" font-weight="500.000000">06:30:00</text>

  <text x="645.251953" y="478.500000" fill="#000000ff" font-size="27.500000" font-family="Arial,Helvetica,'Helvetica Neue',sans-serif" font-weight="500.000000">07:00:00</text>

  <text x="800.748047" y="478.500000" fill="#000000ff" font-size="27.500000" font-family="Arial,Helvetica,'Helvetica Neue',sans-serif" font-weight="500.000000">07:30:00</text>

  <text x="956.244141" y="478.500000" fill="#000000ff" font-size="27.500000" font-family="Arial,Helvetica,'Helvetica Neue',sans-serif" font-weight="500.000000">08:00:00</text>

  <text x="1111.740234" y="478.500000" fill="#000000ff" font-size="27.500000" font-family="Arial,Helvetica,'Helvetica Neue',sans-serif" font-weight="500.000000">08:30:00</text>

  <text x="1267.236328" y="478.500000" fill="#000000ff" font-size="27.500000" font-family="Arial,Helvetica,'Helvetica Neue',sans-serif" font-weight="500.000000">09:00:00</text>

  <text x="1422.732422" y="478.500000" fill="#000000ff" font-size="27.500000" font-family="Arial,Helvetica,'Helvetica Neue',sans-serif" font-weight="500.000000">09:30:00</text>

  <text x="1578.228516" y="478.500000" fill="#000000ff" font-size="27.500000" font-family="Arial,Helvetica,'Helvetica Neue',sans-serif" font-weight="500.000000">10:00:00</text>

  <text x="1733.724609" y="478.500000" fill="#000000ff" font-size="27.500000" font-family="Arial,Helvetica,'Helvetica Neue',sans-serif" font-weight="500.000000">10:30:00</text>

  <text x="1890.244141" y="478.500000" fill="#000000ff" font-size="27.500000" font-family="Arial,Helvetica,'Helvetica Neue',sans-serif" font-weight="500.000000">11:00:00</text>

  <path d="M154.547 431.5 L154.547 27.5 " fill="none" stroke-width="2.500000" stroke="#000000ff"/>

  <path d="M154.547 431.5 L164.547 431.5 " fill="none" stroke-width="2.500000" stroke="#000000ff"/>

  <path d="M154.547 391.1 L164.547 391.1 " fill="none" stroke-width="2.500000" stroke="#000000ff"/>

  <path d="M154.547 350.7 L164.547 350.7 " fill="none" stroke-width="2.500000" stroke="#000000ff"/>

  <path d="M154.547 310.3 L164.547 310.3 " fill="none" stroke-width="2.500000" stroke="#000000ff"/>

  <path d="M154.547 269.9 L164.547 269.9 " fill="none" stroke-width="2.500000" stroke="#000000ff"/>

  <path d="M154.547 229.5 L164.547 229.5 " fill="none" stroke-width="2.500000" stroke="#000000ff"/>

  <path d="M154.547 189.1 L164.547 189.1 " fill="none" stroke-width="2.500000" stroke="#000000ff"/>

  <path d="M154.547 148.7 L164.547 148.7 " fill="none" stroke-width="2.500000" stroke="#000000ff"/>

  <path d="M154.547 108.3 L164.547 108.3 " fill="none" stroke-width="2.500000" stroke="#000000ff"/>

  <path d="M154.547 67.9 L164.547 67.9 " fill="none" stroke-width="2.500000" stroke="#000000ff"/>

  <path d="M154.547 27.5 L164.547 27.5 " fill="none" stroke-width="2.500000" stroke="#000000ff"/>

  <text x="27.500000" y="438.000000" fill="#000000ff" font-size="27.500000" font-family="Arial,Helvetica,'Helvetica Neue',sans-serif" font-weight="500.000000">6.0 × 10⁶</text>

  <text x="27.500000" y="397.599999" fill="#000000ff" font-size="27.500000" font-family="Arial,Helvetica,'Helvetica Neue',sans-serif" font-weight="500.000000">6.4 × 10⁶</text>

  <text x="27.500000" y="357.199999" fill="#000000ff" font-size="27.500000" font-family="Arial,Helvetica,'Helvetica Neue',sans-serif" font-weight="500.000000">6.8 × 10⁶</text>

  <text x="27.500000" y="316.799995" fill="#000000ff" font-size="27.500000" font-family="Arial,Helvetica,'Helvetica Neue',sans-serif" font-weight="500.000000">7.2 × 10⁶</text>

  <text x="27.500000" y="276.399998" fill="#000000ff" font-size="27.500000" font-family="Arial,Helvetica,'Helvetica Neue',sans-serif" font-weight="500.000000">7.6 × 10⁶</text>

  <text x="27.500000" y="236.000000" fill="#000000ff" font-size="27.500000" font-family="Arial,Helvetica,'Helvetica Neue',sans-serif" font-weight="500.000000">8.0 × 10⁶</text>

  <text x="27.500000" y="195.599990" fill="#000000ff" font-size="27.500000" font-family="Arial,Helvetica,'Helvetica Neue',sans-serif" font-weight="500.000000">8.4 × 10⁶</text>

  <text x="27.500000" y="155.200005" fill="#000000ff" font-size="27.500000" font-family="Arial,Helvetica,'Helvetica Neue',sans-serif" font-weight="500.000000">8.8 × 10⁶</text>

  <text x="27.500000" y="114.799995" fill="#000000ff" font-size="27.500000" font-family="Arial,Helvetica,'Helvetica Neue',sans-serif" font-weight="500.000000">9.2 × 10⁶</text>

  <text x="27.500000" y="74.399986" fill="#000000ff" font-size="27.500000" font-family="Arial,Helvetica,'Helvetica Neue',sans-serif" font-weight="500.000000">9.6 × 10⁶</text>

  <text x="27.500000" y="34.000000" fill="#000000ff" font-size="27.500000" font-family="Arial,Helvetica,'Helvetica Neue',sans-serif" font-weight="500.000000">1.0 × 10⁷</text>

  <path d="M154.547 166.676 L180.463 195.418 L206.379 213.119 L232.295 211.704 L258.211 225.997 L284.127 235.002 L310.043 241.006 L335.959 244.685 L361.875 254.1 L387.791 237.396 L413.707 242.656 L439.623 258.777 L465.539 238.187 L491.455 240.701 L517.371 256.608 L543.287 254.462 L569.203 265.07 L595.119 272.332 L621.035 283.42 L646.951 287.535 L672.867 293.265 L698.783 248.665 L724.699 215.424 L750.615 206.424 L776.531 214.377 L802.447 232.76 L828.363 258.251 L854.279 256.221 L880.195 271.609 L906.111 276.811 L932.027 284.125 L957.943 277.495 L983.859 285.583 L1009.78 270.085 L1035.69 257.406 L1061.61 283.771 L1087.52 287.123 L1113.44 291.348 L1139.36 301.646 L1165.27 280.295 L1191.19 270.882 L1217.1 271.866 L1243.02 277.081 L1268.94 263.088 L1294.85 285.021 L1320.77 270.131 L1346.68 264.081 L1372.6 264.745 L1398.52 272.731 L1424.43 256.264 L1450.35 253.541 L1476.26 242.893 L1502.18 256.253 L1528.1 269.668 L1554.01 280.315 L1579.93 259.804 L1605.84 269.463 L1631.76 267.398 L1657.68 285.764 L1683.59 291.056 L1709.51 285.438 L1735.42 289.702 L1761.34 285.317 L1787.26 278.027 L1813.17 280.406 L1839.09 275.559 L1865 268.247 L1890.92 272.303 L1916.84 278.907 L1942.75 254.895 L1968.67 251.681 L1994.58 238.649 L2020.5 240 " fill="none" stroke-width="3.750000" stroke="#0066ccff"/>

  <text x="1806.812500" y="85.500000" fill="#000000ff" font-size="27.500000" font-family="Arial,Helvetica,'Helvetica Neue',sans-serif" font-weight="500.000000">Random Data</text>

  <path d="M1780.69 86.3125 C1774.99 86.3125 1770.38 81.6954 1770.38 76 C1770.38 70.3046 1774.99 65.6875 1780.69 65.6875 C1786.38 65.6875 1791 70.3046 1791 76 C1791 81.6954 1786.38 86.3125 1780.69 86.3125 Z" fill="#0066cc" fill-opacity="1.000000"/>

</svg>
 
 No newline at end of file

doc/example.tpl.html

+1 −1
Original line number Diff line number Diff line
@@ -2,7 +2,7 @@ 


<h4>Output File:</h4>

<p style="text-align: center;">

  <img style="max-width: 80%;" src="/examples/{{example_url}}.svg" />

  <a href="/examples/{{example_url}}.svg" target="_blank"><img src="/examples/{{example_url}}.svg" /></a>

</p>



<h4>Source File:</h4>

CRA Git | Maintained and supported by SUSTech CRA and CCSE