\documentclass{doc}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{document}

\title{BibMate -- readme}

\author{Michał Lenart}

\maketitle


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section*{About}

BibMate is a simple, web-based reference management service, developed at the
Institute of Computer Science, Polish Academy of Sciences, Warsaw.

It features:
\begin{itemize}
\item import and export of bibliographic data to and from BibTeX (with full unicode support)
\item filtering publication lists by author, title, year and keyword
\item attaching PDF files to publications
\item generating pretty-formatted lists of citations in HTML, ready to be embedded on an external webpage
\item flawless MoinMoin wiki integration with provided plugin
\end{itemize}

\textbf{Homepage:} \url{http://zil.ipipan.waw.pl/BibMate/}

\textbf{Author:} Michał Lenart [michal.lenart@ipipan.waw.pl]

\textbf{License:} GPL v.3

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Requirements}

\subsection{Client}
On the client side it can be used with any modern web browser.

\subsection{Server}
BibMate service was tested only on Linux operating system (preferrably Debian-based one).

\subsubsection{Dependencies}
The service requires following libraries:
\begin{itemize}
\item Python \(v \ge 2.7\)
\item Django \(v \ge 1.3\)
\item Pybtex - Python library for BibTeX manipulation - \url{http://pybtex.sourceforge.net/} \(v \ge 0.15\)
\item lighttpd \(v \ge 1.4\) (should also work with Apache)
\item detex (part of texlive-binaries Ubuntu/Debian package)
\item bibclean \(v \ge 2.11.4\)
\end{itemize}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Standards for representation of bibliographic information}

BibMate uses BibTeX both for input and output of data.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Installation}

In order to run BibMate you need to proceed following steps.

\subsection{Editing application settings}
\label{EditingApplicationSettings}
Go to \verb|bibmate/bibmate| directory in the package. Edit the \verb|settings.py.SAMPLE| file.

You need to edit at least following variables:
\begin{itemize}
\item \verb|ROOT_URL| - the root URL for BibMate - for example: \url{http://zil.ipipan.waw.pl/publications}
\item \verb|STATIC_URL| - URL prefix for static files - CSS, images, Javascript, etc. (NOTE: it is highly recommended to host static files on different server then the BibMate application). The \verb|bibmate/static| directory (or its copy) has to be accessible from that address.
\item \verb|TITLE| - the title to be displayed on the front page, for example "My Publications Database"
\item \verb|LOGO_URL| - link to the logo to be displayed on the front page
\item \verb|TIME_ZONE| - local time zone for your installation
\item \verb|SQLITE_DB_LOCATION| - path to the file the application database will be stored in
\end{itemize}

\subsection{Initializing and running the application}
\label{InitializingAndRunning}

\subsubsection{Database initialization}
To initialize the database and create superuser account run:

\begin{verbatim}
python manage.py syncdb
\end{verbatim}

After that the application database will be initialized and BibMate will be ready to run.

\subsubsection{Running in development mode}
In order to test BibMate you can run it in development mode:
\begin{verbatim}
python manage.py runserver
\end{verbatim}

Now you can test BibMate at \url{http://127.0.0.1:8000} using your web browser (please don't use Internet Explorer when running development mode).

\subsubsection{Running as FastCGI server}

Suggested method for running production mode is via FastCGI:
\begin{verbatim}
python manage.py runfcgi host=<hostname> port=<port> \
    method=threaded \
    pidfile=/path/to/django/pid/file.pid \
    daemonize=true \
    errlog=/path/to/error.log \
    outlog=/path/to/output.log
\end{verbatim}

Each request sent by client web browser will be sent to this FastCGI server by lighttpd. If it is run on the same machine as webserver (lighttpd) then \verb|hostname| should be equal to \verb|127.0.0.1|.

\subsection{Configuring lighttpd webserver}

Once you have your BibMate instance running as FastCGI server you need to configure your webserver to connect to it.
The recommended way is to use lighttpd. All you need is edit sample configuration file provided in the package and run:
\begin{verbatim}
lighttpd -f lighttpd.conf
\end{verbatim}

From now on BibMate should be fully functional.

\subsection{Installing MoinMoin BibMate macro (optional)}
\label{InstallingMoinMoinBibMateMacro}

In order to use MoinMoin plugin you have to do the following:
\begin{itemize}
\item copy \verb|BibMate.py| file from \verb|bibmate/moin_macro| to \verb|/path_to_wiki_instance/data/plugin/macro|
\item change \verb|BIBMATE_PATH| variable in that file to the BibMate's URL (the same as \verb|ROOT_URL| variable mentioned in \ref{EditingApplicationSettings})
\item restart wiki server
\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Usage}

This section covers BibMate usage.

\subsection{Importing publications list from BibTeX}

Use ,,import'' link on the menu. You must be logged in to do this.

\subsection{Attaching PDF files}

Find desired publication, select the triangle on the left, click ,,edit'' link and upload the PDF file. You must be logged in to do this.

\subsection{Browsing publications list}

To see all of the publications simply enter the main BibMate webpage. You can also search by author, title, year and keywords with the search form on the top of the page.

\subsection{Exporting to BibTeX}

Click the ,,Download BibTeX file'' link on the top of the publications list. All currently viewed publications (with their crossrefs) will be exported to BibTeX.

\subsection{Embedding publications list on external webpage}

You can easily get your list of publications in HTML, without menu and logo by just getting a page at address \url{http://example.com/publications/list/} (with added ,,/list'' to the end of the URL) instead of \url{http://example.com/publications/}.

Moreover by adding some query parameters you can filter your publications list by:
\begin{itemize}
\item author names (list entries containing ,,kowalski'' or ,,nowak''):\linebreak
  \url{http://example.com/publications/list/?searchBy=author\&argument=kowalski\&argument=nowak}
\item title (list entries containing string ,,formal approach''):\linebreak
  \url{http://example.com/publications/list/?searchBy=title\&argument=formal\%20approach}
\item year (list entries published in years 2001 or 2002):\linebreak
 \url{http://example.com/publications/list/?searchBy=year\&argument=2001\&argument=2002}
\item keyword (list entries containing keywords ,,xml'' or ,,corpora''):\linebreak
  \url{http://example.com/publications/list/?searchBy=keyword\&argument=xml\&argument=corpora}
\item key (list entries with key equal to ,,key\_1'' or ,,key\_2''):\linebreak
  \url{http://example.com/publications/list/?searchBy=key\&argument=key1\&argument=key2}
\end{itemize}

\subsection{Using MoinMoin wiki plugin}

Once you have MoinMoin wiki with correctly installed plugin (see \ref{InstallingMoinMoinBibMateMacro}), you can embed into your wiki page:
\begin{itemize}
\item publications of people with given names: \verb|<<BibMate(author, "Jan Kowalski", "Jerzy Nowak")>>|
\item publications with given keys: \verb|<<BibMate(key, "prz:etal:11:ed", "coling:posters:10")>>|
\item publications with given keywords: \verb|<<BibMate(keyword, "xml", "corpora")>>|
\end{itemize}

You can also omit year headers in publications list on your wiki by using \verb|omitYears=true| parameter: \verb|<<BibMate(keyword, xml, corpora, omitYears=true)>>|


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Administration}

This section covers basic administration tasks regarding BibMate service.

\subsection{Running the service}
Running the service is covered in \ref{InitializingAndRunning}.
\subsection{Managing user accounts}
Use \url{http://example.com/publications/admin} page (assuming \url{http://example.com/publications} is your BibMate's root URL).
\subsection{Importing BibTeX using a commandline}
To import publications from BibTeX using a command line, you need to type (in bibmate directory):
\begin{verbatim}
python manage.py bib_import <path_to_bibtex_file>
\end{verbatim}
\end{document}
