1# Make(1) a webpage for your code
2
3CHUM is an unholy program is a (GNU)makefile that embeds awk, html, and css to generate a static HTML viewer for your code, à la [stagit][], [repo2html][] or whatever powers [depp.brause.cc][depp].
4
5[stagit]: https://codemadness.org/stagit.html
6[repo2html]: https://git.m455.casa/repo2html/
7[depp]: https://depp.brause.cc/
8
9However, CHUM is more versatile than these: it can work with *any* source repository, under *any* version control---or indeed, under no version control whatsoever. It just reads a `.chum` file in the current directory for its configuration, and builds a snapshot of the current state of your repo with HTML, source code, and an index.
10
11Sadly, it cannot do anything with history, but really, someone should clone your repository to get that, shouldn't they?
12
13## CHUM dependencies
14
15- GNU Make (POSIX just doesn't cut the mustard)
16- Rsync
17- Awk (POSIX should be fine)
18
19## Using CHUM
20
21Using CHUM can be as simple as running `chum` in your project root. That will build the project and place the generated site in `OUTDIR` (see below). You can also run the following recipes included in CHUM:
22
23`chum serve`
24: build the site and serve it locally.
25
26`chum publish`
27: build the site and publish it to `REMOTE`.
28
29`chum clean`
30: remove the generated output directory.
31
32Because CHUM is a makefile, you can also set variables on the commandline to override variables in your `.chum` file at run-time. And whatever other funky stuff GNU make lets you do with the commandline!
33
34### Configuration
35
36By default, CHUM doesn't do a lot. You'll want a `.chum` file in your project root to tell CHUM what to do. This file is included as CHUM does its work, so it's a (GNU)makefile declaring variables and what-not. Here are the variables you can set:
37
38NAME
39: the project name.
40: Default: the basename of the current directory.
41
42AUTHOR
43: the project author(s).
44: Default: none.
45
46DESCRIPTION
47: the project description.
48: Default: none.
49
50OUTDIR
51: where the built site will reside.
52: Default: `out`.
53
54SERVER
55: a command to serve the out directory locally.
56: Default: none.
57
58SOURCES
59: all the files to include in the generated site.
60: Default: none.
61: *Notes: README and LICENSE are included automatically.*
62
63README
64: the README file for the project -- included in the generated index.
65: Default: none.
66
67READMEFILTER
68: a Unix-style text filter to pass README through for rendering html.
69: Default: `cat`.
70
71LICENSE
72: the license file for the code.
73: Default: none.
74
75TARBALL
76: the name of a generated tarball for downloading.
77: Default: `OUTDIR`/`NAME`.tar.gz
78
79STATICS
80: any extra static files to copy to the site.
81: Default: none.
82: *Note: could be used for images or other binary files.*
83
84REMOTE
85: the remote ssh server to rsync the site to.
86: Default: none.
87
88URL_ROOT
89: the root URL of the site. Useful in templates.
90: Default: none.
91
92URL_CLONE
93: a URL where a user can clone the repository.
94: Default: none.
95
96URL_DOWNLOAD
97: a URL where a user can download a repository snapshot.
98: Default: `URL_ROOT`/`BASENAME(TARBALL)`.
99
100TEMPLATE
101: the HTML template for each page. See TEMPLATES, below.
102: *Note: use the GNU make `define`...`endef` format for this variable.*
103
104STYLE
105: the site style, included on each page.
106: *Note: use the GNU make `define`...`endef` format for this variable.*
107
108### Templates
109
110You can also define a template for your pages to fit within. The template format should be vaguely familiar to you if you've ever worked with templates before --- it has `{{VARIABLES}}` to replace with well, variables:
111
112- `STYLE`: `STYLE`
113- `CLONE`: `URL_CLONE`
114- `DOWNLOAD`: `URL_DOWNLOAD`
115- `DESCRIPTION`: `DESCRIPTION`
116- `AUTHOR`: `AUTHOR`
117- `ROOT`: `URL_ROOT`
118- `DIRECTORY`: the last component of the current directory name
119- `FILENAME`: the current filename
120- `OUTFILE`: the output filename
121- `RAWFILE`: the raw-text filename
122
123To differentiate between normal pages and the index page (e.g. for including a list of files in the index only), you can also use
124`<!--NORMAL--> ... <!--/NORMAL-->` and `<!--INDEX--> ... <!--/INDEX-->` tags to guard content. Text between the NORMAL comments will only appear in normal pages, and text between INDEX comments will only appear on the index page.
125
126For completeness's sake, here is the default TEMPLATE:
127
128```
129<!DOCTYPE html>
130<html><head>
131<meta charset="utf-8">
132<title>{{FILENAME}}</title>
133<style>{{STYLE}}</style></head>
134<body>
135<h1><!--NORMAL-->{{DIRECTORY}}/<!--/NORMAL-->{{FILENAME}}</h1>
136<!--INDEX-->{{DESCRIPTION}}<!--/INDEX-->
137<!--NORMAL-->
138<nav><ul>
139<li><a href="{{ROOT}}">index</a></li>
140<li><a href="{{RAWFILE}}">source</a></li>
141</ul></nav>
142<!--/NORMAL-->
143<main>{{CONTENT}}</main>
144<footer><p>(C) {{AUTHOR}}.
145<a href="{{CLONE}}">clone</a>
146<a href="{{DOWNLOAD}}">download</a>
147</p></footer>
148</body>
149</html>
150```
151
152And for extra completeness's sake, here's the default STYLE. Note the styling of `.ll` (line number links):
153
154```
155#readme{max-width:48em;}
156.ll{display:inline-block;width:3em;text-align:right;
157padding-right:0.5em;margin-right:0.5em;}
158```
159
160## License
161
162Basically, you're good. See COPYING for details.
163
164## Contributing
165
166Email me with comments, suggestions, complaints, or praise!