add documentation for platforms

Author: Gerit Wagner

docs/source/platforms/ebsco.rst

@@ -1,7 +1,46 @@
 .. _ebsco:
 
 EBSCOHost
-====================
+=========
 
+EBSCOHost provides access to a wide range of academic databases across disciplines, including business, education, psychology, and health sciences.
 
-TODO : interface, fields, ...
+Run a Query
+-----------
+
+EBSCOHost queries can be constructed using:
+
+- the standard `EBSCOHost advanced search interface <https://search.ebscohost.com/>`_ (requires institutional access), or
+- the **persistent link feature**, which captures the full query string for reproducibility.
+
+When working with `search-query`, we recommend extracting the **Search terms** from the **Search History** panel or persistent URL for use as the `search_string`.
+
+.. note::
+
+   EBSCOHost query syntax includes field tags such as `AB`, `TI`, `SU`, etc. These should be included directly in the `search_string`.
+
+   Avoid setting a `general_search_field` unless the entire query targets the same field (e.g., all terms limited to `AB` for Abstract). Mixed fields should keep `general_search_field` empty.
+
+Store a Query
+-------------
+
+When storing an EBSCOHost query in a `.json` file or as a string:
+
+- Use the **Search History** or the **Search Terms** as the `search_string`.
+- Leave the `general_search_field` empty **unless** the same field is used consistently across all terms.
+
+.. tip::
+
+   To ensure reproducibility, consider including the EBSCO database used (e.g., Business Source Complete) in the `database` field.
+
+Best Practices and Recommendations
+----------------------------------
+
+- **Use field tags** (e.g., `AB`, `TI`) explicitly in the query string.
+- **Group nexted queries** using parentheses to preserve logic.
+
+Resources
+---------
+
+- `EBSCO Search Help <https://connect.ebsco.com/s/article/Searching-EBSCO-Databases?language=en_US>`_
+- `EBSCO Search Fields Guide <https://connect.ebsco.com/s/article/Field-Codes-Searchable-EBSCOhost?language=en_US>`_

docs/source/platforms/pubmed.rst

@@ -1,33 +1,46 @@
+
 .. _pubmed:
 
 PubMed
-====================
+======
+
+PubMed is a free resource supporting the search and retrieval of biomedical and life sciences literature.
+
+Run a Query
+-----------
+
+Queries can be entered using either:
+
+- the `basic search box <https://pubmed.ncbi.nlm.nih.gov/>`_, or
+- the `advanced Query builder <https://pubmed.ncbi.nlm.nih.gov/advanced/>`_.
+
+These interfaces are functionally equivalent for the purposes of `search-query`. We recommend users always **copy and store the full query string** from either interface.
 
-Run a query
---------------
+.. note::
 
-Queries can be executed in the [basic search box](https://pubmed.ncbi.nlm.nih.gov/) or the advanced [Query box](https://pubmed.ncbi.nlm.nih.gov/advanced/).
+   For parsing PubMed queries, we recommend using the queries entered in the basic or advanced box as the *search_string* and leave the *general_search_field* empty.
 
-Report a query
------------------
+   When running the same query with different serach fields, as in this `example <https://www.cabidigitallibrary.org/doi/10.1079/SEARCHRXIV.2023.00236>`_, *search-query* will assume that the queries are added with an "OR" operator.
 
-It is recommended to store the queries entered in the basic or advanced box as the *search_string* and leave the *general_search_field* empty.
+Store a Query
+-------------
 
-TODO : interface illustration?
+When storing a PubMed query in a `.json` file or as a string:
 
-The advanced search page also offers the option to "Add terms to the query box" (by selecting specific fields in the drop-down).
-This box offers a convenient way to add queries and apply the same search field (from the drop-down menu) to the whole query.
-Here, it is important to
-- use search fields only in the *general_search_field*
-- when running the same query with different serach fields, as in this `example <https://www.cabidigitallibrary.org/doi/10.1079/SEARCHRXIV.2023.00236>`_, *search-query* will assume that the queries are added with an "OR" operator.
+- Use the content of the **Query box** or **Search details** section as the `search_string`.
+- Leave the `general_search_field` empty.
 
-TODO : interface illustration (highlight "OR"  button)
 
-TODO : add a linter warning (convention) when multiple general_search_fields are given? (operator unclear)
+Best Practices and Recommendations
+----------------------------------
 
+The advanced PubMed interface offers a dropdown for search fields such as `[Title/Abstract]`, `[Author]`, etc. When using this feature:
 
-Note: We assume that the [basic search box](https://pubmed.ncbi.nlm.nih.gov/) and the advanced [Query box](https://pubmed.ncbi.nlm.nih.gov/advanced/) handle queries equivalently.
+- If you apply the **same field** to the entire query, it is safe to store this value in the `general_search_field`.
+- If the query contains **multiple search fields**, `search-query` will treat each term individually, and **leaving `general_search_field` empty is preferred**.
 
-Resources:
+Resources
+---------
 
 - `PubMed User Guide <https://pubmed.ncbi.nlm.nih.gov/help/>`_
+- `Search Builder Help <https://pubmed.ncbi.nlm.nih.gov/advanced/>`_

docs/source/platforms/wos.rst

@@ -1,15 +1,50 @@
 .. _wos:
 
 Web of Science
-====================
+==============
 
+Web of Science (WoS) is a multidisciplinary citation database that supports structured search queries with field tags and Boolean operators.
 
-TODO : interface, fields, ...
+Run a Query
+-----------
 
+Queries in Web of Science can be constructed using:
 
-Note:
-Field tags on the following page are outdated (e.g., "DI" no longer works)
-https://images.webofknowledge.com/images/help/WOS/hs_wos_fieldtags.html
+- the `Basic search interface <https://www.webofscience.com/wos/woscc/basic-search>`_, or
+- the `Advanced search interface <https://www.webofscience.com/wos/woscc/advanced-search>`_, which allows for precise control using field tags (e.g., `TI=`, `TS=`, `AU=`).
 
+When working with `search-query`, we recommend copying the **Advanced search query string** directly for use as the `search_string`.
 
+.. note::
+
+   Web of Science supports structured queries using field tags such as `TS=` (Topic), `TI=` (Title), `AB=` (Abstract), `AU=` (Author), etc.
+
+   You should include these tags explicitly in the `search_string`. Leave the `general_search_field` empty unless the entire query is uniformly scoped to a single field.
+
+Store a Query
+-------------
+
+When storing a Web of Science query:
+
+- Use the **Advanced search query string** as the `search_string`.
+- Leave the `general_search_field` empty unless all terms share the same field tag.
+
+Example::
+
+   (TS="digital health") AND (TS="privacy")
+
+Best Practices and Recommendations
+----------------------------------
+
+- Prefer **Advanced Search** for reproducible and structured queries.
+- Use **explicit field tags** (`TS=`, `TI=`, `AB=`, etc.) instead of relying on default fields.
+
+
+Resources
+---------
+
+- `Field Tags Reference <https://webofscience.help.clarivate.com/Content/wos-core-collection/woscc-search-field-tags.htm>`_
 - `Web of Science Errors <https://images.webofknowledge.com/WOKRS528R6/help/TCT/ht_errors.html>`_
+
+.. note::
+    Field tags on `this page <https://images.webofknowledge.com/images/help/WOS/hs_wos_fieldtags.html>`_ are outdated (e.g., "DI" no longer works).