endorphant/ttbp
1
0
Fork 1
Code Issues 2 Pull Requests Releases Wiki Activity

updating docs, closes #32

Browse Source
This commit is contained in:
Vincent Zeng 2018-03-22 23:11:27 -04:00
parent e1359d3899
commit f564168bc1
4 changed files with 621 additions and 153 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

254
README.html
View File

@ -1,160 +1,190 @@
<p><em>a command-line based blogging platform running on tilde.town</em></p>
<p><code>ttbp</code> stands for "tilde.town blogging platform", the original working name for
this project.</p>
<p><img src="http://tilde.town/~endorphant/ttbp/screenshots/ttbp-main.png" alt="ttbp main menu screenshot" /></p>
<p><img src="http://tilde.town/~endorphant/ttbp/screenshots/ttbp-entries.png" alt="ttbp entries view screenshot" /></p>
<p><img src="http://tilde.town/~endorphant/ttbp/screenshots/ttbp-compose.png" alt="ttbp compose view screenshot" /></p>
<p><img alt="ttbp main menu screenshot" src="http://tilde.town/~endorphant/ttbp/screenshots/ttbp-main.png" /></p>
<p><img alt="ttbp entries view screenshot" src="http://tilde.town/~endorphant/ttbp/screenshots/ttbp-entries.png" /></p>
<p><img alt="ttbp compose view screenshot" src="http://tilde.town/~endorphant/ttbp/screenshots/ttbp-compose.png" /></p>
<p><code>ttbp</code> 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.</p>
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.</p>
<p>to use, run <code>feels</code> while logged in to tilde.town</p>
<p>(<code>feels</code> is a tilde.town specific command; if you're running this locally, or on
a different server, run <code>ttbp</code> from the command line)</p>
<h3 id="quickstart">QUICK START</h3>
<p>this is a project that runs on tilde.town, so all users of this program are
expected to operate under the tilde.town <a href="http://tilde.town/wiki/conduct.html">code of
conduct</a>. content/personal issues should be
worked out according to the CoC, with support from the <a href="http://tilde.town/wiki/administration/index.html">administrative
team</a> if needed.</p>
<h3>QUICK START</h3>
<p>no coding or html experience is necessary to get started. just log in to your
tilde.town account and enter:</p>
<p><code>feels</code></p>
<p>ttbp will ask you a few questions to get you started. after that, writing and
reading entries all happen within the program.</p>
<p>that's it!</p>
<h3 id="support">SUPPORT</h3>
<h3>support</h3>
<p>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!</p>
<h3 id="writingentries">writing entries</h3>
<p>entries are recorded as plaintext files in your ~/.ttbp/entries
directory. you can edit them there directly, or fix old entries, or
delete entries.</p>
<p><em>warning</em>: 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.</p>
<h4 id="generalentrywritingnotes">general entry-writing notes</h4>
<p>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.</p>
<h3>writing entries</h3>
<p>entries are recorded as plaintext files in your <code>~/.ttbp/entries</code> directory.
<code>ttbp</code> 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.</p>
<p>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 <code>ttbp</code>.</p>
<p><em>(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.)</em></p>
<h4>general entry-writing notes</h4>
<ul>
<li>you can use <a href="https://daringfireball.net/projects/markdown/syntax">markdown</a></li>
<li>you can use html</li>
<li>you can also put things between <code>&lt;!-- comments --&gt;</code> to have them show up
in the feed but not render in a browser (but people can still read
them with view-source)</li>
in the feed but not render in a browser (but people can still read
them with view-source)</li>
</ul>
<h3 id="privacy">privacy</h3>
<h3>reading other feels</h3>
<p>the <code>browse global feels</code> 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.</p>
<p>you can also pull up a list of a single user's feels through <code>check out your
neighbors</code>, which displays all users who are writing on <code>ttbp</code> based on their
most recently updated entry, and a link to their public html blog if they've
opted to publish their posts.</p>
<p><strong>please note!</strong> entries written on <code>ttbp</code> 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 <code>ttbp</code> is
designed to give individuals control over their content.</p>
<h3>privacy</h3>
<p>when you start your ttbp, you have the option of publishing or not publishing
your blog.</p>
<p>if you opt to publish, the program creates a directory <code>~/.ttbp/www</code>
where it stores all html files it generates, and symlinks this from your
<code>~/public_html</code> with your chosen blog directory. your blog will also be listed
on the <a href="https://tilde.town/~endorphant/ttbp">main ttbp page</a>.</p>
<p>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
<p>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
<code>~/.ttbp/entries</code> directory.</p>
<p>if you want to further protect your entries, you can <code>chmod 700</code> your entries
directory.</p>
<h3 id="changingyourpagelayout">changing your page layout</h3>
<p>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.
<strong>you might want to back up your ~/.ttbp/entries directory before you do
this.</strong></p>
<p>if you opt to publish, the program creates a directory <code>~/.ttbp/www</code> where it
stores all html files it generates, and symlinks this from your <code>~/public_html</code>
with your chosen blog directory. your blog will also be listed on the <a href="https://tilde.town/~endorphant/ttbp">main ttbp
page</a>.</p>
<p>you can also opt to publish to gopher, and the program will automatically
generate a gophermap of your feels.</p>
<p>you can set publishing status on individual entries, or bury individual feels;
see "data management" below for details.</p>
<h3>data management</h3>
<p>the <code>manage your feels</code> 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.</p>
<ul>
<li>to modify your stylesheet, edit your ~/.ttbp/config/style.css
<li><strong>read over feels</strong>--a list of all your entries, which you can open and
read like any other feel</li>
<li><strong>modify feels publishing</strong>--this lets you toggle privacy on individual
posts. entries marked <code>(nopub)</code> 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)</li>
<li><strong>backup your feels</strong>--makes a .tar.gz of all your entries, saving one
copy to <code>~/.ttbp/backups/</code> with the current date, and a second copy to
your home directory for safekeeping.</li>
<li><strong>import a feels backup</strong>--unpacks a backup file into your current feels
list. this tool checks the <code>~/.ttbp/backups</code> 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 <code>(nopub)</code> will retain their nopub
status.</li>
<li><strong>bury some feels</strong>--hides individual feels from viewing; entries are
moved to <code>~/.ttbp/buried</code> (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 <code>read over feels</code>, 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.</li>
<li><strong>delete feels by day</strong>--<em>permanently removes individual entries</em>,
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.</li>
<li><strong>purge all feels</strong>--<em>permanently removes all feels</em>, 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.</li>
<li><strong>wipe feels account</strong>--<em>permanently removes all data associated with
feels</em>, including deleting any published hmtl/gopher files and removing
your <code>~/.ttbp</code> directory. any backups that you have in <code>~/.ttbp/backups</code>
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.</li>
</ul>
<h3>changing your page layout</h3>
<p>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. <strong>you might want to back up your
~/.ttbp/entries directory before you do this.</strong></p>
<ul>
<li>(future feature: having multiple stylesheets you can select)</li></ul>
</li>
<li>to modify the page header, edit your ~/.ttbp/config/header.txt
<ul>
<li>you might note that there's a place marked off in the default header where
you can safely put custom HTML elements!</li></ul>
</li>
<li>to modify your stylesheet, edit your ~/.ttbp/config/style.css</li>
<li>to modify the page header, edit your ~/.ttbp/config/header.txt</li>
<li>there's a place marked off in the default header where you can safely put
custom HTML elements!</li>
<li>to modify the page footer, edit your ~/.ttbp/config/footer.txt</li>
</ul>
<h3 id="generaltipstroubleshooting">general tips/troubleshooting</h3>
<h3>general tips/troubleshooting</h3>
<ul>
<li>add <code>alias ttbp="~endorphant/bin/ttbp"</code> to your .bash_aliases for fewer keystrokes</li>
<li>(similarly, <code>alias ttbp-beta="~endorphant/bin/ttbp-beta"</code>)</li>
<li>if the date looks like it's ahead or behind, it's because you haven't set
your local timezone yet. here are some
<a href="http://www.cyberciti.biz/faq/linux-unix-set-tz-environment-variable/">timezone setting instructions</a></li>
your local timezone yet. here are some
<a href="http://www.cyberciti.biz/faq/linux-unix-set-tz-environment-variable/">timezone setting instructions</a></li>
<li>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</li>
</ul>
<h3 id="futurefeatures">future features</h3>
<h3>future features</h3>
<p>these are a few ideas being kicked around, or under active development:</p>
<ul>
<li>better entry privacy/publish control options</li>
<li>stylesheet/theme selector</li>
<li>responding to entries</li>
<li>paginated list view</li>
<li>better entry display within ttbp</li>
<li>better entry display within ttbp (currently just offloads to <code>less</code>)</li>
<li>buried feels browser</li>
</ul>
<h3 id="dependencies">dependencies</h3>
<p>other ideas are listed on github as
<a href="https://github.com/modgethanc/ttbp/issues?q=is%3Aissue+is%3Aopen+label%3A" title="upcoming+features">upcoming features</a> or <a href="https://github.com/modgethanc/ttbp/issues?q=is%3Aissue+is%3Aopen+label%3A" title="feature+request">feature requests</a>!</p>
<h3>dependencies</h3>
<p>(this section is only relevant if you plan on forking the repo and running an
instance of this yourself)</p>
<ul>
<li><a href="https://pypi.python.org/pypi/mistune">mistune</a></li>
<li><a href="https://pypi.python.org/pypi/inflect">inflect</a></li>
<li><a href="https://pypi.python.org/pypi/six">six</a></li>
</ul>
<h3 id="contributing">contributing</h3>
<h3>contributing</h3>
<p>please check out my <a href="https://github.com/modgethanc/ttbp/blob/master/.github/CONTRIBUTING.md">contributor
guidelines</a>
on github if you'd like to get involved with development!</p>
<p>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.</p>
<p>if you're interested in helping with the code, please drop me some tildemail!</p>
<p>i accept tips for development work on
<a href="https://liberapay.com/modgethanc">liberapay</a></p>
<h3>contributor shout-outs</h3>
<p>thanks to:</p>
<ul>
<li>~vilmibm, packaging help and gopher support</li>
<li>~sanqui, the bug swatter</li>
<li>~sinacutie, for css updates</li>
</ul>

181
README.md
View File

@ -11,14 +11,18 @@ 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.
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.
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](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.
### QUICK START
@ -32,84 +36,169 @@ reading entries all happen within the program.
that's it!
### SUPPORT
### 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. you can edit them there directly, or fix old entries, or
delete 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.
*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.
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 `<!-- comments -->` to have them show up
in the feed but not render in a browser (but people can still read
them with view-source)
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 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).
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.
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.**
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
* (future feature: having multiple stylesheets you can select)
* to modify the page header, edit your ~/.ttbp/config/header.txt
* you might note that there's a place marked off in the default header where
you can safely put custom HTML elements!
* 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
* add `alias ttbp="~endorphant/bin/ttbp"` to your .bash_aliases for fewer keystrokes
* (similarly, `alias ttbp-beta="~endorphant/bin/ttbp-beta"`)
* 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:
* better entry privacy/publish control options
* stylesheet/theme selector
* responding to entries
* paginated list view
* better entry display within ttbp
* 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")!
### dependencies
@ -118,6 +207,7 @@ instance of this yourself)
* [mistune](https://pypi.python.org/pypi/mistune)
* [inflect](https://pypi.python.org/pypi/inflect)
* [six](https://pypi.python.org/pypi/six)
### contributing
@ -129,3 +219,14 @@ 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!
i accept tips for development work on
[liberapay](https://liberapay.com/modgethanc)
### contributor shout-outs
thanks to:
* ~vilmibm, packaging help and gopher support
* ~sanqui, the bug swatter
* ~sinacutie, for css updates

156
doc/manual.html Normal file
View File

@ -0,0 +1,156 @@
<h1>FEELS MANUAL</h1>
<p><code>ttbp</code> stands for "tilde.town blogging platform", the original working name for
this project. the complete codebase is available on
<a href="https://github.com/modgethanc/ttbp">github</a>.</p>
<p><code>ttbp</code> 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.</p>
<p>this is a project that runs on tilde.town, so all users of this program are
expected to operate under the tilde.town <a href="http://tilde.town/wiki/conduct.html">code of
conduct</a>. content/personal issues should be
worked out according to the CoC, with support from the <a href="http://tilde.town/wiki/administration/index.html">administrative
team</a> if needed.</p>
<h3>support</h3>
<p>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!</p>
<p>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.</p>
<h3>writing entries</h3>
<p>entries are recorded as plaintext files in your <code>~/.ttbp/entries</code> directory.
<code>ttbp</code> 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.</p>
<p>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 <code>ttbp</code>.</p>
<p><em>(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.)</em></p>
<h4>general entry-writing notes</h4>
<ul>
<li>you can use <a href="https://daringfireball.net/projects/markdown/syntax">markdown</a></li>
<li>you can use html</li>
<li>you can also put things between <code>&lt;!-- comments --&gt;</code> to have them show up
in the feed but not render in a browser (but people can still read them with
view-source)</li>
</ul>
<h3>reading other feels</h3>
<p>the <code>browse global feels</code> 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.</p>
<p>you can also pull up a list of a single user's feels through <code>check out your
neighbors</code>, which displays all users who are writing on <code>ttbp</code> based on their
most recently updated entry, and a link to their public html blog if they've
opted to publish their posts.</p>
<p><strong>please note!</strong> entries written on <code>ttbp</code> 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 <code>ttbp</code> is
designed to give individuals control over their content.</p>
<h3>privacy</h3>
<p>when you start your ttbp, you have the option of publishing or not publishing
your blog.</p>
<p>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
<code>~/.ttbp/entries</code> directory.</p>
<p>if you want to further protect your entries, you can <code>chmod 700</code> your entries
directory.</p>
<p>if you opt to publish, the program creates a directory <code>~/.ttbp/www</code> where it
stores all html files it generates, and symlinks this from your <code>~/public_html</code>
with your chosen blog directory. your blog will also be listed on the <a href="https://tilde.town/~endorphant/ttbp">main ttbp
page</a>.</p>
<p>you can also opt to publish to gopher, and the program will automatically
generate a gophermap of your feels.</p>
<p>you can set publishing status on individual entries, or bury individual feels;
see "data management" below for details.</p>
<h3>data management</h3>
<p>the <code>manage your feels</code> 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.</p>
<ul>
<li><strong>read over feels</strong>--a list of all your entries, which you can open and
read like any other feel</li>
<li><strong>modify feels publishing</strong>--this lets you toggle privacy on individual
posts. entries marked <code>(nopub)</code> 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)</li>
<li><strong>backup your feels</strong>--makes a .tar.gz of all your entries, saving one
copy to <code>~/.ttbp/backups/</code> with the current date, and a second copy to
your home directory for safekeeping.</li>
<li><strong>import a feels backup</strong>--unpacks a backup file into your current feels
list. this tool checks the <code>~/.ttbp/backups</code> 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 <code>(nopub)</code> will retain their nopub
status.</li>
<li><strong>bury some feels</strong>--hides individual feels from viewing; entries are
moved to <code>~/.ttbp/buried</code> (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 <code>read over feels</code>, 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.</li>
<li><strong>delete feels by day</strong>--<em>permanently removes individual entries</em>,
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.</li>
<li><strong>purge all feels</strong>--<em>permanently removes all feels</em>, 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.</li>
<li><strong>wipe feels account</strong>--<em>permanently removes all data associated with
feels</em>, including deleting any published hmtl/gopher files and removing
your <code>~/.ttbp</code> directory. any backups that you have in <code>~/.ttbp/backups</code>
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.</li>
</ul>
<h3>changing your page layout</h3>
<p>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. <strong>you might want to back up your
~/.ttbp/entries directory before you do this.</strong></p>
<ul>
<li>to modify your stylesheet, edit your ~/.ttbp/config/style.css</li>
<li>to modify the page header, edit your ~/.ttbp/config/header.txt</li>
<li>there's a place marked off in the default header where you can safely put
custom HTML elements!</li>
<li>to modify the page footer, edit your ~/.ttbp/config/footer.txt</li>
</ul>
<h3>general tips/troubleshooting</h3>
<ul>
<li>if the date looks like it's ahead or behind, it's because you haven't set
your local timezone yet. here are some
<a href="http://www.cyberciti.biz/faq/linux-unix-set-tz-environment-variable/">timezone setting instructions</a></li>
<li>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</li>
</ul>
<h3>future features</h3>
<p>these are a few ideas being kicked around, or under active development:</p>
<ul>
<li>stylesheet/theme selector</li>
<li>better entry display within ttbp (currently just offloads to <code>less</code>)</li>
<li>buried feels browser</li>
</ul>
<p>other ideas are listed on github as
<a href="https://github.com/modgethanc/ttbp/issues?q=is%3Aissue+is%3Aopen+label%3A" title="upcoming+features">upcoming features</a> or <a href="https://github.com/modgethanc/ttbp/issues?q=is%3Aissue+is%3Aopen+label%3A" title="feature+request">feature requests</a>!</p>

181
doc/manual.md Normal file
View File

@ -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 `<!-- comments -->` 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")!