2022-04-28 15:00:22 +00:00
|
|
|
# Inweb 7.1.0
|
2020-03-23 21:39:27 +00:00
|
|
|
|
2022-08-09 09:04:38 +00:00
|
|
|
v7.1.0-beta+1B14 'Escape to Danger' (9 August 2022)
|
2019-03-12 23:32:12 +00:00
|
|
|
|
|
|
|
## About Inweb
|
|
|
|
|
2019-03-18 11:16:10 +00:00
|
|
|
Inweb offers a modern approach to literate programming. Unlike the original
|
|
|
|
LP tools of the late 1970s, led by Donald Knuth, or of the 1990s revival,
|
|
|
|
Inweb aims to serve programmers in the Github age. It scales to much larger
|
|
|
|
programs than CWEB, and since 2004 has been the tool used by the
|
2019-03-18 11:24:26 +00:00
|
|
|
[Inform programming language project](https://github.com/ganelson/inform),
|
2019-03-18 11:16:10 +00:00
|
|
|
where it manages a 300,000-line code base.
|
2019-03-12 23:32:12 +00:00
|
|
|
|
2019-03-18 11:16:10 +00:00
|
|
|
Literate programming is a methodology created by Donald Knuth in the late
|
|
|
|
1970s. A literate program, or "web", is written as a narrative intended to
|
2022-04-24 11:07:47 +00:00
|
|
|
be readable by humans as well as by other programs. Inweb is itself written as
|
2022-04-28 15:25:04 +00:00
|
|
|
a web, and its human-readable form is a [companion website to this one](https://ganelson.github.io/inweb/index.html).
|
2019-03-12 23:32:12 +00:00
|
|
|
|
2022-04-28 15:25:04 +00:00
|
|
|
For the Inweb manual, see [★ inweb/Preliminaries](https://ganelson.github.io/inweb/inweb/M-iti).
|
2019-03-18 11:16:10 +00:00
|
|
|
|
2022-04-24 09:36:52 +00:00
|
|
|
## Licence and copyright
|
2019-03-17 12:53:52 +00:00
|
|
|
|
|
|
|
Except as noted, copyright in material in this repository (the "Package") is
|
|
|
|
held by Graham Nelson (the "Author"), who retains copyright so that there is
|
|
|
|
a single point of reference. As from the first date of this repository
|
2022-04-28 14:49:28 +00:00
|
|
|
becoming public, 28 April 2022, the Package is placed under the
|
|
|
|
[Artistic License 2.0](https://opensource.org/licenses/Artistic-2.0).
|
2019-03-17 12:53:52 +00:00
|
|
|
This is a highly permissive licence, used by Perl among other notable projects,
|
|
|
|
recognised by the Open Source Initiative as open and by the Free Software
|
|
|
|
Foundation as free in both senses.
|
|
|
|
|
2022-04-24 09:36:52 +00:00
|
|
|
A condition of any pull-request being made (i.e., to make suggested amendments
|
|
|
|
to this software) is that, if the request is accepted, copyright on any contribution
|
|
|
|
made by it immediately transfers to the project's copyright-holder, Graham Nelson.
|
|
|
|
This is in order that there can be clear ownership.
|
|
|
|
|
2019-03-12 23:32:12 +00:00
|
|
|
## Build Instructions
|
|
|
|
|
2019-03-18 11:16:10 +00:00
|
|
|
Inweb is intentionally self-sufficient, with no dependencies on any other
|
|
|
|
software beyond a modern C compiler. However, it does in a sense depend on
|
|
|
|
itself: because Inweb is itself a web, you need Inweb to compile Inweb.
|
2019-03-25 23:33:12 +00:00
|
|
|
Getting around that circularity means that the initial setup takes a few steps.
|
|
|
|
|
|
|
|
Make a directory in which to work: let's call this "work". Then:
|
2019-03-12 23:32:12 +00:00
|
|
|
|
2019-03-18 11:16:10 +00:00
|
|
|
* Change the current directory to this: "cd work"
|
2019-03-25 23:28:06 +00:00
|
|
|
* Clone Inweb: "git clone https://github.com/ganelson/inweb.git"
|
2022-04-30 16:12:14 +00:00
|
|
|
* Run **one of the following commands**.
|
2022-04-23 23:40:37 +00:00
|
|
|
* "bash inweb/scripts/first.sh linux"
|
|
|
|
* "bash inweb/scripts/first.sh macos"
|
|
|
|
* "bash inweb/scripts/first.sh macos32"
|
2022-04-30 16:12:14 +00:00
|
|
|
* "bash inweb/scripts/first.sh macosarm"
|
|
|
|
* "bash inweb/scripts/first.sh macosuniv"
|
2022-04-23 23:40:37 +00:00
|
|
|
* "bash inweb/scripts/first.sh unix"
|
|
|
|
* "bash inweb/scripts/first.sh windows"
|
2019-03-18 11:16:10 +00:00
|
|
|
* Test that all is well: "inweb/Tangled/inweb -help"
|
|
|
|
|
2022-04-30 16:12:14 +00:00
|
|
|
Some notes on which platform to choose:
|
|
|
|
* For Intel Macs running MacOS 10.13 ("High Sierra") or earlier, use macos32.
|
|
|
|
This will produce 32-bit x86 executables; we are no longer really supporting this.
|
|
|
|
* For Intel Macs running MacOS 10.14 ("Mojave"), use macos. This will produce
|
|
|
|
64-bit x86 executables.
|
|
|
|
* For Apple Silicon Macs, use macosarm. This will produce 64-bit ARM executables.
|
|
|
|
* To produce universal binaries (64-bit x86 and ARM combined) on Apple Silicon
|
|
|
|
Macs, use macosuniv, but expect your compilation times to double, of course.
|
|
|
|
* For a generic version of Unix where the Linux settings do not work, try using
|
|
|
|
unix. (For Solaris, for example.)
|
|
|
|
* Android support has existed in the past, but the Android Inform community
|
|
|
|
has not yet an opportunity to contribute build settings.
|
|
|
|
|
2022-04-23 23:40:37 +00:00
|
|
|
You should now have a working copy of Inweb, with its own makefile tailored
|
|
|
|
to your platform now in place (at inweb/inweb.mk). To build inweb again, e.g.
|
|
|
|
after editing inweb's source code, do not run the shell script first.sh again.
|
2022-04-23 23:44:16 +00:00
|
|
|
Instead, you must use: "make -f inweb/inweb.mk"
|
2022-04-23 23:40:37 +00:00
|
|
|
|
|
|
|
If you wish to tweak the makefile, do not edit it directly. Instead,
|
|
|
|
edit inweb/scripts/inweb.mkscript and inweb/Materials/platforms/PLATFORM.mkscript,
|
|
|
|
where PLATFORM is your choice as above (e.g., 'macos'). Then run "make -f inweb/inweb.mk makers"
|
2022-04-23 23:44:16 +00:00
|
|
|
to rebuild all these makefiles with your changes incorporated; and then run
|
2022-04-23 23:40:37 +00:00
|
|
|
the shell script "inweb/scripts/first.sh" again.
|
2019-03-18 11:16:10 +00:00
|
|
|
|
2022-05-20 22:31:56 +00:00
|
|
|
A few features of inweb used when integrating the core Inform software into its
|
|
|
|
apps rely on having the standard Unix tool "rsync" installed: so on Linux, where
|
|
|
|
not all installations provide rsync by default, you may want to install this if
|
|
|
|
you are intending to do development work with the Inform apps. But since rsync
|
|
|
|
is not needed for the core literate-programming functions of inweb, most users
|
|
|
|
will have no need.
|
|
|
|
|
2022-04-24 09:36:52 +00:00
|
|
|
## Reporting Issues
|
|
|
|
|
|
|
|
The bug tracker for Inweb is powered by Jira and hosted
|
|
|
|
[at the Atlassian website](https://inform7.atlassian.net/jira/software/c/projects/INWEB/issues).
|
|
|
|
(Note that Inform, Inweb and Intest are three different projects in Jira: please
|
|
|
|
do not report Inweb issues on the Inform bug tracker or vice versa.)
|
|
|
|
|
|
|
|
The curator of the bug tracker is Brian Rushton, and the administrator is
|
|
|
|
Hugo Labrande.
|
|
|
|
|
|
|
|
## Pull Requests and Adding Features
|
|
|
|
|
|
|
|
Substantially different versions of Inweb have been open-source before, but this
|
|
|
|
version is essentially a fresh reimplementation with a different design. It is
|
|
|
|
the curse of literate-programming tools that they serve only their own authors,
|
|
|
|
that is, few LP tools please users other than the creators: thus, only Knuth
|
|
|
|
really uses CWEB, for example. But perhaps that will change. It's time for LP
|
|
|
|
to be tried again, and Inweb may be a start.
|
|
|
|
|
|
|
|
For the moment, however, Inweb's future direction remains in the hands of the
|
|
|
|
original author. It needs to be reliable and to keep the Inform and Intest projects
|
|
|
|
working, as well as itself.
|
|
|
|
|
|
|
|
At some point a more formal process may emerge, but for now community discussion
|
|
|
|
of possible features is best kept to the IF forum. In particular, please do not
|
|
|
|
use the bug trackers to propose new features.
|
|
|
|
|
|
|
|
Pull requests adding functionality or making any significant changes are therefore
|
|
|
|
not likely to be accepted from non-members of the wider Inform team without prior
|
|
|
|
agreement, unless they are clear-cut bug fixes or corrections of typos, broken
|
|
|
|
links, or similar. See also the note about copyright above.
|
|
|
|
|
|
|
|
The Inweb licence is highly permissive, and forks which develop in quite different
|
|
|
|
ways are entirely within the rules. (But one of the few requirements of the
|
|
|
|
Artistic Licence is that such forks be given a name which is not simply "Inweb",
|
|
|
|
to avoid confusion.)
|
|
|
|
|
2019-03-18 11:16:10 +00:00
|
|
|
## Also Included
|
|
|
|
|
|
|
|
Inweb contains a substantial library of code shared by a number of other
|
2019-03-18 11:24:26 +00:00
|
|
|
programs, such as the [Intest testing tool](https://github.com/ganelson/intest)
|
|
|
|
and the [Inform compiler and related tools](https://github.com/ganelson/inform).
|
2019-03-18 11:16:10 +00:00
|
|
|
|
|
|
|
This library is called "Foundation", and has its own web
|
2022-04-28 15:25:04 +00:00
|
|
|
here: [★ foundation-module](https://ganelson.github.io/inweb/foundation-module/index.html).
|
2019-03-18 11:16:10 +00:00
|
|
|
|
|
|
|
A small executable for running unit tests against Foundation is also included:
|
2022-04-28 15:25:04 +00:00
|
|
|
[★ foundation-test](https://ganelson.github.io/inweb/foundation-test/index.html).
|
2019-03-18 11:16:10 +00:00
|
|
|
|
|
|
|
## Testing Inweb
|
|
|
|
|
|
|
|
If you have also built Intest as "work/intest", then you can try these:
|
|
|
|
|
|
|
|
* intest/Tangled/intest inweb all
|
|
|
|
* intest/Tangled/intest inweb/foundation-test all
|
|
|
|
|
|
|
|
### Colophon
|
|
|
|
|
2020-03-23 21:39:27 +00:00
|
|
|
This README.mk file was generated automatically by Inweb, and should not
|
2022-04-23 22:41:01 +00:00
|
|
|
be edited. To make changes, edit inweb.rmscript and re-generate.
|
2019-03-12 23:32:12 +00:00
|
|
|
|