Documentation Unclear About What a Preview Is

[july8six]

A few parts of the documentation do not explain what a preview is and what certain settings do in regards to a preview. The section of the documents are copied from the OwnCloud documents but the functionality is different on NextCloud. This will confuse admins coming from Owncloud to nextcloud as well as users new users coming from services like Google Drive, Dropbox, and OneDrive.

First issue: the word 'preview' is used interchangeably with the word 'thumbnail'. When people think of preview, they think of actually viewing what the file contains instead of seeing an actual thumbnail of the file. This is how it works in all other cloud storage platforms. NextCloud should not redefine this term because it makes it difficult for new users to understand the platform. Here are places in the documentation where the term is redefined:

Config.php Parameters

For preview generation (optional):

PHP module imagick avconv or ffmpeg OpenOffice or LibreOffice

Installation on Linux

Second Issue: The following text indicates there is a difference between a preview and a thumbnail when they are the same thing. The text needs to use the word preview correctly and thumbnail correctly.

Nextcloud supports previews of image files, the covers of MP3 files, and text files. These options control enabling and disabling previews, and thumbnail size.

Please see the dictionary definitions below:

Preview - a facility for inspecting the appearance of a document before it is printed.

Thumbnail - a small picture of an image or page layout.

From the definitions, the average user does not think preview = thumbnail.

Third Issue: Indicate what files can actually be 'previewed' (viewed in full format) when clicked on in nextcloud rather than having a thumbnail preview. Such files that need to be indicated in the admin docs include:

• mp4

• txt

• png

• jpg

• jpeg

• PDF (requires PDF Viewer an app that is preinstalled)

In the user guide, it indicates preview means viewing a file type. A user cannot view OpenDocument files so this needs to be updated.

Previewing files¶ You can display uncompressed text files, OpenDocument files, videos, and image files in the Nextcloud embedded viewers by clicking on the file name. There may be other file types you can preview if your Nextcloud administrator has enabled them. If Nextcloud cannot display a file, it starts a download process and downloads the file to your computer.

Previewing Files

Fourth Issue: The docs should be fixed so that the admin understands they are generating a thumbnail based on the pixel size of the original image, not they are changing the default 50 x 50 px size of the thumbnail.

'preview_max_x' => 4096, The maximum width, in pixels, of a preview. A value of null means there is no limit.

Defaults to 4096

'preview_max_y' => 4096, The maximum height, in pixels, of a preview. A value of null means there is no limit.

Defaults to 4096

The maximum width, in pixels, of a preview. This should read, "The maximum width in pixels used to generate a thumbnail preview."

The maximum height, in pixels, of a preview. This should read, "The maximum height in pixels used to generate a thumbnail preview."

Fifth Issue: Should indicate that generating thumbnails for certain document types require additional programs to be installed. Examples:

OC\Preview\SVG - requires ImageMagick OC\Preview\OpenDocument - requires LibreOffice/OpenOffice

Sixth Issue: Enabling a preview (thumbnail) is not secure for certain file types. What process is nextcloud using to make the preview (thumbnail) generation unseurce? This is not explained to the administrator.

This paragraph should be added to this section as a warning:

Nextcloud is able to generate preview images of common filetypes such as images or text files. By default the preview generation for some file types that we consider secure enough for deployment is enabled by default. However, administrators should be aware that these previews are generated using PHP libraries written in C which might be vulnerable to attack vectors.

The following providers are disabled by default due to performance or privacy concerns:

OC\Preview\Illustrator OC\Preview\Movie OC\Preview\MSOffice2003 OC\Preview\MSOffice2007 OC\Preview\MSOfficeDoc OC\Preview\OpenDocument OC\Preview\PDF OC\Preview\Photoshop OC\Preview\Postscript OC\Preview\StarOffice OC\Preview\SVG OC\Preview\TIFF OC\Preview\Font

Seventh Issue: In the installation instructions, it should be clear the end user is only going to see a thumbnail preview of a file if OpenOffice/LibreOffice and avconv/FFmpeg are installed. That way the end user can determine if they want to install resource heavy programs or go through the hassle of installing these programs for a simple thumbnail preview of a document instead of the default icon. Give admins the information they need to make informed decisions. Also, Imagick should be removed from the list and put with the other recommended PHP modules because it does more.

For preview generation (optional):

PHP module imagick avconv or ffmpeg OpenOffice or LibreOffice

Eight Issue: I was able to see the preview(thumbnail) of an odt document without entering the path to LibreOffice. After I entered the path there was not change. I am using CentOS7. It should be indicated in the documentation that no path to LibreOffice is needed on certain operating systems to see the preview(thumbnail) of the document. The documentation should also better explain the purpose of the path. It should basically indicate that nextcloud by default automatically looks for the openoffice/libre office path and if it can't find it, a custom path may need to be entered.

'preview_libreoffice_path' => '/usr/bin/libreoffice', custom path for LibreOffice/OpenOffice binary

Defaults to '' (empty string)

'preview_office_cl_parameters' =>
        ' --headless --nologo --nofirststartwizard --invisible --norestore '.
        '--convert-to pdf --outdir ',

Use this if LibreOffice/OpenOffice requires additional arguments.

Defaults to '' (empty string)

[MorrisJobke]

cc @rullzer

[july8six]

Another section that needs to be updated:

Ninth Issue: This should indicate the administrator is disabling thumbnail preview and an icon will replace the thumbnail of an image. The word thumbnail should be used instead of preview to indicate this is a thumbnail, not an actual preview of the file. This needs to be clear so an admin knows they are not reducing a large amount of functionality for users.

Disable preview image generation Nextcloud is able to generate preview images of common filetypes such as images or text files. By default the preview generation for some file types that we consider secure enough for deployment is enabled by default. However, administrators should be aware that these previews are generated using PHP libraries written in C which might be vulnerable to attack vectors.

For high security deployments we recommend disabling the preview generation by setting the enable_previews switch to false in config.php. As an administrator you are also able to manage which preview providers are enabled by modifying the enabledPreviewProviders option switch.

Disbale Preview Image Generation Tenth Issue: It seems as though this feature has been deprecated in owncloud. This si a suggestion that it could be deprecated in nextcloud.

By default, ownCloud can generate previews for the following filetypes:

Images files Cover of MP3 files Text documents

Older versions of ownCloud also supported the preview generation of other file types such as PDF, SVG or various office documents. Due to security concerns those providers have been disabled by default and are considered unsupported. While those providers are still available, we discourage enabling them, and they are not documented.

ownCloud preview Configuration

The following settings should be listed as unsupported are moved somewhere to indicate advanced configuration:

The following providers are disabled by default due to performance or privacy concerns:

OC\Preview\Illustrator OC\Preview\Movie OC\Preview\MSOffice2003 OC\Preview\MSOffice2007 OC\Preview\MSOfficeDoc OC\Preview\OpenDocument OC\Preview\PDF OC\Preview\Photoshop OC\Preview\Postscript OC\Preview\StarOffice OC\Preview\SVG OC\Preview\TIFF OC\Preview\Font

• 'enabledPreviewProviders' => array
• 'preview_libreoffice_path'
• 'preview_office_cl_parameters'

The following programs should be removed from the optional installation:

• avconv or ffmpeg
• OpenOffice or LibreOffice

[rullzer]

Actually previews and thumbnails are closely related in this context. And they do (as far as I know still reflect what they did at ownCloud as well).

For images, the preview is just a scaled down version. A thumbnail is the same only it is also square and even smaller.

What our server side preview system does is take files and generate images from them which are easy and quick to view.

Having said all that yes our docs could use some love probably. But my todo is already very full so it won't be soon. But PR's are welcome.

[c0fe]

@rullzer mind if I bite into this?

[MorrisJobke]

@rullzer mind if I bite into this?

Sure :) Go ahead and we can iterate on it then. 👍

[rullzer]

@c0fe yes please!

[c0fe]

@rullzer @MorrisJobke ok I will start work on it, hopefully my most recent pull request can be accepted.

I will scour the open tickets for any other issues that I can stomp out as well.

[c0fe]

I made changes to the documentation in my PR, but I feel that this issue ticket would work better if it was split into multiple ones. @rullzer what do you think?