revise docs

closes #53

Author: Gerit Wagner

CHANGELOG.md

@@ -1,5 +1,5 @@
 
-# Change Log
+# Changelog
 All notable changes to this project will be documented in this file.
 
 ## Unreleased

README.md

@@ -75,8 +75,8 @@ The translated query can be saved as follows:
 from search_query import SearchFile
 
 search_file = SearchFile(
-    filename="search-file.json",
-    query_str=wos_query.to_string(platform="wos"),
+    filepath="search-file.json",
+    search_string=wos_query.to_string(),
     platform="wos",
     version="1",
     authors=[{"name": "Tom Brady"}],

docs/source/dev_docs/linter_development.rst

@@ -6,7 +6,7 @@ They analyze token sequences, syntax, search fields, and operator use to identif
 errors or ambiguities and print meaningful messages (documented in the `messages <../messages/errors_index.html>`_ section).
 Each platform implements its own linter, which interhits from the base class `linter_base.py`. Linters are used in the parser methods.
 
-Base Classes
+Base classes
 ------------
 Use the appropriate base class when developing a new linter:
 
@@ -16,7 +16,7 @@ Use the appropriate base class when developing a new linter:
 Each linter must override the `validate_tokens()` method and the `validate_query_tree()`.
 `validate_tokens()` is called when the query is parsed, and `validate_query_tree()` is called when the query tree is built (i.e., at the end of the parsing process **and** when the query is constructed programmatically).
 
-Best Practices
+Best practices
 --------------
 - **Use standardized linter messages** defined in `constants.QueryErrorCode`.
 - **Add details** in messages for guidance (e.g., invalid format, missing logic).

docs/source/dev_docs/parser_development.rst

@@ -18,7 +18,7 @@ When introducing a new parser version, copy the previous versioned
 directory, adjust the implementation, and register the version in the
 ``PARSERS`` dictionary.
 
-1. Inherit from Base Classes
+1. Inherit from base classes
 -----------------------------------
 
 Use the provided base classes, which provide a number of utility methods:
@@ -107,8 +107,8 @@ Check whether ``SearchFields`` can be created for nested queries (e.g., ``TI=(eH
    :language: python
 
 
-List Format Support
------------------------------------
+List format support
+----------------------------------
 
 Implement  ``QueryListParser`` to handle numbered sub-queries and references like ``#1 AND #2``.
 

docs/source/dev_docs/tests.rst

@@ -10,7 +10,7 @@ To run all tests:
 
     pytest test
 
-Test Types
+Test types
 ----------
 
 1. **Tokenization Tests**

docs/source/dev_docs/translator_development.rst

@@ -8,8 +8,8 @@ Translators convert between:
 
 Each translator implements `QueryTranslator`, the abstract base class from ``translator_base.py``.
 
-Translator Responsibilities
----------------------------
+Translator responsibilities
+--------------------------
 
 A translator must implement the following two class methods:
 
@@ -35,8 +35,8 @@ specified platform.
 To introduce a new translator version, duplicate the previous versioned directory,
 update the implementation as needed, and register the new version in the ``TRANSLATORS`` dictionary.
 
-Utility Methods Provided
-------------------------
+Utility methods provided
+-----------------------
 
 The base class (`QueryTranslator`) provides the following utilities:
 
@@ -47,8 +47,8 @@ The base class (`QueryTranslator`) provides the following utilities:
 - ``move_fields_to_operator(query)``:
   If all children have the same field, moves it to the parent node.
 
-Search Field Mapping
---------------------
+Search field mapping
+-------------------
 
 Field mapping is expected to be defined in a `constants_<source>.py` file and typically includes:
 
@@ -61,15 +61,15 @@ Each translator should:
 2. Handle combined fields (e.g., `[tiab]` in PubMed)
 3. Optionally restructure the query for consistency
 
-Code Skeleton
--------------
+Code skeleton
+------------
 
 .. literalinclude:: translator_skeleton.py
    :language: python
 
 
-Advanced Features
------------------
+Advanced features
+----------------
 
 Some translators include advanced restructuring logic:
 

docs/source/index.rst

@@ -94,8 +94,8 @@ The translated query can be saved as follows:
    from search_query import SearchFile
 
    search_file = SearchFile(
-      filename="search-file.json",
-      query_str=wos_query.to_string(platform="wos"),
+      filepath="search-file.json",
+      search_string=wos_query.to_string(),
       platform="wos",
       version="1",
       authors=[{"name": "Tom Brady"}],
@@ -113,8 +113,8 @@ A Jupyter Notebook demo (hosted on Binder) is available here:
 .. image:: https://mybinder.org/badge_logo.svg
    :target: https://mybinder.org/v2/gh/CoLRev-Environment/search-query/HEAD?labpath=docs%2Fsource%2Fdemo.ipynb
 
-Functional Overview
-=======================
+Functional overview
+======================
 
 The search-query package supports the entire lifecycle of academic search query management.
 Below is a high-level overview of the core functionalities:

docs/source/lint/errors_index.rst

@@ -98,7 +98,7 @@ Database errors: Web of Science
 
    WOS_0012
 
-Database errors: EBSCOHost
+Database errors: EBSCOhost
 --------------------------
 
 .. toctree::

docs/source/load.rst

@@ -5,7 +5,7 @@ Load
 
 Queries can be loaded from strings/files, defined as objects, or retrieved from the internal database.
 
-String/File
+String/file
 -------------------------
 
 Search-query can parse queries from strings and JSON query files.
@@ -59,30 +59,13 @@ Queries can be loaded from the internal database directly:
    from search_query.database_queries import AIS_8
 
    print(AIS_8.to_string())
-   # Output:
-   # (SO=("European Journal of Information Systems" OR
-   #      "Information Systems Journal" OR
-   #      "Information Systems Research" OR
-   #      "Journal of the Association for Information Systems" OR
-   #      "Journal of Information Technology" OR
-   #      "Journal of Management Information Systems" OR
-   #      "Journal of Strategic Information Systems" OR
-   #      "MIS Quarterly") OR
-   # IS=(0960-085X OR
-   #     1476-9344 OR
-   #     1350-1917 OR
-   #     1365-2575 OR
-   #     1047-7047 OR
-   #     1526-5536 OR
-   #     1536-9323 OR
-   #     0268-3962 OR
-   #     1466-4437 OR
-   #     0742-1222 OR
-   #     1557-928X OR
-   #     0963-8687 OR
-   #     1873-1198 OR
-   #     0276-7783 OR
-   #     2162-9730))
+   # SO=("European Journal of Information Systems" OR "Information Systems Journal"
+   # OR "Information Systems Research" OR "Journal of the Association for Information Systems"
+   # OR "Journal of Information Technology" OR "Journal of Management Information Systems"
+   # OR "Journal of Strategic Information Systems" OR "MIS Quarterly")
+   # OR IS=(0960-085X OR 1476-9344 OR 1350-1917 OR 1365-2575 OR 1047-7047 OR 1526-5536
+   # OR 1536-9323 OR 0268-3962 OR 1466-4437 OR 0742-1222 OR 1557-928X OR 0963-8687 
+   # OR 1873-1198 OR 0276-7783 OR 2162-9730)
 
 
 It is also possible to load queries from the database using the `database` module:

docs/source/platforms/ebsco.rst

@@ -1,36 +1,36 @@
 .. _ebsco:
 
-EBSCOHost
+EBSCOhost
 =========
 
-EBSCOHost provides access to a wide range of academic databases across disciplines, including business, education, psychology, and health sciences.
+EBSCOhost provides access to a wide range of academic databases across disciplines, including business, education, psychology, and health sciences.
 
-Run a Query
+Run a query
 -----------
 
-EBSCOHost queries can be constructed using the standard `EBSCOHost advanced search interface <https://search.ebscohost.com/>`_ (requires institutional access).
+EBSCOhost queries can be constructed using the standard `EBSCOhost advanced search interface <https://search.ebscohost.com/>`_ (requires institutional access).
 
 When working with `search-query`, extract the **Search terms** from the **Search History** panel or persistent URL for use as the `search_string`.
 
-EBSCOHost query syntax includes field tags such as `AB`, `TI`, `SU`, etc. These should be included directly in the `search_string`.
+EBSCOhost query syntax includes field tags such as `AB`, `TI`, `SU`, etc. These should be included directly in the `search_string`.
 
-Store a Query
+Store a query
 -------------
 
-When storing an EBSCOHost query in a `.json` file or as a string:
+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`.
 
 .. tip::
 
    To ensure reproducibility, report the EBSCO database used (e.g., Business Source Complete) in the `database` field.
 
-   Avoid setting a `general_field` (available in `Advanced Search`) unless the entire query targets the same field (e.g., all terms limited to `AB` for Abstract). Mixed fields should keep `general_field` empty.
+   Avoid setting a general `field` (available in `Advanced Search`) unless the entire query targets the same field (e.g., all terms limited to `AB` for Abstract). Mixed fields should keep general `field` empty.
 
    Do not use the **persistent link feature**.
 
-List Query Format
---------------------
+List query format
+-----------------
 
 EBSCOhost supports building **multi-line queries** where individual components are defined as numbered search lines and later combined using references like ``S1 AND S2``. This method is often used in advanced or expert search modes.
 
@@ -40,13 +40,13 @@ List queries should be formatted as follows:
 
    {
        "search_string": "1. TI (digital health OR telemedicine)\n2. AB (physical activity OR exercise)\n3. S1 AND S2",
-       "general_field": ""
+       "field": ""
    }
 
 Each numbered item defines a part of the query using EBSCOhost's field syntax. Later lines can combine them using boolean operators like ``AND``, ``OR``, or ``NOT``, allowing for structured, transparent query design.
 
 
-Best Practices and Recommendations
+Best practices and recommendations
 ----------------------------------
 
 - **Use field tags** (e.g., `AB`, `TI`) explicitly in the query string.