2022-04-23 22:41:01 +00:00
# Inweb {bibliographic datum: Version Number of: inweb}
2020-03-23 21:39:27 +00:00
2022-04-23 22:41:01 +00:00
v{bibliographic datum: Semantic Version Number of: inweb} '{bibliographic datum: Version Name of: inweb}' ({bibliographic datum: Build Date of: inweb})
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
be readable by humans as well as by other programs. The human-readable form
for Inweb (which is itself a web) is here: [★ inweb](docs/inweb/index.html).
2019-03-12 23:32:12 +00:00
2020-03-22 11:24:10 +00:00
For the Inweb manual, see [★ inweb/Preliminaries](docs/inweb/M-iti).
2019-03-18 11:16:10 +00:00
__Disclaimer__. Because this is a private repository (until the next public
release of Inform, when it will open), its GitHub pages server cannot be
2019-03-18 11:24:26 +00:00
enabled yet. As a result links marked ★ lead only to raw HTML
2019-03-18 11:16:10 +00:00
source, not to served web pages. They can in the mean time be browsed offline
as static HTML files stored in "docs".
2019-03-12 23:32:12 +00:00
2019-03-13 20:17:02 +00:00
## Licence
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
becoming public, the Package is placed under the [Artistic License 2.0](https://opensource.org/licenses/Artistic-2.0).
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.
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"
2019-03-12 23:32:12 +00:00
* Run **one of the following commands**. Unix is for any generic version of Unix,
2019-03-18 11:16:10 +00:00
non-Linux, non-MacOS: Solaris, for example. Android support is currently disabled,
though only because its build settings are currently missing from the inweb
distribution. The older macos32 platform won't build with the MacOS SDK from
2019-03-12 23:32:12 +00:00
10.14 onwards, and in any case 32-bit executables won't run from 10.15 onwards:
so use the default macos unless you need to build for an old version of MacOS.
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"
* "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-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
## 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
here: [★ foundation-module](docs/foundation-module/index.html).
A small executable for running unit tests against Foundation is also included:
[★ foundation-test](docs/foundation-test/index.html).
## 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.
