Maintainer tools for the Multicians Web site

Tom Van Vleck

This note describes how to set up a personal computer to maintain the multicians.org web site.

Rules for maintenance and content of multicians.org are in Web Site Design.
Detailed instructions for maintenance tasks for multicians.org are listed in Maintenance tasks for the Multicians Website.
Web Site Build Process for the Multicians Website describes the Makefile.

The multicians.org website is built on a site editor's personal computer from HTMX source using Unix tools and the open source program expandfile. The editor generates the site HTML from HTMX source on a Mac or Unix machine, and copies generated HTML and graphics to the ISP host server.

multicians.org is served on the Web as static pages and graphics by a virtual private server running the Apache web server under Ubuntu Linux.

1. Summary

In order to create the site's HTML files from HTMX source files, either the Unix or Mac operating system can be used. The site editor's computer has a standard macOS installation with programming tools and a command line, supplemented by tools such as Perl and MySQL which are installed by a package manager in /usr/local/bin (I use Homebrew on the Mac). expandfile comes with some helper executables written in Perl installed in $HOME/bin. Additional site creation tools are in the /tools subdirectory of the source directory.

expandfile Install instructions describes how to set up Perl, CPAN, MySQL and expandfile.

Setup of Site Editor's Computer

Directories on Site Editor's Computer

Multics source files: .htmx, makefile, .git
Multics object files: .html, graphics and thumbnails subdirectories
Multics binary directory $HOME/bin: expandfile and other tools

Tools Needed on Site Editor's Computer

Function	Mac version	Source
email client	Mail.app	macOS
text editor	Emacs.app	aquamacs.org
command line	Terminal.app	macOS
Unix shell	bash	macOS
template expansion	expandfile	multicians.org/thvv/htmx
compile site	make	macOS/homebrew
install pages on host	rsync	homebrew
source version control	git	macOS/homebrew
source database	mysql	homebrew
host access	ssh	macOS
run expandfile	perl	homebrew
Perl library	CPAN	homebrew
local web server	apache	macOS
image conversion	ImageMagick	homebrew
HTML checking	HTML Tidy	macOS

Similar tables for building the website on other platforms should be created. The editor has done such installations on Fedora Linux and Ubuntu Linux.

Symbolic links from source directory to object directory

The source directory needs a few links to subdirectories of the object directory. In particular, in order for the image reference macros such as getimgdiv to work correctly, they need to access the pixel dimensions of target images (by invoking the helper program bin/gifsize2 with the *shell builtin). Symbolic links to the object subdirectories /mulimg and /thumbnails150 are placed in the source directory. I don't know how one would do this on Windows or Cygwin.

Git

The maintainer's Multics source directory contains a local Git repository that contains all the source .htmx and .sql files. Doing a make install does a git status.

The Makefile rule that copies files to the ISP ends with a git status which reminds the editor to do a git diff and update loadc.sql with a description of significant changes, and then do git commit -a with a brief message describing the changes.

hiddenmail.sql is not included in the git repo. The makefile pushes it separately to a directory on the ISP that is not visible on the web, and loads into the protected ISP database used when users send mail to Multicians. Various temporary files, scratch files, obsolete files are named in .gitignore and don't go into the repo. Future: upstream repo on github, and a way for others to request changes and build their own copy.

2. MacOS Setup

I created the initial version of the Multicians website on a Macintosh running Macintosh System 7 in 1994. I edited HTML files on a Mac and uploaded them via scp to an ISP account on an SGI machine. Subsequently I upgraded my Mac to System 8 and then, in 2001, to MacOS System X.

I wrote expandfile in 2002 and created HTMX files to generate corresponding HTML files on multicians.org.

For each change, I edit HTMX files on my Mac using emacs, compile them to HTML with expandfile, and upload the HTML files via rsync to my ISP account. (Initially, multicicans.org was hosted on a shell account on a shared server running FreBSD. Later, I changed to a Virtual Private Server that runs Ubuntu Linux.)

Expandfile has installation instructions for expandfile.

Mac System X has evolved into MacOS and it has been my tool for maintaining the site for over 20 years. My current usage of MacOS is described in

3. UNIX Setup

multicians.org could be maintained on a personal machine using some flavor of Unix.

Fedora Linux - I have a Dell x86 mini-tower that runs Fedora. I installed Expandfile, MySQL, etc and successfully expanded HTMX files to HTML. I have not updated this Linux in a while.
Ubuntu Linux - for consulting work, I have installed expandfile, MySQL, etc on several Ubuntu Linux releases, on remote physical servers and virtual servers. In general, installing expandfile and its suppoting tools was straightforward. These machines ran jobs that expanded HTMX files to HTML, and created web usage reports using expandfile. I created HTML pages with Web traffic reports, as well as formatted reports generated from JSON and XML data.

4. Windows Setup

I did some experiments creating web sites with expandfile using Windows arount 2002, but I don't currently have a Windows machine or use Windows to maintain multicians.org. I think it would be possible set up Perl on Windows and do this.

I had a version of expandfile running under Cygwin, years ago.

Use an environment like MINGW, MSYS2, or Cygwin to install a command shell, Perl, MySQL, CPAN Perl modules, and then use the Unix instructions. (I haven't tried this in a long time. I have never tried PowerShell.)

For Windows 10/11, there is a facility called "Windows Subsystem for Linux". I have never used it: supposedly it provides a Unix kernel and Bash-like shell, and supports Perl and MySQL. If anyone tries this and gets it working, we could document it here.

Web Site Maintainer Tools