-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathindex.html
127 lines (125 loc) · 5.82 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
<!DOCTYPE html>
<html>
<head>
<title>Codemeta + Pandoc Examples</title>
<link href='https://fonts.googleapis.com/css?family=Open+Sans' rel='stylesheet' type='text/css'>
<link rel="stylesheet" href="https://caltechlibrary.github.io/css/site.css">
</head>
<body>
<header>
<a href="http://library.caltech.edu" title="link to Caltech Library Homepage"><img src="https://caltechlibrary.github.io/assets/liblogo.gif" alt="Caltech Library logo"></a>
</header>
<nav>
<ul>
<li><a href="/">Home</a></li>
<li><a href="index.html">README</a></li>
<li><a href="LICENSE">LICENSE</a></li>
<li><a href="about.html">About</a></li>
<li><a href="search.html">Project Search</a></li>
<li><a href="https://github.com/caltechlibrary/curl-installer-sh-example">GitHub</a></li>
</ul>
</nav>
<section>
<h1 id="codemeta-pandoc-examples">Codemeta + Pandoc Examples</h1>
<p>In this repository you see three examples of using Pandoc, Pandoc
templates and codemeta.json to create an <a href="about.html">about
page</a>, a <a href="CITATION.cff">CITATION.cff</a> and an <a
href="https://caltechlibrary.github.io/irdmtools/installer.sh">installer.sh</a>
file.</p>
<h2 id="generating-a-citation.cff">Generating a CITATION.cff</h2>
<p>The codemeta.json file can be use to generate a CITATION.cff file
using the Pandoc template <a
href="codemeta-cff.tmpl">codemeta-cff.tmpl</a>.</p>
<pre class="shell"><code> echo '' | pandoc -s --metadata title='Citation' \
--metadata-file codemeta.json \
--template codemeta-cff.tmpl \
>CITATION.cff</code></pre>
<h2 id="generating-an-about-page">Generating an about page</h2>
<p>Like <a href="CITATION.cff">CITATION.cff</a> we can generate a
standard about page, <a href="about.html">about.md</a> from our
codemeta.json using the Pandoc template <a
href="codemeta-about.tmpl">codemeta-about.tmpl</a>.</p>
<pre class="shell"><code> echo '' | pandoc -s --metadata title='About' \
--metadata-file codemeta.json \
--template codemeta-about.tmpl \
>about.md</code></pre>
<h2 id="generating-version.sql">Generating version.sql</h2>
<p>If you’re building a Postgres+PostgREST application it is nice to
have an end point the shows the name and version of the web application
you are building. This can be done with the <a
href="codemeta-version-sql.tmpl">codemeta-version-sql.tmpl</a> Pandoc
template.</p>
<pre class="shell"><code> echo '' | pandoc -s metadata title='Version Info' \
--metadata-file codemeta.json \
--template codemete-version-sql.tmpl \
>version.sql</code></pre>
<h2 id="generating-an-installer.sh">Generating an installer.sh</h2>
<p>The nice thing about the Pandoc approach is you can also use it as a
shell script generator. Today (2023) many software tools[1] developers
use have installation instructions like</p>
<pre class="shell"><code> curl https://caltechlibrary.github.io/datatools/installer.sh | sh</code></pre>
<p>With a single POSIX shell installer script you easily install your
tools on macOS and Linux.</p>
<p>The codemeta.json file provides much of what is needed to generate
the installer script from <a
href="codemeta-installer.tmpl">codemeta-installer.tmpl</a>. There are
three addition Pandoc metadata variables needed not explicitly found in
the codemeta.json. The installer script expects to use a Zip file as an
q<F5>0Additionally you need to name the zip archive of the content to be
installed needs to be predictably named.</p>
<p>To have Pandoc generate a workable installer script requires to
parts. First the name of your installation zip files need to be
predictable.</p>
<p>Secondly the codemeta-installer.tmpl file needs to know some metadata
inorder for the generated script to be runable.</p>
<p>The [codemeta.json] file provides much of the information needed to
render our <strong>installer.sh</strong>. Our template, does make some
specific assumptions</p>
<ul>
<li>You’ve installation files are in a zip archive</li>
<li>There hosted under the GitHub in the releases directory for your
repository</li>
<li>The name of the zip file is in the form of
<code><PACKAGE>-v<VERSION>-<OS_NAME>-<ARCHITECTURE>.zip</code></li>
<li>The version number in the codemeta.json file does NOT have a leading
‘v’</li>
<li>curl is available on the machine where you want to install the
software and it has a network connection</li>
</ul>
<dl>
<dt>PACKAGE</dt>
<dd>
This would be the name of your Git repository, e.g. datatools
</dd>
<dt>VERSION</dt>
<dd>
This would be the version number without the leading “v”, e.g. “0.0.1”
</dd>
<dt>OS_NAME</dt>
<dd>
would be “macOS”, “Linux” or “Windows”
</dd>
<dt>MACHINE-TYPE</dt>
<dd>
This would be what is reported by the command <code>uname -m</code>
</dd>
</dl>
<p>Rendering the <strong>installer.sh</strong> file can be done with the
following Pandoc command.</p>
<pre><code>echo '' | pandoc -s --metadata title='Installer' \
--metadata-file codemeta.json \
--template installer.sh</code></pre>
<p>If you host this installer script can then be uploaded to your
website. The curl command would be of the form</p>
<pre><code> curl <URL_TO_SITE>/installer.sh | sh</code></pre>
<p>[1]: Examples Rust with <a href="https://rustup.rs/">Rustup</a> and
Haskell’s <a href="https://www.haskell.org/ghcup/">GHCup</a></p>
</section>
<footer>
<span>© 2023 <a href="https://www.library.caltech.edu/copyright">Caltech Library</a></span>
<address>1200 E California Blvd, Mail Code 1-32, Pasadena, CA 91125-3200</address>
<span><a href="mailto:[email protected]">Email Us</a></span>
<span>Phone: <a href="tel:+1-626-395-3405">(626)395-3405</a></span>
</footer>
</body>
</html>