Metadata-Version: 2.4
Name: docomod
Version: 1.0.1
Summary: Advanced Docx Comment Editor - A lightweight solution for managing Docx comment metadata
Author-email: EasyCam <easycam@example.com>
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://github.com/easycam/docomod
Project-URL: Documentation, https://github.com/easycam/docomod#readme
Project-URL: Repository, https://github.com/easycam/docomod
Project-URL: Issues, https://github.com/easycam/docomod/issues
Project-URL: Changelog, https://github.com/easycam/docomod/blob/main/CHANGELOG.md
Keywords: docx,comment,editor,metadata,word,annotation
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business
Classifier: Topic :: Text Processing
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PySide6>=6.0.0
Requires-Dist: python-docx>=0.8.11
Requires-Dist: lxml>=4.6.0
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Dynamic: license-file

# docomod - Advanced Docx Comment Editor

## Project Background

In the landscape of modern digital documentation, collaborative editing serves as a cornerstone for professional and academic workflows. The pervasive Docx format utilizes robust change tracking and commenting features to facilitate asynchronous communication between authors, editors, and reviewers. A significant challenge arises, however, from the rigid manner in which comment metadata—specifically the author's name and initials—is embedded within these files. This information is typically hard-coded based on the system configuration at the moment of creation, leading to persistent difficulties when documents require anonymization for blind peer review, standardization for corporate publication, or correction of attribution errors resulting from shared workstation usage. Traditional remediation methods often involve cumbersome workarounds such as manual XML manipulation or the use of opaque, proprietary tools that lack granular control over metadata.

docomod addresses these limitations by providing a lightweight, open-source solution designed specifically for the precise management of Docx comment metadata. Leveraging the Python programming language and the Qt framework, the software abstracts the complexities of the OpenXML standard, offering a graphical interface for parsing, viewing, and modifying the underlying XML structure of documents. By focusing strictly on the `word/comments.xml` component, docomod ensures that modifications to author names, initials, and content are executed safely without compromising the integrity of the document's main body or formatting. This utility empowers users to maintain data privacy, ensure professional consistency, and rectify historical errors with an efficiency that native editing suites do not currently provide.

## Application Scenarios

The utility of docomod extends across various professional and academic domains where document metadata management is critical. In the realm of academic publishing, the double-blind peer review process necessitates the complete removal of author identity. docomod facilitates the batch renaming of comment authors to generic titles such as "Reviewer" or "Author," thereby ensuring anonymity is preserved without the loss of contextual feedback. Similarly, within corporate environments, documents prepared for external release often require a unified voice. Comments attributed to individual team members can be standardized to reflect a departmental identity, such as "Legal Team" or "Editorial Board," presenting a cohesive professional image.

Legal and compliance sectors also benefit significantly from the ability to sanitize document metadata. When sharing drafts with external parties, it is often necessary to redact specific names while retaining the substance of legal notes. docomod provides the granular control required to protect individual privacy and adhere to strict confidentiality protocols. Furthermore, in environments where workstations are shared, documents are frequently edited under incorrect user profiles. The software allows for the retrospective correction of these attribution errors, ensuring that document history accurately reflects the true contributors, a function vital for accountability and accurate project tracking.

## Hardware and System Requirements

docomod is engineered as a lightweight utility compatible with a broad spectrum of hardware configurations. The application's single-threaded logic relies on the efficiency of the underlying Python interpreter and the Qt event loop, making it functional on any modern x86-64 or ARM-based processor. A minimum specification of a dual-core processor with a clock speed of 1.6 GHz or higher is recommended to ensure GUI responsiveness, particularly when parsing large XML structures associated with extensive document comments. While the software is optimized for memory efficiency, loading document structures into memory for real-time editing requires adequate system RAM. For standard documents, 4GB is sufficient, though 8GB is advisable for a smoother experience when multitasking.

Storage requirements are minimal, with the source code and assets occupying less than 10MB, and the Python environment with dependencies requiring approximately 200MB to 500MB. The use of Solid State Drives (SSD) is recommended to enhance startup times and file I/O performance. The graphical user interface supports a minimum resolution of 1024x768 pixels, but a Full HD (1920x1080) display is preferred for optimal viewing of the multi-column comment table.

Regarding operating systems, the software is cross-platform, leveraging the portability of Python and Qt 6. It is fully compatible with Windows 10 (Build 1809 or later) and Windows 11, supporting both x86_64 and ARM architectures. On macOS, it runs natively on versions 11 (Big Sur) through 14 (Sonoma), supporting both Intel and Apple Silicon hardware. Major Linux distributions including Ubuntu, Fedora, and Debian are also supported, provided a compliant X11 or Wayland display server is present. The application utilizes standard Qt styling to integrate with the host operating system's desktop environment.

## Environment and Dependencies

The execution of docomod requires a specific software environment centered around Python 3.8 or newer. This version requirement ensures access to necessary syntax features and optimizations utilized within the codebase. The latest stable release of Python is recommended for optimal performance and security. The graphical user interface is constructed using PySide6, the official Python bindings for the Qt 6 framework. Version 6.0.0 or higher is required to handle window management, event processing, and widget rendering, providing the application with a native look and feel.

Interaction with Docx files is managed through the `python-docx` library (version 0.8.11 or newer). This library provides the API for creating and updating files according to the ECMA-376 OpenXML standard. While `python-docx` handles the general document structure, docomod interfaces directly with the exposed XML elements to perform specific comment edits that are not natively supported by the high-level API. Underlying these operations is the `lxml` library, a high-performance XML processing tool used for parsing structural components like `comments.xml` and executing XPath queries to locate and modify attributes such as `w:author` or `w:initials`.

## Installation and Execution

Setting up docomod involves establishing a Python environment and installing the necessary dependencies. It is assumed that the source code has already been obtained and resides on the local file system. The first requirement is a valid installation of Python 3.8+ on the host machine. It is standard practice to execute the application within a virtual environment to isolate dependencies from the system-wide Python installation. This can be achieved by navigating to the project directory in a terminal and creating a virtual environment (e.g., using `python -m venv venv`), then activating it.

With the environment active, the dependencies listed in `requirements.txt` must be installed using the pip package manager (`pip install -r requirements.txt`). This process retrieves and installs PySide6, python-docx, lxml, and their respective sub-dependencies. Once the environment is configured and dependencies are satisfied, the application is launched by executing the main entry script `docomod` via the Python interpreter. This action initializes the GUI, making the tool ready for document processing.

## Operational Workflow

The workflow of docomod is designed for simplicity and efficiency, guiding the user through a logical progression of steps to modify document metadata.

### 1. Application Startup
Upon initialization, the application presents a minimalist interface designed to be intuitive and distraction-free. The main window is divided into three functional areas: a top toolbar for file operations and language selection, a central data table for viewing comments, and a bottom editing panel for modifying specific entries. At this stage, the workspace is clear, indicating readiness for user input.

![Startup Interface](images/0-启动界面.png)

### 2. Opening a Document
The "Open File" function invokes the operating system's native file dialog, filtered to accept only Docx files. This ensures that users can easily navigate their file system to select the target document. Once a file is selected, docomod parses the internal XML structure, identifying all comments and populating the central table with their ID, Author, Initials, and Content.

![Open File](images/1-打开文件.png)

### 3. Modifying a Comment
Users can select any row in the data table to load the corresponding comment's details into the editing panel below. Here, the author's name, initials, and the comment text itself can be modified. This interface allows for precise adjustments to metadata without altering the document's main body text.

![Edit Comment](images/2-修改批注.png)

### 4. Applying Changes
After editing the desired fields, clicking "Apply Changes" updates the application's in-memory representation of the document. The table view refreshes immediately to reflect these updates, providing visual confirmation that the changes have been registered. Note that at this stage, the original file on the disk remains untouched.

![Modify Success](images/3-修改成功.png)

### 5. Saving the File
To finalize the process, the "Save File" function is triggered. This opens a standard "Save As" dialog, giving the user the choice to overwrite the original document or save the modified version as a new file. This step is crucial for writing the in-memory changes back to the Docx container format.

![Save File](images/4-保存文件.png)

### 6. Save Confirmation
A successful save operation is confirmed via a status message box. This provides assurance that the XML structure has been correctly reassembled and written to the disk, and the document is now ready for use.

![Save Success](images/5-保存成功.png)

### 7. Verifying Results
The final output can be verified by opening the document in any standard word processor. As shown, the metadata updates (such as the author name change) are fully integrated, ensuring that the document meets the required standards for anonymity or professional consistency.

![Modification Effect](images/6-修改效果.png)

## License Agreement

docomod is distributed as free and open-source software under the terms of the **GNU General Public License version 3 (GPLv3)**. This license grants users the freedom to run the program for any purpose, including personal, academic, and commercial use, without the requirement of usage fees or activation keys. Access to the source code is guaranteed, allowing for inspection, modification, and adaptation of the software to meet specific needs.

Redistribution of the software, whether in its original or modified form, is permitted. However, the copyleft nature of GPLv3 mandates that any modified versions distributed must also be released under the same license, ensuring that the freedoms to run, study, and modify are preserved for all downstream users. It is explicitly stated that the software is provided "AS IS," without warranty of any kind, expressed or implied, regarding merchantability or fitness for a particular purpose. The risk associated with the quality and performance of the program rests entirely with the user.
