Skip to content

Commit 8d9ac4c

Browse files
author
R. S. Doiel
committed
sketched some notes on where CMTools could go
1 parent e7a6969 commit 8d9ac4c

9 files changed

+227
-1
lines changed

‎pagefind/fragment/en-US_80465e4.pf_fragment

258 Bytes
Binary file not shown.

‎pagefind/fragment/en-US_9dac604.pf_fragment

2.25 KB
Binary file not shown.

‎pagefind/index/en-US_2278a72.pf_index

11.2 KB
Binary file not shown.

‎pagefind/pagefind-entry.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
{"version":"1.3.0","languages":{"en-US":{"hash":"en-US_27eff27688f6f","wasm":"en-US","page_count":8}}}
1+
{"version":"1.3.0","languages":{"en-US":{"hash":"en-US_357fada4835b9","wasm":"en-US","page_count":9}}}

‎pagefind/pagefind.en-US_357fada4835b9.pf_meta

171 Bytes
Binary file not shown.

‎someday_maybe.html

+142
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
<html lang="en-US">
2+
<head>
3+
<title>CMTools</title>
4+
<link rel="stylesheet" href="/css/site.css">
5+
</head>
6+
<body>
7+
<nav>
8+
<ul>
9+
<li><a href="/">Home</a></li>
10+
<li><a href="index.html">README</a></li>
11+
<li><a href="LICENSE">LICENSE</a></li>
12+
<li><a href="INSTALL.html">INSTALL</a></li>
13+
<li><a href="user_manual.html">User Manual</a></li>
14+
<li><a href="about.html">About</a></li>
15+
<li><a href="search.html">Search</a></li>
16+
<li><a href="https://github.com/caltechlibrary/CMTools">GitHub</a></li>
17+
</ul>
18+
</nav>
19+
<section>
20+
<h1 id="someday-maybe">Someday, maybe</h1>
21+
<p>CMTools is currently just a working proof of concept. It is intended
22+
to show the benefits could be pursuing the project to a stable and
23+
sustainable conclusion. What might the next steps look like?</p>
24+
<p>What follows is a hypothetical roadmap, not a promise of
25+
implementation. That’s why this document is called “Someday, maybe”.</p>
26+
<h2 id="files-should-be-generator">Files should be generator</h2>
27+
<h3 id="readme.md-readme.txt-readme">README.md, README.txt, README</h3>
28+
<p>Assuming the README is a basic brief document describing the
29+
document. This could be generated completely from the CodeMeta data. It
30+
probably should be as the important parts of the README are covered by
31+
the following CodeMeta attributes</p>
32+
<dl>
33+
<dt><code>.name</code></dt>
34+
<dd>
35+
Name of the project
36+
</dd>
37+
<dt><code>.description</code></dt>
38+
<dd>
39+
Provides a <strong>short</strong> high level view of the project
40+
</dd>
41+
<dt><code>.releaseNotes</code></dt>
42+
<dd>
43+
Provides a brief summery of recent changes
44+
</dd>
45+
<dt><code>.version</code> and <code>.dateReleased</code></dt>
46+
<dd>
47+
The version and date release info
48+
</dd>
49+
<dt><code>.relatedUrls</code></dt>
50+
<dd>
51+
Provides links to more detail
52+
</dd>
53+
<dt><code>.operatingSystem</code>, <code>.runtimePlatform</code> and
54+
<code>.softwareRequirements</code></dt>
55+
<dd>
56+
provide the important software context
57+
</dd>
58+
<dt><code>.license</code></dt>
59+
<dd>
60+
Provides a URL to the Open Source license used
61+
</dd>
62+
<dt><code>.codeRepository</code> and <code>.issueTracker</code></dt>
63+
<dd>
64+
Provide where to find the project and how to communicate with the
65+
project owner(s)
66+
</dd>
67+
<dt><code>.author</code>, <code>.contributor</code> and
68+
<code>.maintainer</code></dt>
69+
<dd>
70+
Provide additional contact information as well as important citation
71+
information
72+
</dd>
73+
</dl>
74+
<p>All that data is recommended to be provided in a README. It can be
75+
reduced to boiler plate. Why don’t we just generate the README document
76+
from the CodeMeta?</p>
77+
<h3 id="install.md-install.txt-install">INSTALL.md, INSTALL.txt,
78+
INSTALL</h3>
79+
<p>Installation documents tend to wind up being very similar like a well
80+
assembled README. Also the practice of curating a simple net based
81+
install script (e.g. installer.sh, installer.ps1) has become a common
82+
practice for non-commercial software. It maybe possible to reduce much
83+
of the INSTALL file just as we did with the README. The installer
84+
scripts can be generated from the CodeMeta and the quick install via
85+
curl/sh (POSIX) or irm/iex (Windows) can easy be generated based on a
86+
stable practice. The prologue to the build from source description
87+
similarly can be generated. If we can assume the steps work the same on
88+
Windows as well as POSIX then a simple formula can be generated for
89+
building the project from source.</p>
90+
<pre><code>deno task configure
91+
deno task build
92+
deno task test
93+
deno task install</code></pre>
94+
<p>Since Deno tasks can be written similarly regardless of POSIX or
95+
Windows operating system it makes sense to include something similar as
96+
boiler plate. If you do provide POSIX a Makefile then you could also
97+
include the recipe of</p>
98+
<pre><code>./configure --prefix=$HOME
99+
make
100+
make test
101+
make install</code></pre>
102+
<h3 id="deno.json-and-using-deno-to-manage-your-build-process">deno.json
103+
and using Deno to manage your build process</h3>
104+
<p>While Deno should create the <code>deno.json</code> file, CMTools can
105+
manage to tasks based on a predefined vocabulary, (e.g. “configure”,
106+
“build”, “test”, “install”). Additional Deno tasks can be used to build
107+
projects that do not involve TypeScript or JavaScript. Deno tasks can
108+
also provide TypeScript support for more complex build operations that
109+
are maintained on a website like <a
110+
href="https://caltechlibrary/CMTools"
111+
class="uri">https://caltechlibrary/CMTools</a>.</p>
112+
<h2 id="how-do-you-manage-your-codemeta.json-file">How do you manage
113+
your “codemeta.json” file?</h2>
114+
<p>The CodeMeta file content is represented in JSON. JSON can be tedious
115+
to manually edit by hand. I usually rely on the <a
116+
href="https://codemeta.github.io/codemeta-generator/">CodeMeta
117+
Generator</a> for this chore. But even that isn’t ideal. This is
118+
particularly true if you are using the description attribute to describe
119+
your project in more detail. While links are easy enough to extract can
120+
check with cURL spell check is troublesome for the description
121+
attribute. What you will want is to be able to review your CodeMeta file
122+
and easily edit it.</p>
123+
<p>One approach would be to write and maintain your CodeMeta in
124+
equivalent YAML or TOML. But that approach means on more layer of
125+
abstraction to manage and one more point of synchronization (at least
126+
until someone decides codemeta.yaml, codemeta.toml are equivalent to
127+
codemeta.json).</p>
128+
<p>A better approach would be a for CMTools to provide something like a
129+
<code>cmedit</code> command. This would let you create or edit a
130+
CodeMeta file much as the CodeMeta generator does but it should also
131+
allow you to pop out specific elements into your favorite text editor
132+
(e.g. like cron edit does). This would allow for more comfortable
133+
editing as well as easier spell checking. The advantage of a tool like
134+
this would be that you can always reading a older version of CodeMeta
135+
and then write out a normalized version you can rely on. It also means
136+
you can work completely off line and avoid a tedious copy/edit
137+
cycle.</p>
138+
<p>Making it preferable to manage your project metadata in the CodeMeta
139+
file lowers the friction in maintaining your software.</p>
140+
</section>
141+
</body>
142+
</html>

‎someday_maybe.md

+81
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
title: Someday, maybe
3+
keywords:
4+
- roadmap
5+
---
6+
7+
# Someday, maybe
8+
9+
CMTools is currently just a working proof of concept. It is intended to show the benefits could be pursuing the project to a stable and sustainable conclusion. What might the next steps look like?
10+
11+
What follows is a hypothetical roadmap, not a promise of implementation. That's why this document is called "Someday, maybe".
12+
13+
## Files should be generator
14+
15+
### README.md, README.txt, README
16+
17+
Assuming the README is a basic brief document describing the document. This could be generated completely from the CodeMeta data. It probably should be as the important parts of the README are covered by the following CodeMeta attributes
18+
19+
`.name`
20+
: Name of the project
21+
22+
`.description`
23+
: Provides a **short** high level view of the project
24+
25+
`.releaseNotes`
26+
: Provides a brief summery of recent changes
27+
28+
`.version` and `.dateReleased`
29+
: The version and date release info
30+
31+
`.relatedUrls`
32+
: Provides links to more detail
33+
34+
`.operatingSystem`, `.runtimePlatform` and `.softwareRequirements`
35+
: provide the important software context
36+
37+
`.license`
38+
: Provides a URL to the Open Source license used
39+
40+
`.codeRepository` and `.issueTracker`
41+
: Provide where to find the project and how to communicate with the project owner(s)
42+
43+
`.author`, `.contributor` and `.maintainer`
44+
: Provide additional contact information as well as important citation information
45+
46+
All that data is recommended to be provided in a README. It can be reduced to boiler plate. Why don't we just generate the README document from the CodeMeta?
47+
48+
### INSTALL.md, INSTALL.txt, INSTALL
49+
50+
Installation documents tend to wind up being very similar like a well assembled README. Also the practice of curating a simple net based install script (e.g. installer.sh, installer.ps1) has become a common practice for non-commercial software. It maybe possible to reduce much of the INSTALL file just as we did with the README. The installer scripts can be generated from the CodeMeta and the quick install via curl/sh (POSIX) or irm/iex (Windows) can easy be generated based on a stable practice. The prologue to the build from source description similarly can be generated. If we can assume the steps work the same on Windows as well as POSIX then a simple formula can be generated for building the project from source.
51+
52+
```
53+
deno task configure
54+
deno task build
55+
deno task test
56+
deno task install
57+
```
58+
59+
Since Deno tasks can be written similarly regardless of POSIX or Windows operating system it makes sense to include something similar as boiler plate. If you do provide POSIX a Makefile then you could also include the recipe of
60+
61+
```
62+
./configure --prefix=$HOME
63+
make
64+
make test
65+
make install
66+
```
67+
68+
### deno.json and using Deno to manage your build process
69+
70+
While Deno should create the `deno.json` file, CMTools can manage to tasks based on a predefined vocabulary, (e.g. "configure", "build", "test", "install"). Additional Deno tasks can be used to build projects that do not involve TypeScript or JavaScript. Deno tasks can also provide TypeScript support for more complex build operations that are maintained on a website like <https://caltechlibrary/CMTools>.
71+
72+
## How do you manage your "codemeta.json" file?
73+
74+
The CodeMeta file content is represented in JSON. JSON can be tedious to manually edit by hand. I usually rely on the [CodeMeta Generator](https://codemeta.github.io/codemeta-generator/) for this chore. But even that isn't ideal. This is particularly true if you are using the description attribute to describe your project in more detail. While links are easy enough to extract can check with cURL spell check is troublesome for the description attribute. What you will want is to be able to review your CodeMeta file and easily edit it.
75+
76+
One approach would be to write and maintain your CodeMeta in equivalent YAML or TOML. But that approach means on more layer of abstraction to manage and one more point of synchronization (at least until someone decides codemeta.yaml, codemeta.toml are equivalent to codemeta.json).
77+
78+
A better approach would be a for CMTools to provide something like a `cmedit` command. This would let you create or edit a CodeMeta file much as the CodeMeta generator does but it should also allow you to pop out specific elements into your favorite text editor (e.g. like cron edit does). This would allow for more comfortable editing as well as easier spell checking. The advantage of a tool like this would be that you can always reading a older version of CodeMeta and then write out a normalized version you can rely on. It also means you can work completely off line and avoid a tedious copy/edit cycle.
79+
80+
Making it preferable to manage your project metadata in the CodeMeta file lowers the friction in maintaining your software.
81+

‎user_manual.html

+2
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,8 @@ <h1 id="user-manual">User Manual</h1>
2828
<ul>
2929
<li><a href="presentations/presentation1.html">Proof of concept</a></li>
3030
</ul></li>
31+
<li><a href="someday_maybe.html">Someday, maybe</a>, a hypthetical
32+
roadmap</li>
3133
</ul>
3234
</section>
3335
</body>

‎user_manual.md

+1
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,5 @@
66
- [cmt](cmt.1.md) command
77
- Presentations
88
- [Proof of concept](presentations/presentation1.html)
9+
- [Someday, maybe](someday_maybe.md), a hypthetical roadmap
910

0 commit comments

Comments
 (0)