Better documentation for joinfiles command.

diff --git a/doc/index.org b/doc/index.org
index 03c7da6..f9b2613 100644 (file)
--- a/doc/index.org
+++ b/doc/index.org
@@ -36,9 +36,6 @@
   understand diagrams. Diagrams were generated using [[https://www3.svjatoslav.eu/projects/javainspect/][JavaInspect tool]].
 
 * Introduction
-:PROPERTIES:
-:GPTEL_TOPIC: introduction
-:END:
 
 The *Älyverkko CLI* application is a user-friendly tool developed in
 Java, specifically tailored to streamline the utilization of expansive
@@ -102,7 +99,9 @@ product.
 
 *Usage Procedure:*
 1. User collects customer reviews in plain text format within the
-   configured mail directory.
+   configured mail directory. Lets say, about 150 kilobytes of reviews
+   per input file (this is dictated by AI model available context
+   size).
 2. Each review file is prefixed with "TOCOMPUTE:".
 3. The Älyverkko CLI application processes these files, generating
    sentiment analysis results and feature extraction insights.
@@ -399,17 +398,66 @@ ready for processing, you should [[id:883d6e7c-60e0-422b-8c00-5cdc9dfec20d][init
 
 ** joinfiles command
 
-To simplify appending together multiple files from filesystem for AI
-processing in a single query, *joinfiles* command can be used. It
-prompts user for the name of the output file (without extension),
-thereafter it scans and recursively appends contents of all files in
-the current directory and its subdirectories.
+The *joinfiles* command is a utility for aggregating the contents of
+multiple files into a single document, which can then be processed by
+AI. This is particularly useful for preparing comprehensive problem
+statements from various source files, such as software project
+directories or collections of text documents.
+
+*** Usage
+
+To use the *joinfiles* command, specify the source directory
+containing the files you wish to join and a topic name that will be
+used to generate the output file name:
+
+#+begin_example
+alyverkko-cli joinfiles -s /path/to/source/directory -t "my_topic"
+#+end_example
+
+If desired, you can also specify a glob pattern to match only certain files within the directory:
+
+#+begin_example
+alyverkko-cli joinfiles -s /path/to/source/directory -p "*.java" -t "my_topic"
+#+end_example
+
+After joining the files, you can choose to open the resulting document
+in text editor for further editing or review:
+
+#+begin_example
+alyverkko-cli joinfiles -t "my_topic" --edit
+#+end_example
 
-Usage example:
-: alyverkko-cli joinfiles
+*** Options
 
-This is useful for example when you want to submit entire software
-project source code directory to AI for processing.
+- **-s, --src-dir**: Specifies the source directory from which to join
+  files.
+
+- **-p, --pattern**: An optional glob pattern to match specific files
+  within the source directory.
+
+- **-t, --topic**: The topic name that will be used as a basis for the
+  output file name and should reflect the subject matter of the joined
+  content.
+
+- **-e, --edit**: Opens the joined file in text editor after the join
+  operation is complete.
+
+*** Example Use Case
+
+Imagine you have a software project with various source files that you
+want to analyze using AI. You can use the *joinfiles* command to
+create a single document for processing:
+
+#+begin_example
+alyverkko-cli joinfiles -s /path/to/project -p "*.java" -t "software_analysis" --edit
+#+end_example
+
+This will recursively search the project directory for Java source
+files, aggregate their contents into a file named
+*software_analysis.org* (within AI processor input files directory),
+and open text editor on the file, so that you can add your analysis
+instructions or problem statement. Finally you [[id:883d6e7c-60e0-422b-8c00-5cdc9dfec20d][Initiate AI processing]]
+and after some time, you will get results and the end of the file.
 
 * Initiate AI processing
 :PROPERTIES:
@@ -464,9 +512,6 @@ use Älyverkko CLI. Their purpose is to increase comfort for existing
 GNU Emacs users.
 
 ***** Easily compose new problem statement for AI from emacs
-:PROPERTIES:
-:GPTEL_TOPIC: create-new-topic-dedicated-file
-:END:
 
 The Elisp function *ai-new-topic* facilitates the creation and opening
 of a new Org-mode file dedicated to a user-defined topic within a

diff --git a/src/main/java/eu/svjatoslav/alyverkko_cli/commands/JoinFilesCommand.java b/src/main/java/eu/svjatoslav/alyverkko_cli/commands/JoinFilesCommand.java
index 186cbce..ba05ffa 100644 (file)
--- a/src/main/java/eu/svjatoslav/alyverkko_cli/commands/JoinFilesCommand.java
+++ b/src/main/java/eu/svjatoslav/alyverkko_cli/commands/JoinFilesCommand.java
@@ -6,6 +6,7 @@ import eu.svjatoslav.commons.cli_helper.parameter_parser.parameter.DirectoryOpti
 import eu.svjatoslav.commons.cli_helper.parameter_parser.parameter.NullOption;
 import eu.svjatoslav.commons.cli_helper.parameter_parser.parameter.StringOption;
 import eu.svjatoslav.commons.string.GlobMatcher;
+import org.apache.commons.lang3.StringUtils;
 
 import java.io.BufferedWriter;
 import java.io.File;
@@ -66,13 +67,18 @@ public class JoinFilesCommand implements Command {
             joinFiles();
         }
 
-        if (editOption.isPresent()) {
-            // User requested to edit the file after joining
-            System.out.println("Editing the file: " + outputFile.getAbsolutePath());
-            String editorCommand = "emc " + outputFile.getAbsolutePath();
-            Runtime.getRuntime().exec(editorCommand);
-        }
+        if (editOption.isPresent()) openFileWithEditor();
+
+    }
+
+    private void openFileWithEditor() throws IOException {
+        String editorCommand = sanitizeArgumentForShell(StringUtils.join(" ", "emc", outputFile.getAbsolutePath()));
+        Runtime.getRuntime().exec(editorCommand);
+    }
 
+    private String sanitizeArgumentForShell(String argument) {
+        // Implement logic to escape or quote the argument for use in shell commands
+        return "\"" + argument.replace("\"", "\\\"") + "\"";
     }
 
     private void joinFiles() throws IOException {