Commit: 9b12e6e7d6d2e39ed61ac3bff9bc582d62aa5ddd

Commit

Author:

Hash:

Timestamp:

+119 -83 +/-8 browse

Kevin Schoon [me@kevinschoon.com]

9b12e6e7d6d2e39ed61ac3bff9bc582d62aa5ddd

Sat, 20 Jun 2026 10:27:09 +0000 (4 weeks ago)

drop scdoc in favor of go-md2man, clean up man pages a bit

1	diff --git a/README.md b/README.md
2	index 14c064a..87e00a2 100644
3	--- a/README.md
4	+++ b/README.md
5	@@ -8,8 +8,10 @@ with a variety of standards based integrations.
6	## Project Status & Collaboration
7
8	Please note that this project is both a work in progress and a labour of love
9	- (sometimes) and as such contributions can be challenging to adopt since the
10	- project is changing rapidly.
11	+ (sometimes) by a single developer and as such contributions can be challenging
12	+ to adopt since the project is changing rapidly. Small fixes and updates are
13	+ appreciated and typically easy to merge but larger changes will likely require
14	+ coordination.
15
16	To facilitate collaboration we have mirrors available
17	at [codeberg](https://codeberg.org/ayllu/ayllu) and
18	diff --git a/ayllu.5.md b/ayllu.5.md
19	new file mode 100644
20	index 0000000..d1077fe
21	--- /dev/null
22	+++ b/ayllu.5.md
23	@@ -0,0 +1,30 @@
24	+ ayllu 5 "Configuration"
25	+ ==========================
26	+
27	+ # CONFIGURATION
28	+
29	+ Ayllu's configuration is managed by a single TOML file which can reside in
30	+ a variety of places. All content stored in the configuration file is considered
31	+ public and appropriate for viewing by any users of the installation. The file
32	+ is read by all components of Ayllu and contains a global configuration section
33	+ which influences all applications as well as specific sections for different
34	+ components.
35	+
36	+ ## LOADING
37	+
38	+ All binaries accept the `--config` flag which if provided takes prescience over
39	+ all other options. If unspecified the following locations environment variables
40	+ will be checked:
41	+
42	+ * `$AYLLU_CONFIG_PATH`
43	+ * `$XDG_CONFIG_HOME/ayllu/config.toml`
44	+ * `$CONFIGURATION_DIRECTORY/config.toml`
45	+
46	+ Finally two hard coded paths will be inspected:
47	+
48	+ * `config.toml`
49	+ * `/etc/ayllu/config.toml`
50	+
51	+ If no configuration file is found typically Ayllu can be run with only defaults.
52	+
53	+ # ANNOTATED EXAMPLE CONFIGURATION
54	diff --git a/ayllu.5.scd b/ayllu.5.scd
55	deleted file mode 100644
56	index e8c5d90..0000000
57	--- a/ayllu.5.scd
58	+++ /dev/null
59	@@ -1,11 +0,0 @@
60	- AYLLU(5)
61	-
62	- # CONFIGURATION
63	-
64	- Ayllu's configuration is managed by a single TOML file which typically resides
65	- in $XDG_CONFIG_HOME/ayllu/config.toml for user based installation and at
66	- /etc/ayllu/config.toml for system wide installations. All content contained
67	- within the file is considered public and appropriate to be viewed by all system
68	- users. This file contains a mixture of global configuration options which
69	- control behavior of various ayllu binaries and also package specific behavior
70	- which share a global configuration namespace.
71	diff --git a/ayllu.7.md b/ayllu.7.md
72	new file mode 100644
73	index 0000000..2945356
74	--- /dev/null
75	+++ b/ayllu.7.md
76	@@ -0,0 +1,72 @@
77	+ ayllu 7 "User Manual"
78	+ ==================================================
79	+
80	+ # NAME
81	+
82	+ Ayllu The Hyper Performant & Hackable Code Forge
83	+
84	+ The name Ayllu _/ˈajʎu/_, _eye-joo_ is the Quechua word for the traditional
85	+ form of a community in the Andes region of South America, particularly in
86	+ Bolivia and Peru.
87	+
88	+ # OVERVIEW
89	+
90	+ Ayllu is a lightweight code forge oriented towards multi-user single server
91	+ environments, is designed to be interoperable via open standards, and encourage
92	+ the proliferation of independent software communities. It is built with the
93	+ assumption that a single computer is sufficiently capable of providing resources
94	+ to an entire team of developers building software [1]. It is a rejection of the
95	+ horizontal "cloud scale" paradigm, an endorsement of reducing computational
96	+ waste with a preference for vertical scaling where necessary. Ayllu attempts
97	+ to capture the ethos of old school Unix time-sharing systems paired with the
98	+ optimism and interoperability of the early web 2.0 era while providing a robust
99	+ and secure tool chain oriented specifically for building free software.
100	+
101	+ *1. For a specific architecture, if you can't emulate a specific target then of
102	+ course you need an additional computer.*
103	+
104	+ # ALPHA STATUS
105	+
106	+ For the moment Ayllu is considered ALPHA software and so it should not be
107	+ depended on unless you are willing to tolerate pain, suffering, or worse.
108	+
109	+ # HISTORY
110	+
111	+ Ayllu started as a personal project to learn the Rust programming language but
112	+ was influenced by several attempts to setup a lightweight environment for
113	+ doing software development in a combination of private and public settings.
114	+
115	+ # WHAT IS A SOFTWARE FORGE?
116	+
117	+ Forge is a nebulous term but roughly refers to a virtual space in which software
118	+ is discussed, constructed, tested, and documented. More generally it refers to
119	+ a digital commons where hackers congregate together and create digital tools.
120	+
121	+ # COMPONENTS
122	+
123	+ Ayllu is shipped with several distinct binaries which are composed together.
124	+
125	+ \| Component \| Description \|
126	+ \|-------------------\|------------------------------------------------------------\|
127	+ \| ayllu-build \| OCI based continuous integration system \|
128	+ \| ayllu-keys \| OpenSSH AuthorizedKeysCommand \|
129	+ \| ayllu-migrate \| Database Migration Tool \|
130	+ \| ayllu-shell \| Restricted shll for SSH based administration \|
131	+ \| ayllu-web \| Asynchronous Tokio powered web interface for Ayllu \|
132	+ \| quipu \| CLI tool to interact with local and remote Ayllu instances \|
133	+
134	+ # SEE ALSO
135	+
136	+ ayllu(5)
137	+
138	+ ayllu-build(1)
139	+
140	+ ayllu-keys(1)
141	+
142	+ ayllu-migrate(1)
143	+
144	+ ayllu-shell(1)
145	+
146	+ ayllu-web(1)
147	+
148	+ quipu(1)
149	diff --git a/ayllu.7.scd b/ayllu.7.scd
150	deleted file mode 100644
151	index 226563e..0000000
152	--- a/ayllu.7.scd
153	+++ /dev/null
154	@@ -1,58 +0,0 @@
155	- AYLLU(7)
156	-
157	- # NAME
158	-
159	- Ayllu The Hyper Performant & Hackable Code Forge
160	-
161	- The name Ayllu _/ˈajʎu/_, _eye-joo_ is the Quechua word for the traditional
162	- form of a community in the Andes region of South America, particularly in
163	- Bolivia and Peru.
164	-
165	- # OVERVIEW
166	-
167	- Ayllu is a lightweight code forge oriented towards multi-user single server
168	- environments and is designed to be interoperable via open standards and
169	- encourage the proliferation of independent software communities. Ayllu is built
170	- with the assumption that a single computer is sufficiently powerful to satisfy
171	- the computational needs of small to medium size FOSS community projects. It aims
172	- to capture the ethos of old school Unix time-sharing systems paired with the
173	- optimism and interoperability of the early web 2.0 era while providing modern
174	- robust tooling for a secure distributed free software supply chain.
175	-
176	- For the moment Ayllu is considered ALPHA software and so it should not be
177	- depended on unless you are willing to tolerate pain, suffering, or worse.
178	-
179	- # HISTORY
180	-
181	- Ayllu started as a personal project to learn the Rust programming language but
182	- was influenced by several attempts to setup a lightweight environment for
183	- doing software development in a combination of private and public settings.
184	-
185	- # WHAT IS A SOFTWARE FORGE?
186	-
187	- Forge is a nebulous term but roughly refers to a virtual space in which software
188	- is discussed, constructed, tested, and documented.
189	-
190	- # COMPONENTS
191	-
192	- Ayllu is shipped with several distinct binaries which are composed together.
193	-
194	- [[ Executable
195	- :- Description
196	- \| ayllu-build
197	- : OCI based continuous integration system
198	- \| ayllu-keys
199	- : OpenSSH AuthorizedKeysCommand shim script
200	- \| ayllu-migrate
201	- : Database migration tool
202	- \| ayllu-shell
203	- : Restricted shell for SSH based administration
204	- \| ayllu-web
205	- : Tokio powered web interface for Ayllu
206	- \| quipu
207	- : CLI tool to interact with local and remote Ayllu instances
208	-
209	- # SEE ALSO
210	-
211	- ayllu-build(1)
212	- quipu(1)
213	diff --git a/containers/Containerfile.arch b/containers/Containerfile.arch
214	index 469a134..16ac7e0 100644
215	--- a/containers/Containerfile.arch
216	+++ b/containers/Containerfile.arch
217	@@ -6,9 +6,9 @@ RUN echo "Server = http://$MIRROR_SERVER/repo/archlinux/\$repo/os/\$arch" > /etc
218	RUN pacman -Syu --needed --noconfirm \
219	curl \
220	git \
221	+ go-md2man \
222	mandoc \
223	sqlite \
224	- scdoc \
225	fakeroot \
226	rust \
227	rust-analyzer \
228	diff --git a/containers/Containerfile.debian b/containers/Containerfile.debian
229	index 60d13d5..7e19b5c 100644
230	--- a/containers/Containerfile.debian
231	+++ b/containers/Containerfile.debian
232	@@ -5,6 +5,7 @@ RUN apt-get update && apt-get install -yyq \
233	cargo \
234	dpkg-dev \
235	git \
236	+ go-md2man \
237	mandoc \
238	rust-clippy \
239	sqlite3 \
240	diff --git a/xtask/src/main.rs b/xtask/src/main.rs
241	index 759ee4d..d6f4322 100644
242	--- a/xtask/src/main.rs
243	+++ b/xtask/src/main.rs
244	@@ -14,8 +14,8 @@ use clap_complete::{
245	const DIST_COMPLETE_PATH: &str = "dist/completion";
246	const DIST_MAN_PATH: &str = "dist/man";
247
248	- const AYLLU_SUMMARY: &[u8] = include_bytes!("../../ayllu.7.scd");
249	- const AYLLU_CONFIG: &str = include_str!("../../ayllu.5.scd");
250	+ const AYLLU_SUMMARY: &[u8] = include_bytes!("../../ayllu.7.md");
251	+ const AYLLU_CONFIG: &str = include_str!("../../ayllu.5.md");
252	const AYLLU_ANNOTATED_EXAMPLE: &str = include_str!("../../config.example.toml");
253
254	fn target_dir(base: &str) -> PathBuf {
255	@@ -39,8 +39,9 @@ fn open(target: &Path) -> Result<std::fs::File, std::io::Error> {
256	Ok(fp)
257	}
258
259	- fn scdoc_gen(input: &[u8], dst: &Path) -> std::io::Result<()> {
260	- let mut fp = Command::new("scdoc")
261	+ fn md2man(input: &[u8], dst: &Path) -> std::io::Result<()> {
262	+ println!("Writing {dst:?}");
263	+ let mut fp = Command::new("go-md2man")
264	.stdin(Stdio::piped())
265	.stdout(Stdio::piped())
266	.spawn()?;
267	@@ -150,14 +151,13 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
268	man_gen::<ayllu_cmd::quipu::Command>(&man_dir)?;
269
270	// Misc man pages
271	- scdoc_gen(AYLLU_SUMMARY, &man_dir.join("ayllu.7"))?;
272	+ md2man(AYLLU_SUMMARY, &man_dir.join("ayllu.7"))?;
273	html_gen(&man_dir.join("ayllu.7"), &man_dir.join("ayllu.7.html"))?;
274	- let mut scdoc_input = AYLLU_CONFIG.to_string();
275	- scdoc_input.push_str("\n```\n");
276	- scdoc_input.push_str(AYLLU_ANNOTATED_EXAMPLE);
277	- scdoc_input.push_str("\n```\n");
278	-
279	- scdoc_gen(scdoc_input.as_bytes(), &man_dir.join("ayllu.5"))?;
280	+ let mut md_input = AYLLU_CONFIG.to_string();
281	+ md_input.push_str("\n```\n");
282	+ md_input.push_str(AYLLU_ANNOTATED_EXAMPLE);
283	+ md_input.push_str("\n```\n");
284	+ md2man(md_input.as_bytes(), &man_dir.join("ayllu.5"))?;
285	html_gen(&man_dir.join("ayllu.5"), &man_dir.join("ayllu.5.html"))?;
286	}
287	_ => unimplemented!(),