Merge pull request #38 from abap2UI5/claude/review-abap2ui5-docs-D3bWD

oblomov-dev · web-flow · commit 3732621aec82 · 2026-02-11T19:29:06.000+03:00
Unify English writing style across all documentation pages
diff --git a/docs/advanced/local.md b/docs/advanced/local.md
@@ -1,6 +1,6 @@
 # Local 
 
-abap2UI5-local is a special build of abap2UI5 that combines all artifacts into a single HTTP handler. You only need to create an additional database table, allowing you to run abap2UI5 independently from the rest of the system or any other abap2UI5 installation.
+abap2UI5-local is a special build that combines all artifacts into a single HTTP handler. You only need to create one additional database table, allowing you to run abap2UI5 independently from any other installation on the system.
 
-Find all information in the repository: <br>
+Find all information in the repository:
 https://github.com/abap2UI5/abap2UI5-local
diff --git a/docs/configuration/performance.md b/docs/configuration/performance.md
@@ -4,9 +4,9 @@ outline: [2, 4]
 
 # Performance
 
-abap2UI5 is fast! Almost everything's processed in the backend, leveraging the ABAP stack, which performs much faster than client-side or browser-based processing. <br>
+abap2UI5 is fast. Almost all processing happens on the ABAP backend, which is significantly faster than client-side or browser-based processing.
 
-Frontend logic is kept to a minimum: no business logic is executed, and everything's passed directly to the UI5 framework, focusing solely on UI rendering. <br>
+Frontend logic is kept to a minimum: no business logic runs in the browser. Everything is passed directly to the UI5 framework, which focuses solely on UI rendering.
 
 abap2UI5 has been successfully tested with tables containing large numbers of entries and columns. So, you can confidently develop your app — performance shouldn't be a concern.
 
diff --git a/docs/configuration/security.md b/docs/configuration/security.md
@@ -3,7 +3,7 @@ outline: [2, 3]
 ---
 
 # Security
-abap2UI5 is a backend-centric framework. All logic and business data remain securely on the backend, and the frontend only receives the data it needs to render the view. This approach helps maintain security while providing efficient functionality.
+abap2UI5 is a backend-centric framework. All logic and business data stay on the server, and the frontend only receives the data it needs to render the view.
 
 ### HTTP Endpoint
 The abap2UI5 framework operates as an HTTP handler. You create this HTTP handler and call the abap2UI5 API within it. End users can access abap2UI5 by calling the endpoint externally, with security managed similarly to any other UI5 application.
diff --git a/docs/development/events.md b/docs/development/events.md
@@ -3,7 +3,7 @@ outline: [2, 4]
 ---
 # Events
 
-UI5 Control properties can be used not only to display data but also to trigger events. Let's explore how you can leverage this functionality.
+UI5 control properties can be used not only to display data but also to trigger events. This section shows how to work with backend events, frontend events, and follow-up actions.
 
 ### Backend
 You can trigger backend processing when an event occurs using the `client->_event` method.
diff --git a/docs/development/general.md b/docs/development/general.md
@@ -1,6 +1,8 @@
 # Controller
 
-abap2UI5 offers great flexibility in app development. Most sample applications follow a process similar to the sequence outlined below. You can use it as a starting point, but feel free to create your own sequence or build a wrapper on top of abap2UI5 for more customized behavior:
+abap2UI5 offers great flexibility in how you structure your apps. Most sample applications follow a pattern similar to the one below. You can use it as a starting point, but feel free to adapt it or build a wrapper on top of abap2UI5 for more customized behavior.
+
+The basic idea: every request enters the `main` method, and you use `CASE` to distinguish between initialization, navigation returns, and user events:
 
 ```abap
 CLASS z2ui5_cl_app DEFINITION PUBLIC.
@@ -42,4 +44,4 @@ CLASS z2ui5_cl_app IMPLEMENTATION.
   ENDMETHOD.
 ENDCLASS.
 ```
-Refer to the specific sections of this development guide for more details on the implementation process.
+Refer to the specific sections of this development guide for more details on views, events, data binding, and navigation.
diff --git a/docs/development/messages.md b/docs/development/messages.md
@@ -20,7 +20,7 @@ ENDMETHOD.
 
 #### Message Box
 
-Want the user to acknowledge the message? You can display a message box that requires manual closure:
+If you need the user to acknowledge the message, display a message box that requires manual closure:
 
 ```abap
 METHOD z2ui5_if_app~main.
diff --git a/docs/development/model/expression_binding.md b/docs/development/model/expression_binding.md
@@ -1,6 +1,6 @@
 # Expression Binding
 
-Expression Binding in UI5 allows you to compute values directly in XML views using JavaScript-like expressions. This feature is especially useful in abap2UI5 development, as it can reduce server roundtrips by enabling calculations, logical conditions, and string operations directly on the frontend.
+Expression Binding lets you compute values directly in XML views using JavaScript-like expressions. This is especially useful in abap2UI5, as it can reduce server roundtrips by moving calculations, logical conditions, and string operations to the frontend.
 
 #### Calculate the Maximum Value at the Frontend
 
diff --git a/docs/development/model/model.md b/docs/development/model/model.md
@@ -3,7 +3,7 @@ outline: [2, 4]
 ---
 # Model
 
-In abap2UI5, there are two ways to exchange data with the frontend.
+In abap2UI5, there are two ways to exchange data between your ABAP code and the UI5 frontend.
 
 #### One-Way Binding
 Use one-way binding when you need to display data on the frontend without allowing changes. The `client->_bind` method sends data to the frontend and connects it to the view:
diff --git a/docs/development/model/odata.md b/docs/development/model/odata.md
@@ -3,7 +3,7 @@ outline: [2, 4]
 ---
 # OData
 
-By default, you can bind all public attributes of your implementation class to UI5 properties, enabling the display of internal tables and, with bind_edit, even updating data. Additionally, in scenarios where direct access to database tables is required, using pre-defined OData services can be beneficial. Leveraging OData protocols provides features such as pagination and growing, which enhance performance when handling large datasets.
+By default, you bind public attributes of your class to UI5 properties using `_bind` and `_bind_edit`. For scenarios that require access to large datasets, you can also use existing OData services. OData provides features like pagination and growing that improve performance when handling large amounts of data.
 
 #### Define Additional Model
 As an example, we will use the test OData service `/sap/opu/odata/DMO/UI_FLIGHT_R_V2/`, which is available in most ABAP systems. Ensure the service is publicly accessible. Use the following method to define the model and make it available under the name `FLIGHT`:
diff --git a/docs/development/model/tables.md b/docs/development/model/tables.md
@@ -1,5 +1,5 @@
 # Tables, Trees
-In this section, we will explore how to display deep data models, such as tables and trees.
+This section covers how to display complex data structures like tables, trees, and nested structures in your views.
 
 ### Tables 
 The example below demonstrates how to bind a simple table to a UI5 control:
diff --git a/docs/development/navigation/app_state.md b/docs/development/navigation/app_state.md
@@ -1,6 +1,6 @@
 # App State
 
-In UI5 applications, you have the ability to save the current app state and return to it later. A similar functionality is supported in the abap2UI5 framework too.
+abap2UI5 supports saving the current app state so you can return to it later -- similar to how standard UI5 applications handle state management.
 
 ### Usage
 Each state is saved as a draft with a unique ID, you can display this ID in the URL using the `client->set_app_state_active` method. This command generates a URL that you can copy and paste into another browser window. An example URL looks like this: <br>
diff --git a/docs/development/navigation/navigation.md b/docs/development/navigation/navigation.md
@@ -3,7 +3,7 @@ outline: [2, 4]
 ---
 # Navigation
 
-In abap2UI5, each application is represented by a single ABAP class. While you can embed all logic within a single class, it's generally better practice to keep individual classes manageable in size. You can achieve this by creating multiple classes that interact with each other, letting you build reusable, generic applications and popups that can be called in various contexts.
+In abap2UI5, each application is a single ABAP class. While you can put all logic into one class, it's better practice to keep classes manageable in size. By splitting functionality into multiple classes that interact with each other, you can build reusable applications and popups that work across different contexts.
 
 ### Cross App Navigation
 
diff --git a/docs/development/navigation/share.md b/docs/development/navigation/share.md
@@ -1,6 +1,6 @@
 # Share, Bookmark
 
-The app state feature leads to various additional use cases.
+The app state feature opens up several useful scenarios, such as sharing and bookmarking the current state of your app.
 
 ### Share
 You can easily integrate a share button, which copies the actual state into the clipboard for sharing with your colleagues. Check out the following snippet:
diff --git a/docs/development/popups.md b/docs/development/popups.md
@@ -3,7 +3,7 @@ outline: [2, 4]
 ---
 # Popups, Popovers
 
-UI5 offers functionality for displaying popups and popovers that overlay only specific areas of the view. Let's see how you can implement this using abap2UI5.
+UI5 offers popups and popovers that overlay specific areas of the view. This section shows how to implement them in abap2UI5.
 
 ### Popup
 
diff --git a/docs/development/specific/camera.md b/docs/development/specific/camera.md
@@ -3,10 +3,11 @@ outline: [2, 4]
 ---
 # Camera
 
+abap2UI5 provides a custom control for capturing photos directly from the device camera. The image is returned as a base64-encoded string that you can process on the backend.
 
-For camera capabilities, refer to the sample `z2ui5_cl_demo_app_306`:
+Here's a basic example based on sample `z2ui5_cl_demo_app_306`:
 ```abap
-CLASS z2ui5_cl_demo_app_306 DEFINITION PUBLIC FINAL CREATE PUBLIC .
+CLASS z2ui5_cl_demo_app_306 DEFINITION PUBLIC FINAL CREATE PUBLIC.
 
   PUBLIC SECTION.
     INTERFACES z2ui5_if_app.
@@ -21,19 +22,18 @@ CLASS z2ui5_cl_demo_app_306 IMPLEMENTATION.
       DATA(page) = z2ui5_cl_xml_view=>factory( )->shell( )->page( `abap2UI5 - Device Camera Picture`
                 )->_z2ui5( )->camera_picture(
                     value    = client->_bind_edit( mv_picture_base )
-                    onphoto  = client->_event( `CAPTURE` )  ).
+                    onphoto  = client->_event( `CAPTURE` ) ).
       client->view_display( page->stringify( ) ).
     ENDIF.
 
     IF client->get( )-event = `CAPTURE`.
-      "handle mv_picture_base
-      "...
+      "process mv_picture_base here...
     ENDIF.
 
   ENDMETHOD.
 ENDCLASS.
 ```
 
 ::: tip **Browser Restrictions**
-Depending on browser permissions and configuration settings, access to or use of native device capabilities (NDC) may be restricted. Watch out for any warning messages directly from your browser during testing.
+Camera access depends on browser permissions and security settings. Most browsers require HTTPS and will show a permission prompt. Watch for browser-level warning messages during testing.
 :::
diff --git a/docs/development/specific/cds.md b/docs/development/specific/cds.md
@@ -3,7 +3,7 @@ outline: [2, 4]
 ---
 # CDS, EML
 
-While all examples and snippets in our documentation are designed for compatibility without requiring CDS or EML, you can leverage these modern ABAP features in your abap2UI5 applications if you're using the latest ABAP releases.
+All examples in this documentation work without CDS or EML. However, if you're on a recent ABAP release, you can use these modern features in your abap2UI5 applications as well.
 
 ### ABAP CDS
 ABAP Core Data Services (CDS) enable you to define powerful views and consume data directly from the database. The following example demonstrates how to fetch sales orders using the I_SalesOrder view from the Virtual Data Model (VDM) and display them in a UI5 table:
diff --git a/docs/development/specific/demo_output.md b/docs/development/specific/demo_output.md
@@ -1,6 +1,8 @@
 # CL_DEMO_OUTPUT
 
-You can also display the HTML output of the class cl_demo_output with abap2UI5. Take the following snippet to see how it works:
+If you're familiar with `CL_DEMO_OUTPUT` from classic ABAP, you can display its HTML output inside an abap2UI5 app as well. This is handy for quick data visualization or when migrating existing demo code.
+
+The approach: generate the HTML with `cl_demo_output=>get( )`, inject CSS styles via `_cc_plain_xml`, and render the result with the `html` control:
 
 ```abap
 METHOD z2ui5_if_app~main.
@@ -68,28 +70,19 @@ METHOD z2ui5_if_app~main.
                                       `}` && |\n|  &&
                                       `</html:style>`.
 
+    "generate HTML output, e.g. from a database query:
+    "SELECT * FROM scarr INTO TABLE @DATA(carriers).
+    "DATA(lv_html) = cl_demo_output=>get( carriers ).
 
-
-    DATA(lv_html) = `` && |\n|  &&
-                    |\n|  &&
-                    `<h2 title="I'm a header">The title Attribute</h2>` && |\n|  &&
-                    |\n|  &&
-                    `<p title="I'm a tooltip">Mouse over this paragraph, to display the title attribute as a tooltip.</p>` && |\n|  &&
-                    |\n|  &&
-                    ``.
-
-*    SELECT *from scarr
-*           INTO TABLE @DATA(carriers).
-*
-*    DATA(lv_html) = cl_demo_output=>get( carriers ).
+    DATA(lv_html) = `<h2 title="I'm a header">The title Attribute</h2>` && |\n|  &&
+                    `<p title="I'm a tooltip">Mouse over this paragraph, to display the title attribute as a tooltip.</p>`.
 
     DATA(view) = z2ui5_cl_xml_view=>factory( ).
     view->shell(
            )->page(
            )->button( text = `test`
           )->_cc_plain_xml( lv_style
-          )->html( lv_html
-          ).
+          )->html( lv_html ).
 
     client->view_display( view->stringify( ) ).
 
diff --git a/docs/development/specific/drag.md b/docs/development/specific/drag.md
@@ -1,3 +1,5 @@
 # Drag & Drop
 
-With abap2UI5 you can leverage the drag-and-drop events of UI5 controls. To learn more, explore the sample `z2ui5_cl_demo_app_307`.
+UI5 controls support drag-and-drop interactions for reordering list items, moving data between tables, or building custom workflows. abap2UI5 lets you use these events just like any other UI5 control property.
+
+For a working example, explore the sample `z2ui5_cl_demo_app_307`.
diff --git a/docs/development/specific/files.md b/docs/development/specific/files.md
@@ -3,7 +3,7 @@ outline: [2, 4]
 ---
 # File Handling
 
-Implement File handling with base64 data exchange using two-way binding.
+abap2UI5 supports file uploads and downloads by exchanging base64-encoded data through two-way binding.
 
 #### Upload
 See also `Z2UI5_CL_DEMO_APP_075`:
diff --git a/docs/development/specific/geolocation.md b/docs/development/specific/geolocation.md
@@ -1,16 +1,14 @@
 # Geolocation, Maps
 
-This example demonstrates how to retrieve geolocation data such as longitude, latitude, altitude, and speed. Also see `Z2UI5_CL_DEMO_APP_120`.
+abap2UI5 includes a custom control for retrieving geolocation data from the user's device, such as longitude, latitude, altitude, and speed. This is useful for logistics apps, field service tools, or any scenario where location matters.
+
+The control fires a `finished` event once the browser has determined the device position. All values are exchanged via two-way binding. See also `Z2UI5_CL_DEMO_APP_120`.
 
 ```abap
-CLASS z2ui5_cl_sample_geolocation DEFINITION
-  PUBLIC
-  CREATE PUBLIC .
+CLASS z2ui5_cl_sample_geolocation DEFINITION PUBLIC CREATE PUBLIC.
 
   PUBLIC SECTION.
-
-    INTERFACES z2ui5_if_app .
-
+    INTERFACES z2ui5_if_app.
     DATA longitude TYPE string.
     DATA latitude TYPE string.
     DATA altitude TYPE string.
@@ -24,24 +22,28 @@ CLASS z2ui5_cl_sample_geolocation IMPLEMENTATION.
 
   METHOD z2ui5_if_app~main.
 
-       DATA(view) = z2ui5_cl_xml_view=>factory( ).
-        client->view_display( view->shell(
-            )->page( )->_z2ui5( 
-                )->geolocation(
-                    finished         = client->_event( `POST` )
-                    longitude        = client->_bind_edit( longitude )
-                    latitude         = client->_bind_edit( latitude )
-                    altitude         = client->_bind_edit( altitude )
-                    altitudeaccuracy = client->_bind_edit( altitudeaccuracy )
-                    accuracy         = client->_bind_edit( accuracy )
-                    speed            = client->_bind_edit( speed )
-            )->stringify( ) ).
+    DATA(view) = z2ui5_cl_xml_view=>factory( ).
+    client->view_display( view->shell(
+        )->page( )->_z2ui5(
+            )->geolocation(
+                finished         = client->_event( `POST` )
+                longitude        = client->_bind_edit( longitude )
+                latitude         = client->_bind_edit( latitude )
+                altitude         = client->_bind_edit( altitude )
+                altitudeaccuracy = client->_bind_edit( altitudeaccuracy )
+                accuracy         = client->_bind_edit( accuracy )
+                speed            = client->_bind_edit( speed )
+        )->stringify( ) ).
 
     CASE client->get( )-event.
       WHEN `POST`.
-        "processing...
+        "process geolocation data here...
     ENDCASE.
 
   ENDMETHOD.
 ENDCLASS.
 ```
+
+::: tip **Browser Permissions**
+Geolocation requires the user to grant permission in the browser. Make sure your HTTP service uses HTTPS, as most browsers block geolocation on insecure origins.
+:::
diff --git a/docs/development/specific/logging.md b/docs/development/specific/logging.md
@@ -3,7 +3,7 @@ outline: [2, 6]
 ---
 # Logging, BAL
 
-Logging is essential for developing end-user business processes. In ABAP systems, the standard tool for this purpose is the Business Application Log (BAL), which is supported in both on-premise systems and ABAP Cloud. With abap2UI5, you can use BAL functions just as you would in classic development. Logs can be displayed in tables or using the predefined popups provided by the framework.
+Logging is essential for business processes. In ABAP systems, the standard tool is the Business Application Log (BAL), supported in both on-premise and ABAP Cloud environments. With abap2UI5, you can use BAL just as you would in classic development and display logs through the framework's built-in popups.
 
 ##### BAL Variables
 In ABAP classic, you can use the classic BAL function modules and display the BAL table with the popup `z2ui5_cl_pop_messages`:
diff --git a/docs/development/specific/smart_controls.md b/docs/development/specific/smart_controls.md
@@ -1,3 +1,9 @@
 # Smart Controls
 
-You can use Smart Controls, check out sample `Z2UI5_CL_DEMO_APP_313`. (Experimental Feature)
+Smart Controls are metadata-driven UI5 controls that automatically render UI based on OData annotations. abap2UI5 provides experimental support for using them.
+
+For a working example, check out sample `Z2UI5_CL_DEMO_APP_313`.
+
+::: warning
+This is an experimental feature and may not work with all Smart Control types or configurations.
+:::
diff --git a/docs/development/specific/url.md b/docs/development/specific/url.md
@@ -1,20 +1,22 @@
 # URL
 
-### Read URL Parameter
+Working with URLs is a common requirement -- reading parameters from the current URL, opening links in new tabs, or managing browser history.
 
-You can read URL parameters using the following snippet:
+### Read URL Parameters
+
+Access query parameters from the current URL using the config object:
 ```abap
 DATA(lv_search) = client->get( )-s_config-search.
 ```
 
-### Open a new Tab
-The following action opens a new tab `target blank`:
+### Open a New Tab
+Open a URL in a new browser tab using a frontend event:
 ```abap
 DATA(lv_url) = `https://www.abap2UI5.org`.
-client->follow_up_action( client->_event_client( 
-    val = client->cs_event-open_new_tab 
+client->follow_up_action( client->_event_client(
+    val = client->cs_event-open_new_tab
     t_arg = VALUE #( ( lv_url ) ) ) ).
 ```
 
-### Change History
-Check out sample `Z2UI5_CL_DEMO_APP_139`.
+### Browser History
+For browser history manipulation, check out sample `Z2UI5_CL_DEMO_APP_139`.
diff --git a/docs/development/specific/xlsx.md b/docs/development/specific/xlsx.md
@@ -3,7 +3,7 @@ outline: [2, 6]
 ---
 # XLSX
 
-With abap2UI5 you can leverage the existing XLSX APIs of your ABAP system. It allows you to implement file uploads and downloads, converting XLSX contents into internal ABAP tables and vice versa.
+abap2UI5 lets you use your ABAP system's XLSX APIs to upload and download spreadsheets, converting between XLSX files and internal tables.
 
 #### Upload
 
diff --git a/docs/development/translation.md b/docs/development/translation.md
@@ -3,7 +3,7 @@ outline: [2, 4]
 ---
 # Translation, i18n
 
-In UI5 apps, translations are typically managed through i18n files, with translation content stored in frontend artifacts. In abap2UI5, since all apps reside on the ABAP backend, we can leverage ABAP's built-in translation mechanisms, such as text elements or message classes.
+In standard UI5 apps, translations are managed through i18n files stored as frontend artifacts. Since abap2UI5 apps live entirely on the ABAP backend, you can use ABAP's built-in translation mechanisms instead -- text elements, message classes, or data element descriptions.
 
 ### Text Element
 Messages can be translated using the ABAP text elements, making them available in different languages without changing the code:
diff --git a/docs/development/view.md b/docs/development/view.md
diff --git a/docs/get_started/about.md b/docs/get_started/about.md
diff --git a/docs/get_started/hello_world.md b/docs/get_started/hello_world.md
diff --git a/docs/get_started/next.md b/docs/get_started/next.md
diff --git a/docs/get_started/quickstart.md b/docs/get_started/quickstart.md
diff --git a/docs/get_started/samples.md b/docs/get_started/samples.md
diff --git a/docs/get_started/use_cases.md b/docs/get_started/use_cases.md
diff --git a/docs/technical/cloud.md b/docs/technical/cloud.md
diff --git a/docs/technical/how_it_all_works.md b/docs/technical/how_it_all_works.md
