Documentation updates#1697
Conversation
moved Installation to admin directory linked some already existing documentation files
README.md
Outdated
| 6. Advanced configuration settings can be seen in [config.default.php](./config.default.php) and modified in `data/config.php`. | ||
| 7. When using Apache, enable [`AllowEncodedSlashes`](http://httpd.apache.org/docs/trunk/mod/core.html#allowencodedslashes) for better compatibility with mobile clients. | ||
|
|
||
| More about installation and server configuration can be found in [our documentation](https://freshrss.github.io/FreshRSS/en/admins/02_Installation.html). |
docs/en/admins/01_Index.md
Outdated
| @@ -0,0 +1,10 @@ | |||
|
|
|||
|
|
||
| # Security | ||
|
|
||
| Make sure to expose only the `./p/` folder on the web, the other directories contain personal and sensitive data. |
There was a problem hiding this comment.
There are examples for this somewhere in common configurations (Apache, nginx). I think they should either be moved here or linked to.
There was a problem hiding this comment.
Yes in the same file, only a couple of lines above this sentence
There was a problem hiding this comment.
I see. Maybe it'd be better to add a pointer? You might still have a somewhat similar tunnel vision by just using the TOC, although not as bad as GH literally hiding most of the file. :-P
There was a problem hiding this comment.
Hm, I am not sure if I get your point.
I'll add another sentence "See the Apache and nginx config examples above.", or did you mean something different?
|
|
||
| # Update to a newer version of FreshRSS, | ||
| # assuming you are on the /master or /dev branch | ||
| git pull |
There was a problem hiding this comment.
Since a git fetch was already executed above all this does is git merge. Not sure if it matters. :-P
There was a problem hiding this comment.
I just moved that existing docu here but didn't change the text.
I think this part is not meant to be executed in that exact order, but more a bunch of useful commands on how to get an (updated) FreshRSS version. I don't believe that someone uses git for installation without enough know-how to perform a pull?!
I don't mind changing it, but then we would need several chapters (use a tagged version, use the development version ...) and I don't want to write a git beginners instruction.
docs/en/admins/03_Updating.md
Outdated
|
|
||
| ```sh | ||
| # If your local user does not have write access, prefix all commands by sudo: | ||
| sudo ... |
There was a problem hiding this comment.
Wouldn't it look better/be more readable to only do that to the commands, like this.
If your local user does not have write access, prefix all commands by sudo:
sudo ...
There was a problem hiding this comment.
I'll push one chapter with that formatting and then you can have a look what you like more
There was a problem hiding this comment.
Just to be explicit about what I mean by "that formatting." ;-)
Commands intended to be executed in order (you can c/p the whole block if desired)
# creates directory
mkdir bla
# change to said directory
cd blaRandom commands
Creates directory:
mkdir blaCreates file:
touch blaThere was a problem hiding this comment.
PS Of course those two can follow each other. So we have one block above, followed by two separate blocks about file permissions (first-time only?) and sudo.
There was a problem hiding this comment.
Just to make sure: shall I revert everything back to the former state? From my opinion the previous was cleaner
There was a problem hiding this comment.
I'd personally separate out the sudo thing but either way.
There was a problem hiding this comment.
I will remove that sudo completely. It was part of the already existing documentation, but I doubt that someone has a server and installs FreshRSS without basic knowledge of the bash and permissions.
docs/en/contributing.md
Outdated
| If you have to write code, please follow [our coding style recommendations](http://doc2.freshrss.org/en/Developer_documentation/First_steps/Coding_style). | ||
| If you have to write code, please follow [our coding style recommendations](developers/01_First_steps.md). | ||
|
|
||
| **Tip:** if you are searching for bugs easy to fix, have a look at the « [New comers](https://github.com/FreshRSS/FreshRSS/labels/New%20comers) » ticket label. |
There was a problem hiding this comment.
I intend to go through it with editorial glasses at some point and this isn't your sentence, but the "that" isn't optional here.
Either "easy-to-fix bugs" or "bugs that are easy to fix."
Also newcomer is one word. ;-)
There was a problem hiding this comment.
I love getting feedback on stuff that I did not even touch ;-) I'll tackle that as well.
docs/en/developers/01_First_steps.md
Outdated
|
|
||
| # Extensions | ||
|
|
||
| If you want to create your own FreshRSS extension, either use the [incomplete english documentation](03_Backend/05_Extensions.md) or try the more complete [french version](../../fr/developers/03_Backend/05_Extensions.md). |
There was a problem hiding this comment.
Unfortunately DeepL (the best for French, at least to French) doesn't offer full page translation, but it could be an idea to include a link to some machine translation? But if you're not touching the extensions file I'll just start a separate PR to translate the remainder of the French and you can leave out the remark about completeness.
There was a problem hiding this comment.
DeepL is the best for german as well, but never tried it with technical docus. Actually I started the english version before DeepL came out, but using Google Translate was a nightmare ... I could only concentrate on the possible meaning of Googles translations instead of the actual content. I'll change it accordingly.
docs/en/index.md
Outdated
| - And a lot more! | ||
|
|
||
| This documentation is splitted in two sections: | ||
| This documentation is splitted in four sections: |
There was a problem hiding this comment.
The past tense of split is split. When combined with sections, it's split into.
docs/en/index.md
Outdated
|
|
||
| - [users documentation](users/02_First_steps.md) so you can discover all the power of FreshRSS | ||
| - [developers documentation](developers/01_First_steps.md) to guide you in the source code of FreshRSS and to help you if you want to contribute | ||
| - [administration documentation](admins/01_Index.md) to guide you in the source code of FreshRSS and to help you if you want to contribute |
There was a problem hiding this comment.
- user documentation
- developer documentation
- administrator documentation (for stylistic consistency; nothing grammatical)
Please also change the two above. ;-)
docs/en/users/02_First_steps.md
Outdated
| This section guides you to the pages you need as a new comer. | ||
|
|
||
| [After you installed the application](01_Installation.md), the first step is to add one or more feeds. You have few options: | ||
| [After you installed the application](../admins/02_Installation.md), the first step is to add one or more feeds. You have few options: |
There was a problem hiding this comment.
After installing the application
How about "the first step is to add some feeds"?
|
Many thanks for the work so far @kevinpapst and @Frenzie 👍 |
|
Added another commit with the review feedback from @Frenzie |
|
Sorry, I was a little too late with my opinion on code blocks. :-( I don't think I like how the latest commit breaks the ability to c/p. See #1697 (comment) |
docs/en/users/02_First_steps.md
Outdated
| This section guides you to the pages you need as a new comer. | ||
|
|
||
| [After you installed the application](01_Installation.md), the first step is to add one or more feeds. You have few options: | ||
| [After installing the application](../admins/02_Installation.md), the first step is to some feeds. You have a few options: |
There was a problem hiding this comment.
Damned ;-) Thanks for your detailed feedback, I'll push another one later
docs/en/contributing.md
Outdated
| If you have to write code, please follow [our coding style recommendations](developers/01_First_steps.md). | ||
|
|
||
| **Tip:** if you are searching for bugs easy to fix, have a look at the « [New comers](https://github.com/FreshRSS/FreshRSS/labels/New%20comers) » ticket label. | ||
| **Tip:** if you are searching for easy-to-fix bugs, have a look at the « [New comers](https://github.com/FreshRSS/FreshRSS/labels/New%20comers) » ticket label. |
There was a problem hiding this comment.
I checked and the linked label does not even exist anymore, I will delete that section completely.
There was a problem hiding this comment.
Wait, before you do that I imagine it's been changed to https://github.com/FreshRSS/FreshRSS/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22
There was a problem hiding this comment.
Ah, alright, then I change the link to "Newcomers" and this label
|
And another try ;-) |
docs/en/contributing.md
Outdated
| If you have to write code, please follow [our coding style recommendations](developers/01_First_steps.md). | ||
|
|
||
| **Tip:** if you are searching for bugs easy to fix, have a look at the « [New comers](https://github.com/FreshRSS/FreshRSS/labels/New%20comers) » ticket label. | ||
| **Tip:** if you are searching for easy-to-fix bugs, have a look at the « [Newcomers](https://github.com/FreshRSS/FreshRSS/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) » ticket label. |
There was a problem hiding this comment.
But now it's the "good first issue" label. ;-)
There was a problem hiding this comment.
Yes, I thought about that one as well, no prob, I'll change it
|
No complaints here besides the one little nitpick. |
cli/README.md
Outdated
| # Install and updates | ||
|
|
||
| ## Using git | ||
| For installation using git checkout out the [README](https://freshrss.github.io/FreshRSS/en/users/05_Configuration.html#). |
There was a problem hiding this comment.
The link is not a README anymore, is it?
There was a problem hiding this comment.
Whoops, Copy & Paste error - totally wrong URL, good catch!
|
Next try! |
|
No more comments @Frenzie ? :-) |
cli/README.md
Outdated
| # (Example for Debian / Ubuntu) | ||
| chown -R :www-data . && chmod -R g+r . && chmod -R g+w ./data/ | ||
| ``` | ||
| If you want to administrate FreshRSS using git, please read our [Installation docs](https://freshrss.github.io/FreshRSS/en/admins/02_Installation.html) |
|
@Alkarex Added one final comment. |
|
Alright then, restructuring done |
|
Is there a manual process that needs to be triggered before the new documentation is available at https://freshrss.github.io/FreshRSS/en/ ? |
|
I think it happens automatically as soon as it is merged in /master. I think we should release 1.8.1 soon, as I am a bit delayed for the main features of 1.9 (refactor upgrade mechanism). |
|
True, totally makes sense. Sorry, actually a stupid question... Depends on your versioning strategy. There were new features as well, so 1.9 could be used as well. |
See FreshRSS#1697 (comment) * lowercase dir as pointed out by @kevinpapst in FreshRSS#1704 (comment) * Add French translation with improvements suggested by @aledeg
FreshRSS#907 CURLOPT_FOLLOWLOCATION open_basedir bug (FreshRSS#1657) CURLOPT_FOLLOWLOCATION cannot be activated when an open_basedir is set FreshRSS#1655 (comment) https://stackoverflow.com/questions/6918623/curlopt-followlocation-cannot-be-activated Manual merge dev Add an entry in the subscription tool page I reworked @Alkarex idea proposed in FreshRSS#1292. I though it was a good idea to merge everything in the same location. Improve translation tools I was not happy with the previous version. I refactored everything to make it reusable. It allows me do do more verifications and to build a tool to handle the files themselves. Merge pull request FreshRSS#1660 from aledeg/api-subscription-tool Add an entry in the subscription tool page Merge pull request FreshRSS#1658 from aledeg/improve-i18n-tools Improve translation tools Changelog 1247 FreshRSS#1660 FreshRSS#1292 FreshRSS#1247 Merge branch 'FreshRSS/dev' into github-update [i18] nl/sub: add a few translations Merge pull request FreshRSS#1661 from FreshRSS/Frenzie-patch-1 [i18] nl/sub: add a few translations Reworded changelog 1247 FreshRSS#1660 FreshRSS#1292 FreshRSS#1247 Merge branch 'dev' of https://github.com/FreshRSS/FreshRSS into FreshRSS/dev CLI optimize database (FreshRSS#1663) CLI optimize database FreshRSS#1583 And VACUUM in SQLite FreshRSS#918 Add VACUUM for PostgreSQL (Not tested yet) A bit of Apache documentation (FreshRSS#1670) FreshRSS#1666 FreshRSS#1669 FreshRSS#908 Merge branch 'FreshRSS/dev' into github-update Delete unneeded update files Move update scripts Merge branch 'staging-branch' into github-update Fix Travis syntax Fix typo in nl i18n (FreshRSS#1675) improve zh-cn i18n (FreshRSS#1678) Move translation tools into the cli folder (FreshRSS#1673) Translation tools must be used on cli. It is better to have them in the cli folder. Add a Mastodon share (FreshRSS#1674) See FreshRSS#1521 Minor language Small fix Mastodon share $a['method'] can be undefined. FreshRSS#1674 FreshRSS#1521 Changelog Mastodon Merge pull request FreshRSS#1682 from Alkarex/fix_mastodon_share Small fix Mastodon share Merge branch 'FreshRSS/dev' into github-update More update Split post-update in disctinct file Post-update will thus contain code from the new version Better case for git Fix link encoding in API (FreshRSS#1686) FreshRSS#1683 Alkarex/EasyRSS#35 A bit of documentation for the API (FreshRSS#1689) FreshRSS#1687 FreshRSS#443 (comment) Merge branch 'FreshRSS/dev' into github-update [docs] Configuration: some stylistic improvements (FreshRSS#1693) The main purpose is to fix the `imapcted` typo that was exposed by FreshRSS#1259 (comment) [FIX] FreshRSS#1690 - Also check pdo_pgsql extension in check_install() [ADD] 'blankoworld' as contributor in CREDITS Changelog 1690 FreshRSS#1690 FreshRSS#1691 FreshRSS#1692 I18n - DE (FreshRSS#1698) * added missing german translations Call idn_to_ascii with INTL_IDNA_VARIANT_UTS46 Under PHP 7.2, calling `idn_to_ascii($idn)` results in a deprecation warning: 'INTL_IDNA_VARIANT_2003 is deprecated' See https://secure.php.net/manual/en/function.idn-to-ascii.php Therefore, if possible, `idn_to_ascii($idn, 0, INTL_IDNA_VARIANT_UTS46)` should be used instead. `INTL_IDNA_VARIANT_UTS46` was introduced in PHP 5.4, so on versions before that, `idn_to_ascii($idn)` must still be used. Fixed FreshRSS#1699 A bit more for git updates Documentation updates (FreshRSS#1697) * added documentation about updating FreshRSS moved Installation to admin directory linked some already existing documentation files Update panel shows latest version message as success (FreshRSS#1701) show latest version message as success, FIXES FreshRSS#1586 Merge branch 'FreshRSS/master' into FreshRSS/dev Remove forgotten punycode line Credits Craig Andrews Merge pull request FreshRSS#1700 from candrews/patch-1 Call idn_to_ascii with INTL_IDNA_VARIANT_UTS46 Changelog 1586 1698 1699 FreshRSS#1586 FreshRSS#1701 FreshRSS#1698 FreshRSS#1699 FreshRSS#1700 Merge branch 'dev' of https://github.com/FreshRSS/FreshRSS into FreshRSS/dev Merge branch 'FreshRSS/dev' into github-update Add more glyphs for opensans font (FreshRSS#1032) * Add more glyphs for opensans font * Update .htaccess to support woff2 file format * Fixed browser support for new font face * Fixed Origine theme css and .htaccess * Deleted unneeded fonts * Added stylefiles for OpenSans font * Fixed all themes with new font css * Avoid additional CSS file * htaccess cache control public * Font casing bug * Remove TTF font Too big, low need https://caniuse.com/#search=woff * Changelog 1032 FreshRSS#1032 FreshRSS#1028 Extension function to override entry hash (FreshRSS#1707) Extension function to override entry hash FreshRSS#1706 Merge branch 'FreshRSS/dev' into github-update Show existing extensions in admin panel (FreshRSS#1708) * first draft * display installed extension state * fixed whitespace vs tabs * added translation in all languages * added error checks and log messages * fixed tabs vs whitespace * another try in fixing whitespaces * another try in fixing whitespaces * improved extension list translations * using JSON from official extension repo * improved version compare * updated translations * French translation make sure that we do not exceed a certain file size for the users log file renamed method incorporated code review feedback added new extension hook using hook for reading modes in navigation refactored ReadingModes to Model Log rotation, use Minz_Log, new log constants ADMIN_LOG, API_LOG, PSHB_LOG Check requirement in CLI script (FreshRSS#1711) * check requirements in actualize_script before executing, fixes FreshRSS#1710 * removed empty whiteline * testing all requirements * incorporated code review feedback * removed code that is already executed in _cli.php * added newline at eof * fixed include problems * fixed include problems Merge branch 'dev' into logfilesize Merge branch 'dev' into logfilesize Changelog 1708 1711 FreshRSS#1708 FreshRSS#1711 Merge pull request FreshRSS#1712 from kevinpapst/logfilesize Prevent logfile from growing unlimited Changelog 1712 FreshRSS#1712 FreshRSS#1562 Use __DIR__ for relative include and require For uniformity, and to avoid having PHP searching in include_path. http://php.net/manual/function.include.php FreshRSS#1715 FreshRSS#1711 (comment) Merge pull request FreshRSS#1717 from Alkarex/dir_in_require Use __DIR__ for relative include and require fixed bug in catch block added types to docblocks Merge pull request FreshRSS#1724 from kevinpapst/exception-bug ExtensionManager fixes [doc] Extensions: translate various sections from French See FreshRSS#1697 (comment) * lowercase dir as pointed out by @kevinpapst in FreshRSS#1704 (comment) * Add French translation with improvements suggested by @aledeg Merge branch 'dev' into hebrew-i18n Fix whitespace Add message after log rotation FreshRSS#1712 FreshRSS#1562 Minz Dispatcher Controllers path FreshRSS#1704 Customisable constants.local.php (FreshRSS#1725) FreshRSS#1562 FreshRSS#1607 FreshRSS#1656 FreshRSS#1705 FreshRSS#1712 Merge pull request FreshRSS#1726 from Alkarex/message_log_rotation Add message after log rotation i18n hebrew more 18n Hebrew more 2 Changelog 1716 1724 1725 https://github.com/FreshRSS/FreshRSS/pull/1716 FreshRSS#1724 FreshRSS#1725 Merge branch 'FreshRSS/dev' into Minz_Dispatcher_paths Changelog 1729 Merge pull request #1716 from FreshRSS/hebrew-i18n Add hebrew translation Changelog 1716 https://github.com/FreshRSS/FreshRSS/pull/1716 Merge pull request FreshRSS#1729 from Alkarex/Minz_Dispatcher_paths Minz Dispatcher Controllers path added .editorconfig with basic settings Minz Controllers directory uppercase FreshRSS#1729 Merge pull request FreshRSS#1704 from Frenzie/doc-translate-extensions [doc] Extensions: translate various sections from French Merge pull request FreshRSS#1732 from kevinpapst/editorconfig Added .editorconfig Changelog 1697, 1704, 1732 FreshRSS#1697 FreshRSS#1704 FreshRSS#1732 Merge branch 'dev' of https://github.com/FreshRSS/FreshRSS into FreshRSS/dev fixed bug when adding a category and feed at the same time (FreshRSS#1731) fixed bug when adding a category and feed at the same time Changelog 1731 FreshRSS#1731 Fix favicon for open_basedir (FreshRSS#1733) Remove open_basedir warning for CURLOPT_FOLLOWLOCATION with PHP 5.6.0- https://bugs.php.net/bug.php?id=65646 Remove warning for CURLOPT_FOLLOWLOCATION with open_basedir (FreshRSS#1734) For PHP 5.6.0- http://www.php.net/ChangeLog-5.php#5.6.0 https://bugs.php.net/bug.php?id=65646 FreshRSS#1733 FreshRSS#1657 FreshRSS#1655 Prepare release of FreshRSS 1.9.0 Merge pull request FreshRSS#1720 from FreshRSS/dev FreshRSS 1.9.0 Update FreshRSS version to 1.9.0 Merge branch 'FreshRSS/dev' into FreshRSS/master [docs] Extensions: fix typo (FreshRSS#1735) Merge branch 'FreshRSS/dev' into FreshRSS/master New development version 1.9.1-dev PHP 7.2: Fix a warning when retrieving the list of entries (FreshRSS#1739) When retrieving the list of entries when the context was 'all' or 'starred', there was the following warning: > Warning: count(): Parameter must be an array or an object that implements Countable in /home/alexis/FreshRSS/app/Controllers/indexController.php on line 206 I fixed that by changing how the array is tested. Fixes link to the "update guidelines" (FreshRSS#1740) Fixes link to the "update guidelines" (FreshRSS#1740) Minor changes (FreshRSS#1747) Tiny additions to .editorconfig (FreshRSS#1744) Improving README in English and French (FreshRSS#1746) Merge branch 'FreshRSS/master' into FreshRSS/dev Adding new items to force-https.default.txt (FreshRSS#1745) credits RyDroid FreshRSS#1747 FreshRSS#1746 FreshRSS#1745 FreshRSS#1744 [doc] Editing for better style (FreshRSS#1736) * Also removed references to Persona authentication. * Changed code comment about Persona because it's for HTTP auth in general. See FreshRSS@3d87609 and FreshRSS#358 (comment) [i18n] Add translation ignore/nl (FreshRSS#1752) Add shortcuts to switch views (FreshRSS#1755) Add mute strategy configuration (FreshRSS#1750) Minor syntax Merge pull request FreshRSS#1714 from kevinpapst/hook-readingmodes Added extension hook for reading modes Changelog 1739, 1745, 1750, 1755 FreshRSS#1739 FreshRSS#1745 FreshRSS#1750 FreshRSS#1755 Fix login bug when HTTP REMOTE_USER changes YunoHost-Apps/freshrss_ynh#33 Merge pull request FreshRSS#1756 from Alkarex/YunoHost_HTTP_Auth Fix login bug when HTTP REMOTE_USER changes Changelog 1756 FreshRSS#1756 YunoHost-Apps/freshrss_ynh#33 Merge branch 'dev' of https://github.com/FreshRSS/FreshRSS into FreshRSS/dev Fix shortcuts triggering view switching Merge pull request FreshRSS#1758 from aledeg/fix-nav-buttons Fix shortcuts triggering view switching Merge branch 'dev' into github-update Merge branch 'dev' into github-update

Documentation updates:
Fixes #861
Closes #1696
Work in progress, feedback is highly welcome!