a command-line based blogging platform running on tilde.town
-ttbp stands for "tilde.town blogging platform", the original working name for
this project.
ttbp runs from the command line, providing a hub for writing personal blog
posts and reading posts written by other users of tilde.town. it's a little bit
-like livejournal or dreamwidth or tumblr. you can opt to publish your posts to
-a public html file hosted on your tilde page, or keep all your entries private
-to the tilde.town server.
to use, run feels while logged in to tilde.town
(feels is a tilde.town specific command; if you're running this locally, or on
-a different server, run ttbp from the command line)
this is a project that runs on tilde.town, so all users of this program are +expected to operate under the tilde.town code of +conduct. content/personal issues should be +worked out according to the CoC, with support from the administrative +team if needed.
+no coding or html experience is necessary to get started. just log in to your tilde.town account and enter:
-feels
ttbp will ask you a few questions to get you started. after that, writing and reading entries all happen within the program.
-that's it!
- -if you're having trouble getting started, or run into program errors or strange behavior, please send internal tilde.town mail to ~endorphant and i'll try to sort things out!
- -entries are recorded as plaintext files in your ~/.ttbp/entries -directory. you can edit them there directly, or fix old entries, or -delete entries.
- -warning: changing old entries might cause strange things to -happen with timestamps. the main program looks at the filename -first for setting the date, then the last modified time to sort -recent posts. it expects YYYMMDD.txt as the filename; anything else -won't show up as a valid entry. yes, this means you can post things out -of date order by creating files with any date you want.
- -there's also a function from the main menu that lets you send feedback/inquiries +to me directly; this uses internal tilde.town mail, which is what i'll respond +to.
+entries are recorded as plaintext files in your ~/.ttbp/entries directory.
+ttbp will use your selected editor to open and write files; each day is its
+own entry, like a diary page. at midnight for whatever timezone you've set for
+your user account on tilde.town, you'll get a fresh entry. if you don't write
+any feels on a particular day, no entries will show up there.
when you save and quit the text editor, your entry will automatically propagate
+to the global feels list; if you've opted to publish your feels to html/gopher,
+those files will update immediately. you can always go back to the current day's
+entry and edit/add as you'd like, but older entries will not be available for
+editing from ttbp.
(since files are just stored as plaintext in your directory, it's possible to +edit and move old entries directly from the command line. however, changing old +entries might cause strange things to happen with timestamps. the main program +looks at the filename first for setting the date, then the last modified time to +sort recent posts. it expects YYYMMDD.txt as the filename; anything else won't +show up as a valid entry. yes, this means you can post things out of date order +by creating files with any date you want.)
+<!-- comments --> to have them show up
-in the feed but not render in a browser (but people can still read
-them with view-source)the browse global feels feature shows the ten most recent entries that anyone
+has written on ttbp. this list is only accessible from within tilde.town,
+although individual entries may be posted to html or gopher.
you can also pull up a list of a single user's feels through check out your
+neighbors, which displays all users who are writing on ttbp based on their
+most recently updated entry, and a link to their public html blog if they've
+opted to publish their posts.
please note! entries written on ttbp should be considered sensitive,
+private information, even if a particular user is publishing entries in a
+world-viewable way! please be respectful about having access to other people's
+feels, and do not copy/repeat any information without getting their explicit
+permission. tilde.town operates on a high level of mutual trust, and ttbp is
+designed to give individuals control over their content.
when you start your ttbp, you have the option of publishing or not publishing your blog.
- -if you opt to publish, the program creates a directory ~/.ttbp/www
-where it stores all html files it generates, and symlinks this from your
-~/public_html with your chosen blog directory. your blog will also be listed
-on the main ttbp page.
if you opt to not publish, your entires will never be accessible from outside -of the tilde.town network; other tilde.town users will still be able to read -your entries through the ttbp interface, or by directly accessing your +
if you opt to not publish, your entires will never be accessible from outside of
+the tilde.town network; other tilde.town users will still be able to read your
+entries through the ttbp interface, or by directly accessing your
~/.ttbp/entries directory.
if you want to further protect your entries, you can chmod 700 your entries
directory.
you can modify how your blog looks by editing the stylesheet or -header and footer files. the program sets you up with basic -default. if you break your page somehow, you can force the program to -regenerate your configuration by deleting your ~/.ttbp directory entirely. -you might want to back up your ~/.ttbp/entries directory before you do -this.
- +if you opt to publish, the program creates a directory ~/.ttbp/www where it
+stores all html files it generates, and symlinks this from your ~/public_html
+with your chosen blog directory. your blog will also be listed on the main ttbp
+page.
you can also opt to publish to gopher, and the program will automatically +generate a gophermap of your feels.
+you can set publishing status on individual entries, or bury individual feels; +see "data management" below for details.
+the manage your feels menu provides several tools for organizing your feels.
+these are all actions you can perform manually from the command line, but doing
+them from within the program can help keep your files properly linked up.
(nopub) will not get written to html or gopher,
+ and toggling them from this menu will immediately publish or unpublish
+ that entry (if you're not publishing your posts at all, these settings
+ won't matter, since your feels will never show up outside of tilde.town)~/.ttbp/backups/ with the current date, and a second copy to
+ your home directory for safekeeping.~/.ttbp/backups directory for archives, and
+ expects a file created by the above backup utility. if it detects any file
+ collisions, it will preserve your current live copy and leave the backup
+ verison in a temp directory, and notify you that this happened. also, any
+ entries that were previously marked as (nopub) will retain their nopub
+ status.~/.ttbp/buried (and marked with a unique timestamp to prevent
+ file collision) with permissions set to 600, meaning no one except you
+ will be able to open that file. these entries are also hidden from your
+ own view from read over feels, and you'll have to open the files from
+ the command line if you want to see them. this is intended to be a
+ permament action, so you'll be asked to type the entry date once to load
+ the feel, then shown a preview of that feel, and then type the date again
+ to confirm burying.~/.ttbp directory. any backups that you have in ~/.ttbp/backups
+ will also be deleted with this action (which is why the backup function
+ makes a second copy for safekeeping in your home directory). you will no
+ longer show up in any lists as a user.you can modify how your blog looks by editing the stylesheet or header and +footer files. the program sets you up with basic default. if you break your page +somehow, you can force the program to regenerate your configuration by deleting +your ~/.ttbp directory entirely. you might want to back up your +~/.ttbp/entries directory before you do this.
alias ttbp="~endorphant/bin/ttbp" to your .bash_aliases for fewer keystrokesalias ttbp-beta="~endorphant/bin/ttbp-beta")these are a few ideas being kicked around, or under active development:
-less)other ideas are listed on github as +upcoming features or feature requests!
+(this section is only relevant if you plan on forking the repo and running an instance of this yourself)
- - -please check out my contributor guidelines on github if you'd like to get involved with development!
-if you find any bugs or strange behavior, please message me locally on tildemail or open a github issue and i'll get back to you as soon as i can.
- -if you're interested in helping with the code, please drop me some tildemail!
\ No newline at end of file +if you're interested in helping with the code, please drop me some tildemail!
+i accept tips for development work on +liberapay
+thanks to:
+ttbp stands for "tilde.town blogging platform", the original working name for
+this project. the complete codebase is available on
+github.
ttbp runs from the command line, providing a hub for writing personal blog
+posts and reading posts written by other users of tilde.town. it's a little bit
+like livejournal or dreamwidth or tumblr. you can opt to publish your posts to a
+public html file hosted on your tilde page, to tilde.town's gopher server, or
+keep all your entries private to the tilde.town server.
this is a project that runs on tilde.town, so all users of this program are +expected to operate under the tilde.town code of +conduct. content/personal issues should be +worked out according to the CoC, with support from the administrative +team if needed.
+if you're having trouble getting started, or run into program errors or strange +behavior, please send internal tilde.town mail to ~endorphant and i'll try to +sort things out!
+there's also a function from the main menu that lets you send feedback/inquiries +to me directly; this uses internal tilde.town mail, which is what i'll respond +to.
+entries are recorded as plaintext files in your ~/.ttbp/entries directory.
+ttbp will use your selected editor to open and write files; each day is its
+own entry, like a diary page. at midnight for whatever timezone you've set for
+your user account on tilde.town, you'll get a fresh entry. if you don't write
+any feels on a particular day, no entries will show up there.
when you save and quit the text editor, your entry will automatically propagate
+to the global feels list; if you've opted to publish your feels to html/gopher,
+those files will update immediately. you can always go back to the current day's
+entry and edit/add as you'd like, but older entries will not be available for
+editing from ttbp.
(since files are just stored as plaintext in your directory, it's possible to +edit and move old entries directly from the command line. however, changing old +entries might cause strange things to happen with timestamps. the main program +looks at the filename first for setting the date, then the last modified time to +sort recent posts. it expects YYYMMDD.txt as the filename; anything else won't +show up as a valid entry. yes, this means you can post things out of date order +by creating files with any date you want.)
+<!-- comments --> to have them show up
+ in the feed but not render in a browser (but people can still read them with
+ view-source)the browse global feels feature shows the ten most recent entries that anyone
+has written on ttbp. this list is only accessible from within tilde.town,
+although individual entries may be posted to html or gopher.
you can also pull up a list of a single user's feels through check out your
+neighbors, which displays all users who are writing on ttbp based on their
+most recently updated entry, and a link to their public html blog if they've
+opted to publish their posts.
please note! entries written on ttbp should be considered sensitive,
+private information, even if a particular user is publishing entries in a
+world-viewable way! please be respectful about having access to other people's
+feels, and do not copy/repeat any information without getting their explicit
+permission. tilde.town operates on a high level of mutual trust, and ttbp is
+designed to give individuals control over their content.
when you start your ttbp, you have the option of publishing or not publishing +your blog.
+if you opt to not publish, your entires will never be accessible from outside of
+the tilde.town network; other tilde.town users will still be able to read your
+entries through the ttbp interface, or by directly accessing your
+~/.ttbp/entries directory.
if you want to further protect your entries, you can chmod 700 your entries
+directory.
if you opt to publish, the program creates a directory ~/.ttbp/www where it
+stores all html files it generates, and symlinks this from your ~/public_html
+with your chosen blog directory. your blog will also be listed on the main ttbp
+page.
you can also opt to publish to gopher, and the program will automatically +generate a gophermap of your feels.
+you can set publishing status on individual entries, or bury individual feels; +see "data management" below for details.
+the manage your feels menu provides several tools for organizing your feels.
+these are all actions you can perform manually from the command line, but doing
+them from within the program can help keep your files properly linked up.
(nopub) will not get written to html or gopher,
+ and toggling them from this menu will immediately publish or unpublish
+ that entry (if you're not publishing your posts at all, these settings
+ won't matter, since your feels will never show up outside of tilde.town)~/.ttbp/backups/ with the current date, and a second copy to
+ your home directory for safekeeping.~/.ttbp/backups directory for archives, and
+ expects a file created by the above backup utility. if it detects any file
+ collisions, it will preserve your current live copy and leave the backup
+ verison in a temp directory, and notify you that this happened. also, any
+ entries that were previously marked as (nopub) will retain their nopub
+ status.~/.ttbp/buried (and marked with a unique timestamp to prevent
+ file collision) with permissions set to 600, meaning no one except you
+ will be able to open that file. these entries are also hidden from your
+ own view from read over feels, and you'll have to open the files from
+ the command line if you want to see them. this is intended to be a
+ permament action, so you'll be asked to type the entry date once to load
+ the feel, then shown a preview of that feel, and then type the date again
+ to confirm burying.~/.ttbp directory. any backups that you have in ~/.ttbp/backups
+ will also be deleted with this action (which is why the backup function
+ makes a second copy for safekeeping in your home directory). you will no
+ longer show up in any lists as a user.you can modify how your blog looks by editing the stylesheet or header and +footer files. the program sets you up with basic default. if you break your page +somehow, you can force the program to regenerate your configuration by deleting +your ~/.ttbp directory entirely. you might want to back up your +~/.ttbp/entries directory before you do this.
+these are a few ideas being kicked around, or under active development:
+less)other ideas are listed on github as +upcoming features or feature requests!
\ No newline at end of file diff --git a/doc/manual.md b/doc/manual.md new file mode 100644 index 0000000..e8454d0 --- /dev/null +++ b/doc/manual.md @@ -0,0 +1,181 @@ +# FEELS MANUAL # + +`ttbp` stands for "tilde.town blogging platform", the original working name for +this project. the complete codebase is available on +[github](https://github.com/modgethanc/ttbp). + +`ttbp` runs from the command line, providing a hub for writing personal blog +posts and reading posts written by other users of tilde.town. it's a little bit +like livejournal or dreamwidth or tumblr. you can opt to publish your posts to a +public html file hosted on your tilde page, to tilde.town's gopher server, or +keep all your entries private to the tilde.town server. + +this is a project that runs on tilde.town, so all users of this program are +expected to operate under the tilde.town [code of +conduct](http://tilde.town/wiki/conduct.html). content/personal issues should be +worked out according to the CoC, with support from the [administrative +team](http://tilde.town/wiki/administration/index.html) if needed. + +### support + +if you're having trouble getting started, or run into program errors or strange +behavior, please send internal tilde.town mail to ~endorphant and i'll try to +sort things out! + +there's also a function from the main menu that lets you send feedback/inquiries +to me directly; this uses internal tilde.town mail, which is what i'll respond +to. + +### writing entries + +entries are recorded as plaintext files in your `~/.ttbp/entries` directory. +`ttbp` will use your selected editor to open and write files; each day is its +own entry, like a diary page. at midnight for whatever timezone you've set for +your user account on tilde.town, you'll get a fresh entry. if you don't write +any feels on a particular day, no entries will show up there. + +when you save and quit the text editor, your entry will automatically propagate +to the global feels list; if you've opted to publish your feels to html/gopher, +those files will update immediately. you can always go back to the current day's +entry and edit/add as you'd like, but older entries will not be available for +editing from `ttbp`. + +*(since files are just stored as plaintext in your directory, it's possible to +edit and move old entries directly from the command line. however, changing old +entries might cause strange things to happen with timestamps. the main program +looks at the filename first for setting the date, then the last modified time to +sort recent posts. it expects YYYMMDD.txt as the filename; anything else won't +show up as a valid entry. yes, this means you can post things out of date order +by creating files with any date you want.)* + +#### general entry-writing notes + +* you can use [markdown](https://daringfireball.net/projects/markdown/syntax) +* you can use html +* you can also put things between `` to have them show up + in the feed but not render in a browser (but people can still read them with + view-source) + +### reading other feels + +the `browse global feels` feature shows the ten most recent entries that anyone +has written on ttbp. this list is only accessible from within tilde.town, +although individual entries may be posted to html or gopher. + +you can also pull up a list of a single user's feels through `check out your +neighbors`, which displays all users who are writing on `ttbp` based on their +most recently updated entry, and a link to their public html blog if they've +opted to publish their posts. + +**please note!** entries written on `ttbp` should be considered sensitive, +private information, even if a particular user is publishing entries in a +world-viewable way! please be respectful about having access to other people's +feels, and do not copy/repeat any information without getting their explicit +permission. tilde.town operates on a high level of mutual trust, and `ttbp` is +designed to give individuals control over their content. + +### privacy + +when you start your ttbp, you have the option of publishing or not publishing +your blog. + +if you opt to not publish, your entires will never be accessible from outside of +the tilde.town network; other tilde.town users will still be able to read your +entries through the ttbp interface, or by directly accessing your +`~/.ttbp/entries` directory. + +if you want to further protect your entries, you can `chmod 700` your entries +directory. + +if you opt to publish, the program creates a directory `~/.ttbp/www` where it +stores all html files it generates, and symlinks this from your `~/public_html` +with your chosen blog directory. your blog will also be listed on the [main ttbp +page](https://tilde.town/~endorphant/ttbp). + +you can also opt to publish to gopher, and the program will automatically +generate a gophermap of your feels. + +you can set publishing status on individual entries, or bury individual feels; +see "data management" below for details. + +### data management + +the `manage your feels` menu provides several tools for organizing your feels. +these are all actions you can perform manually from the command line, but doing +them from within the program can help keep your files properly linked up. + +* **read over feels**--a list of all your entries, which you can open and + read like any other feel +* **modify feels publishing**--this lets you toggle privacy on individual + posts. entries marked `(nopub)` will not get written to html or gopher, + and toggling them from this menu will immediately publish or unpublish + that entry (if you're not publishing your posts at all, these settings + won't matter, since your feels will never show up outside of tilde.town) +* **backup your feels**--makes a .tar.gz of all your entries, saving one + copy to `~/.ttbp/backups/` with the current date, and a second copy to + your home directory for safekeeping. +* **import a feels backup**--unpacks a backup file into your current feels + list. this tool checks the `~/.ttbp/backups` directory for archives, and + expects a file created by the above backup utility. if it detects any file + collisions, it will preserve your current live copy and leave the backup + verison in a temp directory, and notify you that this happened. also, any + entries that were previously marked as `(nopub)` will retain their nopub + status. +* **bury some feels**--hides individual feels from viewing; entries are + moved to `~/.ttbp/buried` (and marked with a unique timestamp to prevent + file collision) with permissions set to 600, meaning no one except you + will be able to open that file. these entries are also hidden from your + own view from `read over feels`, and you'll have to open the files from + the command line if you want to see them. this is intended to be a + permament action, so you'll be asked to type the entry date once to load + the feel, then shown a preview of that feel, and then type the date again + to confirm burying. +* **delete feels by day**--*permanently removes individual entries*, + including deleting published html/gopher files if needed. this action is + not recoverable, unless you have a backup to restore; you'll be asked to + type the entry date once to load the feel, then shown a preview of that + feel, and then type the date again to confirm deletion. +* **purge all feels**--*permanently removes all feels*, including deleting + all published html/gopher files if needed. this action is not recoverable, + unless you have a backup to restore. you'll be asked to type a + one-time-use purge code to confirm this action. +* **wipe feels account**--*permanently removes all data associated with + feels*, including deleting any published hmtl/gopher files and removing + your `~/.ttbp` directory. any backups that you have in `~/.ttbp/backups` + will also be deleted with this action (which is why the backup function + makes a second copy for safekeeping in your home directory). you will no + longer show up in any lists as a user. + +### changing your page layout + +you can modify how your blog looks by editing the stylesheet or header and +footer files. the program sets you up with basic default. if you break your page +somehow, you can force the program to regenerate your configuration by deleting +your ~/.ttbp directory entirely. **you might want to back up your +~/.ttbp/entries directory before you do this.** + +* to modify your stylesheet, edit your ~/.ttbp/config/style.css +* to modify the page header, edit your ~/.ttbp/config/header.txt + * there's a place marked off in the default header where you can safely put + custom HTML elements! +* to modify the page footer, edit your ~/.ttbp/config/footer.txt + +### general tips/troubleshooting + +* if the date looks like it's ahead or behind, it's because you haven't set + your local timezone yet. here are some + [timezone setting instructions](http://www.cyberciti.biz/faq/linux-unix-set-tz-environment-variable/) +* the feels burying tool will effectively clear your post for the day; you can + use this feature to start a fresh entry on a particular day by burying the + current day's feels and then editing a new file + +### future features + +these are a few ideas being kicked around, or under active development: + +* stylesheet/theme selector +* better entry display within ttbp (currently just offloads to `less`) +* buried feels browser + +other ideas are listed on github as +[upcoming features](https://github.com/modgethanc/ttbp/issues?q=is%3Aissue+is%3Aopen+label%3A"upcoming+features") or [feature requests](https://github.com/modgethanc/ttbp/issues?q=is%3Aissue+is%3Aopen+label%3A"feature+request")!