From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Philip Kaludercic Newsgroups: gmane.emacs.devel Subject: Re: [ELPA] New package: tchanges Date: Sun, 22 Sep 2024 17:28:18 +0000 Message-ID: <87o74f8uod.fsf@posteo.net> References: <86tte88sfl.fsf@gmx.net> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="35047"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org To: James Thomas Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sun Sep 22 19:29:10 2024 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1ssQOT-0008zB-D3 for ged-emacs-devel@m.gmane-mx.org; Sun, 22 Sep 2024 19:29:09 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ssQNu-0001je-R2; Sun, 22 Sep 2024 13:28:36 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ssQNm-0001iN-Ba for emacs-devel@gnu.org; Sun, 22 Sep 2024 13:28:27 -0400 Original-Received: from mout01.posteo.de ([185.67.36.65]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ssQNi-0006tN-E5 for emacs-devel@gnu.org; Sun, 22 Sep 2024 13:28:24 -0400 Original-Received: from submission (posteo.de [185.67.36.169]) by mout01.posteo.de (Postfix) with ESMTPS id D64AF240027 for ; Sun, 22 Sep 2024 19:28:19 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1727026099; bh=zLN/jdihV2ND215GzYCRDu8ARPxMIptx2lw0IeqJ+ig=; h=From:To:Cc:Subject:Autocrypt:OpenPGP:Date:Message-ID:MIME-Version: Content-Type:From; b=FDNDACzIGCM6MfzCefV838tRl/ds7PQ7f2UU3L9ifZjgffu8fS/L7glXGhLxfylPo jzUBwkRjH0kZBpJTTaM2VmTymOEjuqRitQpqdaeQvYRVrdywAkJ8Wu3SERT/JK5Yku sePPKSX7IUWzDhug/QdxtS3ebybjf70z0DuGOz5R4363h46TzozM0aXjnB9LQ7CHYW isx5ACLAicacrrnFfLj86f5J5D9ajrAjQ5SAaMYNa0xAQY8S2+Rq++IBsdyPE7nmYw +VUzyCoeAzn6EmsiM58GQE26ILFcV/nEKKXHyc3JMG50uIt3euWDGaeWNY6QzjQ7cU j3I/NGWtNJVFg== Original-Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4XBY4M35xYz6tn4; Sun, 22 Sep 2024 19:28:19 +0200 (CEST) In-Reply-To: <86tte88sfl.fsf@gmx.net> (James Thomas's message of "Sun, 22 Sep 2024 05:34:30 +0530") Autocrypt: addr=philipk@posteo.net; keydata= mDMEZBBQQhYJKwYBBAHaRw8BAQdAHJuofBrfqFh12uQu0Yi7mrl525F28eTmwUDflFNmdui0QlBo aWxpcCBLYWx1ZGVyY2ljIChnZW5lcmF0ZWQgYnkgYXV0b2NyeXB0LmVsKSA8cGhpbGlwa0Bwb3N0 ZW8ubmV0PoiWBBMWCAA+FiEEDg7HY17ghYlni8XN8xYDWXahwukFAmQQUEICGwMFCQHhM4AFCwkI BwIGFQoJCAsCBBYCAwECHgECF4AACgkQ8xYDWXahwulikAEA77hloUiSrXgFkUVJhlKBpLCHUjA0 mWZ9j9w5d08+jVwBAK6c4iGP7j+/PhbkxaEKa4V3MzIl7zJkcNNjHCXmvFcEuDgEZBBQQhIKKwYB BAGXVQEFAQEHQI5NLiLRjZy3OfSt1dhCmFyn+fN/QKELUYQetiaoe+MMAwEIB4h+BBgWCAAmFiEE Dg7HY17ghYlni8XN8xYDWXahwukFAmQQUEICGwwFCQHhM4AACgkQ8xYDWXahwukm+wEA8cml4JpK NeAu65rg+auKrPOP6TP/4YWRCTIvuYDm0joBALw98AMz7/qMHvSCeU/hw9PL6u6R2EScxtpKnWof z4oM OpenPGP: id=7126E1DE2F0CE35C770BED01F2C3CC513DB89F66; url="https://keys.openpgp.org/vks/v1/by-fingerprint/7126E1DE2F0CE35C770BED01F2C3CC513DB89F66"; preference=signencrypt Received-SPF: pass client-ip=185.67.36.65; envelope-from=philipk@posteo.net; helo=mout01.posteo.de X-Spam_score_int: -43 X-Spam_score: -4.4 X-Spam_bar: ---- X-Spam_report: (-4.4 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_MED=-2.3, RCVD_IN_MSPIKE_H3=-0.01, RCVD_IN_MSPIKE_WL=-0.01, RCVD_IN_VALIDITY_CERTIFIED_BLOCKED=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.devel:323930 Archived-At: --=-=-= Content-Type: text/plain James Thomas writes: > Hi, > > I propose to include this package that I wrote, to GNU ELPA. It's for > collaborating with users of word-processing software, such as > Libreoffice Writer, using the latter's 'track changes' feature. > > https://codeberg.org/quotuva/tchanges I haven't tested it, but here are a few quick comments: --=-=-= Content-Type: text/plain Content-Disposition: inline Content-Transfer-Encoding: 8bit diff --git a/tchanges.el b/tchanges.el index a3e6829..4bf6395 100644 --- a/tchanges.el +++ b/tchanges.el @@ -5,6 +5,7 @@ ;; Author: James Thomas ;; Maintainer: James Thomas ;; Keywords: wp, convenience, files +;; Package-Requires: ((emacs "30")) ;; URL: https://codeberg.org/quotuva/tchanges ;; Version: 0.1 @@ -26,19 +27,24 @@ (require 'bookmark) (defgroup tchanges nil - "Collaborate with Office (docx) users using 'track changes'.") + "Collaborate with Office (docx) users using 'track changes'." + :group '???) ;this is missing! (defcustom tchanges-output-format "org" - "Default output format. See man page `pandoc(1)' for available options." - :type '(string) - :group 'tchanges) + "Default output format. +See man page `pandoc(1)' for available options." + ;; By default, a user option is added to the last declared group, so + ;; you can omit it here! + :type 'string) ;Is this actually a string, or + ;a symbol? Should you give a + ;list of suggestions? (defcustom tchanges-pandoc-extra-args nil - "Extra args passed to pandoc. Value is a list of strings, which may be nil." - :type '(repeat (string :tag "Argument")) - :group 'tchanges) + "Extra args passed to pandoc. +Value is a list of strings, which may be nil." + :type '(repeat :tag "Arguments" string)) (defvar tchanges-script (expand-file-name @@ -51,12 +57,13 @@ ;; Global value used during import, the local in the comment editor. (defvar tchanges-buffer nil) + ;; Separate uses for the org buffer and the comment editor. (defvar-local tchanges-comments nil) (defun tchanges--sentinel (process event) - "Sentinel for pandoc process completion." - (if (not (string-match "finished" event)) + "Sentinel for pandoc process completion." ;checkdoc would like some more documentation! + (if (not (string-match "finished" event)) ;(elisp) Sentinels says it should be "finished\n". Or use `process-status'. (error "%s %s" process event) (message "tchanges: Running pandoc...done") (tchanges--postproc))) @@ -71,17 +78,18 @@ (setq tchanges-buffer nil)) (defun tchanges--postproc-2 (tag) + ;; Documentation missing here! Flymake + checkdoc should warn you about this. (let ((insdel-regexp "\\([id]\\)[^]*?[^]*?\\([^]*?\\)") (comments-regexp "[se][^]*?") (bookmark-make-record-function #'tchanges-bookmark-make-record) (bookmark-use-annotations nil) bookmark-alist (count 0)) - (cl-letf (((symbol-function #'bookmark--set-fringe-mark) - (symbol-function #'ignore))) + (cl-letf (((symbol-function #'bookmark--set-fringe-mark) #'ignore)) (goto-char (point-min)) (while (re-search-forward + ;; I think that using `rx' would make this more readable and maintainable. "s\\([^]*?\\)\\([^]*?\\)\\([^]*?\\)\\([^]*?\\)" nil t) (let* ((beg (match-beginning 0)) @@ -142,13 +150,14 @@ ;;;###autoload (defun tchanges-find-file (file &optional format) + ;; checkdoc warns you that the first sentence should fit on a line! "Convert a word processor document FILE with \\='tracked changes\\=' to pre- and post- buffers. These may be `diff'ed or, more conveniently, `ediff3'd with the original version of the file before it was shared (as \\='ancestor\\='), inorder to hide (or nullify) common changes (the ones related to conversion). -(For even more accuracy, you may \\='regenerate\\=' the above original +\(For even more accuracy, you may \\='regenerate\\=' the above original version by a reverse conversion using the same Pandoc arguments immediately after the forward conversion) @@ -180,10 +189,10 @@ Comment regions are highlighted with tooltips, but also see (defun tchanges-inline-comments () "Prepare the buffer by inlining the comments, for export or saving." (interactive) - (if (or (not (bound-and-true-p tchanges-comments))) + (if (or (not (bound-and-true-p tchanges-comments))) ;isn't it always bound? (user-error "No comments in buffer.") (let ((bookmark-alist - (sort tchanges-comments + (sort tchanges-comments ;the :lessp requires Emacs 30, but you could also call `sort' without keyword parameters :lessp (lambda (x y) (> (bookmark-get-position x) @@ -239,7 +248,7 @@ Comment regions are highlighted with tooltips, but also see Copied from the default function." (let* ((posn (or (and (use-region-p) (region-beginning)) (point))) - (len (when (use-region-p) (- (region-end) posn)))) + (len (and (use-region-p) (- (region-end) posn)))) ;is it ok if this is nil? `((buffer . ,(current-buffer)) (front-context-string . ,(if (>= (- (point-max) (point)) @@ -263,7 +272,7 @@ Copied from the default function." (handler . ,#'tchanges--bookmark-handler)))) (defun tchanges-edit-annotation-confirm () - "TODO" + "TODO" ;TODO (interactive) (let* ((buf tchanges-buffer) (newp (string-prefix-p "g" bookmark-annotation-name)) @@ -318,16 +327,15 @@ Copied from the default function." (bookmark-use-annotations t) bookmark-alist (buf (current-buffer))) - (cl-letf (((symbol-function #'bookmark--set-fringe-mark) - (symbol-function #'ignore))) + (cl-letf (((symbol-function #'bookmark--set-fringe-mark) #'ignore)) (bookmark-set (symbol-name (gensym)) t)) ;; Single bookmark (setq-local tchanges-buffer buf) (setq tchanges-comments bookmark-alist) (tchanges--remap '(bookmark-edit-annotation-confirm)))) -(defun tchanges-bmenu--revert () - "Re-populate `tabulated-list-entries'. (Copied from the bookmark-...)" +(defun tchanges-bmenu--revert () ;Copied from the bookmark-... + "Re-populate `tabulated-list-entries'." (setq tabulated-list-entries nil) (dolist (full-record bookmark-alist) (let* ((name (bookmark-name-from-full-record full-record)) @@ -354,8 +362,9 @@ Copied from the default function." (tabulated-list-print t)) (defun tchanges-list-comments () - "View buffer with all the comments. May be run in the buffer, after using -`tchanges-comment'. If point is at a comment, jump to it in the listing." + "View buffer with all the comments. +May be run in the buffer, after using `tchanges-comment'. If point is at +a comment, jump to it in the listing." (interactive) (let ((id (get-char-property (point) 'tchanges-comment)) (buf (current-buffer)) @@ -402,9 +411,9 @@ Copied from the default function." tchanges-buffer)) bookmark-watch-bookmark-file) (cl-letf (((symbol-function #'bookmark--remove-fringe-mark) - (symbol-function #'tchanges--remove-highlight)) + #'tchanges--remove-highlight) ((symbol-function #'bookmark-bmenu-list) - (symbol-function #'tchanges-bmenu--revert))) + #'tchanges-bmenu--revert)) (bookmark-bmenu-execute-deletions)) (with-current-buffer tchanges-buffer (setq tchanges-comments bookmark-alist)))) --=-=-= Content-Type: text/plain > > Here's a short screencast (.gif) demonstrating most of the features: > > https://codeberg.org/attachments/5096c13b-ff1f-47f6-8741-f3d955e34211 I am afraid this demonstration is not that useful if you don't already understand what is going on. If you believe a visual introduction to be useful, I would recommend preparing a recorded version with narration and uploading it to a Peertube server. > I'd previously mentioned this in the other mailing lists as well[1]. > > Regards, > James > > 1: > https://lists.gnu.org/archive/html/emacs-orgmode/2024-07/msg00009.html > https://lists.gnu.org/archive/html/help-gnu-emacs/2024-05/msg00167.html > (older repo URL) > > -- Philip Kaludercic on siskin --=-=-=--