From 1acd3ab09be1b65bfd6122ee351490c3b5527bb8 Mon Sep 17 00:00:00 2001 From: Alexandre Alapetite Date: Sat, 8 Jan 2022 21:58:55 +0100 Subject: Use typographic quotes (#4133) * Use typographic quotes * A few fixes * Fix * Fix not saved * Implement feedback * Detail * Revert spoken English fixes Left for a future dedicated discussion * More reverts * Final reverts * Final minor --- docs/en/admins/01_Index.md | 2 +- docs/en/admins/03_Installation.md | 12 ++++----- docs/en/admins/04_Frequently_Asked_Questions.md | 2 +- docs/en/admins/04_Updating.md | 4 +-- docs/en/admins/05_Backup.md | 12 ++++----- docs/en/admins/05_Configuring_email_validation.md | 30 +++++++++++------------ docs/en/admins/06_LinuxInstall.md | 14 +++++------ docs/en/admins/07_LinuxUpdate.md | 12 ++++----- docs/en/admins/08_FeedUpdates.md | 10 ++++---- docs/en/admins/13_Default_user.md | 2 +- docs/en/contributing.md | 16 ++++++------ docs/en/developers/01_Index.md | 2 +- docs/en/developers/02_First_steps.md | 22 ++++++++--------- docs/en/developers/02_Github.md | 2 +- docs/en/developers/03_Backend/05_Extensions.md | 18 +++++++------- docs/en/developers/03_Running_tests.md | 2 +- docs/en/developers/04_Frontend/02_Design.md | 4 +-- docs/en/developers/04_Pull_requests.md | 26 ++++++++++---------- docs/en/developers/05_Release_new_version.md | 28 ++++++++++----------- docs/en/developers/06_Fever_API.md | 4 +-- docs/en/developers/06_GoogleReader_API.md | 2 +- docs/en/developers/06_Reporting_Bugs.md | 26 ++++++++++---------- docs/en/internationalization.md | 24 +++++++++--------- docs/en/users/02_First_steps.md | 4 +-- docs/en/users/03_Main_view.md | 20 +++++++-------- docs/en/users/04_Subscriptions.md | 14 +++++------ docs/en/users/05_Configuration.md | 26 ++++++++++---------- docs/en/users/07_Frequently_Asked_Questions.md | 12 ++++----- 28 files changed, 176 insertions(+), 176 deletions(-) (limited to 'docs/en') diff --git a/docs/en/admins/01_Index.md b/docs/en/admins/01_Index.md index 9842cba8f..ebf09dc07 100644 --- a/docs/en/admins/01_Index.md +++ b/docs/en/admins/01_Index.md @@ -2,7 +2,7 @@ Learn how to install, update, and backup FreshRSS, as well as how to use the command line tools. -1. [Prerequisites](02_Prerequisites.md): What you'll need to run FreshRSS +1. [Prerequisites](02_Prerequisites.md): What you’ll need to run FreshRSS 2. [General installation instructions](03_Installation.md) for FreshRSS 3. [Update your installation](04_Updating.md) to the latest stable or development version diff --git a/docs/en/admins/03_Installation.md b/docs/en/admins/03_Installation.md index e96200911..a77054a27 100644 --- a/docs/en/admins/03_Installation.md +++ b/docs/en/admins/03_Installation.md @@ -1,12 +1,12 @@ # General Installation Instructions -These instructions are intended as general guidelines for installing FreshRSS. You may wish to consult the [Step-by-step Tutorial for installing FreshRSS on Debian 9/Ubuntu 16.04](06_LinuxInstall.md) if you don't currently have a web server and don't have experience setting one up. +These instructions are intended as general guidelines for installing FreshRSS. You may wish to consult the [Step-by-step Tutorial for installing FreshRSS on Debian 9/Ubuntu 16.04](06_LinuxInstall.md) if you don’t currently have a web server and don’t have experience setting one up. -Before you begin, make sure that you've read the [prerequisites](02_Prerequisites.md) for running FreshRSS. As shorthand, `.` refers to the directory to which your FreshRSS installation lives. +Before you begin, make sure that you’ve read the [prerequisites](02_Prerequisites.md) for running FreshRSS. As shorthand, `.` refers to the directory to which your FreshRSS installation lives. -1. If the computer you're running on is not currently running a web server, you'll first need to install and configure a web server, a version of PHP, and an appropriate database, as listed in the prerequisites. Specially, if you are using NGINX, please keep in mind that FreshRSS needs some specified variables to run properly. So make sure you've checked our configuration file. [Example Apache and Nginx configuration files can be found here](10_ServerConfig.md). +1. If the computer you’re running on is not currently running a web server, you’ll first need to install and configure a web server, a version of PHP, and an appropriate database, as listed in the prerequisites. Specially, if you are using NGINX, please keep in mind that FreshRSS needs some specified variables to run properly. So make sure you’ve checked our configuration file. [Example Apache and Nginx configuration files can be found here](10_ServerConfig.md). -2. Download your chosen version of FreshRSS, or fetch it via git. It's advisable that you put FreshRSS in `/usr/share/`, and symlink the `./p/` folder to the root of your web server.[^1] +2. Download your chosen version of FreshRSS, or fetch it via git. It’s advisable that you put FreshRSS in `/usr/share/`, and symlink the `./p/` folder to the root of your web server.[^1] 3. Give ownership of the FreshRSS folder to your web server user (often `www-data`). Give group read permissions to all files in `.`[^2], and group write permissions to `./data/`. @@ -14,7 +14,7 @@ Before you begin, make sure that you've read the [prerequisites](02_Prerequisite 5. Create a database for FreshRSS to use. Note the username and password for this database, as it will be needed during installation! -6. Using your supported web browser of choice, navigate to the address you've installed your server to complete the installation from the GUI.[^3] +6. Using your supported web browser of choice, navigate to the address you’ve installed your server to complete the installation from the GUI.[^3] 7. You can then customize [the configuration of your instance](https://github.com/FreshRSS/FreshRSS/blob/edge/config.default.php#L3-L4), [the default configuration for new users](https://github.com/FreshRSS/FreshRSS/blob/edge/config-user.default.php#L3-L5) or [the default set of feeds for new users](https://github.com/FreshRSS/FreshRSS/blob/edge/opml.default.xml#L2-L5). @@ -24,4 +24,4 @@ Before you begin, make sure that you've read the [prerequisites](02_Prerequisite [^2]: If you wish to allow updates from the web interface, also give group write permissions to this folder. -[^3]: Assuming your server is `http://example.net`, this address could be `http://example.net/p/` if you didn't follow our previous advice about not exposing the `./p/` folder. +[^3]: Assuming your server is `http://example.net`, this address could be `http://example.net/p/` if you didn’t follow our previous advice about not exposing the `./p/` folder. diff --git a/docs/en/admins/04_Frequently_Asked_Questions.md b/docs/en/admins/04_Frequently_Asked_Questions.md index cbabc3867..2e18ba802 100644 --- a/docs/en/admins/04_Frequently_Asked_Questions.md +++ b/docs/en/admins/04_Frequently_Asked_Questions.md @@ -15,7 +15,7 @@ You only have to do is to run the following command: Alternatively, you can edit configuration files manually. To do so, you need to change the *default_user* value in the file *./data/config.php*. -As the file is a PHP file, you have to make sure that it's still valid after the update by running the following command: +As the file is a PHP file, you have to make sure that it’s still valid after the update by running the following command: ```sh php -l ./data/config.php ``` diff --git a/docs/en/admins/04_Updating.md b/docs/en/admins/04_Updating.md index 2004d5318..27874d25c 100644 --- a/docs/en/admins/04_Updating.md +++ b/docs/en/admins/04_Updating.md @@ -4,7 +4,7 @@ The following is general procedure; [specific commands for Linux may be found he ## Backing Up -Before you update to a new version of FreshRSS, it's always a good idea to backup your current installation. Simply make an archive of your FreshRSS directory, which can be restored if needed by following the "Updating from a Zip Archive" section at the bottom of this document. +Before you update to a new version of FreshRSS, it’s always a good idea to backup your current installation. Simply make an archive of your FreshRSS directory, which can be restored if needed by following the "Updating from a Zip Archive" section at the bottom of this document. ## Updating From the Web @@ -18,7 +18,7 @@ If you installed FreshRSS using git, you can update, change branches, or switch Generally, the update procedure via git works as follows: -1. Making sure you're in your FreshRSS install directory, and fetch updates. +1. Making sure you’re in your FreshRSS install directory, and fetch updates. 2. Checkout the branch you wish to use. 3. Perform a hard reset to discard local changes. 4. Delete manual additions. Be sure to move your backup out of the directory before doing this step! diff --git a/docs/en/admins/05_Backup.md b/docs/en/admins/05_Backup.md index cf8516f29..ccc7810aa 100644 --- a/docs/en/admins/05_Backup.md +++ b/docs/en/admins/05_Backup.md @@ -1,6 +1,6 @@ # Backup -This tutorial demonstrates commands for backing up FreshRSS. It assumes that your main FreshRSS directory is `/usr/share/FreshRSS`; If you've installed it somewhere else, substitute your path as necessary. +This tutorial demonstrates commands for backing up FreshRSS. It assumes that your main FreshRSS directory is `/usr/share/FreshRSS`; If you’ve installed it somewhere else, substitute your path as necessary. ## Installation Backup @@ -8,19 +8,19 @@ Do this before an upgrade. ### Creating a Backup -First, Enter the directory you wish to save your backup to. Here, for example, we'll save the backup to the user home directory +First, Enter the directory you wish to save your backup to. Here, for example, we’ll save the backup to the user home directory ```sh cd ~ ``` -Next, we'll create a gzipped tar archive of the FreshRSS directory. The following command will archive the entire contents of your FreshRSS installation in it's current state. +Next, we’ll create a gzipped tar archive of the FreshRSS directory. The following command will archive the entire contents of your FreshRSS installation in it’s current state. ```sh tar -czf FreshRSS-backup.tgz -C /usr/share/FreshRSS/ . ``` -And you're done! +And you’re done! ### Restoring from a Backup @@ -56,14 +56,14 @@ You can export your feed list in OPML format either from the web interface, or f ### Saving Articles -**If you are using MySQL** +**If you are using MySQL** You can use [phpMyAdmin](https://www.phpmyadmin.net/) or MySQL tools, where `` is your database username, `` is the hostname of your web server containing your FreshRSS database, and `` is the database used by FreshRSS: ```sh mysqldump --skip-comments --disable-keys --user= --password --host --result-file=freshrss.dump.sql --databases ``` -**From any database** +**From any database** You can use the [Command-Line Interface](https://github.com/FreshRSS/FreshRSS/blob/edge/cli/README.md) to export your database to a SQLite database file: ```sh diff --git a/docs/en/admins/05_Configuring_email_validation.md b/docs/en/admins/05_Configuring_email_validation.md index 66b26bd3b..500a2b5aa 100644 --- a/docs/en/admins/05_Configuring_email_validation.md +++ b/docs/en/admins/05_Configuring_email_validation.md @@ -1,14 +1,14 @@ # Configuring the email address validation FreshRSS can verify that users give a valid email address. It is not configured -by default so you'll have to follow these few steps to verify email addresses. +by default so you’ll have to follow these few steps to verify email addresses. It is intended to administrators who host users and want to be sure to be able to contact them. ## Force email validation -In your `data/config.php` file, you'll find a `force_email_validation` item: +In your `data/config.php` file, you’ll find a `force_email_validation` item: set it to `true`. An email field now appears on the registration page and emails are sent when users change their email. @@ -19,45 +19,45 @@ You can also enable this feature directly in FreshRSS: `Administration` > By default, FreshRSS will attempt to send emails with the [`mail`](https://www.php.net/manual/en/function.mail.php) function of PHP. It is the simpler solution but it might not work as expected. -For example, we don't support (yet?) sending emails from inside our official +For example, we don’t support (yet?) sending emails from inside our official Docker images. We recommend to use a proper SMTP server. -To configure a SMTP server, you'll have to modify the `data/config.php` file. +To configure a SMTP server, you’ll have to modify the `data/config.php` file. First, change the `mailer` item to `smtp` (instead of the default `mail`). Then, you should change the `smtp` options like you would do with a regular email client. You can find the full list of options in the [`config.default.php` file](https://github.com/FreshRSS/FreshRSS/blob/edge/config.default.php). -If you're not sure to what each item is corresponding, you may find useful [the +If you’re not sure to what each item is corresponding, you may find useful [the PHPMailer documentation](http://phpmailer.github.io/PHPMailer/classes/PHPMailer.PHPMailer.PHPMailer.html#properties) (which is used by FreshRSS under the hood). ## Check your SMTP server is correctly configured -To do so, once you've enabled the `force_email_validation` option, you only +To do so, once you’ve enabled the `force_email_validation` option, you only need to change your email address on the profile page and check that an email arrives on the new address. If it fails, you can change the environment (in `data/config.php` file, change -`production` to `development`). PHPMailer will become more verbose and you'll -be able to see what happens in the PHP logs. If something's wrong here, you'll +`production` to `development`). PHPMailer will become more verbose and you’ll +be able to see what happens in the PHP logs. If something’s wrong here, you’ll probably better served by asking to your favorite search engine than asking us. -If you think that something's wrong in FreshRSS code, don't hesitate to open a +If you think that something’s wrong in FreshRSS code, don’t hesitate to open a ticket though. -Also, make sure the email didn't arrive in your spam. +Also, make sure the email didn’t arrive in your spam. -Once you're done, don't forget to reconfigure your environment to `production`. +Once you’re done, don’t forget to reconfigure your environment to `production`. ## Access the validation URL during development -You might find painful to configure a SMTP server when you're developping and +You might find painful to configure a SMTP server when you’re developping and `mail` function will not work on your local machine. For the moment, there is -no easy way to access the validation URL unless forging it. You'll need to +no easy way to access the validation URL unless forging it. You’ll need to information: - the username of the user to validate (you should know it) -- its validation token, that you'll find in its configuration file: +- its validation token, that you’ll find in its configuration file: ```console $ # For instance, for a user called `alice` @@ -67,4 +67,4 @@ $ grep email_validation_token data/users/alice/config.php | cut -d \' -f 4 - Then, the validation URL should be `http://localhost:8080/i/?c=user&a=validateEmail&username=alice&token=3d75042a4471994a0346e18ae87602f19220a795` -Don't forget to adapt this URL with the correct port, username and token. +Don’t forget to adapt this URL with the correct port, username and token. diff --git a/docs/en/admins/06_LinuxInstall.md b/docs/en/admins/06_LinuxInstall.md index ab42fb992..e92fc3247 100644 --- a/docs/en/admins/06_LinuxInstall.md +++ b/docs/en/admins/06_LinuxInstall.md @@ -1,6 +1,6 @@ # Installation on Debian 9/Ubuntu 16.04 -This tutorial will give you step-by-step commands to install the latest stable release of FreshRSS with Apache and MySQL using git. It's always recommended that you [backup your installation](05_Backup.md) before updating +This tutorial will give you step-by-step commands to install the latest stable release of FreshRSS with Apache and MySQL using git. It’s always recommended that you [backup your installation](05_Backup.md) before updating Please note: Commands need to be run as an administrator; either perform the following from a sudo shell (`sudo -s`) or use an administrator account. @@ -13,7 +13,7 @@ apt install apache2 a2enmod headers expires rewrite ssl ``` -Then, you have to configure Apache. You can create a file in `/etc/apache2/sites-available`, based on [our example configuration file](10_ServerConfig.md). Once you're done, create a symbolic link from this file to the `sites-enabled` folder: +Then, you have to configure Apache. You can create a file in `/etc/apache2/sites-available`, based on [our example configuration file](10_ServerConfig.md). Once you’re done, create a symbolic link from this file to the `sites-enabled` folder: ```sh ln -s /etc/apache2/sites-available/freshrss.conf /etc/apache2/sites-enabled/freshrss.conf @@ -31,7 +31,7 @@ Install the PHP module for Apache apt install libapache2-mod-php ``` -Next, we'll need to install and configure MySQL. Install MySQL components like so: +Next, we’ll need to install and configure MySQL. Install MySQL components like so: ```sh sudo apt install mysql-server mysql-client php-mysql @@ -43,8 +43,8 @@ MySQL must now be started: service mysql-server start ``` -We'll need to configure MySQL. -**Note:** As you've just installed mysql, there will be no root password; simply hit enter on the first step +We’ll need to configure MySQL. +**Note:** As you’ve just installed mysql, there will be no root password; simply hit enter on the first step ```sh mysql_secure_installation @@ -64,7 +64,7 @@ service apache2 restart ## Part 2: Installing FreshRSS -Begin by installing git, if you don't already have it installed. +Begin by installing git, if you don’t already have it installed. ```sh apt install git @@ -85,7 +85,7 @@ chown -R :www-data . sudo chmod -R g+r . ``` -We'll also need to allow the data folder to be written to, like so: +We’ll also need to allow the data folder to be written to, like so: ```sh chmod -R g+w ./data/ diff --git a/docs/en/admins/07_LinuxUpdate.md b/docs/en/admins/07_LinuxUpdate.md index 6323c2a1a..bc8a00aeb 100644 --- a/docs/en/admins/07_LinuxUpdate.md +++ b/docs/en/admins/07_LinuxUpdate.md @@ -1,8 +1,8 @@ # Updating on Linux -This tutorial demonstrates commands for updating FreshRSS. It assumes that your main FreshRSS directory is `/usr/share/FreshRSS`; If you've installed it somewhere else, substitute your path as necessary. +This tutorial demonstrates commands for updating FreshRSS. It assumes that your main FreshRSS directory is `/usr/share/FreshRSS`; If you’ve installed it somewhere else, substitute your path as necessary. -**Note that FreshRSS contains a built-in update system.** It's easier to use if you don't understand the commands that follow. It's available through the web interface of your FreshRSS installation, Administration → Update. +**Note that FreshRSS contains a built-in update system.** It’s easier to use if you don’t understand the commands that follow. It’s available through the web interface of your FreshRSS installation, Administration → Update. ## Pausing automatic feed updates @@ -24,7 +24,7 @@ You may wish to run the cron task or systemd unit (`freshrss.service`) immediate **You must have used git to install FreshRSS to use this update method.** -If your local user doesn't have write access to the FreshRSS folder, use a sudo shell (`sudo -s`), prefix the following commands with `sudo`, or switch to an account that does have write access to the folder. +If your local user doesn’t have write access to the FreshRSS folder, use a sudo shell (`sudo -s`), prefix the following commands with `sudo`, or switch to an account that does have write access to the folder. 1. Change to your FreshRSS directory ```sh @@ -42,7 +42,7 @@ If your local user doesn't have write access to the FreshRSS folder, use a sudo git clean -f -d ``` - Note: If you wish to keep your changes, it's better to [create a pull request](https://github.com/FreshRSS/FreshRSS/compare) or [an extension](../developers/03_Backend/05_Extensions.md). + Note: If you wish to keep your changes, it’s better to [create a pull request](https://github.com/FreshRSS/FreshRSS/compare) or [an extension](../developers/03_Backend/05_Extensions.md). 4. Update FreshRSS ```sh @@ -58,7 +58,7 @@ If your local user doesn't have write access to the FreshRSS folder, use a sudo git status ``` - The command should tell you the tag that you're using. It must be the same as the one associated with [the latest release on GitHub](https://github.com/FreshRSS/FreshRSS/releases/latest). If you use the rolling release, it should tell you that your `edge` branch is up to date with `origin`. + The command should tell you the tag that you’re using. It must be the same as the one associated with [the latest release on GitHub](https://github.com/FreshRSS/FreshRSS/releases/latest). If you use the rolling release, it should tell you that your `edge` branch is up to date with `origin`. 6. Re-set correct permissions so that your web server can access the files ```sh @@ -67,7 +67,7 @@ If your local user doesn't have write access to the FreshRSS folder, use a sudo ## Using the Zip archive -If your local user doesn't have write access to the FreshRSS folder, use a sudo shell (`sudo -s`), prefix the following commands with `sudo`, or switch to an account that does have write access to the folder. +If your local user doesn’t have write access to the FreshRSS folder, use a sudo shell (`sudo -s`), prefix the following commands with `sudo`, or switch to an account that does have write access to the folder. 1. Change to your FreshRSS directory ```sh diff --git a/docs/en/admins/08_FeedUpdates.md b/docs/en/admins/08_FeedUpdates.md index e1a02af31..2072188bd 100644 --- a/docs/en/admins/08_FeedUpdates.md +++ b/docs/en/admins/08_FeedUpdates.md @@ -2,17 +2,17 @@ FreshRSS is updated by the `./app/actualize_script.php` script. Knowing this, we can periodically trigger it to ensure up-to-date feeds. -**Note:** the update script won't update any particular feed more often than once every twenty minutes, so it doesn't make sense to trigger it much more frequently than that. +**Note:** the update script won’t update any particular feed more often than once every twenty minutes, so it doesn’t make sense to trigger it much more frequently than that. -**Note:** the following examples assume that FreshRSS is installed to `/usr/share/FreshRSS`. You'll need to modify the FreshRSS path to reflect your own system. +**Note:** the following examples assume that FreshRSS is installed to `/usr/share/FreshRSS`. You’ll need to modify the FreshRSS path to reflect your own system. **Note:** If you cannot configure a local Cronjob, [see an alternative using online cron](../users/03_Main_view.md#online-cron). ## Cron as a trigger -You'll need to check the Cron documentation for your specific distribution ([Debian/Ubuntu](https://help.ubuntu.com/community/CronHowto), [Red Hat/Fedora/CentOS](https://fedoraproject.org/wiki/Administration_Guide_Draft/Cron), [Slackware](https://docs.slackware.com/fr:slackbook:process_control?#cron), [Gentoo](https://wiki.gentoo.org/wiki/Cron), [Arch Linux](https://wiki.archlinux.org/index.php/Cron) ...) to make sure you set the Cron job correctly. +You’ll need to check the Cron documentation for your specific distribution ([Debian/Ubuntu](https://help.ubuntu.com/community/CronHowto), [Red Hat/Fedora/CentOS](https://fedoraproject.org/wiki/Administration_Guide_Draft/Cron), [Slackware](https://docs.slackware.com/fr:slackbook:process_control?#cron), [Gentoo](https://wiki.gentoo.org/wiki/Cron), [Arch Linux](https://wiki.archlinux.org/index.php/Cron) …) to make sure you set the Cron job correctly. -It's advisable that you run the Cron job as your Web server user (often `www-data`). +It’s advisable that you run the Cron job as your Web server user (often `www-data`). ### Example on Debian/Ubuntu @@ -25,7 +25,7 @@ Edit `/etc/crontab` and append the following line: ## Systemd as a trigger -Some systems can't use a Cron job, but they can use systemd. It's easy to configure it to mimic Cron's features. +Some systems can’t use a Cron job, but they can use systemd. It’s easy to configure it to mimic Cron’s features. First you need to add a `freshrss.timer` file in `/etc/systemd/system/` with the following content: diff --git a/docs/en/admins/13_Default_user.md b/docs/en/admins/13_Default_user.md index 946d53814..16312111f 100644 --- a/docs/en/admins/13_Default_user.md +++ b/docs/en/admins/13_Default_user.md @@ -16,7 +16,7 @@ The default user is used for the anonymous reading. How to enable the anonymous reading mode: * go to settings `Administration` → `Authentication` -* enable the checkbox of `Allow anonymous reading of the default user's articles` +* enable the checkbox of `Allow anonymous reading of the default user’s articles` * when no user is logged in then the feeds of the default user is shown ## Change the default user diff --git a/docs/en/contributing.md b/docs/en/contributing.md index 62c74b2c2..f18ddda26 100644 --- a/docs/en/contributing.md +++ b/docs/en/contributing.md @@ -1,10 +1,10 @@ ## Report a bug -Have you found a bug? Don't panic, here are some steps to report it with ease: +Have you found a bug? Don’t panic, here are some steps to report it with ease: -1. Search for it on [the bug tracker](https://github.com/FreshRSS/FreshRSS/issues) (don't forget to use the search bar). -2. If you find a similar bug, don't hesitate to post a comment to add more importance to the related ticket. -3. If you didn't find it, [open a new ticket](https://github.com/FreshRSS/FreshRSS/issues/new). +1. Search for it on [the bug tracker](https://github.com/FreshRSS/FreshRSS/issues) (don’t forget to use the search bar). +2. If you find a similar bug, don’t hesitate to post a comment to add more importance to the related ticket. +3. If you didn’t find it, [open a new ticket](https://github.com/FreshRSS/FreshRSS/issues/new). If you have to create a new ticket, please try to keep in mind the following advice: @@ -24,20 +24,20 @@ For a more detailed guide on writing bug reports, please refer to [the in-depth Would you like to fix a bug? For optimum coordination between collaborators, you should follow these indications: -1. Be sure the bug is associated with a ticket and indicate that you'll work on it. +1. Be sure the bug is associated with a ticket and indicate that you’ll work on it. 2. [Fork the project repository](https://help.github.com/articles/fork-a-repo/). 3. [Create a new branch](https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/). The name of the branch should be clear, and ideally prefixed by the related ticket id. For instance, `783-contributing-file` to fix [ticket #783](https://github.com/FreshRSS/FreshRSS/issues/783). 4. Make your changes to your fork and [send a pull request](https://help.github.com/articles/using-pull-requests/). If you have to write code, please follow [our coding style recommendations](developers/02_First_steps.md). -**Tip:** if you're searching for easy-to-fix bugs, please have a look at the "[good first issue](https://github.com/FreshRSS/FreshRSS/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)" ticket label. +**Tip:** if you’re searching for easy-to-fix bugs, please have a look at the “[good first issue](https://github.com/FreshRSS/FreshRSS/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)” ticket label. ## Submit an idea -You have great ideas, yes! Don't be shy and open [a new ticket](https://github.com/FreshRSS/FreshRSS/issues/new) on our bug tracker to ask if we can implement it. The greatest ideas often come from the shyest suggestions! +You have great ideas, yes! Don’t be shy and open [a new ticket](https://github.com/FreshRSS/FreshRSS/issues/new) on our bug tracker to ask if we can implement it. The greatest ideas often come from the shyest suggestions! -If your idea is nice, we'll have a look at it. +If your idea is nice, we’ll have a look at it. ## Contribute to internationalization (i18n) diff --git a/docs/en/developers/01_Index.md b/docs/en/developers/01_Index.md index 28d11a6cc..c32c1d4d7 100644 --- a/docs/en/developers/01_Index.md +++ b/docs/en/developers/01_Index.md @@ -2,7 +2,7 @@ ## First Steps -Start by creating your development environment. A guide to setting up FreshRSS's development environment can be found on [the appropriate page](02_First_steps.md). +Start by creating your development environment. A guide to setting up FreshRSS’s development environment can be found on [the appropriate page](02_First_steps.md). ## After That diff --git a/docs/en/developers/02_First_steps.md b/docs/en/developers/02_First_steps.md index 626ee84fc..e79d86691 100644 --- a/docs/en/developers/02_First_steps.md +++ b/docs/en/developers/02_First_steps.md @@ -1,16 +1,16 @@ # Environment configuration (Docker) -FreshRSS is built with PHP and uses a homemade framework, Minz. The dependencies are directly included in the source code, so you don't need Composer. +FreshRSS is built with PHP and uses a homemade framework, Minz. The dependencies are directly included in the source code, so you don’t need Composer. -There are various ways to configure your development environment. The easiest and most supported method is based on Docker, which is the solution documented below. If you already have a working PHP environment, you probably don't need it. +There are various ways to configure your development environment. The easiest and most supported method is based on Docker, which is the solution documented below. If you already have a working PHP environment, you probably don’t need it. -We assume here that you use a GNU/Linux distribution, capable of running Docker. Otherwise, you'll have to adapt the commands accordingly. +We assume here that you use a GNU/Linux distribution, capable of running Docker. Otherwise, you’ll have to adapt the commands accordingly. -The commands that follow have to be executed in a console. They start by `$` when commands need to be executed as normal user, and by `#` when they need to be executed as root user. You don't have to type these characters. A path may be indicated before these characters to help you identify where they need to be executed. For instance, `app$ echo 'Hello World'` indicates that you have to execute `echo` command in the `app/` directory. +The commands that follow have to be executed in a console. They start by `$` when commands need to be executed as normal user, and by `#` when they need to be executed as root user. You don’t have to type these characters. A path may be indicated before these characters to help you identify where they need to be executed. For instance, `app$ echo 'Hello World'` indicates that you have to execute `echo` command in the `app/` directory. First, you need to install [Docker](https://docs.docker.com/install/linux/docker-ce/ubuntu/). -Once you're done, clone the repository with: +Once you’re done, clone the repository with: ```sh git clone https://github.com/FreshRSS/FreshRSS.git @@ -25,7 +25,7 @@ Then, the only command you need to know is the following: make start ``` -This might take some time while Docker downloads the image. If your user isn't in the `docker` group, you'll need to prepend the command with `sudo`. +This might take some time while Docker downloads the image. If your user isn’t in the `docker` group, you’ll need to prepend the command with `sudo`. **You can now access FreshRSS at [http://localhost:8080](http://localhost:8080).** Just follow the install process and select the SQLite database. @@ -35,7 +35,7 @@ You can stop the containers by typing Control + c or with make stop ``` -If you're interested in the configuration, the `make` commands are defined in the [`Makefile`](/Makefile). +If you’re interested in the configuration, the `make` commands are defined in the [`Makefile`](/Makefile). If you need to use a different tag image (default is `alpine`), you can set the `TAG` environment variable: @@ -65,9 +65,9 @@ If you want to create your own FreshRSS extension, take a look at the [extension ## Coding style -If you want to contribute to the source code, it's important to follow the project's coding style. The actual code doesn't always follow it throughout the project, but we should fix it every time an opportunity presents itself. +If you want to contribute to the source code, it’s important to follow the project’s coding style. The actual code doesn’t always follow it throughout the project, but we should fix it every time an opportunity presents itself. -Contributions which don't follow the coding style will be rejected as long as the coding style is not fixed. +Contributions which don’t follow the coding style will be rejected as long as the coding style is not fixed. ## Spaces, tabs and other whitespace characters @@ -119,7 +119,7 @@ echo $a ? 1 : 0; ### Parentheses -There should be no spaces in between brackets. There should be no spaces before the opening bracket, except if it's after a keyword. There shouldn't be any spaces after the closing bracket, except if it's followed by a curly bracket. +There should be no spaces in between brackets. There should be no spaces before the opening bracket, except if it’s after a keyword. There shouldn’t be any spaces after the closing bracket, except if it’s followed by a curly bracket. ```php if ($a == 10) { @@ -133,7 +133,7 @@ if ((int)$a == 10) { ### With chained functions -It happens most of the time in Javascript files. When there are chained functions with closures and callback functions, it's hard to understand the code if not properly formatted. In those cases, we add a new indent level for the complete instruction and reset the indent for a new instruction on the same level. +It happens most of the time in Javascript files. When there are chained functions with closures and callback functions, it’s hard to understand the code if not properly formatted. In those cases, we add a new indent level for the complete instruction and reset the indent for a new instruction on the same level. ```javascript // First instruction diff --git a/docs/en/developers/02_Github.md b/docs/en/developers/02_Github.md index 7a7769caa..4e6a84ab3 100644 --- a/docs/en/developers/02_Github.md +++ b/docs/en/developers/02_Github.md @@ -4,7 +4,7 @@ If you are new to Git, here are some of the resources you might find useful: -* [GitHub's blog post](https://github.com/blog/120-new-to-git) +* [GitHub’s blog post](https://github.com/blog/120-new-to-git) * * * diff --git a/docs/en/developers/03_Backend/05_Extensions.md b/docs/en/developers/03_Backend/05_Extensions.md index 90fe6f699..d58521799 100644 --- a/docs/en/developers/03_Backend/05_Extensions.md +++ b/docs/en/developers/03_Backend/05_Extensions.md @@ -26,7 +26,7 @@ Note: it is quite conceivable that the functionalities of an extension can later **TODO** : move to 02_Minz.md -This data sheet should refer to the official FreshRSS and Minz documentation (the PHP framework on which FreshRSS is based). Unfortunately, this documentation does not yet exist. In a few words, here are the main things you should know. It is not necessary to read all the chapters in this section if you don't need to use a feature in your extension (if you don't need to translate your extension, no need to know more about the `Minz_Translate` module for example). +This data sheet should refer to the official FreshRSS and Minz documentation (the PHP framework on which FreshRSS is based). Unfortunately, this documentation does not yet exist. In a few words, here are the main things you should know. It is not necessary to read all the chapters in this section if you don’t need to use a feature in your extension (if you don’t need to translate your extension, no need to know more about the `Minz_Translate` module for example). ### MVC Architecture @@ -214,13 +214,13 @@ This part [is explained here](/docs/en/internationalization.md). ## Write an extension for FreshRSS -Here we are! We've talked about the most useful features of Minz and how to run FreshRSS correctly and it's about time to address the extensions themselves. +Here we are! We’ve talked about the most useful features of Minz and how to run FreshRSS correctly and it’s about time to address the extensions themselves. An extension allows you to easily add functionality to FreshRSS without having to touch the core of the project directly. ### Make it work in Docker -When working on an extension, it's easier to see it working directly in its environment. With Docker, you can leverage the use of the ```volume``` option when starting the container. Hopefully, you can use it without Docker-related knowledge by using the Makefile rule: +When working on an extension, it’s easier to see it working directly in its environment. With Docker, you can leverage the use of the ```volume``` option when starting the container. Hopefully, you can use it without Docker-related knowledge by using the Makefile rule: ```sh make start extensions="/full/path/to/extension/1 /full/path/to/extension/2" ``` @@ -266,7 +266,7 @@ In addition, it is good to have a `LICENSE` file indicating the license under wh The `metadata.json` file defines your extension through a number of important elements. It must contain a valid JSON array containing the following entries: * `name`: the name of your extension -* `author`: your name, your e-mail address ... but there is no specific format to adopt +* `author`: your name, your e-mail address … but there is no specific format to adopt * `description`: a description of your extension * `version`: the current version number of the extension * `entrypoint`: Indicates the entry point of your extension. It must match the name of the class contained in the file `extension.php` without the suffix `Extension` @@ -291,11 +291,11 @@ It must define some key elements to be loaded by the extension system: 1. The class must define the `init` method. This method is called **only** if the extension is loaded. Its purpose is to initialize the extension and its behavior during every page load. The `Minz_Extension` abstract class defines a set of methods that can be overridden to fit your needs: -* the `install` method is called when the user enables the extension in the configuration page. It must return _true_ when successful and a string containing an error message when not. Its purpose is to prepare FreshRSS for the extension (adding a table to the database, creating a folder tree, ...). -* the `uninstall` method is called when the user disables the extension in the configuration page. It must return _true_ when successful and a string containing an error message when not. Its purpose is to clean FreshRSS (removing a table from the database, deleting a folder tree, ...). Usually it reverts changes introduced by the `install` method. +* the `install` method is called when the user enables the extension in the configuration page. It must return _true_ when successful and a string containing an error message when not. Its purpose is to prepare FreshRSS for the extension (adding a table to the database, creating a folder tree, …). +* the `uninstall` method is called when the user disables the extension in the configuration page. It must return _true_ when successful and a string containing an error message when not. Its purpose is to clean FreshRSS (removing a table from the database, deleting a folder tree, …). Usually it reverts changes introduced by the `install` method. * the `handleConfigureAction` method is called when a user loads the extension configuration panel. It contains the logic to validate and store the submitted values defined in the `configure.phtml` file. -> If your extension code is scattered in different classes, you need to load their source before using them. Of course you could include the files manually, but it's more efficient to load them automatically. To do so, you just need to define the `autoload` method which will include them when needed. This method will be registered automatically when the extension is enabled. +> If your extension code is scattered in different classes, you need to load their source before using them. Of course you could include the files manually, but it’s more efficient to load them automatically. To do so, you just need to define the `autoload` method which will include them when needed. This method will be registered automatically when the extension is enabled. The `Minz_Extension` abstract class defines another set of methods that should not be overridden: * the `getName`, `getEntrypoint`, `getPath`, `getAuthor`, `getDescription`, `getVersion`, and `getType` methods return the extension internal properties. Those properties are extracted from the `metadata.json` file. @@ -311,7 +311,7 @@ The `Minz_Extension` abstract class defines another set of methods that should n * the `setUserConfiguration` method stores the extension configuration for the current user. * the `removeUserConfiguration` method removes the extension configuration for the current user. -> Note that if you modify the later set of methods, you might break the extension system. Thus making FreshRSS unusable. So it's highly recommended to let those unmodified. +> Note that if you modify the later set of methods, you might break the extension system. Thus making FreshRSS unusable. So it’s highly recommended to let those unmodified. ### The "hooks" system @@ -332,7 +332,7 @@ class HelloWorldExtension extends Minz_Extension The following events are available: -* `check_url_before_add` (`function($url) -> Url | null`): will be executed every time a URL is added. The URL itself will be passed as parameter. This way a website known to have feeds which doesn't advertise it in the header can still be automatically supported. +* `check_url_before_add` (`function($url) -> Url | null`): will be executed every time a URL is added. The URL itself will be passed as parameter. This way a website known to have feeds which doesn’t advertise it in the header can still be automatically supported. * `entry_before_display` (`function($entry) -> Entry | null`): will be executed every time an entry is rendered. The entry itself (instance of FreshRSS\_Entry) will be passed as parameter. * `entry_before_insert` (`function($entry) -> Entry | null`): will be executed when a feed is refreshed and new entries will be imported into the database. The new entry (instance of FreshRSS\_Entry) will be passed as parameter. * `feed_before_actualize` (`function($feed) -> Feed | null`): will be executed when a feed is updated. The feed (instance of FreshRSS\_Feed) will be passed as parameter. diff --git a/docs/en/developers/03_Running_tests.md b/docs/en/developers/03_Running_tests.md index b20f38985..197a01057 100644 --- a/docs/en/developers/03_Running_tests.md +++ b/docs/en/developers/03_Running_tests.md @@ -12,7 +12,7 @@ make test This command downloads the PHPUnit binary and verifies its checksum. If the verification fails, the file is deleted. In this case, you should [open an issue on GitHub](https://github.com/FreshRSS/FreshRSS/issues/new) to let maintainers know about the problem. -Then, it executes PHPUnit in a Docker container. If you don't use Docker, you can run the command directly with: +Then, it executes PHPUnit in a Docker container. If you don’t use Docker, you can run the command directly with: ```sh NO_DOCKER=true make test diff --git a/docs/en/developers/04_Frontend/02_Design.md b/docs/en/developers/04_Frontend/02_Design.md index 4ec8253ad..f3dbc10eb 100644 --- a/docs/en/developers/04_Frontend/02_Design.md +++ b/docs/en/developers/04_Frontend/02_Design.md @@ -7,7 +7,7 @@ The easiest way to create a theme is by copying and modifying the base theme (or another of the pre-installed themes). The base theme can be found in [/p/themes/base-theme](https://github.com/FreshRSS/FreshRSS/tree/edge/p/themes/base-theme). Themes require: - a **metadata.json** file to describe the theme. -- a **loader.gif** file to use as a loading icon (assuming .loading's background has not been overridden) +- a **loader.gif** file to use as a loading icon (assuming .loading’s background has not been overridden) - an **icons** folder containing .svg, .ico, and .png files to override existing icons - a **thumbs** folder containing a file, **original.png** that will be used as the preview for the theme @@ -19,7 +19,7 @@ RTL (right-to-left) support for languages such as Hebrew and Arabic is handled t ## Overriding icons -To replace the default icons, add an "icons" folder to your theme's folder. Use files with the same name as the default icon to override them. +To replace the default icons, add an "icons" folder to your theme’s folder. Use files with the same name as the default icon to override them. ## Template file diff --git a/docs/en/developers/04_Pull_requests.md b/docs/en/developers/04_Pull_requests.md index 6f5bab655..1169a10b1 100644 --- a/docs/en/developers/04_Pull_requests.md +++ b/docs/en/developers/04_Pull_requests.md @@ -1,8 +1,8 @@ # Opening a pull request -So you want to propose a patch to the community? It's time to open a [pull request](https://github.com/FreshRSS/FreshRSS/pulls)! +So you want to propose a patch to the community? It’s time to open a [pull request](https://github.com/FreshRSS/FreshRSS/pulls)! -When you open a PR, your message will be prefilled with a message based on [a template](https://github.com/FreshRSS/FreshRSS/blob/edge/docs/pull_request_template.md). It contains a checklist to make sure you didn't forget anything. It is very important to verify you did everything mentioned so documentation is up-to-date, the commit history stays clear and the code is always stable. +When you open a PR, your message will be prefilled with a message based on [a template](https://github.com/FreshRSS/FreshRSS/blob/edge/docs/pull_request_template.md). It contains a checklist to make sure you didn’t forget anything. It is very important to verify you did everything mentioned so documentation is up-to-date, the commit history stays clear and the code is always stable. The rest of this document explains specific points. @@ -12,11 +12,11 @@ The rest of this document explains specific points. Rebasing a branch is useful to make sure your code is based on the most recent version of FreshRSS and there are no conflicts. You have two ways to do that. -If you have any doubt, please let us know and we'll help you! We all began with Git one day and it's not an easy thing to work with. +If you have any doubt, please let us know and we’ll help you! We all began with Git one day and it’s not an easy thing to work with. ### Rebasing -Rebasing is the cleanest method because the Git history will be completely linear and consequently easier to read and navigate. It might also be more difficult if you're not at ease with Git since conflicts are harder to resolve. +Rebasing is the cleanest method because the Git history will be completely linear and consequently easier to read and navigate. It might also be more difficult if you’re not at ease with Git since conflicts are harder to resolve. Note that you should never rebase a branch if someone else is working on it. Otherwise, since it rewrites the history, it can be a real mess to sort it out. @@ -33,7 +33,7 @@ If you feel confident, you can use `git rebase -i edge` to rewrite your history ### Merging -If you prefer, you can simply merge `edge` into your own branch. Conflicts might be easier to resolve, but your Git history will be less readable. Don't worry, we'll take care of it before merging your PR back into `edge`. +If you prefer, you can simply merge `edge` into your own branch. Conflicts might be easier to resolve, but your Git history will be less readable. Don’t worry, we will take care of it before merging your PR back into `edge`. To merge `edge`: @@ -46,13 +46,13 @@ git merge edge # merge edge into your branch ## How to write a Git commit message -It's important to have proper commit messages in order to facilitate later debugging, so please read the following advice. Commit messages should explain the choices made in the past (the “why?”) +It’s important to have proper commit messages in order to facilitate later debugging, so please read the following advice. Commit messages should explain the choices made in the past (the “why?”) -The first line should start with a verb (e.g., "Add") and explain the objective of the commit in few words. It's usually less than 50 characters so it remains concise. You can consider this line the subject of your commit. Think of it as the second part of a sentence that starts with the words "This commit will." +The first line should start with a verb (e.g., “Add”) and explain the objective of the commit in few words. It’s usually less than 50 characters so it remains concise. You can consider this line the subject of your commit. Think of it as the second part of a sentence that starts with the words “This commit will.” * This commit will *add feature X* -Then, insert a blank line, and start to write the body. It's usually wrapped at 72 characters, but you are pretty free in the tone of the message. The body is the place where you can clarify the context of your patch. For instance, you can explain what you were doing when you identified a bug, or the problem you had before your patch. Providing this information helps other developers understand why a specific choice was made, especially when a patch introduces a bug that is identified months later. +Then, insert a blank line, and start to write the body. It’s usually wrapped at 72 characters, but you are pretty free in the tone of the message. The body is the place where you can clarify the context of your patch. For instance, you can explain what you were doing when you identified a bug, or the problem you had before your patch. Providing this information helps other developers understand why a specific choice was made, especially when a patch introduces a bug that is identified months later. You also can add references (e.g., the URL to the initial ticket in the bug tracker, or a reference to some forum explaining a point). @@ -60,16 +60,16 @@ You can find more information about commit messages [on this blog post](https:// ## How to write tests -FreshRSS has few tests for now, but we're working on it. We added this point to the checklist to help us to write more tests, and we would really appreciate it if you wrote a test that ensures your patch is working. +FreshRSS has few tests for now, but we’re working on it. We added this point to the checklist to help us to write more tests, and we would really appreciate it if you wrote a test that ensures your patch is working. We use [PHPUnit](https://phpunit.de/) version 7.5 ([documentation](https://phpunit.readthedocs.io/en/7.5/)). -You'll find more information on how to run tests [in this document](03_Running_tests.md). +You’ll find more information on how to run tests [in this document](03_Running_tests.md). -Feel free to ask us for assistance. Not everything will be easy to test, so don't spend too much time on this. +Feel free to ask us for assistance. Not everything will be easy to test, so don’t spend too much time on this. ## Why you should write documentation -A friendly project should have correct and complete documentation, so newcomers don't have to ask too many questions, and users can find answers to their problems. The documentation should not be written “later” or chances are it'll never be. +A friendly project should have correct and complete documentation, so newcomers don’t have to ask too many questions, and users can find answers to their problems. The documentation should not be written “later” or chances are it’ll never be. -Our documentation can still be improved quite a bit, so you're very welcome if you want to help. +Our documentation can still be improved quite a bit, so you’re very welcome if you want to help. diff --git a/docs/en/developers/05_Release_new_version.md b/docs/en/developers/05_Release_new_version.md index 918451490..46bec973c 100644 --- a/docs/en/developers/05_Release_new_version.md +++ b/docs/en/developers/05_Release_new_version.md @@ -1,9 +1,9 @@ # Preparing the release -In order to get as much feedback as possible before a release, it's preferable to announce it on GitHub by creating a dedicated ticket +In order to get as much feedback as possible before a release, it’s preferable to announce it on GitHub by creating a dedicated ticket ([see examples](https://github.com/FreshRSS/FreshRSS/search?utf8=%E2%9C%93&q=Call+for+testing&type=Issues)). This should be done **at least one week in advance**. -It's also recommended to make the announcement on mailing@freshrss.org. +It’s also recommended to make the announcement on mailing@freshrss.org. ## Check the dev status @@ -27,7 +27,7 @@ $ git push && git push --tags ## Updating `update.freshrss.org` -It's important to update update.freshrss.org since this is the default service for automatic FreshRSS updates. +It’s important to update update.freshrss.org since this is the default service for automatic FreshRSS updates. The repository managing the code is located on GitHub: [FreshRSS/update.freshrss.org](https://github.com/FreshRSS/update.freshrss.org/). @@ -35,7 +35,7 @@ The repository managing the code is located on GitHub: [FreshRSS/update.freshrss The scripts are located in the `./scripts/` directory and must take the form `update_to_x.y.z.z.php`. This directory also contains `update_to_dev.php` intended for updates of the `edge` branch (this script must not include code specific to a particular version!) and `update_util.php`, which contains a list of functions useful for all scripts. -In order to write a new script, it's better to copy/paste the last version or to start from `update_to_dev.php`. The first thing to do is to define the URL from which the FreshRSS package will be downloaded (`PACKAGE_URL`). The URL is in the form of `https://codeload.github.com/FreshRSS/FreshRSS/zip/x.y.z`. +In order to write a new script, it’s better to copy/paste the last version or to start from `update_to_dev.php`. The first thing to do is to define the URL from which the FreshRSS package will be downloaded (`PACKAGE_URL`). The URL is in the form of `https://codeload.github.com/FreshRSS/FreshRSS/zip/x.y.z`. There are then 5 functions that have to be executed: @@ -47,9 +47,9 @@ There are then 5 functions that have to be executed: ## Updating the versions file -Once the script has been written and versioned, it's necessary to update the `./versions.php' file which contains a mapping table indicating which versions are updated to which other versions. +Once the script has been written and versioned, it’s necessary to update the `./versions.php' file which contains a mapping table indicating which versions are updated to which other versions. -Here's an example of a `versions.php` file: +Here’s an example of a `versions.php` file: ```php '1.0.0', '0.8.1' => '1.0.0', - '1.0.0' => '1.0.1', // doesn't exist (yet) + '1.0.0' => '1.0.1', // doesn’t exist (yet) // DEV '1.1.2-dev' => 'dev', '1.1.3-dev' => 'dev', @@ -65,21 +65,21 @@ return array( ); ``` -And here's how this table works: +And here’s how this table works: * on the left you can find the N version, on the right the N+1 version; * the `x.y.z.z-dev` versions are **all** updated to `edge`; * stable versions are updated to stable versions; -* it's possible to skip several versions at once, provided that the update scripts support it; -* it's advisable to indicate the correspondence of the current version to its potential future version by specifying that this version does not yet exist. As long as the corresponding script does not exist, nothing will happen. +* it’s possible to skip several versions at once, provided that the update scripts support it; +* it’s advisable to indicate the correspondence of the current version to its potential future version by specifying that this version does not yet exist. As long as the corresponding script does not exist, nothing will happen. -It's **very strongly** recommended to keep this file organized according to version numbers by separating stable and dev versions. +It’s**very strongly** recommended to keep this file organized according to version numbers by separating stable and dev versions. ## Deployment -Before updating update.freshrss.org, it's better to test with dev.update.freshrss.org, which corresponds to pre-production. So update dev.update.freshrss.org and change the `FRESHRSS_UPDATE_WEBSITE` URL of your FreshRSS instance. Start the update and check that it's running correctly. +Before updating update.freshrss.org, it’s better to test with dev.update.freshrss.org, which corresponds to pre-production. So update dev.update.freshrss.org and change the `FRESHRSS_UPDATE_WEBSITE` URL of your FreshRSS instance. Start the update and check that it’s running correctly. -When you're satisfied, update update.freshrss.org with the new script, test it again, and then move on. +When you’re satisfied, update update.freshrss.org with the new script, test it again, and then move on. ## Updating the FreshRSS services @@ -90,7 +90,7 @@ Two services need to be updated immediately after the update. ## Publicly announce the release -When everything's working, it's time to announce the release to the world! +When everything’s working, it’s time to announce the release to the world! * on GitHub by creating[a new release](https://github.com/FreshRSS/FreshRSS/releases/new) * on the freshrss.org blog, at least for stable versions (write the article on[FreshRSS/freshrss.org](https://github.com/FreshRSS/freshrss.org)) diff --git a/docs/en/developers/06_Fever_API.md b/docs/en/developers/06_Fever_API.md index 909fd6074..287885089 100644 --- a/docs/en/developers/06_Fever_API.md +++ b/docs/en/developers/06_Fever_API.md @@ -7,7 +7,7 @@ Additionally [page about our Google Reader compatible API](06_GoogleReader_API.m ## RSS clients There are many RSS clients that support the Fever API, but they seem to understand the Fever API a bit differently. -If your favourite client doesn't work properly with this API, please create an issue and we'll have a look. +If your favourite client doesn’t work properly with this API, please create an issue and we’ll have a look. But we can **only** do that for free clients. ### Usage & Authentication @@ -80,7 +80,7 @@ This should give: "last_refreshed_on_time": "1520013061" } ``` -Perfect, you're now authenticated and you can start testing the more advanced features. To do so, change the URL and append the possible API actions to your request parameters. Please refer to the [original Fever documentation](https://feedafever.com/api) for more information. +Perfect, you’re now authenticated and you can start testing the more advanced features. To do so, change the URL and append the possible API actions to your request parameters. Please refer to the [original Fever documentation](https://feedafever.com/api) for more information. Some basic calls are: diff --git a/docs/en/developers/06_GoogleReader_API.md b/docs/en/developers/06_GoogleReader_API.md index 5035ca6cf..970ce824f 100644 --- a/docs/en/developers/06_GoogleReader_API.md +++ b/docs/en/developers/06_GoogleReader_API.md @@ -6,7 +6,7 @@ Additionally [page about our Fever compatible API](06_Fever_API.md) for another ## RSS clients There are many RSS clients that support the Fever API, but they might understand the API a bit differently. -If your favourite client doesn't work properly with this API, please create an issue and we'll have a look. +If your favourite client doesn’t work properly with this API, please create an issue and we’ll have a look. But we can **only** do that for free clients. ## Usage & Authentication diff --git a/docs/en/developers/06_Reporting_Bugs.md b/docs/en/developers/06_Reporting_Bugs.md index 77b16251f..4f53c0ee4 100644 --- a/docs/en/developers/06_Reporting_Bugs.md +++ b/docs/en/developers/06_Reporting_Bugs.md @@ -1,17 +1,17 @@ # Reporting a bug or a suggestion -Despite the care given to FreshRSS, it's still possible that bugs occur. Development is dynamic, so issues can be corrected quickly. You might also have a feature in mind that doesn't yet exist. Regardless whether your idea seems silly, far-fetched, useless or too specific, please don't hesitate to propose it to us! "Ideas in the air" often find an attentive ear. It's new external perspectives that make the project evolve the most. +Despite the care given to FreshRSS, it’s still possible that bugs occur. Development is dynamic, so issues can be corrected quickly. You might also have a feature in mind that doesn’t yet exist. Regardless whether your idea seems silly, far-fetched, useless or too specific, please don’t hesitate to propose it to us! “Ideas in the air” often find an attentive ear. It’s new external perspectives that make the project evolve the most. -If you're convinced that you should be heard, here's how you can go about it. +If you’re convinced that you should be heard, here’s how you can go about it. ## On GitHub -GitHub is the ideal platform to submit your requests. It allows us to discuss a problem or suggestion with others and it often generates new ideas. Let's not neglect this "social" aspect! +GitHub is the ideal platform to submit your requests. It allows us to discuss a problem or suggestion with others and it often generates new ideas. Let’s not neglect this “social” aspect! 1. [Go to the bug ticket manager](https://github.com/FreshRSS/FreshRSS/issues) -2. Start by checking if a similar request hasn't already been made. If so, please feel free to add your voice to the request. +2. Start by checking if a similar request hasn’t already been made. If so, please feel free to add your voice to the request. 3. If your request is new, [open a new bug ticket](https://github.com/FreshRSS/FreshRSS/issues/new) -4. Finally, write your request. If you're fluent in English, it's the preferred language because it allows for discussion with the largest number of people. +4. Finally, write your request. If you’re fluent in English, it’s the preferred language because it allows for discussion with the largest number of people. 5. Please follow the tips below to make it easier to let your ticket be heard. ## Informal @@ -29,17 +29,17 @@ Not everyone likes or uses GitHub for a variety of legitimate reasons. That is w Here are some tips to help you present your bug report or suggestion: -* **Pay attention to spelling**. Even if it's not always easy, try your best! -* **Give an explicit title to your request**, even if it's a bit long. This not only helps us understand your request, but also to find your ticket later. -* **One request = one ticket.** You may have lots of ideas while being afraid to spam the bug manager: it doesn't matter. It's better to have a few too many tickets than too many requests in one. We'll close and consolidate requests when possible. +* **Pay attention to spelling**. Even if it’s not always easy, try your best! +* **Give an explicit title to your request**, even if it’s a bit long. This not only helps us understand your request, but also to find your ticket later. +* **One request = one ticket.** You may have lots of ideas while being afraid to spam the bug manager: it doesn’t matter. It’s better to have a few too many tickets than too many requests in one. We’ll close and consolidate requests when possible. * If you report a bug, think about **providing us with the FreshRSS logs** (accessible in the FreshRSS `data/log/` folder) and the **PHP logs** (the location may vary by distribution, but consider searching in `/var/log/httpd` or `/var/log/apache`). -* If you can't find the log files, specify it in your ticket so we know you've already searched. +* If you can’t find the log files, specify it in your ticket so we know you’ve already searched. * Not all bugs require logs, but if you have any doubts, it is better to provide them to us. Logs are important and very useful for debugging! * The logs may reveal confidential information, so **be careful not to disclose anything sensitive.** -In addition, when facing a bug, you're encouraged to follow this message format (from the [Sam & Max website](http://sametmax.com/template-de-demande-daide-en-informatique/): +In addition, when facing a bug, you’re encouraged to follow this message format (from the [Sam & Max website](http://sametmax.com/template-de-demande-daide-en-informatique/): -### What's my goal? +### What’s my goal? Give the general context of what you were trying to do. @@ -49,7 +49,7 @@ Explain step by step what you have done so that we can reproduce the bug. ### What results have I achieved? -The bug: what you see that shouldn't have happened. Here you can provide the logs. +The bug: what you see that shouldn’t have happened. Here you can provide the logs. ### What was the expected result? @@ -63,4 +63,4 @@ Remember to give the following information if you know it: 2. Which server: Apache, Nginx? Which version? 3. Which version of PHP? 4. Which database: SQLite, MySQL, MariaDB, PostgreSQL? Which version? -5. Which distribution runs on the server? And... which version? +5. Which distribution runs on the server? And… which version? diff --git a/docs/en/internationalization.md b/docs/en/internationalization.md index d20f20a75..3feb4f57c 100644 --- a/docs/en/internationalization.md +++ b/docs/en/internationalization.md @@ -4,7 +4,7 @@ Thanks to our contributors, FreshRSS is translated into more than 15 languages. ## Overview -It is common (and that's an understatement) to want to show some text to the user. The problem is that FreshRSS has users of different nationalities. It is therefore necessary to be able to manage different languages in order not to remain confined to English or French. +It is common (and that’s an understatement) to want to show some text to the user. The problem is that FreshRSS has users of different nationalities. It is therefore necessary to be able to manage different languages in order not to remain confined to English or French. The solution is to use the `Minz_Translate` module, which allows dynamic translation of FreshRSS. Before using this module, it is necessary to know where to find the strings to be translated. Each language has its own subdirectory in a parent directory named `app/i18n/`. For example, English language files are located in [`app/i18n/en/`](/app/i18n/en/). There are seven different files: @@ -19,7 +19,7 @@ The solution is to use the `Minz_Translate` module, which allows dynamic transla This organization makes it possible to avoid a single huge translation file. -The translation files are quite simple: it's only a matter of returning a PHP array containing the translations. As an example, here's an extract from [`app/i18n/fr/gen.php`](/app/i18n/fr/gen.php): +The translation files are quite simple: it’s only a matter of returning a PHP array containing the translations. As an example, here’s an extract from [`app/i18n/fr/gen.php`](/app/i18n/fr/gen.php): ```php ``` -The function expects a translation key, but there's a special case that sometimes makes life easier: the `_` identifier. This must necessarily be present at the end of the chain and gives a value to the higher-level identifier. It's pretty hard to explain but very simple to understand. In the example given above, an `_` is associated with the value `FreshRSS`: this means that there is no need to write `_t('gen.freshrss._')` but `_t('gen.freshrss')` suffices. +The function expects a translation key, but there’s a special case that sometimes makes life easier: the `_` identifier. This must necessarily be present at the end of the chain and gives a value to the higher-level identifier. It’s pretty hard to explain but very simple to understand. In the example given above, an `_` is associated with the value `FreshRSS`: this means that there is no need to write `_t('gen.freshrss._')` but `_t('gen.freshrss')` suffices. `_t()` can take any number of variables. The variables will then be replaced in the translation if it contains some “conversion specifications” (usually `%s` or `%d`). You can learn more about these specifications in the [`sprintf()` PHP function documentation](https://www.php.net/manual/function.sprintf). -For instance, the English translation for `gen.auth.keep_logged_in` is `Keep me logged in (%s days)`. It means this translation expects a string to be passed as an argument to the `t()` function (well, it should be a `%d` because we want a number here, but it doesn't matter). For instance: +For instance, the English translation for `gen.auth.keep_logged_in` is `Keep me logged in (%s days)`. It means this translation expects a string to be passed as an argument to the `t()` function (well, it should be a `%d` because we want a number here, but it doesn’t matter). For instance: ```php