forked from endorphant/ttbp
updating docs, closes #32
Vincent Zeng
parent
e1359d3899
commit
f564168bc1
246
README.html
246
README.html
|
|
@ -1,160 +1,190 @@
|
||||||
<p><em>a command-line based blogging platform running on tilde.town</em></p>
|
<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
|
<p><code>ttbp</code> stands for "tilde.town blogging platform", the original working name for
|
||||||
this project.</p>
|
this project.</p>
|
||||||
|
<p><img alt="ttbp main menu screenshot" src="http://tilde.town/~endorphant/ttbp/screenshots/ttbp-main.png" /></p>
|
||||||
<p><img src="http://tilde.town/~endorphant/ttbp/screenshots/ttbp-main.png" alt="ttbp main menu screenshot" /></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><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><code>ttbp</code> runs from the command line, providing a hub for writing personal blog
|
<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
|
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
|
like livejournal or dreamwidth or tumblr. you can opt to publish your posts to a
|
||||||
a public html file hosted on your tilde page, or keep all your entries private
|
public html file hosted on your tilde page, to tilde.town's gopher server, or
|
||||||
to the tilde.town server.</p>
|
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>to use, run <code>feels</code> while logged in to tilde.town</p>
|
||||||
|
<p>this is a project that runs on tilde.town, so all users of this program are
|
||||||
<p>(<code>feels</code> is a tilde.town specific command; if you're running this locally, or on
|
expected to operate under the tilde.town <a href="http://tilde.town/wiki/conduct.html">code of
|
||||||
a different server, run <code>ttbp</code> from the command line)</p>
|
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
|
||||||
<h3 id="quickstart">QUICK START</h3>
|
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
|
<p>no coding or html experience is necessary to get started. just log in to your
|
||||||
tilde.town account and enter:</p>
|
tilde.town account and enter:</p>
|
||||||
|
|
||||||
<p><code>feels</code></p>
|
<p><code>feels</code></p>
|
||||||
|
|
||||||
<p>ttbp will ask you a few questions to get you started. after that, writing and
|
<p>ttbp will ask you a few questions to get you started. after that, writing and
|
||||||
reading entries all happen within the program.</p>
|
reading entries all happen within the program.</p>
|
||||||
|
|
||||||
<p>that's it!</p>
|
<p>that's it!</p>
|
||||||
|
<h3>support</h3>
|
||||||
<h3 id="support">SUPPORT</h3>
|
|
||||||
|
|
||||||
<p>if you're having trouble getting started, or run into program errors or strange
|
<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
|
behavior, please send internal tilde.town mail to ~endorphant and i'll try to
|
||||||
sort things out!</p>
|
sort things out!</p>
|
||||||
|
<p>there's also a function from the main menu that lets you send feedback/inquiries
|
||||||
<h3 id="writingentries">writing entries</h3>
|
to me directly; this uses internal tilde.town mail, which is what i'll respond
|
||||||
|
to.</p>
|
||||||
<p>entries are recorded as plaintext files in your ~/.ttbp/entries
|
<h3>writing entries</h3>
|
||||||
directory. you can edit them there directly, or fix old entries, or
|
<p>entries are recorded as plaintext files in your <code>~/.ttbp/entries</code> directory.
|
||||||
delete entries.</p>
|
<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
|
||||||
<p><em>warning</em>: changing old entries might cause strange things to
|
your user account on tilde.town, you'll get a fresh entry. if you don't write
|
||||||
happen with timestamps. the main program looks at the filename
|
any feels on a particular day, no entries will show up there.</p>
|
||||||
first for setting the date, then the last modified time to sort
|
<p>when you save and quit the text editor, your entry will automatically propagate
|
||||||
recent posts. it expects YYYMMDD.txt as the filename; anything else
|
to the global feels list; if you've opted to publish your feels to html/gopher,
|
||||||
won't show up as a valid entry. yes, this means you can post things out
|
those files will update immediately. you can always go back to the current day's
|
||||||
of date order by creating files with any date you want.</p>
|
entry and edit/add as you'd like, but older entries will not be available for
|
||||||
|
editing from <code>ttbp</code>.</p>
|
||||||
<h4 id="generalentrywritingnotes">general entry-writing notes</h4>
|
<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>
|
<ul>
|
||||||
<li>you can use <a href="https://daringfireball.net/projects/markdown/syntax">markdown</a></li>
|
<li>you can use <a href="https://daringfireball.net/projects/markdown/syntax">markdown</a></li>
|
||||||
|
|
||||||
<li>you can use html</li>
|
<li>you can use html</li>
|
||||||
|
|
||||||
<li>you can also put things between <code><!-- comments --></code> to have them show up
|
<li>you can also put things between <code><!-- comments --></code> to have them show up
|
||||||
in the feed but not render in a browser (but people can still read
|
in the feed but not render in a browser (but people can still read
|
||||||
them with view-source)</li>
|
them with view-source)</li>
|
||||||
</ul>
|
</ul>
|
||||||
|
<h3>reading other feels</h3>
|
||||||
<h3 id="privacy">privacy</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
|
<p>when you start your ttbp, you have the option of publishing or not publishing
|
||||||
your blog.</p>
|
your blog.</p>
|
||||||
|
<p>if you opt to not publish, your entires will never be accessible from outside of
|
||||||
<p>if you opt to publish, the program creates a directory <code>~/.ttbp/www</code>
|
the tilde.town network; other tilde.town users will still be able to read your
|
||||||
where it stores all html files it generates, and symlinks this from your
|
entries through the ttbp interface, or by directly accessing 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
|
|
||||||
<code>~/.ttbp/entries</code> directory.</p>
|
<code>~/.ttbp/entries</code> directory.</p>
|
||||||
|
|
||||||
<p>if you want to further protect your entries, you can <code>chmod 700</code> your entries
|
<p>if you want to further protect your entries, you can <code>chmod 700</code> your entries
|
||||||
directory.</p>
|
directory.</p>
|
||||||
|
<p>if you opt to publish, the program creates a directory <code>~/.ttbp/www</code> where it
|
||||||
<h3 id="changingyourpagelayout">changing your page layout</h3>
|
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
|
||||||
<p>you can modify how your blog looks by editing the stylesheet or
|
page</a>.</p>
|
||||||
header and footer files. the program sets you up with basic
|
<p>you can also opt to publish to gopher, and the program will automatically
|
||||||
default. if you break your page somehow, you can force the program to
|
generate a gophermap of your feels.</p>
|
||||||
regenerate your configuration by deleting your ~/.ttbp directory entirely.
|
<p>you can set publishing status on individual entries, or bury individual feels;
|
||||||
<strong>you might want to back up your ~/.ttbp/entries directory before you do
|
see "data management" below for details.</p>
|
||||||
this.</strong></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>
|
<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>
|
<ul>
|
||||||
<li>(future feature: having multiple stylesheets you can select)</li></ul>
|
<li>to modify your stylesheet, edit your ~/.ttbp/config/style.css</li>
|
||||||
</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
|
||||||
<li>to modify the page header, edit your ~/.ttbp/config/header.txt
|
custom HTML elements!</li>
|
||||||
|
|
||||||
|
|
||||||
<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 the page footer, edit your ~/.ttbp/config/footer.txt</li>
|
<li>to modify the page footer, edit your ~/.ttbp/config/footer.txt</li>
|
||||||
</ul>
|
</ul>
|
||||||
|
<h3>general tips/troubleshooting</h3>
|
||||||
<h3 id="generaltipstroubleshooting">general tips/troubleshooting</h3>
|
|
||||||
|
|
||||||
<ul>
|
<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
|
<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
|
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>
|
<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>
|
</ul>
|
||||||
|
<h3>future features</h3>
|
||||||
<h3 id="futurefeatures">future features</h3>
|
|
||||||
|
|
||||||
<p>these are a few ideas being kicked around, or under active development:</p>
|
<p>these are a few ideas being kicked around, or under active development:</p>
|
||||||
|
|
||||||
<ul>
|
<ul>
|
||||||
<li>better entry privacy/publish control options</li>
|
|
||||||
|
|
||||||
<li>stylesheet/theme selector</li>
|
<li>stylesheet/theme selector</li>
|
||||||
|
<li>better entry display within ttbp (currently just offloads to <code>less</code>)</li>
|
||||||
<li>responding to entries</li>
|
<li>buried feels browser</li>
|
||||||
|
|
||||||
<li>paginated list view</li>
|
|
||||||
|
|
||||||
<li>better entry display within ttbp</li>
|
|
||||||
</ul>
|
</ul>
|
||||||
|
<p>other ideas are listed on github as
|
||||||
<h3 id="dependencies">dependencies</h3>
|
<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
|
<p>(this section is only relevant if you plan on forking the repo and running an
|
||||||
instance of this yourself)</p>
|
instance of this yourself)</p>
|
||||||
|
|
||||||
<ul>
|
<ul>
|
||||||
<li><a href="https://pypi.python.org/pypi/mistune">mistune</a></li>
|
<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/inflect">inflect</a></li>
|
||||||
|
<li><a href="https://pypi.python.org/pypi/six">six</a></li>
|
||||||
</ul>
|
</ul>
|
||||||
|
<h3>contributing</h3>
|
||||||
<h3 id="contributing">contributing</h3>
|
|
||||||
|
|
||||||
<p>please check out my <a href="https://github.com/modgethanc/ttbp/blob/master/.github/CONTRIBUTING.md">contributor
|
<p>please check out my <a href="https://github.com/modgethanc/ttbp/blob/master/.github/CONTRIBUTING.md">contributor
|
||||||
guidelines</a>
|
guidelines</a>
|
||||||
on github if you'd like to get involved with development!</p>
|
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
|
<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>
|
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>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>
|
||||||
177
README.md
177
README.md
|
|
@ -11,14 +11,18 @@ this project.
|
||||||
|
|
||||||
`ttbp` runs from the command line, providing a hub for writing personal blog
|
`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
|
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
|
like livejournal or dreamwidth or tumblr. you can opt to publish your posts to a
|
||||||
a public html file hosted on your tilde page, or keep all your entries private
|
public html file hosted on your tilde page, to tilde.town's gopher server, or
|
||||||
to the tilde.town server.
|
keep all your entries private to the tilde.town server.
|
||||||
|
|
||||||
to use, run `feels` while logged in to tilde.town
|
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
|
this is a project that runs on tilde.town, so all users of this program are
|
||||||
a different server, run `ttbp` from the command line)
|
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
|
### QUICK START
|
||||||
|
|
||||||
|
|
@ -32,24 +36,37 @@ reading entries all happen within the program.
|
||||||
|
|
||||||
that's it!
|
that's it!
|
||||||
|
|
||||||
### SUPPORT
|
### support
|
||||||
|
|
||||||
if you're having trouble getting started, or run into program errors or strange
|
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
|
behavior, please send internal tilde.town mail to ~endorphant and i'll try to
|
||||||
sort things out!
|
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
|
### writing entries
|
||||||
|
|
||||||
entries are recorded as plaintext files in your ~/.ttbp/entries
|
entries are recorded as plaintext files in your `~/.ttbp/entries` directory.
|
||||||
directory. you can edit them there directly, or fix old entries, or
|
`ttbp` will use your selected editor to open and write files; each day is its
|
||||||
delete entries.
|
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
|
when you save and quit the text editor, your entry will automatically propagate
|
||||||
happen with timestamps. the main program looks at the filename
|
to the global feels list; if you've opted to publish your feels to html/gopher,
|
||||||
first for setting the date, then the last modified time to sort
|
those files will update immediately. you can always go back to the current day's
|
||||||
recent posts. it expects YYYMMDD.txt as the filename; anything else
|
entry and edit/add as you'd like, but older entries will not be available for
|
||||||
won't show up as a valid entry. yes, this means you can post things out
|
editing from `ttbp`.
|
||||||
of date order by creating files with any date you want.
|
|
||||||
|
*(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
|
#### general entry-writing notes
|
||||||
|
|
||||||
|
|
@ -59,57 +76,129 @@ of date order by creating files with any date you want.
|
||||||
in the feed but not render in a browser (but people can still read
|
in the feed but not render in a browser (but people can still read
|
||||||
them with view-source)
|
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
|
### privacy
|
||||||
|
|
||||||
when you start your ttbp, you have the option of publishing or not publishing
|
when you start your ttbp, you have the option of publishing or not publishing
|
||||||
your blog.
|
your blog.
|
||||||
|
|
||||||
if you opt to publish, the program creates a directory `~/.ttbp/www`
|
if you opt to not publish, your entires will never be accessible from outside of
|
||||||
where it stores all html files it generates, and symlinks this from your
|
the tilde.town network; other tilde.town users will still be able to read your
|
||||||
`~/public_html` with your chosen blog directory. your blog will also be listed
|
entries through the ttbp interface, or by directly accessing your
|
||||||
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
|
|
||||||
`~/.ttbp/entries` directory.
|
`~/.ttbp/entries` directory.
|
||||||
|
|
||||||
if you want to further protect your entries, you can `chmod 700` your entries
|
if you want to further protect your entries, you can `chmod 700` your entries
|
||||||
directory.
|
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
|
### changing your page layout
|
||||||
|
|
||||||
you can modify how your blog looks by editing the stylesheet or
|
you can modify how your blog looks by editing the stylesheet or header and
|
||||||
header and footer files. the program sets you up with basic
|
footer files. the program sets you up with basic default. if you break your page
|
||||||
default. if you break your page somehow, you can force the program to
|
somehow, you can force the program to regenerate your configuration by deleting
|
||||||
regenerate your configuration by deleting your ~/.ttbp directory entirely.
|
your ~/.ttbp directory entirely. **you might want to back up your
|
||||||
**you might want to back up your ~/.ttbp/entries directory before you do
|
~/.ttbp/entries directory before you do this.**
|
||||||
this.**
|
|
||||||
|
|
||||||
* to modify your stylesheet, edit your ~/.ttbp/config/style.css
|
* 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
|
* 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
|
* there's a place marked off in the default header where you can safely put
|
||||||
you can safely put custom HTML elements!
|
custom HTML elements!
|
||||||
* to modify the page footer, edit your ~/.ttbp/config/footer.txt
|
* to modify the page footer, edit your ~/.ttbp/config/footer.txt
|
||||||
|
|
||||||
### general tips/troubleshooting
|
### 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
|
* if the date looks like it's ahead or behind, it's because you haven't set
|
||||||
your local timezone yet. here are some
|
your local timezone yet. here are some
|
||||||
[timezone setting instructions](http://www.cyberciti.biz/faq/linux-unix-set-tz-environment-variable/)
|
[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
|
### future features
|
||||||
|
|
||||||
these are a few ideas being kicked around, or under active development:
|
these are a few ideas being kicked around, or under active development:
|
||||||
|
|
||||||
* better entry privacy/publish control options
|
|
||||||
* stylesheet/theme selector
|
* stylesheet/theme selector
|
||||||
* responding to entries
|
* better entry display within ttbp (currently just offloads to `less`)
|
||||||
* paginated list view
|
* buried feels browser
|
||||||
* better entry display within ttbp
|
|
||||||
|
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
|
### dependencies
|
||||||
|
|
||||||
|
|
@ -118,6 +207,7 @@ instance of this yourself)
|
||||||
|
|
||||||
* [mistune](https://pypi.python.org/pypi/mistune)
|
* [mistune](https://pypi.python.org/pypi/mistune)
|
||||||
* [inflect](https://pypi.python.org/pypi/inflect)
|
* [inflect](https://pypi.python.org/pypi/inflect)
|
||||||
|
* [six](https://pypi.python.org/pypi/six)
|
||||||
|
|
||||||
### contributing
|
### 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.
|
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!
|
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
|
||||||
|
|
|
||||||
|
|
@ -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><!-- comments --></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>
|
||||||
|
|
@ -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")!
|
||||||
Loading…
Reference in New Issue