On 6/6/07, will <willg@...> wrote:
> John, Ryan and I finished converting documents from docbook to reST
> format. In the process of doing that, I did a pass on updating the
> language in them and fixing areas that needed improvement. There's
> still a lot of work that can be done, but hopefully switching to reST
> will make it a lot easier for people to contribute.
Great news Will. Thanks.
> If anyone can lend me 15-20 minutes of their time to help QC the RC,
> that'd be really fantastic.
I just made some time to download the rc1 and try it out. Note, I'm
still a very new pyblosxom user. Some first things I notice:
1. I wanted to read the docs as html. I see that, in the docs
directory, there's a couple of css files and a docutils conf file. You
might also provide a simple script that generates all the html docs
for the user.
2. Also regarding the doc files:
2.A. In the index.txt file, the first of those links to the
pyblosxom-devel ML should probably point to
https://lists.sourceforge.net/lists/listinfo/pyblosxom-devel . The 2nd
link should probably just be `let us know`__ , where that link is the
2.B. about_pyblosxom: make "Blosxom" a link to http://www.blosxom.com/
2.C. installation: why have 2 install docs: the INSTALL file and this
one? Can we consolidate them? Maybe have INSTALL just be a note
referring the user to look in docs/installation.txt?
3. In config.py, change 2005 to 2007. Also correct "shouldt".
So, it installed and worked fine on a Slackware server running Apache,
with Python 2.5 out of my own home directory (installed in
``~/py-2.5.1``). I've got the docutils installed here too, so figured
I'd set things up so I could write my entries formatted in reST.
Grabbed contrib-1.3.3 for this. I might've tried getting it from svn,
but I didn't see rst listed at
. Is it supposed to be there? In the contrib-1.3.3 archive, the entry
parsers are separated from the plugins. Why is that?
Incidentally, the writing_entries.txt doc calls them "entry parsers"
-- you might mention there that they're located in the "text" section
of the plugin registry.
Anyhow, after copying the rst.py file to my plugins directory, setting
py['plugin_dirs'] in config.py, and making a new .rst entry for the
blog, I tried accessing it and got an error from my webhost. No error
in the pyblosxom.log file. My plugins directory now contains a rst.pyc
file. From a Python prompt, I can import the docutils modules, but
cannot import Pyblosxom modules.
After uncommenting the ``import cgitb; cgitb.enable()`` line in
pyblosxom.cgi, the resulting error page tells me ``ImportError: No
module named docutils.core`` and that the system Python is running
instead of my locally installed one. I changed the shebang in
pyblosxom.cgi to explicitly use my own python (instead of relying on
/usr/bin/env), and that fixed things.
Next up was to try making it look a little prettier. Reading the
flavours_and_templates page, I notice you use the word "style" here.
Users reading this chapter will be thinking of css stylesheets, so you
might want to use a different word.
For now, I only want to use the blosxom renderer, and only want html
output, and I'm guessing that most pyblosxom users start out this way.
Maybe this portion of the manual should have a "Common basic setups"
section for this. Also, it's seeming like there should be more
overview material in the about_pyblosxom chapter of the manual -- or
else maybe an overview.txt chapter of the manual.
Well, I grabbed the Gray plugin. Still reading the
flavours_and_templates chapter, I think the first paragraph of the
"Where to Put Your Flavour Files" could use some clarification. I
don't yet know whether I want to (or what it means to) override and
existing flavour or add a new flavour. So, the manual starts talking
about "order of overiding" (sic), and ... and then I'm totally lost at
A tutorial for creating your own very simple html flavour would be
most helpful here.