Re: [pyblosxom-users] pyblosxom 1.5rc2 released!

[seanh <sn...@gm...>]

On Tue, Sep 28, 2010 at 01:15:04AM +0000, Will Kahn-Greene wrote:
> 
> So let's work through your issues one at a time:
> 
> 1. The INSTALL file is different than the instructions on the
> web-site. That's because I did the 1.5rc2 release and then we did
> some documentation changes which I pushed to the web-site.  The
> changes should be persisted in git, but they haven't made it to a
> release tarball yet.

Right. So the instructions on the site are the newest ones.

> It's also possible that you were looking at the wrong site.  Were
> you looking at the instructions on http://pyblosxom.bluesock.org/ or
> http://pyblosxom.sourceforge.net/ ?

No, it was bluesock.org.

> 4. You couldn't get it to work with virtualenv.  It sounds like you
> missed a step when setting up the virtual environment.
> Incidentally, using virtual environments makes it really easy to
> encapsulate PyBlosxom and it's dependencies into a directory that
> you can wipe away if you don't want it around anymore.

That's good to know about. I'll have to learn my way around virtualenv
for the future.

> 5. You've now got a situation where you don't know what you've got
> on your system.  Ubuntu packages Python 2.6 such that all site
> packages are stored in the same place (might be dist packages--I
> know they changed the name between Python 2.5 and 2.6, but I don't
> remember the details offhand). Find that directory and you can just
> delete the pyblosxom related directory trees.  Then it won't be on
> your system anymore.

Great, thanks! Now I no how to clean up after python installers.

Haven't had time to return to trying to install pyblosxom yet. I thought
I'd try Jekyll instead, it is easy to install after all, just a simple
gem install ARGH! :)

> If anyone has any ideas on how to alleviate the confusion in the
> installation instructions, I'm interested in hearing them.  The
> source for the instructions is the INSTALL file in the git
> repository.

Sorry that I don't have time to work on the docs, but I will give my
thoughts.

Try not to duplicate instructions because they might go out of sync,
e.g. by having an INSTALL file and also install instructions on the
website.

The two notes at the top of the Installing PyBlosxom section in the docs
are insufficient. This is the version of the docs I'm talking about:

http://pyblosxom.bluesock.org/1.5/notes/INSTALL.html

Here's what I would do to it:

I think the Installing PyBlosxom section and subsections and the various
Deploying PyBlosxom sections and the upgrading pyblosxom section
probably need to be merged, they should each become subsections of one
big installing and deploying page. They have some overlap I think (e.g.
virtualenv and paste),  and the difference between 'installing' and
'deploying' is not obvious, if they were merged into one section then
that section could explain the difference at the top and contain all the
info on one page instead of spread about. I would suggest the following
headings:

Section: Installing and Deploying PyBlosxom
Subsection: Installing PyBlosxom on Your Computer
Subsubsection: Installing PyBlosxom with virtualenv and paste
Subsubsection: Upgrading PyBlosxom with virtualenv and paste
Subsubsection: Installing PyBlosxom with distribute and pip
Subsubsection: Upgrading PyBlosxom with distribute and pip
Subsubsection: Installing PyBlosxom with setuptools and easy_install
Subsubsection: Upgrading PyBlosxom with setuptools and easy_install
Subsection: Deploying PyBlosxom to a Web Server
The various subsubsections about the different ways of deploying.

At the top of "Section: Installing and Deploying PyBlosxom" explain the
difference between "Installing PyBlosxom on Your Computer" and
"Deploying PyBlosxom to a Web Server".

At the top of "Subsection: Installing PyBlosxom on Your Computer" add a
paragraph explaining why there are multiple ways of installing pyblosxom
on your computer, and some advice to the user about which they should
choose.  This should be in the form of an explanatory paragraph, an
introduction to the section, currently there is a brief note saying
virtualenv is easiest (and the instructions for virtualenv are elsewhere
in a different section!). This is what I think it should explain: from
what I now understand there are three ways to install: with virtualenv
and paste, with distribute and pip, or with setuptools and easy_install.
New users who just want to try out PyBlosxom and people who want to hack
on PyBlosxom want to use virtualenv because it's easy to undo, it should
say this right at the top of the section, and then the first subsection
in the section should be the one that tells you how to install with
virtualenv. Then, after trying PyBlosxom and deciding you want to use
it, if you need to install it on your system you can do so with either
distribute and pip or with setuptools and easy_install.  There are two
ways to install because Python, unfortunately, currently has two
incompatible packaging systems.  Warning: Choose one or the other, but
don't try both as they will conflict with each other. Then the
subsections about virtualenv, distribute and pip, and setuptools and
easy_install would follow.

In the subsubsections about each way of installing, explain briefly and
in general terms what the install commands do. I know you won't be able
to give exact details as it varies from system to system, but something
like "it installs files to a specific place, e.g.
/path/to/dist-packages on Ubuntu", would be a good idea, just so these
commands seem less like sorcery and the user has at least a starting
point if they need to debug or undo something.

Hope that helps anyone who might do some work on the docs!