1
0
Fork 0
mirror of https://github.com/wallabag/wallabag.git synced 2025-09-15 18:57:05 +00:00
This commit is contained in:
Nicolas Lœuillet 2015-10-21 14:14:51 +02:00
parent a4e1ddf2d6
commit 59e91bc893
58 changed files with 2643 additions and 0 deletions

View file

@ -0,0 +1,85 @@
Hidden options
==============
Caution
-------
**Be careful**, this section is destined to advanced users. We are going
to modify an important wallabag configuration file,
``inc/poche/config.inc.php``. It is therefore advised to do a backup of
this file before you proceed. **Any error occuring during the
modification of a wallabag file could lead to malfunctions**.
This file is created when you install wallabag. Install wallabag, do a
backup copy of the file, then open it in your favorite text editor.
In this file, there are some options that are not, as of now, available
in the **config** page of wallabag.
Modification of advanced options
--------------------------------
Each option is defined this way:
::
@define ('OPTION_NAME', 'Value');
For each line, you can only modify the ``Value`` field.
Here is the list of each option you can change:
- ``HTTP_PORT`` (default: ``80``) : the HTTP port of your web server.
You may need to change it if your server is behind a proxy. Accepted
values: number
- ``SSL_PORT`` (default: ``443``) : the HTTP port of your web server.
You may need to change it if your server use SSLH. Accepted values:
number
- ``MODE_DEMO`` (default : ``FALSE)``: If you ever wanted to set up a
demonstration server… Accepted values: ``TRUE`` or ``FALSE``.
- ``DEBUG_POCHE`` (default: ``FALSE``) : if you encounter some problems
with wallabag, we may ask you to active Debug mode. Accepted values:
``TRUE`` or ``FALSE``. Check the logs in cache/log.txt after
activating that.
- ``ERROR_REPORTING`` (default : ``E_ALL & ~E_NOTICE``) : Set to
``E_ALL`` if needed to look for eventual PHP errors.
- ``DOWNLOAD_PICTURES`` (default: ``FALSE``) : Allows wallabag to fetch
images from the articles you save on your server, instead of fetching
only the text. We prefer to let you activate this option yourself.
Accepted values: ``TRUE`` or ``FALSE``.
- ``REGENERATE_PICTURES_QUALITY`` (default : ``75``) : In order to
avoid security problems, pictures are regenerated if you activate the
download of pictures. This is the percentage of quality at which they
are saved. Increase that numbler if you want better quality, lower if
you need better performances.
- ``SHARE_TWITTER`` (default: ``TRUE``) : enables Twitter sharing.
Accepted values: ``TRUE`` or ``FALSE``.
- ``SHARE_MAIL`` (default: ``TRUE``) : enables mail sharing. Accepted
values: ``TRUE`` or ``FALSE``.
- ``SHARE_EVERNOTE``\ (default : ``FALSE``) : enables sharing with your
Evernote account. Accepted values: ``TRUE`` or ``FALSE``.
- ``SHARE_DIASPORA`` (default : ``FALSE``) : enables to share an
article on your Diaspora account.
- ``DIASPORA_URL`` (default : ``http://diasporapod.com``) : The URL of
your Diaspora\* pod
- ``CARROT`` (default : ``FALSE``) : Like Flattr, its a service to
give small amounts of money to a web page. See http://carrot.org/
- ``SHARE_SHAARLI`` (default: ``FALSE``) : enables sharing via your
Shaarli installation (Shaarli is an open-source bookmark manager).
Accepted values: ``TRUE`` or ``FALSE``.
- ``SHAARLI_URL`` (default: ``'http://myshaarliurl.com'``) : defines
your Shaarli installation URL. Accepted values: an URL.
- ``FLATTR`` (default: ``TRUE``) : enables the possibility to Flattr an
article (`Flattr is a microdonation platform`_). If an article is
Flattr-able, an icon will be displayed, allowing you to send a
microdonation to the author. Accepted values: ``TRUE`` or ``FALSE``.
- ``SHOW_PRINTLINK`` (default: ``'1'``) : enables the Print button for
articles. Accepted values: ``'1'`` to enable or ``'0'`` to disable.
- ``SHOW_READPERCENT`` (default: ``'1'``) : enables the reading
progress on articles (working on the ``default``, ``dark``,
``dmagenta``, ``solarized``, ``solarized-dark`` themes). Accepted
values: ``'1'`` to enable or ``'0'`` to disable.
- ``PAGINATION`` (default: ``'12'``) : defines the number of articles
that are displayed on a list. Accepted values: number.
.. _Flattr is a microdonation platform: http://en.wikipedia.org/wiki/Flattr

View file

@ -0,0 +1,200 @@
Download and install wallabag
=============================
I dont want to install wallabag
--------------------------------
If you cant or dont want to install Wallabag on your server, we
suggest you create a free account on `Framabag`_ which uses our
software (see :ref:`Framabag account creation`).
I want to install wallabag
--------------------------
I want to download wallabag manually
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
`Download the latest wallabag version`_ and unpack it:
::
wget http://wllbg.org/latest
unzip latest
mv wallabag-version-number wallabag
Copy the files on your web server. For Ubuntu/Debian, it is the
directory /var/www/html/ :
::
sudo mv wallabag /var/www/html/
Then, jump off to next section.
I want to download wallabag via composer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You need to install composer:
::
curl -s http://getcomposer.org/installer | php
Next, on your web server, run this command:
::
composer create-project wallabag/wallabag . dev-master
All is downloaded into the current folder.
Prerequisites for your web server
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Wallabag requires that several components to be installed on your web
server. To make sure your server has all the prerequisites, open in your
browser the page ``http://monserveur.com/wallabag/install/index.php``.
The components are:
- `PHP 5.3.3 or above`_ **with `PDO`_ support**
- `XML for PHP`_
- `PCRE`_
- `ZLib`_ (otherwise, the processing of compressed pages will be
affected)
- `mbstring`_ anb/or `iconv`_ (otherwise some pages will not be read -
even in English)
- The `DOM/XML`_ extension
- `Data filtering`_
- `GD`_ (otherwise, pictures will not be saved)
- `Tidy for PHP`_ (otherwise, you may encounter problems with some
pages)
- `cURL`_ with ``Parallel URL fetching`` (optionnal)
- `Parse ini file`_
- `allow\_url\_fopen`_ (optionnal if cURL is installed)
- `gettext`_ (required for multi-language support)
Install the missing components before to proceed. For example, to
install Tidy on Ubuntu/Debian:
::
sudo apt-get install php5-tidy
sudo service apache2 reload
Note : if youre using IIS as a webserver, you have to disable
*Anonymous Authentication* and `enable *Basic Authentication*`_ in order
to be able to login.
Twig installation
^^^^^^^^^^^^^^^^^
wallabag is build with Twig, a template library. You have to download it
for wallabag to work. If you cannot install ``composer`` (for example in
the case of shared hosting), we offer you to download a file which
includes ``Twig``. This file can be downloaed from the page
``http://myservur.com/wallabag/install/index.php`` (section TWIG
INSTALLATION) or directly at http://wllbg.org/vendor. Uncompress it in
your wallabag directory.
Otherwise, you can use Composer to install ``Twig`` by launching
``composer`` from your wallabag directory (in the case of Ubuntu/Debian
too: /var/www/html/wallabag/) by following the commands written on
screen:
::
curl -s http://getcomposer.org/installer | php
php composer.phar install
Creation of the database.
^^^^^^^^^^^^^^^^^^^^^^^^^
Wallabag can be installed on different types of databases:
- `SQLite`_. The easiest system of all. No extra configuration needed.
- `MySQL`_. A well known database system, which is in most cases more
efficient than SQLite.
- `PostgreSQL`_. Some people found it better than MySQL.
We advice you to use MySQL because it is more efficient. In this case,
you should create a new database (for example ``wallabag``), a new user
(for example ``wallabag``) and a password (here ``YourPassWord``). To do
this, you can use ``phpMyAdmin``, or launch the following commands:
::
mysql -p -u root
mysql> CREATE DATABASE wallabag;
mysql> GRANT ALL PRIVILEGES ON `wallabag`.* TO 'wallabag'@'localhost' IDENTIFIED BY 'VotreMotdePasse';
mysql> exit
*Note:* If youre using MySQL or Postgresql, you have to **fill all the
fields**, otherwise the installation will not work and an error message
will tell you whats wrong. You must create the database that you will
use for wallabag manually with a tool like PHPMyAdmin or the console.
Permissions
~~~~~~~~~~~
Your web server needs a writing access to the ``assets``, ``cache`` and
``db`` directories. Otherwise, a message will report that the
installation is impossible:
::
sudo chown -R www-data:www-data /var/www/html/wallabag
Installation of wallabag. At last.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Access to wallabag from your web browser:
``http://votreserveur.com/wallabag``. If your server is correctly
configured, you directly reach the setup screen.
Select the type of database (``sqlite``, ``mysql`` or ``postgresql``)
and fill the information about your database. In the case of the databse
MySQL created before, the standard configuration will be:
::
Database engine: MySQL
Server: localhost
Database: wallabag
Username: wallabag
Password: YourPassWord
Finally, Create your first user and his/her password (different from the
database user).
Wallabag is now installed.
Login
-----
From your web browser, you reach the login screen: fill your username
and your password to connect to your account.
Enjoy!
.. _SQLite: http://php.net/manual/fr/book.sqlite.php
.. _MySQL: http://php.net/manual/fr/book.mysql.php
.. _PostgreSQL: http://php.net/manual/fr/book.pgsql.php
.. _Framabag: https://framabag.org/
.. _Download the latest wallabag version: http://wllbg.org/latest
.. _PHP 5.3.3 or above: http://php.net/manual/fr/install.php
.. _PDO: http://php.net/manual/en/book.pdo.php
.. _XML for PHP: http://php.net/fr/xml
.. _PCRE: http://php.net/fr/pcre
.. _ZLib: http://php.net/en/zlib
.. _mbstring: http://php.net/en/mbstring
.. _iconv: http://php.net/en/iconv
.. _DOM/XML: http://php.net/manual/en/book.dom.php
.. _Data filtering: http://php.net/manual/fr/book.filter.php
.. _GD: http://php.net/manual/en/book.image.php
.. _Tidy for PHP: http://php.net/fr/tidy
.. _cURL: http://php.net/fr/curl
.. _Parse ini file: http://uk.php.net/manual/en/function.parse-ini-file.php
.. _allow\_url\_fopen: http://www.php.net/manual/fr/filesystem.configuration.php#ini.allow-url-fopen
.. _gettext: http://php.net/manual/fr/book.gettext.php
.. _enable *Basic Authentication*: https://technet.microsoft.com/en-us/library/cc772009%28v=ws.10%29.aspx

View file

@ -0,0 +1,47 @@
.. _`Multi users`:
Multi users
===========
Create a new account
--------------------
Administrator mode
------------------
If you want to use wallabag with several persons, you can create new
accounts from the configuration page.
At the bottom of this page there is a form where you should input a user
name and a password.
It is now possible to login to this account from the login page of
wallabag.
No information are shared among the accounts.
Open registration mode
----------------------
Starting from version 1.9, the administrator can let users register by
themselves. This is done by changing the following lines in the
configuration file:
::
// registration
@define ('ALLOW_REGISTER', FALSE);
@define ('SEND_CONFIRMATION_EMAIL', FALSE);
Then, a user will be able to enter his/her user name and password to
create his/her own account. Depending on the configuration, a
confimation email can be sent to users who gave an email address.
Remove an account
-----------------
It is possible to remove your own account from the configuration page.
You simply have to enter your password and to ask for the removal.
Of course, when there is only one account, it is impossible to remove
it.

View file

@ -0,0 +1,26 @@
Session issues
==============
If you end up disconnected even while checking the *Stay signed in
checkbox*, please run the following commands as root (or with sudo) :
::
mkdir /var/lib/wallabag-sessions
chown www-data:www-data /var/lib/wallabag-sessions
*NOTE : The www-data user and group may not exist, you may use
``chown http:http /var/lib/wallabag-sessions`` instead*
Then, using apache add:
``php_admin_value session.save_path /var/lib/wallabag-sessions`` to your
apache vhost, for instance ``wallabag-apache.conf`` Finally, restart
apache, for instance like this : ``/etc/init.d/apache2 restart``
If youre using nginx, add
``php_admin_value[session.save_path] = /var/lib/wallabag-sessions`` in
your nginx configuration file. Then, restart nginx :
``/etc/init.d/nginx restart``
*NOTE : If youre using systemd, you should do
``systemctl restart apache2`` (or nginx).*

View file

@ -0,0 +1,30 @@
Update wallabag
===============
Update an existing wallabag installation
----------------------------------------
In order to update your installation, download and unzip the archive
into your installation folder. For example on Ubuntu/Debian:
::
wget http://wllbg.org/latest
unzip latest
rsync -ur wallabag-version-number/* /var/www/html/wallabag/ # could be another location such as /srv/html, /usr/share/nginx/html
After that, just access wallabag in your browser and follow the
instructions to finish the update.
You can verify at the bottom of the configuration page that youre
running the last version.
**If it fails**, just delete the ``install`` folder and clear the cache:
::
cd /var/www/html/wallabag/
rm -r cache/* install/
Clearing the cache is also possible in the configuration page, clicking
on the link ``Delete Cache``.

View file

@ -0,0 +1,4 @@
Create new theme
================
TODO

View file

@ -0,0 +1,29 @@
Git repository
==============
If you wish to contribute to the project by suggesting new features or
by fixing some bugs, please follow the recommendations below regarding
the git repository available at https://github.com/wallabag/wallabag.
Current state
-------------
To manage the different versions of wallabag, we use Git.
There are multiple branches for the source code of wallabag web app:
- ``master`` branch : this is the stable branch, downloaded by those
who wish to install wallabag for their own use.
- ``dev`` branch : before being added on ``master`` branch, all bug
fixes and new features must go on that branch. This branch is not
recommended for production use.
- ``v2`` branch : this is the branch for a revamp of wallabag.
A whole chapter is to be focused on it.
Workflow
--------
All the rules for contributing to the git repository are in the
`CONTRIBUTING.md file of
wallabag <https://github.com/wallabag/wallabag/blob/master/CONTRIBUTING.md>`__.
Please read carefully this file before you make any change.

View file

@ -0,0 +1,52 @@
Write config files
==================
wallabag can use specific site config files to parse website articles.
These files are stored in the
```inc/3rdparty/site_config/standard`` <https://github.com/wallabag/wallabag/tree/master/inc/3rdparty/site_config/standard>`__
folder.
The format used for these files is
`XPath <http://www.w3.org/TR/xpath20/>`__. Look at some examples in the
folder.
Automatic config files generation
---------------------------------
Fivefilters has created a `very useful
tool <http://siteconfig.fivefilters.org/>`__ to create config files. You
just type in the adress of the article to work on with, and you select
the area containing the content you want.
.. figure:: https://lut.im/RNaO7gGe/l9vRnO1b
:alt: siteconfig
siteconfig
| You should confirm this area by trying with other articles.
| When you got the right area, just click on *Download Full-Text RSS
site config* to download your file.
Manual config file generation
-----------------------------
If Fivefilters tool doesn't work correctly, take a look at the source
(Ctrl + U on Firefox and Chromium). Search for your content and get the
``class`` or the ``id`` attribute of the area containing what you want.
Once you've got the id or class, you can write for example one or
another of these lines:
::
body: //div[@class='myclass']
body: //div[@id='myid']
Then, test you file. If you got the right content but you want to strip
unnecessary parts, do:
::
strip: //div[@class='hidden']
You can look at other options for siteconfig files
`here <http://help.fivefilters.org/customer/portal/articles/223153-site-patterns>`__.

View file

@ -0,0 +1,118 @@
.. _`Configure wallabag`:
Configure wallabag
==================
From the configuration menu, you can change some of wallabag's options.
Some parts won't be detailed here, as they have a dedicated chapter in
the documentation (:ref:`RSS feeds`, :ref:`Import / Export`, :ref:`ePub conversion` and :ref:`Multi users`).
Saving articles
---------------
You'll find help about the different ways to save articles to your
wallabag here.
Save article field
~~~~~~~~~~~~~~~~~~
Enter a link in the field and click “bag it!” to save.
Browser extensions
~~~~~~~~~~~~~~~~~~
Links to download extensions for your favourite browser, Firefox or
Chrome.
Mobile apps
~~~~~~~~~~~
Links to download mobile apps, Android, iOS or Windows Phone.
For Android, you have the choice to download either from Google's Play
Store of from the Free and Open Source market
`F-Droid <https://f-droid.org>`__
Bookmarklet
~~~~~~~~~~~
Lastly, you can use the bookmarklet. A bookmarklet is a simple link you
can drag to your browser's bookmarks. Once it's in your bookmarks,
simply clicking on it will save the webpage you're currently viewing to
your wallabag.
Feeds
-----
Plese refer to `RSS feeds <rss_feed.html>`__ for more details.
.. _`Howto change theme`:
Theme
-----
As they say, “all tastes and colors are found in nature”. That's why
wallabag allows you to change its appearance through the use of themes,
in order to please everyone.
Select the theme of your choice from the drop down list and confirm by
clicking on **Update**.
Language
--------
Select the language of your choice in the drop down list and confirm by
clicking on **Update**.
Import
------
Please refer to `Import/Export <import_export.html>`__ for more details.
Export
------
Please refer to `Import/Export <import_export.html>`__ for more details.
Clear the cache
---------------
The cache allows wallabag perform certain functions faster.
After updating wallabag, it is advised to clear the cache.
Click on “delete cache” to do so (no confirmation will be asked).
Password
--------
Fill in your new password in the two dedicated fields and confirm by
clicking on **Update**.
You will be disconnected and will have to enter your new password to
access your wallabag.
User
----
Add a user here by entering their name, password and (optionnaly) email
in the corresponding fields.
You may not be able to add a user if don't have the rights to do so.
Remind newly created users to change their password the first time they
connect to wallabag!
Delete
------
Delete your user account on wallabag here.
If there is only one account, you won't be able to delete the account.
Upgrade
-------
Wallabag will check its curent version and if there is a new version
available and display this information here.

View file

@ -0,0 +1,32 @@
.. _`ePub conversion`:
ePub conversion
===============
To enable you to read your articles on a e-reader, wallabag can convert
them to the ePub format, and hence create an eBook for your long winter
evenings.
A word of caution
-----------------
Be careful, the creation of ePub files can be very resource demanding
for the server on which wallabag is installed. It depends on the number
of articles and on their length. Do not create a really big eBook if
this is not necessary.
Where to convert the articles
-----------------------------
You can convert your articles at various places in wallabag:
- on the reading page of an article: the ePub link will convert this
article only
- from the list of articles (unread, favorite or archived articles,
articles with a tag): a link at the bottom of the page allows you to
convert all the article of this category
- from a search: the link is at the bottom of the page
- from the configuration page: you can convert all your articles,
whatever the category to which they belong
TODO talk about calibre

View file

@ -0,0 +1,49 @@
.. _`Framabag account creation`:
Framabag account creation
=========================
If you do not want to install and update wallabag, or if you do not have
the know-how to install it, it is possible to create an account for free
at `Framabag.org <https://www.framabag.org>`__.
Account creation
----------------
Click on the button **Créez votre compte / Create your account**.
You have to input some information: your username, your password and
your email address. Your address is used only to validate your account,
except if you check the box to subscribe the newsletter (3 to 4 messages
per year).
Once this form validated, you will receive an email with the
confirmation link. Click on it to create your account.
You will receive a last email with the address of your Framabag account,
which will look like ``https://www.framabag.org/u/Your-username``.
Information storage
-------------------
Framabag use one database per user. We do not and will not use your
stored data.
You have forgotten your password
--------------------------------
| If you have forgotten your password to get connected to Framabag, a
form is available `on the main page of the
service <https://www.framabag.org>`__.
| Fill it, and a confirmation will be sent to you and will allow you to
input a new password.
Account deletion
----------------
If you wish to delete your account, contact us by email:
hello@wallabag.org using the address your created your account with, and
state your username.
We will answer you after your account has been deleted: then, no
information about you will be stored by Framabag.

View file

@ -0,0 +1,107 @@
.. _`Import / Export`:
Import and export data
======================
Import
------
To import data in wallabag, go to the page **Configuration**.
Caution
~~~~~~~
Data import can be a **demanding process** for your server. Hence, it is
done in two steps:
- Insertion of the URL in the wallabag database
- in the second step, the retrieval, for each article, of its full
content.
These two steps cannot be done concurrently, because it let us the
possibility to import thousands of links, but today, wallabag does not
have sufficient technical capabilities to do this task automatically.
From Pocket
~~~~~~~~~~~
Export your data from Pocket
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
From your Pocket account, go to the options. TODO
Import your Pocket data
^^^^^^^^^^^^^^^^^^^^^^^
From the configuration page of wallabag, section **Import**, select the
file ``ril_export.html`` generated by Pocket, then click on **Import**.
Wallabag only insert these links in the database. Now, you have to get
the content of each article.
For this, click on ``Click to finish import``: wallabag will fetch the
content of 10 articles at a time.
TODO
TODO new ticket: why when a click is done, this does not load in a loop?
I believe this was doing this ping @mariroz
From Instapaper
~~~~~~~~~~~~~~~
Export your data from Instapaper
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
TODO
Import your Instapaper data
^^^^^^^^^^^^^^^^^^^^^^^^^^^
TODO
From Readability
~~~~~~~~~~~~~~~~
Export your data from Readability
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
TODO
Import your Readability data
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
TODO
From wallabag
~~~~~~~~~~~~~
Since you can export your data from wallabag (see below), it is of
course possible to re-import them.
In the import form, select your wallabag-exported file (format JSON).
Start the import, et voilà.
Unlike the above imports, this process is shorter because all the data
(title and content of the articles) are already included in the file.
Hence wallabag does not have to access each URL. However, the import
file is necessarily bigger.
From a HTML or JSON file
~~~~~~~~~~~~~~~~~~~~~~~~
TODO
Export
------
It is possible to export your data from the page **Configuration** of
wallabag. Several reasons to do this:
- re-install of wallabag
- leave the Framabag service to install your own wallabag
- a user with an account on a multi-user wallabag want to have his/her
own wallabag installation
- ...
This will lead you to download a file `at the JSON
format <http://en.wikipedia.org/wiki/JavaScript_Object_Notation>`__. As detailed above, you can import this file in wallabag.

View file

@ -0,0 +1,36 @@
.. _`Article is not displayed properly`:
My article is not displayed properly in wallabag
================================================
If you think wallabag do not copy well the content of an article (empty
or incomplete text), here are some suggestions.
Ask for help
------------
Via an email or a ticket, do not forget to give some information that
are important for us to better solve the problem:
- The URL of the article
- What wallabag displays
- What you were expecting
- The wallabag version of if you use Framabag
Open a ticket on github
~~~~~~~~~~~~~~~~~~~~~~~
To open a new ticket, you should `go to
github <https://github.com/wallabag/wallabag/issues/new>`__. An account
is required. Do not forget to send us the information listed above.
Send us an email
~~~~~~~~~~~~~~~~
Send us the link in a email to the address
`hello@wallabag.org <mailto:hello@wallabag.org?subject=Wrong%20display%20in%20wallabag>`__. Do not forget to send us the information listed above.
Solve this display problem
--------------------------
TODO

View file

@ -0,0 +1,109 @@
.. _`Organize articles`:
Organize articles
=================
To be able to find more easily your articles, several methods are
available.
Tags
----
Assign a tag
~~~~~~~~~~~~
When saving an article
^^^^^^^^^^^^^^^^^^^^^^
To tag an article when saving it, just click on the tag icon next to the
URL field before hitting the Save button. At the moment, it is possible
only to do this from the web interface, but it could come to some apps
or extensions.
From the article
^^^^^^^^^^^^^^^^
To tag an already-saved article, go to the reading page of the article.
There is a part ``tags`` followed with a pencil. Click on the pencil.
Input in the box the tags you want to assign. Add as many tags as you
want. They need to be separated by commas and not spaces.
Auto-completion is available here: when you type the first letters of an
existing tag, it is not necessary to type the whole word. Select it in
the drop-down list. Once all your tags are inputted, click on the button
**Tag**.
Then, you can go back to your article and read it.
From the search
^^^^^^^^^^^^^^^
A full chapter on search is available. Here, we will describe only how
to assign a tag from your search.
When your search displays results, there is a link
``Apply the tag ABCD to this search`` at the bottom of the page. Click
on it: a tad depending on your search (here ``ABCD``) will be assigned
to all the articles found.
Find all the articles with a given tag
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In the wallabag menu, click on **Tags**. Then, all the tags you have
created are displayed, sorted by the number of articles for each tag.
Click on one of these tags to find all the articles with this tag.
Preferred articles
------------------
When you wish to set aside an article, you can mark it as preferred.
Set an article as favorite
~~~~~~~~~~~~~~~~~~~~~~~~~~
From the reading page of an article, or from a list of articles (such as
the list of unread articles), you can set an article as favorite simply
by a click on the star which is displayed. Click again on the star will
remove the **favorite** status of this article.
Find all the favorite articles
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In the wallabag menu, click on **Favorites** to display the list of all
the articles that you have set as favorite.
Archived articles
-----------------
When you have read an article, you can archive it: hence it will not be
displayed in your list of unread articles.
Archiving an article does not remove it from wallabag.
Archive an article
~~~~~~~~~~~~~~~~~~
| From the reading page of an article, or from a list of articles (such
as the list of unread articles), you can archive an article simply by
clicking on the icon ✓.
| Click again on this icon will set back the **unread** status of the
article.
Find all the archived articles
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In the wallabag menu, click on **Archive** to find all the articles that
you have archived.
Delete an article
-----------------
Be cautious: the deletion of an article is **definitive**. It is deleted
from the wallabag database.
To delete an article, a trash icon is displayed on the page of an
article or of a list of articles (unread articles, favorites or
archived, for example).
We trust you: that is why there is no confirmation message during the
deletion.

View file

@ -0,0 +1,63 @@
Read an article
===============
Reading an article is not difficult in wallabag: you only have to click on the title of the article for it to be displayed.
Back to where you left the article
----------------------------------
If you stop reading an article halfway through, the next time wallabag will open it right where you left off.
This feature only works with web applications and not with smartphone applications.
Possible actions in an article
------------------------------
The following actions can be performed through the icons displayed at the top of the page. We assume here that you are using the Baggy theme (see the section on :ref:`Howto change theme`). Icons in other themes are very similar.
Here are the actions, in the order of appearance of the icons.
Read the original article
~~~~~~~~~~~~~~~~~~~~~~~~~
Open the article on its original location.
Mark the article as read
~~~~~~~~~~~~~~~~~~~~~~~~
Archive the article, which will be placed into the **Archive** category of the wallabag menu. Clicking again on this button will move the article back to the **unread** category.
Mark the article as favorite
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Mark the article as favorite, and it will be placed into the **Favorites** category of the wallabag menu. Clicking again on this button will remove the favorite status.
Delete the article
~~~~~~~~~~~~~~~~~~
Delete the article from wallabag permanently. It cannot be restored. Be careful: no confirmation message is displayed.
Share through twitter
~~~~~~~~~~~~~~~~~~~~~
Share the title and the original link of the article on twitter.
Share via email
~~~~~~~~~~~~~~~
Share the title and the original link of the article via e-mail.
Print the article
~~~~~~~~~~~~~~~~~
Open the print window of the browser.
Convert into ePub
~~~~~~~~~~~~~~~~~
Convert the article into ePub format: see the section on :ref:`ePub conversion`.
Notify us that the article appears wrong
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Notify the wallabag developers that an article is not displayed as expected (see the section on :ref:`Article is not displayed properly`).

41
docs/en/User/rss_feed.rst Normal file
View file

@ -0,0 +1,41 @@
.. _`RSS feeds`:
RSS feeds
=========
The RSS feeds allow you to:
- read your articles from your favorite RSS feed reader.
- to activate the reading features for smartphone softwares
| First, you must activate the RSS feature by generating a feed token.
| Go to **config** in wallabag and generate a token in the section
**Feeds**. You can generate a new token at any time.
Read articles
-------------
Once the token created, you have access to three RSS feeds:
- the one of the unread articles
- the one of the favorites articles
- the one of the archived articles
Add the feed you want to your RSS feed reader. Be careful: when you will
be reading an article from your feed reader, this will not set it as
read in wallabag.
Share your readings
~~~~~~~~~~~~~~~~~~~
If you wish to share your readings with somebody, send him for example
the RSS feed of your favorite articles. Hence, as soon as an article
will be set as favorite in wallabag, this person will be able to read it
too.
Activate the features for smartphones
-------------------------------------
You ave created an RSS feed token. It will also be useful to you to
configure your smartphone software. For more information about
smartphone sofwares, you can read :ref:`Save your first article`.

View file

@ -0,0 +1,226 @@
.. _`Save your first article`:
Save your first article
=======================
Once connected on wallabag, you have many ways to save an article.
From the web application
------------------------
Lets see first how to do from the web application. In the menu, you
have a link **save a link**. Clicking on it, a form shows up: you simply
have to type the web adress of the article you want to save.
Confirm to store the content of the article.
By default, only the text is saved. If you want to store a copy of the
images on your server, you have to enable the setting
*DOWNLOAD\_PICTURES*. Read the chapter on hidden options for more
information.
From the bookmarklet
--------------------
From `Wikipedias definition`_
A bookmarklet is a `bookmark`_ stored in a `web browser`_ that
contains `JavaScript`_\ commands to extend the browsers
functionality.
Bookmarklets are unobtrusive scripts stored as the URL of a bookmark
in a web browser or as a hyperlink on a web page.
When clicked, a bookmarklet performs some function, one of a wide
variety such as a search query or data extraction. Bookmarklets are
usually `JavaScript programs`_.
From the wallabags menu, click on **settings**. On the first part of
this page, we have listed all the ways to save an article. Youll find
the bookmarklet (its the ``Bag it!`` link) to drag and drop in the
bookmarks bar of your web browser. From now on, when you want to save
the article you are browsing, you just have to click on this bookmarklet
and the article will be automatically saved.
From your smartphone
--------------------
Above all else
~~~~~~~~~~~~~~
To use a smartphone application, you have to enable RSS feeds from the
settings panel of wallabag. Then some information will be displayed,
like your security token. Read the chapter on RSS feeds for more
information.
Android
~~~~~~~
Installation and configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can download the android application from the `Google Play Store`_
and from `F-droid`_. Its the exact same application on those two
stores.
Once installed, start the application, go to the **settings** part et
fill in the **URL (complete address of your wallabag installation or
your Framabag account)** and **User ID (in most cases, youll have to
put 1)** fields. If you have created multiple accounts from wallabag,
you will have to to fill the user account you want to connect to your
application and your security **Token** (enter properly all the tokens
letters as seen in the settings part of wallabag).
Saving of an article
^^^^^^^^^^^^^^^^^^^^
Now that everything is correctly set up, as soon as you browse on your
smartphones web browser, you can share an article in wallabag at any
time from the **Share** menu: youll find a **Bag it!** entry which will
add your article in wallabag.
Reading
^^^^^^^
When you open the application, click on Synchronize: your recently saved
articles will be downloaded on your smartphone.
You dont need an internet connection anymore: click on **List
articles** to start your reading.
At the end of each article, a **Mark as read** button allows you to
archive the article.
To date, the synchronisation occurs in one direction (from wallabag to
the application), thus preventing mark as read an article on wallabag
from your smartphone.
iOS
~~~
Installation and configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can download the iOS application from the `AppStore`_.
Once installed, configure the app by filling following fields inside the
settings: the **URL (complete address of your wallabag installation or
your Framabag account)** and **User ID (in most cases, youll have to
put 1)** field. If you have created multiple accounts from wallabag, you
will have to to fill the user account you want to connect to your
application and your security **Token** (enter properly all the tokens
letters as seen in the settings part of wallabag).
Usage
^^^^^
If the app is configured correctly, the app will automatically download
the articles from your wallabag (use **pull-to-refresh** to trigger this
update manually). Once an article is downloaded, itll be available
offline from your app.
Unfortunately you can only locally mark an article as read (it will not
synchronise to your online wallabag).
Saving articles
~~~~~~~~~~~~~~~
If youre browsing a website and want to add the current article to your
wallabag, simply tap the **Share**-button and select **Bag it!** (if you
dont find the wallabag icon, have a look in the **more**-menu). If
everything is set up correctly, your article will be saved (you may have
to login from time to time).
Windows Phone
~~~~~~~~~~~~~
Installation and configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can download the Windows Phone application from the `Windows Store`_
or directly from your smartphones Store.
Once installed, the application will show you a notification on the
first launch, asking the configuration of your wallabag server. Go to
the **Settings** part of the application by pressing the three dots menu
at the bottom of the screen, then fill in the **URL (complete address of
your wallabag installation or your Framabag account)** and **User ID (in
most cases, youll have to put 1)** fields.
If you have created multiple accounts from wallabag, you will have to to
fill the user account you want to connect to your application and your
security **Token** (enter properly all the tokens letters as seen in
the setting part of wallabag).
From your web browser
---------------------
Firefox Classic Add-on
~~~~~~~~~~~~~~~~~~~~~~
Download the Firefox add-on at `addons.mozilla.org`_ and install it like
any other Firefox add-on.
In the add-ons settings, fill the complete URL of your installation of
wallabag or your Framabag account.
Personalize the Firefox toolbar to add wallabag (**W** icon). When you
find an article you want to save, click on this icon: a new window will
open to add the article and will close itself automatically.
Firefox Social API Service
~~~~~~~~~~~~~~~~~~~~~~~~~~
*Available from wallabag v1.9.1 only*
You will need an https connection to use this. Its a Firefox
`requirement`_, sorry.
With Firefox 29+ versions, your browser comes with an integrated
interface to share things to multiple social services directly from your
browser. In the Firefox interface, it is shown a paper plane-like icon
that you will use to share a page, which means here, save an article.
You can add the service by going into the Config page of wallabag, then
click on Mozilla Services Social API Extension. You must also accept to
use Firefox Services.
Chrome
~~~~~~
Download the Chrome add-on `on the dedicated website`_ and install it
like any other Chrome add-on.
In the add-ons settings, fill the complete URL of your installation of
wallabag or your Framabag account.
During the addons installation, a new icon appear in Chrome toolbar (a
**W** icon). When you find an article you want to save, click on this
icon: a popup will appear to confirm that your article has been saved.
Opera
~~~~~
The recent versions of Opera (15+) allow to install add-ons compatible
with Chrome.
First, install the add-on named `Download Chrome Extensions`_ which will
allow you to install add-ons from the Chrome Web Store. Then, go `to to
Google site`_ and get the Chrome add-on by clicking on *Add to Opera*. A
message will invite you to confirm this action because this add-on is
not coming from a certified source. The behavior will be the same as for
Chrome (see above).
.. _Wikipedias definition: http://fr.wikipedia.org/wiki/Bookmarklet
.. _bookmark: http://en.wikipedia.org/wiki/Internet_bookmark
.. _web browser: http://en.wikipedia.org/wiki/Web_browser
.. _JavaScript: http://en.wikipedia.org/wiki/JavaScript
.. _JavaScript programs: http://en.wikipedia.org/wiki/Computer_program
.. _Google Play Store: https://play.google.com/store/apps/details?id=fr.gaulupeau.apps.InThePoche
.. _F-droid: https://f-droid.org/app/fr.gaulupeau.apps.InThePoche
.. _AppStore: https://itunes.apple.com/app/id828331015
.. _Windows Store: https://www.microsoft.com/en-us/store/apps/wallabag/9nblggh11646
.. _addons.mozilla.org: https://addons.mozilla.org/firefox/addon/wallabag/
.. _requirement: https://developer.mozilla.org/en-US/docs/Mozilla/Projects/Social_API/Manifest#Manifest_Contents
.. _on the dedicated website: https://chrome.google.com/webstore/detail/wallabag/bepdcjnnkglfjehplaogpoonpffbdcdj
.. _Download Chrome Extensions: https://addons.opera.com/en/extensions/details/download-chrome-extension-9/
.. _to to Google site: https://chrome.google.com/webstore/detail/wallabag/bepdcjnnkglfjehplaogpoonpffbdcdj

21
docs/en/User/search.rst Normal file
View file

@ -0,0 +1,21 @@
Search content in wallabag
==========================
To enable you to find an article quickly, we set up a full search
engine.
Click on **Search** in the wallabag menu. Then, enter your search terms.
Wallabag will go through all your articles, and lists the ones
containing the search terms in their title, their content or their URL.
Convert this search into ePub format
------------------------------------
You can convert the listed articles to the ePub format, so that you can
read them in your e-reader, for example. Look at :ref:`ePub conversion` for more about this.
Assign a tag to your search results
-----------------------------------
You can create a tag based on your search criteria. Loot at :ref:`Organize articles` for more about this.

87
docs/en/conf.py Normal file
View file

@ -0,0 +1,87 @@
# -*- coding: utf-8 -*-
#
# wallabag documentation build configuration file, created by
# sphinx-quickstart on Fri Oct 16 06:47:23 2015.
import sys
import os
extensions = []
templates_path = ['_templates']
source_suffix = '.rst'
master_doc = 'index'
project = u'wallabag'
copyright = u'2013-2015, Nicolas Lœuillet - MIT Licence'
version = '2.0.0'
release = version
exclude_patterns = ['_build']
pygments_style = 'sphinx'
html_theme = 'default'
html_static_path = ['_static']
htmlhelp_basename = 'wallabagdoc'
latex_elements = {
}
latex_documents = [
('index', 'wallabag.tex', u'wallabag Documentation',
u'Nicolas Lœuillet', 'manual'),
]
man_pages = [
('index', 'wallabag', u'wallabag Documentation',
[u'Nicolas Lœuillet'], 1)
]
texinfo_documents = [
('index', 'wallabag', u'wallabag Documentation',
u'Nicolas Lœuillet', 'wallabag', 'One line description of project.',
'Miscellaneous'),
]
##### Guzzle sphinx theme
import guzzle_sphinx_theme
html_translator_class = 'guzzle_sphinx_theme.HTMLTranslator'
html_theme_path = guzzle_sphinx_theme.html_theme_path()
html_theme = 'guzzle_sphinx_theme'
# Custom sidebar templates, maps document names to template names.
html_sidebars = {
'**': ['logo-text.html', 'globaltoc.html', 'searchbox.html']
}
# Register the theme as an extension to generate a sitemap.xml
extensions.append("guzzle_sphinx_theme")
# Guzzle theme options (see theme.conf for more information)
html_theme_options = {
# Set the path to a special layout to include for the homepage
# "index_template": "homepage.html",
# Allow a separate homepage from the master_doc
# homepage = index
# Set the name of the project to appear in the nav menu
# "project_nav_name": "Guzzle",
# Set your Disqus short name to enable comments
# "disqus_comments_shortname": "my_disqus_comments_short_name",
# Set you GA account ID to enable tracking
# "google_analytics_account": "my_ga_account",
# Path to a touch icon
# "touch_icon": "",
# Specify a base_url used to generate sitemap.xml links. If not
# specified, then no sitemap will be built.
#"base_url": "http://guzzlephp.org"
# Allow the "Table of Contents" page to be defined separately from "master_doc"
# tocpage = Contents
# Allow the project link to be overriden to a custom URL.
# projectlink = http://myproject.url
}

57
docs/en/index.rst Normal file
View file

@ -0,0 +1,57 @@
wallabag documentation
======================
.. image:: ../img/wallabag.png
:alt: wallabag logo
:align: center
**wallabag** is a read-it-later application: it saves a web page by
keeping content only. Elements like navigation or ads are deleted.
The main documentation for the site is organized into a couple sections:
* :ref:`user-docs`
* :ref:`admin-docs`
* :ref:`dev-docs`
.. _user-docs:
.. toctree::
:maxdepth: 2
:caption: User Documentation
user/create_account
user/login
user/configuration
user/first_article
user/organize
user/filters
User/read_an_article
User/search
User/epub_conversion
User/issue_with_article
User/rss_feed
User/import_export
.. _admin-docs:
.. toctree::
:maxdepth: 2
:caption: Admin Documentation
Administrator/install
Administrator/update
Administrator/hidden_options
Administrator/multiusers
Administrator/sessions
.. _dev-docs:
.. toctree::
:maxdepth: 2
:caption: Developer Documentation
Developer/write_config_files
Developer/create_new_theme
Developer/git_repo

2
docs/en/requirements.txt Normal file
View file

@ -0,0 +1,2 @@
Sphinx>=1.3.0,<1.4.0
guzzle_sphinx_theme>=0.7.0,<0.8.0

View file

@ -0,0 +1,61 @@
Configuration
=============
Now you're logged in, it's time to configure your account as you want.
Click on ``Config`` menu. You have four tabs: ``Settings``, ``RSS``, ``User information`` and ``Password``.
Settings
--------
Theme
~~~~~
wallabag is customizable. You can choose your prefered theme here. You can also create a new one, a chapter is dedicated for this. The default theme is ``Material``, it's the theme used in the documentation screenshots.
Items per page
~~~~~~~~~~~~~~
You can change the number of articles displayed on each page.
Language
~~~~~~~~
You can change the language of wallabag interface.
RSS
---
wallabag provides RSS feeds for each article status: unread, starred and archive.
Firstly, you need to create a personal token: click on ``Create your token``.
It's possible to change your token by clicking on ``Reset your token``.
Now you have three links, one for each status: add them into your favourite RSS reader.
You can also define how many articles you want in each RSS feed (default value: 50).
User information
----------------
You can change your name, your email address and enable ``Two factor authentication``.
Two factor authentication
~~~~~~~~~~~~~~~~~~~~~~~~~
Two-factor authentication (also known as 2FA) is a technology patented in 1984 that provides identification of users by means of the combination of two different components.
https://en.wikipedia.org/wiki/Two-factor_authentication
If you enable 2FA, each time you want to login to wallabag, you'll receive a code by email. You have to put this code on the following form.
.. image:: ../../img/user/2FA_form.png
:alt: Two factor authentication
:align: center
If you don't want to receive a code each time you want to login, you can check the ``I'm on a trusted computer`` checkbox: wallabag will remember you for 15 days.
Password
--------
You can change your password here.

View file

@ -0,0 +1,43 @@
Create an account
=================
On the login page, click on ``Register`` button.
.. image:: ../../img/user/registration_form.png
:alt: Registration form
:align: center
You have to fill the form. Please sure to type a valid email address, we'll send you an activation email.
.. image:: ../../img/user/sent_email.png
:alt: Email was sent to activate account
:align: center
Check your inbox, you now have a new mail with a link like this ``http://wallabag/register/confirm/Ba19wokGovN-DdBQNfg4YgRkUQWRP4-k2g0Bk-hBTX4``. Click on it to activate your account.
Your account is now activated.
.. image:: ../../img/user/activated_account.png
:alt: Welcome on board!
:align: center
Frequently asked questions
--------------------------
I can't valid the registration form
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Make sure that all fields are well filled:
* valid email address
* same passwords in two fields
I don't receive my activation email
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Are you sure your email address was correct? Did you check your spams folder?
When I click on the activation link, I've got this message: ``The user with confirmation token "DtrOPfbQeVkWf6N" does not exist``.
~~~~~~~~~~~~~~~
You already enabled your account or the URL of the activation email is wrong.

View file

@ -0,0 +1,79 @@
Save your first article
=======================
The main purpose of wallabag is to save web articles. You have many ways to do it.
By using a bookmarklet
----------------------
On the ``Howto`` page, you have a ``Bookmarklet`` tab. Drag and drop the ``bag it!`` link to your bookmarks bar of your browser.
Now, each time you're reading an article on the web and you want to save it, click on the ``bag it!`` link in your bookmarks bar. The article is saved.
By using the classic form
-------------------------
In the top bar of your screen, you have 3 icons. With the first one, a plus sign, you can easily save a new article.
.. image:: ../../img/user/topbar.png
:alt: Top bar
:align: center
Click on it to display a new field, paste the article URL inside and press your ``Return`` key. The article is saved.
By using a browser add-on
-------------------------
Firefox
~~~~~~~
Firefox Classic Add-on
^^^^^^^^^^^^^^^^^^^^^^
Download the Firefox add-on at `addons.mozilla.org`_ and install it like
any other Firefox add-on.
In the add-ons settings, fill the complete URL of your installation of
wallabag or your Framabag account.
Personalize the Firefox toolbar to add wallabag (**W** icon). When you
find an article you want to save, click on this icon: a new window will
open to add the article and will close itself automatically.
Firefox Social API Service
^^^^^^^^^^^^^^^^^^^^^^^^^^
*Available from wallabag v1.9.1 only*
You will need an https connection to use this. Its a Firefox
`requirement`_, sorry.
With Firefox 29+ versions, your browser comes with an integrated
interface to share things to multiple social services directly from your
browser. In the Firefox interface, it is shown a paper plane-like icon
that you will use to share a page, which means here, save an article.
You can add the service by going into the Config page of wallabag, then
click on Mozilla Services Social API Extension. You must also accept to
use Firefox Services.
Chrome
~~~~~~
By using your smarphone application
-----------------------------------
Android
~~~~~~~
Firefox OS
~~~~~~~~~~
Windows Phone
~~~~~~~~~~~~~
iOS
~~~
.. _addons.mozilla.org: https://addons.mozilla.org/firefox/addon/wallabag/
.. _requirement: https://developer.mozilla.org/en-US/docs/Mozilla/Projects/Social_API/Manifest#Manifest_Contents

20
docs/en/user/login.rst Normal file
View file

@ -0,0 +1,20 @@
Login
=====
Your account is now enabled, congratulations!
To login to wallabag, fill the form on login page.
If you are on your personal computer and you want to stay connected, you can check the ``Keep me logged in`` checkbox: wallabag will remember you for one year.
.. image:: ../../img/user/login_form.png
:alt: Login form
:align: center
Frequently asked questions
--------------------------
I forgot my password
~~~~~~~~~~~~~~~~~~~~
You can reset your password by clicking on ``Forgot your password?`` link, on the login page. Then, fill the form with your email address