rawtext.club man pages
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 

138 lines
4.0 KiB

.\" Manpage for gitbbs
.\" Contact me@wangofett.com, wangofett@rawtext.club, or cmccabe@rawtext.club
.TH man 5 "26 April 2020" "0.1.0" "gitbbs man page"
.SH NAME
gitbbs \- rawtext's bulletin board system
.SH SYNOPSIS
quickstart: git clone ~cmccabe/.gitbbs
.SH DESCRIPTION
Here on rawtext.club we really like raw text. It's natural that our bulletin board would be built on some raw text conventions as well. One of the very best ways to
.I share
text in a collaborative fashion is with git. So we decided that we would build our BBS with git! If you're not familiar with git, it's a distributed version control system. That means that rather than one centralized bulletin board, our bulletin board is decentralized. You have to get your copy from another user.
.SS GIT SETUP
The best way to get started is to just clone the git repository. If you've never used git, see
.BR git (1)
for more information, in particular the
.I user.name
section in
.BR git-config (1).
If you just want to get started, you can run the following command:
.RS
git config --global user.name
.I \(dqYour Name\(dq
.sp 0
git config --global user.email
.I you@yourdomain.example.com
.RE
The easiest values to plug in for email is
.I yournick@rawtext.club
if you don't have one you'd rather use.
.SS GET GITBBS
Now that you have git configured, it's time to get a copy of the BBS. As mentioned in the SYNOPSIS, probably the best person to get the first copy of the BBS from is the maintainer of RTC, cmccabe. Run the following command
.RS
git clone ~cmccabe/.gitbbs ~/.gitbbs
.RE
By convention, each users' copy is stored in `.gitbbs`. Now you can `cd ~/.gitbbs` and start using your favorite text editor to read and add posts.
.SH TOPICS/SUBFORUMS IN GITBBS
Topics/forums as found in a typical BBS are literally just directories. Some topics you're likely to see:
.SS meta
That's so meta. Discussion here is for discussing gitbbs itself.
.SS tech
These are technology posts. There may end out subposts in here.
.SS sandbox
"An it harm none do what ye will" - Doreen Valiente
In this folder, anything goes. Nothing in this folder is expected to adhere to any format or even continue living from revision to revision. So if you want to experiment with building tools, or mucking around with things in gitbbs, do it here in the sandbox before you inflict it on the rest of the club.
.SH FILE FORMATS
Post syntax is inspired by RFC-822.
Files are named
.I YYYY-MM-DD-HH:MM:SS-subject-goes-here.txt
The file format is pretty simple:
.RS
From:
.I Post Author
.sp 0
Date:
.I YYYY-MM-DD HH:MM(:SS)
.sp 0
Subject:
.I subject goes here
.RE
Replies are separated from the main post with `---`, and include the `From` and `Date` headers.
Once you've replied to any interesting posts and created any that you want, you'll run the following commands:
.RS
git status # Shows what files have changed
.sp 0
git add
.I file1 file2 file3 # Whatever files you've changed
.sp 0
git commit -m
.I 'my updates' # feel free to use a different message
.RE
Now that your post has been made, just wait for someone to pick up your changes, or let them know that you are now part of of gitbbs! Another thing that you can do is to run
.RS
~/.gitbbs/_util/update_remotes.py
.RE
Which will try everyone on RTC to see if they are on gitbbs. Running
.RS
git fetch --all
.sp 0
~/.gitbbs/_util/get-updates.py
.RE
will pull and merge in everyone's updates after that.
Happy posting!
.SH BUGS
It's possible that your ~/.gitbbs/.git folder (or subfolders) are not world-readable. This will prevent RTC friends from correctly accessing your posts.
You should be able to avoid this by adding the following to ~/.gitbbs/.git/hooks/post-merge and ~/.gitbbs/.git/hooks/post-commit
.RS
#!/bin/sh
.sp 0
chmod -R o+Xr ~/.gitbbs
.RE
And then running
.RS
chmod +x ~/.gitbbs/.git/hooks/post-receive
.sp 0
chmod +x ~/.gitbbs/.git/hooks/post-merge
.RE
.SH AUTHOR
Wango Fett (wangofett@rawtext.club or me@wangofett.com)
.SH SEE ALSO
For more information on git, see
.BR git (1).