From 5329c76dd9b4bc244d96c97ea40575231800e034 Mon Sep 17 00:00:00 2001
From: BERTHAUT Florent <florent.berthaut@univ-lille1.fr>
Date: Wed, 21 Jul 2021 00:28:26 +0200
Subject: [PATCH] Added build and html doc
---
doc/boeuf.html | 29 +++++++++++++++++-
doc/build.sh | 6 ++--
doc/img/.style.css.swp | Bin 12288 -> 0 bytes
doc/img/md_to_html.lua | 16 ++++++++--
doc/img/style.css | 66 ++++++++++++++++++++++++++++++++++++++++-
doc/img/template.html | 46 ++++++++++++++++++++++++++++
doc/index.html | 51 +++++++++++++++++++++++--------
doc/objects.html | 27 +++++++++++++++++
8 files changed, 222 insertions(+), 19 deletions(-)
delete mode 100644 doc/img/.style.css.swp
create mode 100644 doc/img/template.html
diff --git a/doc/boeuf.html b/doc/boeuf.html
index 4396325..e270975 100644
--- a/doc/boeuf.html
+++ b/doc/boeuf.html
@@ -1,3 +1,27 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
+<head>
+ <meta charset="utf-8" />
+ <meta name="generator" content="pandoc" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
+ <title>bf-pd : the BOEUF framework</title>
+ <style>
+ code{white-space: pre-wrap;}
+ span.smallcaps{font-variant: small-caps;}
+ span.underline{text-decoration: underline;}
+ div.column{display: inline-block; vertical-align: top; width: 50%;}
+ div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
+ ul.task-list{list-style: none;}
+ </style>
+ <link rel="stylesheet" href="img/style.css" />
+</head>
+<body>
+<nav>
+ <li><a href="index.html">Home</a></li>
+ <li><a href="boeuf.html">BOEUF</a></li>
+ <li><a href="objects.html">Objects</a></li>
+</nav>
+<main>
<h1 id="the-boeuf-conceptual-framework">The BOEUF conceptual framework</h1>
<p>BOEUF is a conceptual framework for modeling and building orchestras of digital musical instruments. It consists of a classification of <em>modes of collaboration</em>, and a set of <em>components</em> which can be used to enable these modes in digital instruments. We developed this classification after conducting interviews with digital musicians who work in ensembles, as well as literature review of work on digital ensembles and collaborative instruments. The word “boeuf†is french slang for a jam session.</p>
<h2 id="modes-of-collaboration">Modes of Collaboration</h2>
@@ -29,5 +53,8 @@
<h2 id="navigate">Navigate</h2>
<ul>
<li>The BOEUF project: <a href="https://bf-collab.net/bf/"></a></li>
-<li>The Bf-Pd library: <a href="https://gitlab.cristal.univ-lille.fr/boeuf/bf-pd/blob/master/README.md"></a></li>
+<li>The Bf-Pd library: <a href="https://gitlab.cristal.univ-lille.fr/boeuf/bf-pd/blob/master/README.html"></a></li>
</ul>
+</main>
+</body>
+</html>
diff --git a/doc/build.sh b/doc/build.sh
index 3c23d21..2641f2d 100755
--- a/doc/build.sh
+++ b/doc/build.sh
@@ -1,3 +1,3 @@
-pandoc ../README.md -s -o ../index.html --lua-filter=img/md_to_html.lua -c doc/img/style.css
-pandoc boeuf.md -o boeuf.html
-pandoc objects.md -o objects.html
+pandoc ../README.md -o index.html -s --lua-filter=img/md_to_html.lua -c img/style.css --template=img/template.html --metadata title="bf-pd : index"
+pandoc boeuf.md -o boeuf.html -s --lua-filter=img/md_to_html.lua -c img/style.css --template=img/template.html --metadata title="bf-pd : the BOEUF framework"
+pandoc objects.md -o objects.html -s --lua-filter=img/md_to_html.lua -c img/style.css --template=img/template.html --metadata title="bf-pd : objects"
diff --git a/doc/img/.style.css.swp b/doc/img/.style.css.swp
deleted file mode 100644
index 200683201616607614bd5b6e55c649b89baaa2a6..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001
literal 12288
zcmeI%Jxc>I7{Kx8#6>~s%NIDcYnz^3irs|{)j{ms-b-xZBu6hDq^RHrlYR&nzk@hB
zxYQh67nkdL_z#4KBu_$~-xd;fMuVZ>YX{=mp~%PE_xSzj)obp1qEl1MR<`NPrjx8P
zO`hF>YH)pZqi&71Dm2MLt5CPHSj8q%vxj??+s8C%M|oa-8W{*6u(iO#>Q?VSx)(vG
z*mHh%>Yp6nZM~gD1Q0*~0R#|0009ILsK0>CJb7_t?3AVKmeKnY%OL>)1Q0*~0R#|0
z009ILKmY**YA7&?MOF=wPuGk8|IPb<?Z!W@e{I%kSQ}SH009ILKmY**5I_I{1Q0;r
WKMFj_USv`;znmv=U#5Y-6!`^71}lI7
diff --git a/doc/img/md_to_html.lua b/doc/img/md_to_html.lua
index 64a4cbd..f68f936 100644
--- a/doc/img/md_to_html.lua
+++ b/doc/img/md_to_html.lua
@@ -1,5 +1,17 @@
function Link(el)
- el.target = string.gsub(el.target, "%.md", ".html")
- return el
+ el.target = string.gsub(el.target, "%.md", ".html")
+ el.target = string.gsub(el.target, "doc/", "")
+ return el
+end
+
+function Image(el)
+ el.src = string.gsub(el.src, "doc/", "")
+ return el
+end
+
+function RawInline (raw)
+ if raw.format == 'html' then
+ return pandoc.RawInline('html', string.gsub(raw.text, "doc/img", "img"))
+ end
end
diff --git a/doc/img/style.css b/doc/img/style.css
index 632a48b..218e1dc 100644
--- a/doc/img/style.css
+++ b/doc/img/style.css
@@ -1,4 +1,68 @@
+body {
+ display:grid;
+ grid:"nav main" auto
+ / 100px 1fr;
+ grid-gap:10px;
+ padding:0px 5% 50px 5%;
+ font-family:sans-serif;
+}
+
+main {
+ grid-area:main;
+ background-color:#AAA;
+ padding:0px 5px;
+}
+
+nav {
+ grid-area:nav;
+ font-size:1.2em;
+ position:sticky;
+ top:5px;
+ background-color:#333;
+ align-self:start;
+}
+
+nav li {
+ list-style-type:none;
+ width:100%;
+}
+
+nav a {
+ color:white;
+ background-color:#333;
+ width:100%;
+ font-weight:bold;
+}
+
+nav a:hover {
+ color:#333;
+ background-color:white;
+}
+
+a {
+ color:#333;
+}
+
+a:hover {
+ color:white;
+ background-color:#333;
+}
h1 {
- color:red;
+ margin-top:0px;
+}
+
+h1, h2 {
+ color:white;
+ background-color: #333;
}
+
+img {
+ max-width:100%;
+ border:2px black solid;
+}
+
+figcaption {
+ display:none;
+}
+
diff --git a/doc/img/template.html b/doc/img/template.html
new file mode 100644
index 0000000..36142fc
--- /dev/null
+++ b/doc/img/template.html
@@ -0,0 +1,46 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" lang="$lang$" xml:lang="$lang$"$if(dir)$ dir="$dir$"$endif$>
+<head>
+ <meta charset="utf-8" />
+ <meta name="generator" content="pandoc" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
+$for(author-meta)$
+ <meta name="author" content="$author-meta$" />
+$endfor$
+$if(date-meta)$
+ <meta name="dcterms.date" content="$date-meta$" />
+$endif$
+$if(keywords)$
+ <meta name="keywords" content="$for(keywords)$$keywords$$sep$, $endfor$" />
+$endif$
+ <title>$if(title-prefix)$$title-prefix$ – $endif$$pagetitle$</title>
+ <style>
+ $styles.html()$
+ </style>
+$for(css)$
+ <link rel="stylesheet" href="$css$" />
+$endfor$
+$if(math)$
+ $math$
+$endif$
+$for(header-includes)$
+ $header-includes$
+$endfor$
+</head>
+<body>
+$for(include-before)$
+$include-before$
+$endfor$
+<nav>
+ <li><a href="index.html">Home</a></li>
+ <li><a href="boeuf.html">BOEUF</a></li>
+ <li><a href="objects.html">Objects</a></li>
+</nav>
+<main>
+$body$
+</main>
+$for(include-after)$
+$include-after$
+$endfor$
+</body>
+</html>
diff --git a/doc/index.html b/doc/index.html
index 11e0359..3bc590b 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -1,8 +1,32 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
+<head>
+ <meta charset="utf-8" />
+ <meta name="generator" content="pandoc" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
+ <title>bf-pd : index</title>
+ <style>
+ code{white-space: pre-wrap;}
+ span.smallcaps{font-variant: small-caps;}
+ span.underline{text-decoration: underline;}
+ div.column{display: inline-block; vertical-align: top; width: 50%;}
+ div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
+ ul.task-list{list-style: none;}
+ </style>
+ <link rel="stylesheet" href="img/style.css" />
+</head>
+<body>
+<nav>
+ <li><a href="index.html">Home</a></li>
+ <li><a href="boeuf.html">BOEUF</a></li>
+ <li><a href="objects.html">Objects</a></li>
+</nav>
+<main>
<h1 id="bf-pd-a-puredata-external-for-building-digital-orchestras">bf-pd : a PureData external for building Digital Orchestras</h1>
<h2 id="introduction-what-is-bf-pd-and-why-do-you-need-it">Introduction: What is bf-pd and why do you need it?</h2>
<p>Digital instruments allow us to do things that were not possible with purely acoustic instruments. For example musicians can share data between instruments in real-time, in effect creating distributed multi-musician super-instruments. Musicians such as The Hub have been doing this since at least the 1970s. Contemporary digital musicians often write their own software instruments to re-create these functionalities.</p>
<p>Bf-pd is a library built in PureData (Pd) which enables communication and cooperation between digital instruments. Bf-pd can be integrated into any instrument built in Pd. It provides a <em>collaboration window</em> from which musicians can view each others’ activity and share control of instrument parameters and other musical data.</p>
-<p>The design of bf-pd is based on the BOEUF conceptual framework which consists of a classification of modes of collaboration used in collective music performance, and a set of components which affords them. More details on the BOEUF conceptual framework can be found <a href="doc/boeuf.md">on this page</a>.</p>
+<p>The design of bf-pd is based on the BOEUF conceptual framework which consists of a classification of modes of collaboration used in collective music performance, and a set of components which affords them. More details on the BOEUF conceptual framework can be found <a href="boeuf.html">on this page</a>.</p>
<h2 id="installing-bf-pd">Installing bf-pd</h2>
<ul>
<li>Download and install Pure Data (>=0.51) for your operating system from https://puredata.info/downloads/pure-data</li>
@@ -11,7 +35,7 @@
</ul>
<h2 id="getting-started-building-your-instrument">Getting started: Building your instrument</h2>
<figure>
-<img src="doc/img/start.gif" alt="" /><figcaption>doc/img/start.gif</figcaption>
+<img src="img/start.gif" alt="" /><figcaption>doc/img/start.gif</figcaption>
</figure>
<p>Starting from an existing instrument made in PureData :</p>
<ol type="1">
@@ -24,11 +48,11 @@
<h3 id="parameters-and-outputs">Parameters and outputs</h3>
<p><strong>Parameters</strong> correspond to controls you have over your instrument and that you want to share with others.</p>
<figure>
-<img src="doc/img/bf-param.gif" alt="" /><figcaption>doc/img/bf-param.gif</figcaption>
+<img src="img/bf-param.gif" alt="" /><figcaption>doc/img/bf-param.gif</figcaption>
</figure>
<p><strong>Outputs</strong> have the same properties but correspond to musical content produced by your instruments (notes, onsets, envelopes …). They can be used to control others parameters. Three default outputs are automatically created by bf-pd and extracted from the audio you send to bf-instrument : pitch, onsets, loudness.</p>
<figure>
-<img src="doc/img/bf-output.gif" alt="" /><figcaption>doc/img/bf-output.gif</figcaption>
+<img src="img/bf-output.gif" alt="" /><figcaption>doc/img/bf-output.gif</figcaption>
</figure>
<p>Parameters and outputs have the same <strong>arguments</strong> :</p>
<ol type="1">
@@ -44,35 +68,38 @@
<p>To open the collaboration window, simply check the <em>collab</em> toggle in the bf-instrument object.</p>
<p>The leftmost green column shows your instrument with its outputs and parameters. The grey columns show the other instruments in the session with their respective activity, outputs and parameters.</p>
<figure>
-<img src="doc/img/collabwin.png" alt="" /><figcaption>doc/img/collabwin.png</figcaption>
+<img src="img/collabwin.png" alt="" /><figcaption>doc/img/collabwin.png</figcaption>
</figure>
<h3 id="sharing-granting-access-to-your-parameters">Sharing / granting access to your parameters</h3>
<p>By default, all your parameters are in the <em>granted</em> mode, which means that all the other musicians can change your parameter values. You can of course change this by clicking the red <em>grant</em> toggle for each parameter, or the <em>grant all</em> toggle at the top of your column. When your parameter is not granted, values <em>asked</em> by others are only displayed on the gray widgets. You can accept their <em>ask</em> by using the <em>1x</em> bang.</p>
<figure>
-<img src="doc/img/sharing.gif" alt="" /><figcaption>doc/img/sharing.gif</figcaption>
+<img src="img/sharing.gif" alt="" /><figcaption>doc/img/sharing.gif</figcaption>
</figure>
<h3 id="using-others-parameters-and-outputs-to-change-your-parameters">Using others parameters and outputs to change your parameters</h3>
<p>A <em>watch</em> bus selector is placed below each parameter and output of the other instruments. By choosing a bus other than 0, the values are sent to the corresponding bus and can be sent to your parameters connected to the same bus using the <em>watching</em> selector.</p>
<figure>
-<img src="doc/img/watching.gif" alt="" /><figcaption>doc/img/watching.gif</figcaption>
+<img src="img/watching.gif" alt="" /><figcaption>doc/img/watching.gif</figcaption>
</figure>
<h3 id="controlling-others-parameters-with-your-parameters-and-outputs">Controlling others parameters with your parameters and outputs</h3>
<p>Symmetrically, you can control others parameters by choosing a non-zero bus on the <em>ask</em> selector and the same <em>asking</em> bus below one of your outputs or parameters. This requires however that the parameter that you want to controlled is <em>granted</em> (i.e. that the green <em>granted</em> toggle is checked).</p>
<figure>
-<img src="doc/img/asking.gif" alt="" /><figcaption>doc/img/asking.gif</figcaption>
+<img src="img/asking.gif" alt="" /><figcaption>doc/img/asking.gif</figcaption>
</figure>
<h3 id="directly-asking-controlling-others-parameters">Directly asking / controlling others parameters</h3>
<p>You can also ask another instrument’s parameter to be set to a specific value by interacting with the white sliders/toggles/bangs. It the access is granted, the value will be directly set.</p>
<figure>
-<img src="doc/img/direct_asking.gif" alt="" /><figcaption>doc/img/direct_asking.gif</figcaption>
+<img src="img/direct_asking.gif" alt="" /><figcaption>doc/img/direct_asking.gif</figcaption>
</figure>
<h2 id="demo-video">Demo Video</h2>
-<p><a href="https://pod.univ-lille.fr/video/19614-bf-pd-collaboration-window/"><img src="doc/img/video.png" height="300px"/><br/>Video demoing the collab window for bf-pd</a>.</p>
+<p><a href="https://pod.univ-lille.fr/video/19614-bf-pd-collaboration-window/"><img src="img/video.png" height="300px"/><br/>Video demoing the collab window for bf-pd</a>.</p>
<h2 id="more-resources">More resources</h2>
-<p>Documentation for each of the user objects in bf-pd can be found in <a href="doc/objects.md">objects.md</a> and on help patches directly in PureData (right-click an object -> Help)</p>
-<p>The <em>BOEUF conceptual framework</em> describes the <em>modes of collaboration</em> used in musical collaboration and describes a set of <em>components</em> for realizing these modes in a software framework. Bf-pd is based on this framework. More info can be found in <a href="doc/boeuf.md">boeuf.md</a>.</p>
+<p>Documentation for each of the user objects in bf-pd can be found in <a href="objects.html">objects.md</a> and on help patches directly in PureData (right-click an object -> Help)</p>
+<p>The <em>BOEUF conceptual framework</em> describes the <em>modes of collaboration</em> used in musical collaboration and describes a set of <em>components</em> for realizing these modes in a software framework. Bf-pd is based on this framework. More info can be found in <a href="boeuf.html">boeuf.md</a>.</p>
<h2 id="authors">Authors</h2>
<ul>
<li>Luke Dahl, University of Virginia</li>
<li>Florent Berthaut, University of Lille</li>
</ul>
+</main>
+</body>
+</html>
diff --git a/doc/objects.html b/doc/objects.html
index 43880ad..07824e5 100644
--- a/doc/objects.html
+++ b/doc/objects.html
@@ -1,3 +1,27 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
+<head>
+ <meta charset="utf-8" />
+ <meta name="generator" content="pandoc" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
+ <title>bf-pd : objects</title>
+ <style>
+ code{white-space: pre-wrap;}
+ span.smallcaps{font-variant: small-caps;}
+ span.underline{text-decoration: underline;}
+ div.column{display: inline-block; vertical-align: top; width: 50%;}
+ div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
+ ul.task-list{list-style: none;}
+ </style>
+ <link rel="stylesheet" href="img/style.css" />
+</head>
+<body>
+<nav>
+ <li><a href="index.html">Home</a></li>
+ <li><a href="boeuf.html">BOEUF</a></li>
+ <li><a href="objects.html">Objects</a></li>
+</nav>
+<main>
<p>Bf-pd is a library of pd objects for enabling real-time collaboration. This page describes each of the objects in bf-pd, their arguments, inlets and outlets.</p>
<h2 id="bf-session">bf-session</h2>
<p>A bf-session represents a group of musicians (as represented by their bf-instruments) making music together. Within the bf-pd system a bf-session works “behind the scenes†to coordinate the data exchanged between bf-instruments.</p>
@@ -96,3 +120,6 @@
<ol type="1">
<li>blah</li>
</ol>
+</main>
+</body>
+</html>
--
GitLab