Merge pull request #133 from SteffenHeu/faq

add new troubleshooting sections

docs/coding/macos_signing.md

@@ -1,19 +1,43 @@
 # macOS code signing
 
-Code signing is a security feature provided by Apple's macOS that allows developers to digitally sign their applications and verify their identity. This ensures that the application is not tampered with or altered by a third party, and that it can be trusted by users.
-
-MZmine 3 codebase is signed with the Developer ID Application Certificate of the Czech Technical University in Prague (`"Developer ID Application: Ceske vysoke uceni technicke v Praze (LK4H72N842)"`) under the Apple ID `mzmine.devel@gmail.com`. The procedure is implemented in the [gradle build file](https://github.com/mzmine/mzmine3/blob/master/build.gradle) and consists of three main steps described below: signing, notarization, and stapling.
+Code signing is a security feature provided by Apple's macOS that allows developers to digitally
+sign their applications and verify their identity. This ensures that the application is not tampered
+with or altered by a third party, and that it can be trusted by users.
+
+MZmine 3 codebase is signed with the Developer ID Application Certificate of the Czech Technical
+University in
+Prague (`"Developer ID Application: Ceske vysoke uceni technicke v Praze (LK4H72N842)"`) under the
+Apple ID `mzmine.devel@gmail.com`. The procedure is implemented in
+the [gradle build file](https://github.com/mzmine/mzmine3/blob/master/mzmine-community/build.gradle)
+and consists of
+three main steps described below: signing, notarization, and stapling.
 
 ## Signing
 
-Signing is a step embedding a digital signature in the MZmine codebase, which allows macOS to verify the integrity of the application before it is run.
+Signing is a step embedding a digital signature in the MZmine codebase, which allows macOS to verify
+the integrity of the application before it is run.
 
-The necessary condition for the code signing is a Developer ID Application certificate from a Certificate Authority, which is the Czech Technical University in Prague in our case. `base64`-encoded certificated and the associated password are stored as GitHub secrets under the names `MACOS_DEVELOPER_CERTIFICATE` and `MACOS_DEVELOPER_CERTIFICATE_PWD` respectively. In order to use the certificate in [CI/CD build of MZmine](https://github.com/mzmine/mzmine3/blob/e35aceb5a0737a184038b4749b7e29646172954d/.github/workflows/dev_build_release.yml#L96), we add it to macOS keychain with `security set-key-partition-list` command following [Jan Bílek's tutorial](https://localazy.com/blog/how-to-automatically-sign-macos-apps-using-github-actions).
+The necessary condition for the code signing is a Developer ID Application certificate from a
+Certificate Authority, which is the Czech Technical University in Prague in our case. `base64`
+-encoded certificated and the associated password are stored as GitHub secrets under the
+names `MACOS_DEVELOPER_CERTIFICATE` and `MACOS_DEVELOPER_CERTIFICATE_PWD` respectively. In order to
+use the certificate
+in [CI/CD build of MZmine](https://github.com/mzmine/mzmine3/blob/master/.github/workflows/dev_build_release.yml),
+we add it to macOS keychain with `security set-key-partition-list` command
+following [Jan Bílek's tutorial](https://localazy.com/blog/how-to-automatically-sign-macos-apps-using-github-actions).
 
 !!! info
-    Notice, that the Developer ID Application certificate is not publicly available. Therefore, a manually built version of MZmine cannot be signed. Nevertheless, it still can be normally built.
+Notice, that the Developer ID Application certificate is not publicly available. Therefore, a
+manually built version of MZmine cannot be signed. Nevertheless, it still can be normally built.
+
+To sign MZmine code with the certificate, `jpackage` utility needs to be supplied with an
+additional (constant) argument `--mac-sign` and its dependencies such
+as `--mac-package-identifier "io.github.mzmine.main"`
+and `--mac-signing-key-user-name "Developer ID Application: Ceske vysoke uceni technicke v Praze (LK4H72N842)"`.
+Nevertheless, `jpackage` is not able to automatically sign all native libraries. For that reason, we
+manually traverse the entire codebase and sign all such libraries which can be classified into three
+categories:
 
-To sign MZmine code with the certificate, `jpackage` utility needs to be supplied with an additional (constant) argument `--mac-sign` and its dependencies such as `--mac-package-identifier "io.github.mzmine.main"` and `--mac-signing-key-user-name "Developer ID Application: Ceske vysoke uceni technicke v Praze (LK4H72N842)"`. Nevertheless, `jpackage` is not able to automatically sign all native libraries. For that reason, we manually traverse the entire codebase and sign all such libraries which can be classified into three categories:
 1. Any file with one of the following extensions: `.dylib`, `.so`, `.dll`, `.a`, `.lib`.
 2. Any file with an extension from point 1. but nested inside of `.jar` archives.
 3. Content of ThermoRawFileParser `.zip` archive.
@@ -23,23 +47,35 @@ The libraries are signed with
 ```shell
 codesign --deep --force --timestamp -s ${developerID} --options runtime --entitlements ${entitlementsPth} -f -v ${p}
 ```
-, where `${deveperID}` is `"Developer ID Application: Ceske vysoke uceni technicke v Praze (LK4H72N842)"`, `${entitlementsPth}` contains [privileges](https://github.com/mzmine/mzmine3/blob/master/gradle/macos.entitlements) granted to the MZmine executable, and `${p}` is a path to the file to be signed. The files nested in archives are unarchived, signed, and then archived back.
+
+, where `${deveperID}`
+is `"Developer ID Application: Ceske vysoke uceni technicke v Praze (LK4H72N842)"`, `${entitlementsPth}`
+contains [privileges](https://github.com/mzmine/mzmine3/blob/master/mzmine-community/gradle/macos.entitlements)
+granted to the MZmine executable, and `${p}` is a path to the file to be signed. The files nested in
+archives are unarchived, signed, and then archived back.
 
 ## Notarization
 
-Notarization is an additional security step that is performed by Apple after an application is signed and is required to distribute MZmine outside of the Mac App Store. During this step signed MZmine code is uploaded to Apple's servers, where it is scanned for malware and other malicious content. Note, that this procedure usually takes around 10 minutes to be completed.
+Notarization is an additional security step that is performed by Apple after an application is
+signed and is required to distribute MZmine outside of the Mac App Store. During this step signed
+MZmine code is uploaded to Apple's servers, where it is scanned for malware and other malicious
+content. Note, that this procedure usually takes around 10 minutes to be completed.
 
 The notarization is performed using `xcrun notarytool` utility
 
 ```shell
 xcrun notarytool submit --wait --apple-id ${appleID} --password ${appleIDPassword} --team-id ${appleTeamID} "MZmine_macOS_portable.zip"
 ```
 
-, where `${appleTeamID}` is `mzmine.devel@gmail.com` and `${appleTeamID}` is the team of the Developer ID - `LK4H72N842`.
+, where `${appleTeamID}` is `mzmine.devel@gmail.com` and `${appleTeamID}` is the team of the
+Developer ID - `LK4H72N842`.
 
 ## Stapling
 
-Stapling is the process of attaching a notarization ticket to a signed application. When an application is stapled, the notarization ticket is embedded in the application's code, which allows macOS to verify the notarization status of the application even if it is not connected to the internet.
+Stapling is the process of attaching a notarization ticket to a signed application. When an
+application is stapled, the notarization ticket is embedded in the application's code, which allows
+macOS to verify the notarization status of the application even if it is not connected to the
+internet.
 
 Stapling is performed with
 
@@ -48,4 +84,7 @@ xcrun stapler staple "MZmine.app"
 ```
 
 ## Distribution of disk image
-The output of the steps described above is signed portable MZmine `.app`. Since it is more convenient to distribute macOS software as a `.dmg` disk image, we additionally pack the portable into `.dmg` using [`appdmg`](https://github.com/LinusU/node-appdmg) utility.
+
+The output of the steps described above is signed portable MZmine `.app`. Since it is more
+convenient to distribute macOS software as a `.dmg` disk image, we additionally pack the portable
+into `.dmg` using [`appdmg`](https://github.com/LinusU/node-appdmg) utility.

docs/troubleshooting.md

@@ -1,21 +1,62 @@
 # Troubleshooting
 
-
 ## GUI freezes
-The graphical user interface freezes sometimes on remote desktops if the user logs out and logs in again. This is a known issue and might be fixed in future JavaFX versions. 
 
+The graphical user interface freezes sometimes on remote desktops if the user logs out and logs in
+again. This is a known issue and might be fixed in future JavaFX versions.
 
 ## MZmine does not start
-Maybe the MZmine configuration got corrupted (broke). Delete it and reinstall MZmine. The **.mzmine3.conf** file can be found in the user folder and might be hidden. On Windows, activate "Show hidden items" in the Explorer/View menu. 
 
+Maybe the MZmine configuration got corrupted (broke). Delete it and reinstall MZmine. The *
+*.mzmine3.conf** file can be found in the user folder and might be hidden. On Windows, activate "
+Show hidden items" in the Explorer/View menu.
+
+## mzML files not importing
+
+An illegal character might exist in the mzML file. When converting the raw data files to mzML, the
+path of the file is added to the resulting mzML file. The path may contain characters that are not
+parsed correctly by MZmine.
+
+Solution: Reconvert the file and place the input and output directory to a path with only Roman
+characters.
+
+## Thermo raw files not importing
+
+Error message usually contains "No scans found".
+
+Solution: Search for the "mzmine_thermo_raw_parser" folder in the mzmine temp folder and the system
+temp folder and delete it.
+
+## Scans not sorted in retention time dimension
+
+This issue often occurs with raw data from Waters instruments. We recommend re-converting the files
+using the [Waters data connect tool](data_conversion.md#waters).
+
+## Scans were recognised as empty
+
+This is displayed as a warning and means that some scans did not contain any data. This is not
+considered as an error. The warning **may** indicate that a threshold was too high, if conversion
+was applied. You may consider lowering said threshold. If no thresholding was applied, consider
+this a false positive.
+
+## Zero intensity values in scans
+
+0 intensities in scans.
+
+This error occurs when converting files using an old MSConvert version and the "Peak picking" filter
+being used after the "title maker". This caused the wrong peak picking algorithm to be used and not
+just adds zero values but also causes falsely recognised m/z values. We highly recommend to
+re-convert the files with the most recent MSConvert version.
 
 ## Reporting issues
-Report issues on the [MZmine GitHub](https://github.com/mzmine/mzmine3/issues), providing all information to reproduce the issue.
+
+Report issues on the [MZmine GitHub](https://github.com/mzmine/mzmine3/issues), providing all
+information to reproduce the issue.
 
 **This might include**
 
 - **Input data**? provide example file
 - ** Batch file** defining processing steps and settings
-- attach the log file located in the user folder: **mzmine_0_0.log** 
+- attach the log file located in the user folder: **mzmine_0_0.log**
 - **Expected behavior**
-- **Issue** 
+- **Issue**