# pharc wiki

**What is pharc?**

_pharc_ stands for _phlog archiver_. It is a script that organizes
your phlog posts on a yearly basis. It is optimized to archive phlog
posts created with [mkphlog](https://bitbucket.org/octotep/mkphlog),
written by Chris Yealy (octotep).

_mkphlog_, which can also be found at
_gopher://sdf.org/1/users/octotep/dls/mkphlog_ creates each phlog
post inside a directory named in the form: $(date +%m-%d-%y) 

**Is it possible to use _pharc_ even if the phlog was not created
with _mkphlog_?**

Yes, but just as long as you have your posts in directories named in
the form $(date +%m-%d-%y). Otherwise, using _pharc_ is pretty much
useless!!!

**Gopher? Phlog?**

Gopher <http://en.wikipedia.org/wiki/Gopher_(protocol)> 

Phlog <http://en.wikipedia.org/wiki/Phlog>

**Who cares about gopher and who cares about phlogs anymore?**

This question sounds like a song, and the chorus goes: "I do, I do, I
do..." And it seems that a bunch of other people do too.

**Is pharc FOSS?**

Absolutely!!! It is licensed under the GPL:

License GPLv3+: GNU GPL version 3 or later
<http://gnu.org/licenses/gpl.html>. This is free software: you are
free to change and redistribute it. There is NO WARRANTY, to the
extent permitted by law.

**Limitations**

_pharc_ takes for granted that you have a link in your `$HOME` to the
gopher server. Or more exactly, to`$HOME/gopher/phlog`. Even if this
might seem a little bit strange at first, it makes a lot of sense
(you do not need to become root to use it). Even though in certain
use cases this could be seen as a limitation, the path
`$HOME/gopher/phlog` will still be the default.

**Workaround:** You can _export_ `PHARC_WORKDIR=` specifying the path
to your phlog. Be aware that you need write permissions in that
directory. One example could be:

    $ export PHARC_WORKDIR="$HOME/phlog"
    $ pharc

or in just one go:

    $ export PHARC_WORKDIR="$HOME/phlog"; pharc

Another limitation is that _pharc_ only works with the 21st century
year range (2000-2099). If someone is interested in maintaining
_pharc_ from that deadline on, go ahead, feel free to do it. Thanks!

**What is the output of pharc? What will happen after it completes
its task successfully?**

_pharc_ creates *year archives*, so after it finishes, you will find
a directory in your phlog in the form  $(date +'%Y'). _pharc_ also
creates and edits the gophermaps in such a way that they will not
require manual intervention on your part to update the links.

Example: If you start your phlog in 2015, at the end of the year
_pharc_ will move all the scattered posts of the year into a
directory named 2015 and it will create a gophermap with the link:
**Archive 2015**. Much in the same way, the following year _pharc_
will create a directory named 2016 and thus you will have the
following layout at the end of the year:

Archive 2016

Archive 2015

And so on and so forth...

**Where can I catch a glimpse of how pharc works?**

That's easy to achieve:

You can see pharc's flowchart
[here.](https://docs.google.com/drawings/d/1ElvyVIyxDJ4RFGoOKNK3JwiFb1
cnbt1apOISYp4S-mA/edit?pli=1) Notice that it can be used both
interactively and/or non-interactively.

You can also visit my gopher hole at
_gopher://sdf-eu.org/1/users/chals_ or browse it on the web through a
gopher proxy 
[here](https://gopherproxy.meulie.net/sdfeu.org/1/users/chals)
or 
[here](http://gopher.floodgap.com//gopher/gw.lite?gopher://sdf-eu.org
/1/users/chals)

You can see pharc in action with these
[screenshots](http://blog.chalsattack.com/2012/06/pharc-wiki-and-pharc
-in-action.html)

**Is there any usage suggestion?**

_For non-interactive use:_

_pharc_ is meant to be used **only** once a year, **but before the
end of the year**. Since it is very easy to forget to run it manually
on New Year's Eve. I recommend using it with _cron_. For example:

55 23 31 12 *  #On December 31st just five minutes before midnight

In order to keep track of its progress, _pharc_ (v.4.0 and higher)
will create a log by default in `$HOME/pharc.log`. If you are running
an older version you can create a  log like this: `pharc 2>&1 >>
pharc.log` 

If you want to change the name or the location of the log file you
can export `PHARC_LOGFILE=`

    $ export PHARC_LOGFILE="/path/to/pharc.log"

**Note:** When used non-interactively, it is not necessary to specify
any option, _pharc_ will use the defaults. But it is also possible to
specify options.

_For interactive use:_

If you want to specify the year or years to be archived, by means of
the **-a** option, the suggested workflow could be:

First, list all the unarchived posts using the **-l** option:

    $ pharc -l
	
Once you know which year or years you want to archive, use the **-a**
option. For example:

    $ pharc -a 2010 2011 2012
	
If you want to archive all unarchived years at once you can use the
**-A** option.

**What if things go wrong?**

I do not have to say this because I imagine that you keep a backup of
your data, don't you? Anyway, do not worry, _pharc_ (v.3 and higher)
keeps a backup of your `gophermap` named  `gophermap~` This is a
hidden file but I guess you already know this too. Besides, _pharc_
does not overwrite or remove files by default so it should be pretty
much safe to run it.

Before creating the archive, _pharc_ performs several tests to see if
the script can be run. It will exit if optimal conditions are not
met. Once done, it will perform a final test to see if the script was
successful or not.

**What if I discover `pharc` too late and I already have posts from
several different years?**

Well, if you use _pharc_ v.3.0 or lower, it will only archive the
current year's posts and you will have to manually archive the rest
of the years. _pharc3_ includes the `-a|--archive` option to specify
the year of the archive. But be warned, this option is merely
redundant in version 3.0, means, that you can only specify the
current year.

_pharc4_ allows you to specify the year or years of the archive.
Imagine that you have scattered posts from 2012, 2013 and 2014. If
you type _pharc_ without any options it will archive the default
current year 2014. But if you specify, for example:

    $ pharc -a 2012
	
or
	
	$ pharc -a 2012 2013 2014
	
It will archive those years too **\o/**. The `-l|--list` option might
prove really handy to list all the unarchived posts before actually
archiving them.

_pharc5_ (and higher) allows you to archive all unarchived posts at
once by means of the **-A** option. 

**What is the difference between pharcX and pharc v.X.0?**

In a way, _pharcX_ is the development version, used for testing
purposes. And _pharc v.X.0_ is the final release.
Thus, for example, _pharc2_ became _pharc v.2.0_ after being
published.

A little bit of history:

_pharc1_ does not even exist. I wrote _pharc_ in 2011 as a script for
personal use to archive my phlog posts on a yearly basis. When I had
to update it, I named it _pharc1_. It works with _mkphlog v.0.1_

_pharc2_ is a clone of _pharc1_ but updated to work with _mkphlog
v.0.2_. _pharc_ v.2.0 was the preferred version during 2012.

_pharc3_ was released in 2013 as _pharc_ v.3.0. It included several
enhancements. You can read the changelog for the details.

_pharc4_ was released in June 2014 as _pharc_ v.4.0. It includes many
new options. See the changelog for details.

_pharc5_ was released in September 2015 as _pharc_ v.5.0. It includes
one new option. See the changelog for details.

_pharc6_ was released in January 2017 as _pharc_ v.6.0. It includes
minor fixes. See the changelog for details.

_pharc7_ was released in January 2022 as _pharc_ v.7.0. It only 
includes minor fixes. See the changelog for details. 

**How can I install _pharc_?**

If you want to install the raw script, copy it in your $PATH and make
it executable `$ chmod +x pharc`. `/usr/local/bin` is a nice place.
Then, from a terminal, call the script by simply typing `pharc` with
the options you want. Try: _pharc -h_.

If you are using the .deb package, become root and follow the
drill:`dpkg -i pharc_($VERSION)_all.deb`. Then, you can read the man
page if you like and call the script by simply typing _pharc_ (+
options) just like before. The .deb package installs the script in
`/usr/bin/` due to policy. Be warned that the debian package is not
maintained anymore!

**Why a debian package?**

Because I can? :-Þ

Now seriously, I used to build the .deb for personal use and for
learning purposes. It is really interesting to learn how to build
packages for a distribution. 

After releasing pharc v.6.0 with a minor cosmetic fix related to the
Archives layout I decided to drop the debian package for good.

The debian package is still available for pharc v.6.0 and older
releases but it will not be available for pharc v.7.0 or higher.

**Do I have to take a look at the script before using it?**

It depends. It is preferable that you understand what the script is
going to do to avoid possible side effects. The script is very
simple, if you can read shell commands then it will simply take you
five minutes. If you are not interested in reading it, nevermind.
Just fire it up and pray that I have foreseen all the cases in which
things can go wrong in your current phlog layout. But neither me nor
anyone else can guess how you have organized your phlog apart from
the default layout as created by mkphlog. 

**Why don't you edit the gophermaps in place instead of using <
input.file > output.file?**

Because the sed version in NetBSD 6.1.2 does not have the **-i**
option. If you are wondering who cares about NetBSD's sed version
someone could say: "Many people, for example: users, core developers,
contributors, enthusiasts, translators..." And even I do, because my
gopherhole is hosted on a NetBSD cluster so I need the script to work
in that environment.

**Why don't you optimize the calls to the shell?**

I know that for example writing:

    $ mkdir -p ${PHARC_WORKDIR}/${PHARC_ARCHIVE}

would be more optimal than:

    $ cd ${PHARC_WORKDIR}

    $ mkdir ${PHARC_ARCHIVE}

but when testing the script I use **set -x**. And it is easier for me
to follow the trace one step at a time ;)

**Why sh instead of say ksh, bash, zsh...whatever?**

_pharc_ was originally written with the _ksh_ in mind but was tested
on both _ksh_ and _bash_. Eventually, the she-bang was changed to
`#!/bin/sh` to make the script more portable. But to tell you the
truth, I do not care much about the shell as long as it is POSIX
compliant.

**Is pharc still actively developed?**

_pharc_ has now all the features and options I envisioned through all
these years of development. From now on I only intend to make bug
fixes and minor changes. 

**Thanks for using pharc!**

**CHANGELOG**

  * v.7.0

   * Updating file permissions for gophernicus.

  * v.6.0

    * Sort Archives in reverse mode.

  * v.5.0
	
    * Add '-A|--all' option to archive all years at once.

  * v.4.0
  
    * Changed shebang to #!/bin/sh to make script more portable.
    * Improved if[...]else statements to make script more robust.
    * Added functionality to choose year of archive.
    * Added functionality to specify several years in one go.
    * Added '-l|--list' option to list unarchived phlog posts.
    * Logging by default to "$HOME/pharc.log"
    * Split code into functions.
    * Added option '-d|--delete to delete the log file.
	
  * v.3.0

    * Added option -a to specify year of archive (Redundant).
    * Added -v (version information option).
    * Added -h (help menu).
    * Added -y (year of the archive).
    * Help function (usage).
    * Improve coding style.
    * Leave a backup of gophermap -> gophermap~ (in case things
break).
    * Test before echoing "You're done now. Thanks for using pharc."

  * v.2.0 

    * Updating for mkphlog v.0.2
    * Adding version number 2.0
    * Adding license (2012)

  * Initial release