Offline Help/Documentation Portal

[Mikenux]

Reference Issue: #555

Goals

• Provide apps with the ability to open their offline help or documentation when they do not have their own help/documentation viewer.
• Use the desktop environment's help/documentation viewer to ensure consistency of the help/documentation experience.

Requirements

• App side. Apps have their documentation files located in an extension or in their own specific directory.
• System side. A system documentation/help app, fully sandboxed and supporting a wide range of file formats used for help and documentation.
• All supported file formats are to be defined.

"OpenDocumentation" Method

The app can make a request to the portal to open its documentation when focused with an open window and using the "OpenDocumentation" method.

This method has the following two mandatory options:

• location. ID of the documentation extension that the app recommended to install or path to the app root directory where all documentation files are located.
• target_file. Path to a documentation file to open, from the app or extension.

Portal Functioning

1. Validity of the "location" option value. If the value of the "location" option is the ID of an installed extension that the app recommended to install or the path of the root directory belonging to the requesting app, then the portal proceeds to step 2. However, if the extension ID does not exist (i.e., the extension is not installed), the root directory path does not belong to the requesting app or does not exist, or this option has no value, the portal returns an error stating that the documentation cannot be opened.
2. Validity of the "target_file" option value. If the target file exist in the extension or in the app root directory path, the portal sends the values ​​of the "location" and "target_file" options to the system documentation viewer. If the target file does not exist, the portal returns an error stating that the documentation cannot be opened.
3. If the system documentation app received the values, it uses them to open the requesting app's documentation with the specified file. When the documentation viewer is opened, it is automatically focused and the requesting app cannot make any request with the "OpenDocumentation" method until it is focused again.

Bookmarks

The system documentation app may have bookmarks that it stores by app ID to restore them when opening the corresponding documentation later.

Questions

• Is there anything wrong or missing?
• What file formats to support?
• Is it worth supporting the table of contents in the sidebar of a documentation viewer?
• Suggestions? Additions?