Add some more porting instructions

man/man7/package.7

@@ -1,88 +0,0 @@
-.Dd $Mdocdate: November 20 2022 $
-.Dt PACKAGE 7
-.Os Telodendria Project
-.Sh NAME
-.Nm package
-.Nd Some guidelines for packaging Telodendria for your system.
-.Sh DESCRIPTION
-.Pp
-Telodendria is distributed at source code, and does not offer a convenient
-install process. This is intentional; the Telodendria project is primarily
-concerned with developing Telodendria itself, not packaging it for the
-hundreds of different operating systems and Linux distributions that exist.
-It is my firm belief that distributing an open source project is not the
-job of the open source developer; that's the reason software distributions
-exist, to collect and distribute software.
-.Pp
-It would be impossible to package Telodendria for every platform, because
-each platform has very different expectations for software. Even different
-Linux distributions have different conventions for where manual pages,
-binaries, and configuration files go.
-.Pp
-That being said, this page aims to assist those who want to package
-Telodendria, or just install it from source, though that's not recommended.
-.Pp
-See
-.Xr td 8
-for instructions on how to build Telodendria. Only proceed with packaging
-Telodendria after you have successfully built it on your operating system.
-.Pp
-To package Telodendria, you should collect the following files, and figure
-out where they should be installed for your system:
-.Bl -bullet
-.It
-The telodendria server binary itself:
-.Pa build/telodendria
-.It
-All manual pages in the
-.Pa man/
-directory that are prefixed with "telodendria". These are the user documentation
-pages. All pages that do not have the "telodendria" prefix are intended only
-for developers, and so do not need to be installed to the system.
-.It
-An init script. People that wish to install Telodendria to their system
-expect it to be integrated enough that Telodendria can be easily started at
-boot, and otherwise managed by the system's daemon tools, be it systemd, or
-another init system. Consult your system's documentation for writing an
-init script. Do note that Telodendria does not fork itself to the background;
-the init script should do that. Also note that Telodendria responds to SIGINT,
-so a SIGINT should be sent to stop Telodendria instead of a SIGTERM or SIGKILL.
-.It
-A sample
-.Pa telodendria.conf
-file. Whether this file is placed at the actual configuration file location,
-or a directory containing configuration file samples is entirely up to the
-packager. You can use or adapt any of the configuration files in
-.Pa contrib/ ,
-or write your own specifically for your package.
-.El
-.Pp
-Once you have collected the files that need to be installed, make sure your
-package performs the following tasks on install:
-.Bl -bullet
-.It
-If necessary, depending on the config used, create a new system user for
-the Telodendria daemon to run as.
-.It
-If conventional for your system, enable the Telodendria init script so
-that Telodendria is started on system boot.
-.It
-Insruct the user to carefully read the sample
-.Pa telodendria.conf
-as well as the
-.Xr telodendria.conf 5
-manual page before starting Telodendria.
-.El
-.Pp
-The goal of a package should be to get everything as ready-to-run as possible.
-The user should only have to change one or two default options in the configuration
-file before Telodendria can be started.
-.Pp
-Remember to publicly document the setup of Telodendria on your platform so
-that users can easily get Telodendria running. If you're packaging Telodendria
-for a containerization system such as Docker, you can omit the things that
-containers typically do not have, such as the init script and man pages.
-.Sh SEE ALSO
-.Xr telodendria-contributing 7 ,
-.Xr td 8 ,
-.Xr telodendria 7

man/man7/porting.7

@@ -0,0 +1,159 @@
+.Dd $Mdocdate: November 20 2022 $
+.Dt PORTING 7
+.Os Telodendria Project
+.Sh NAME
+.Nm porting
+.Nd Some guidelines for packaging Telodendria for your operating system.
+.Sh DESCRIPTION
+.Pp
+Telodendria is distributed at source code, and does not offer a convenient
+install process. This is intentional; the Telodendria project is primarily
+concerned with developing Telodendria itself, not packaging it for the
+hundreds of different operating systems and Linux distributions that exist.
+It is my firm belief that distributing an open source project is not the
+job of the open source developer; that's the reason software distributions
+exist, to collect and distribute software.
+.Pp
+It would be impossible to single-handedly package Telodendria for every
+platform, because each platform has very different expectations for
+software. Even different Linux distributions have different conventions
+for where manual pages, binaries, and configuration files go.
+.Pp
+That being said, this page aims to assist those who want to package
+Telodendria for their operating system or software distribution.
+.Pp
+See
+.Xr td 8
+for instructions on how to build Telodendria. Only proceed with packaging
+Telodendria after you have successfully built it on your operating system.
+.Pp
+To package Telodendria, you should collect the following files, and figure
+out where they should be installed for your system:
+.Bl -bullet
+.It
+The telodendria server binary itself:
+.Pa build/telodendria
+.It
+All manual pages in the
+.Pa man/
+directory that are prefixed with "telodendria". These are the user documentation
+pages. All pages that do not have the "telodendria" prefix are intended only
+for developers, and so do not need to be installed to the system.
+.It
+An init script. People that wish to install Telodendria to their system
+expect it to be integrated enough that Telodendria can be easily started at
+boot, and otherwise managed by the system's daemon tools, be it systemd, or
+another init system. Consult your system's documentation for writing an
+init script. Do note that Telodendria does not fork itself to the background;
+the init script should do that. Also note that Telodendria responds to SIGINT,
+so a SIGINT should be sent to stop Telodendria instead of a SIGTERM or SIGKILL.
+.It
+A sample
+.Pa telodendria.conf
+file. Whether this file is placed at the actual configuration file location,
+or a directory containing configuration file samples is entirely up to the
+packager. You can use or adapt any of the configuration files in
+.Pa contrib/ ,
+or write your own specifically for your package.
+.El
+.Pp
+Once you have collected the files that need to be installed, make sure your
+package performs the following tasks on install:
+.Bl -bullet
+.It
+If necessary, depending on the config used, create a new system user for
+the Telodendria daemon to run as.
+.It
+If conventional for your system, enable the Telodendria init script so
+that Telodendria is started on system boot.
+.It
+Insruct the user to carefully read the sample
+.Pa telodendria.conf
+as well as the
+.Xr telodendria.conf 5
+manual page before starting Telodendria.
+.El
+.Pp
+The goal of a package should be to get everything as ready-to-run as possible.
+The user should only have to change one or two default options in the configuration
+file before Telodendria can be started.
+.Pp
+Remember to publicly document the setup of Telodendria on your platform so
+that users can easily get Telodendria running. If you're packaging Telodendria
+for a containerization system such as Docker, you can omit the things that
+containers typically do not have, such as the init script and man pages.
+.Pp
+Also remember that your port should feel like it belongs on your target system.
+Follow all of your system's conventions when placing files on the filesystem,
+so your users know what to expect. The goal is not to have a unified experience
+across all operating systems, rather, you should cater to the opinions of your
+operating system. Telodendria is architected in such a way that it does not
+impose the developers opinions of where things should go.
+.Sh PORTS REPOSITORY
+.Pp
+The Telodendria project provides a
+.Pa Telodendria-Ports
+repository that is intended to serve as the official staging environment for
+ports and packages of Telodendria to various operating systems. You can
+most likely take inspiration from the files stored in this repository, or even
+straight up copy and modify files for your own port if you'd like. 
+Telodendria-Ports is a convenient resource for new porters. You can grab
+a copy of the ports repository like this:
+.Bd -literal -offset indent
+$ cvs -d anoncvs@bancino.net:/cvs checkout -P Telodendria-Ports
+.Ed
+.Pp
+(It is assumed that you have read
+.Xr telodendria-contributing 7 ,
+so you already have the proper tools for getting the ports repository.)
+.Pp
+The repository is structured in such a way that each operating system or
+software distribution has a directory. For example, the OpenBSD port has an
+.Pa OpenBSD/
+directory. If you make a HaikuOS port, then make a
+.Pa HaikuOS/
+directory.
+.Pp
+The structure of the operating system directories themselves is really defined
+by the conventions of the packaging system you're working with. There's no standard
+structure, as each system does things differently. Just use the directory as a
+working space that stores all the files your packaging system needs to build
+a package for Telodendria.
+.Pp
+The exact procedure for interacting with this repository is also defined by how
+your packaging system works. For OpenBSD, one is required to copy the
+.Pa OpenBSD/
+directory to
+.Pa /usr/ports/net/telodendria ,
+and then copy files back and forth when modifications are made. You may be able
+to get away with building your package in place, without having to copy files
+anywhere. Otherwise, you can try symlinking directories, but OpenBSD ports did
+not like this at all.
+.Pp
+Submitting your port files to Telodendria-Ports is by no means required,
+but it may be helpful to have a public record that you're working on a port,
+and it's definitely helpful to have a consolidated list of all the ports out
+there, making it much easier to determine whether or not a given platform
+has a port, especially if you're unfamilier with that platform's port system.
+If you are capable of managing your port entirely within your packaging system,
+then go for it! I just wanted a staging environment that I have commit access to
+for my ports, allowing me to prototype and test my port before submitting it
+to the actual ports tree.
+.Pp
+It is important to note that I only maintain the OpenBSD port, because that's
+the operating system I use. But, notice that I follow my own rules; nothing
+inherently OpenBSD-specific, besides a few optional files in
+.Pa contrib/ ,
+actually exists in the main repository. All operating-system specific files,
+such as init scripts and the like, should go to Telodendria-Ports. It's also
+important to note that the files placed in Telodendria-Ports are not automatically
+assumed to be official builds. The developer that committed the files to
+Telodendria-Ports will most likely also have to get them submitted upstream,
+because I'm not going to go to all these upstream packagers with the port files
+here, I'll only do that with ports I officially maintain, which is the
+OpenBSD port.
+.Pp
+.Sh SEE ALSO
+.Xr telodendria-contributing 7 ,
+.Xr td 8 ,
+.Xr telodendria 7

man/man7/telodendria.7

@@ -1,4 +1,4 @@
-.Dd $Mdocdate: November 18 2022 $
+.Dd $Mdocdate: November 20 2022 $
 .Dt TELODENDRIA 7
 .Os Telodendria Project
 .Sh NAME
@@ -64,8 +64,10 @@ ll.
 #telodendria:bancino.net;The public "space" room.
 #telodendria-releases:bancino.net;Get notified of new releases.
 #telodendria-general:bancino.net;General discussion and support.
+#telodendria-newsletter:bancino.net;Periodic status updates.
 #telodendria-issues:bancino.net;Report bugs and issues.
 #telodendria-patches:bancino.net;Submit code patches to the project.
+#telodendria-ports:bancino.net;Discussion about porting and packaging.
 .TE
 .Pp
 .Nm

site/index.html

@@ -111,7 +111,7 @@ package yourself.
 <p>
 If your operating system does <i>not</i> have a package or port of
 <b>Telodendria</b>, please consult the
-<a href="/man/man7/package.7.html">package(7)</a> page for guidelines
+<a href="/man/man7/porting.7.html">porting(7)</a> page for guidelines
 related to packaging <b>Telodendria</b> for your system.
 </p>
 <h2 id="documentation">Documentation</h2>
@@ -162,10 +162,10 @@ Contributing guide.
 <th>Description</th>
 </tr>
 <tr>
-<td><a href="man/man7/package.7.html">package(7)</a></td>
+<td><a href="man/man7/porting.7.html">porting(7)</a></td>
 <td>
-Want to package Telodendria for your operating system, or just install it to
+Want to package Telodendria for your operating system?
-your system from source? Look no further than this page.
+Look no further than this page.
 </td>
 </tr>
 <tr>