mirror of
https://github.com/ganelson/inform.git
synced 2024-07-16 22:14:23 +03:00
191 lines
11 KiB
HTML
191 lines
11 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>A Guide to Project Metadata</title>
|
|
<link href="../docs-assets/Breadcrumbs.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<meta name="viewport" content="width=device-width initial-scale=1">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<meta http-equiv="Content-Language" content="en-gb">
|
|
|
|
<link href="../docs-assets/Contents.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Progress.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Navigation.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Fonts.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Base.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Colours.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
|
|
</head>
|
|
<body class="commentary-font">
|
|
<nav role="navigation">
|
|
<h1><a href="../index.html">
|
|
<img src="../docs-assets/Inform.png" height=72">
|
|
</a></h1>
|
|
<ul><li><a href="../index.html">home</a></li>
|
|
</ul><h2>Compiler</h2><ul>
|
|
<li><a href="../structure.html">structure</a></li>
|
|
<li><a href="../inbuildn.html">inbuild</a></li>
|
|
<li><a href="../inform7n.html">inform7</a></li>
|
|
<li><a href="../intern.html">inter</a></li>
|
|
<li><a href="../services.html">services</a></li>
|
|
<li><a href="../secrets.html">secrets</a></li>
|
|
</ul><h2>Other Tools</h2><ul>
|
|
<li><a href="../inblorbn.html">inblorb</a></li>
|
|
<li><a href="../indocn.html">indoc</a></li>
|
|
<li><a href="../inform6.html">inform6</a></li>
|
|
<li><a href="../inpolicyn.html">inpolicy</a></li>
|
|
<li><a href="../inrtpsn.html">inrtps</a></li>
|
|
</ul><h2>Resources</h2><ul>
|
|
<li><a href="../extensions.html">extensions</a></li>
|
|
<li><a href="../kits.html">kits</a></li>
|
|
</ul><h2>Repository</h2><ul>
|
|
<li><a href="https://github.com/ganelson/inform"><img src="../docs-assets/github.png" height=18> github</a></li>
|
|
</ul><h2>Related Projects</h2><ul>
|
|
<li><a href="../../../inweb/index.html">inweb</a></li>
|
|
<li><a href="../../../intest/index.html">intest</a></li>
|
|
|
|
</ul>
|
|
</nav>
|
|
<main role="main">
|
|
<!--Weave of 'A Guide to Project Metadata' generated by Inweb-->
|
|
<div class="breadcrumbs">
|
|
<ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="index.html">inbuild</a></li><li><a href="index.html#M">Manual</a></li><li><b>A Guide to Project Metadata</b></li></ul></div>
|
|
<p class="purpose">Provisional documentation on giving Inform projects JSON-based metadata.</p>
|
|
|
|
<ul class="toc"><li><a href="M-agtpm.html#SP1">§1. This is optional</a></li><li><a href="M-agtpm.html#SP2">§2. JSON metadata for projects</a></li></ul><hr class="tocbar">
|
|
|
|
<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></a><b>§1. This is optional. </b>An Inform project does not normally need a metadata file to be used. At present,
|
|
the only circumstances where this file would be actually necessary would be
|
|
if the project needs to include non-standard kits of Inter code. (And even
|
|
then, it's not needed to specify the language-of-play kit to use, so merely
|
|
writing an Inform project to make a Spanish story, say, does not count as a
|
|
"non-standard" kit.)
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></a><b>§2. JSON metadata for projects. </b>Like kits and language bundles, projects can be described by "metadata files"
|
|
written in JSON format.
|
|
</p>
|
|
|
|
<p class="commentary">Such a file must be called "project_metadata.json" and be placed in the materials
|
|
directory for the project. (Note: not the .inform directory.)
|
|
</p>
|
|
|
|
<p class="commentary">This is a JSON file very similar to the ones used for kit metadata: see <a href="M-agtk.html" class="internal">A Guide to Kits</a>,
|
|
which it is probably helpful to read before going much further with this.
|
|
</p>
|
|
|
|
<p class="commentary">For example:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax">{</span>
|
|
<span class="plain-syntax"> "is": {</span>
|
|
<span class="plain-syntax"> "type": "project",</span>
|
|
<span class="plain-syntax"> "title": "St Anne Passion",</span>
|
|
<span class="plain-syntax"> "author": "Hermione Marmalade",</span>
|
|
<span class="plain-syntax"> "version": "3.2"</span>
|
|
<span class="plain-syntax"> },</span>
|
|
<span class="plain-syntax"> "needs": [ {</span>
|
|
<span class="plain-syntax"> "need": {</span>
|
|
<span class="plain-syntax"> "type": "kit",</span>
|
|
<span class="plain-syntax"> "title": "CommandParserKit"</span>
|
|
<span class="plain-syntax"> }</span>
|
|
<span class="plain-syntax"> }, {</span>
|
|
<span class="plain-syntax"> "need": {</span>
|
|
<span class="plain-syntax"> "type": "kit",</span>
|
|
<span class="plain-syntax"> "title": "ChoraleKit"</span>
|
|
<span class="plain-syntax"> "version": "4.1.1"</span>
|
|
<span class="plain-syntax"> }</span>
|
|
<span class="plain-syntax"> } ]</span>
|
|
<span class="plain-syntax">}</span>
|
|
</pre>
|
|
<p class="commentary">This example tells inbuild, and hence inform7, that the project is a command-parser
|
|
work of IF, but that it also needs an unusual extra kit called "ChoraleKit".
|
|
Moreover, it will build only with a version of that kit compatible (in the semantic
|
|
version number sense) with v4.1.1.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>§3. </b>The <span class="extract"><span class="extract-syntax">is</span></span> object identifies the project. Note that the type must be <span class="extract"><span class="extract-syntax">"project"</span></span>,
|
|
and that the title and author must both be given, and must exactly match what
|
|
the bibliographic sentence at the top of the source text. (If the work is
|
|
anonymous or untitled, the author or title must be the empty text, but they
|
|
must still be given.) It is an error for the source text and the metadata file
|
|
to disagree about this, and inbuild and inform7 will halt with a problem message
|
|
if they do.
|
|
</p>
|
|
|
|
<p class="commentary">The <span class="extract"><span class="extract-syntax">is.version</span></span> is optional. If given, it must be a valid semantic version
|
|
number. The major part of that semver is then used as the value of the
|
|
"release number" variable; this must not contradict what the source text says.
|
|
For example, if <span class="extract"><span class="extract-syntax">is.version</span></span> is <span class="extract"><span class="extract-syntax">"3.2"</span></span>, then an IF story if built from this
|
|
project would identify itself as Release 3. If the sentence contained
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="identifier-syntax">The</span><span class="plain-syntax"> </span><span class="identifier-syntax">release</span><span class="plain-syntax"> </span><span class="identifier-syntax">number</span><span class="plain-syntax"> </span><span class="identifier-syntax">is</span><span class="plain-syntax"> </span><span class="constant-syntax">3</span><span class="plain-syntax">.</span>
|
|
</pre>
|
|
<p class="commentary">that would cause no problems; but if it contained
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="identifier-syntax">The</span><span class="plain-syntax"> </span><span class="identifier-syntax">release</span><span class="plain-syntax"> </span><span class="identifier-syntax">number</span><span class="plain-syntax"> </span><span class="identifier-syntax">is</span><span class="plain-syntax"> </span><span class="constant-syntax">5</span><span class="plain-syntax">.</span>
|
|
</pre>
|
|
<p class="commentary">then Inform would halt with a problem message about the contradiction.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP4" class="paragraph-anchor"></a><b>§4. </b>The <span class="extract"><span class="extract-syntax">needs</span></span> object identifies any kits to be included with the project when
|
|
it is built, other than BasicInformKit.
|
|
</p>
|
|
|
|
<p class="commentary">So for a Basic Inform only project, which uses a version of the Inform language
|
|
with no IF-like ingredients, no command parser, and no world model, there is
|
|
no need to have a <span class="extract"><span class="extract-syntax">needs</span></span> object at all. But for a more standard use of Inform
|
|
to make command-parser IF, CommandParserKit must be included, like so:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> "needs": [ {</span>
|
|
<span class="plain-syntax"> "need": {</span>
|
|
<span class="plain-syntax"> "type": "kit",</span>
|
|
<span class="plain-syntax"> "title": "CommandParserKit"</span>
|
|
<span class="plain-syntax"> }</span>
|
|
<span class="plain-syntax"> } ]</span>
|
|
</pre>
|
|
<p class="commentary">Because kits can include other kits automatically, other kits may well be
|
|
included too (for example, the presence of CommandParserKit causes WorldModelKit
|
|
also to be used). Those additional kits also do not need to be specified here.
|
|
The language of play can also include kits automatically (for example, if the
|
|
language of play is English, then EnglishLanguageKit is included). That too does
|
|
not need to be specified.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP5" class="paragraph-anchor"></a><b>§5. </b>Project metadata can also specify that given named compiler features should
|
|
be active or inactive when compiling this project. For example, suppose the
|
|
compiler has an experimental feature called <span class="extract"><span class="extract-syntax">fruit cultivation</span></span>, switched
|
|
off by default, and a project needs to test this. It can do so by specifying:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> "activates": [ "fruit cultivation" ],</span>
|
|
</pre>
|
|
<p class="commentary">Similarly for <span class="extract"><span class="extract-syntax">"deactivates"</span></span>. Both clauses are optional and take a list of
|
|
feature names: those features must all exist inside the compiler, or a
|
|
problem will be thrown on compilation. (Note that the JSON here is identical
|
|
to that which kits can also offer: kits can also turn features on or off.)
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP6" class="paragraph-anchor"></a><b>§6. </b>Finally, note that the <span class="extract"><span class="extract-syntax">-basic</span></span> switch at the Inbuild or Inform command line,
|
|
which signals that the project being compiled is for the Basic Inform language,
|
|
is still legal to use if a project metadata file exists, but only so long as
|
|
the metadata does not specify CommandParserKit or WorldModelKit: if it does,
|
|
use of <span class="extract"><span class="extract-syntax">-basic</span></span> throws a problem.
|
|
</p>
|
|
|
|
<nav role="progress"><div class="progresscontainer">
|
|
<ul class="progressbar"><li class="progressprev"><a href="M-agtlb.html">❮</a></li><li class="progresscurrentchapter">M</li><li class="progresssection"><a href="M-ui.html">ui</a></li><li class="progresssection"><a href="M-agtk.html">agtk</a></li><li class="progresssection"><a href="M-agtlb.html">agtlb</a></li><li class="progresscurrent">agtpm</li><li class="progresssection"><a href="M-agtr.html">agtr</a></li><li class="progresssection"><a href="M-rc.html">rc</a></li><li class="progresschapter"><a href="1-mn.html">1</a></li><li class="progressnext"><a href="M-agtr.html">❯</a></li></ul></div>
|
|
</nav><!--End of weave-->
|
|
|
|
</main>
|
|
</body>
|
|
</html>
|
|
|