From f379055a86655b98a0fb813ee4a653c03822a345 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Pinard?= Date: Fri, 25 Jan 2013 09:58:36 -0500 Subject: [PATCH] README.org: Better document a few bugs or suggestions. --- README.org | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/README.org b/README.org index e96a684..db39e6c 100644 --- a/README.org +++ b/README.org @@ -24,20 +24,22 @@ While the comment or string is being copied in the editing buffer and until the Functions added to =poporg-edit-hook= are run once the PopOrg editing buffer has been set up with its contents, with the common prefix already removed, these functions may further modify the buffer contents. Functions added to =poporg-edit-exit-hook= are run when PopOrg is about to reinstate the common prefix and move back the editing buffer contents into the original programming buffer, these functions may alter the contents as needed. (I did not need these hooks, so let's talk if you need them to be defined differenty!) ** Known bugs -- The protective measures against losing a pending edition do not work when the user plainly exits Emacs. +The following list is organized in decreasing order of approximative or subjective priority. You may also check if there are any [[https://github.com/pinard/PopOrg/issues][issues on GitHub]]. - If the cursor is located immediately before the opening delimiter of a string before =poporg-dwim=, some extraneous text to edit may be collected from before the cursor. +- The protective measures against losing a pending edition do not work when the user plainly exits Emacs. - If characters are added immediately before or immediately after the region being edited, while the edition is pending, the characters after the region are preserved when the user completes its PopOrg edition, but the characters before the region are lost, while they should have been preserved. - Even if a region being edited is /intangible/ (meaning that the cursor cannot be pushed into it), it is not /read-only/ and could have its contents deleted by editing from either end of the region. I suspect (without being sure) that this bug, and the preceding one, come from the fact overlays and text-properties do not behave the same. -- Also, maybe, check for [[https://github.com/pinard/PopOrg/issues][issues on GitHub]] if any. -** History -PopOrg recycles a few ideas from two previous Emacs projects: - -- my PO mode ([[http://git.savannah.gnu.org/cgit/gettext.git/tree/gettext-tools/misc/po-mode.el][source]] and [[http://www.gnu.org/software/gettext/manual/html_node/PO-Mode.html][documentation]]), for the idea of using separate buffers for edition. For PO files, the need is quite clear: =msgstr= strings use escaping which is easy to get wrong, so the idea of a separate buffer is a way to remove that concern from the user, PO mode unquotes before presenting the string to the user, and requotes it once the editing is completed. This was also solving the problem that =msgid= and =msgstr= fields, and the reminder of the PO file, could be using different character sets. I intend to recycle some ideas from PO mode for editing many comments and strings at once, instead of necessarily one after another. - -- my Rebox tool ([[https://github.com/pinard/Pymacs/blob/master/contrib/rebox/rebox.el][source]] and [[https://github.com/pinard/Pymacs/blob/master/contrib/rebox/README][documentation]]), for finding the boundaries of block comments. Originally in Emacs Lisp, this tool has later rewritten in Python at the time I was developing Pymacs, with a few minor improvements while doing so. Le Wang, starting from my old Emacs Lisp, wrote a /much/ enhanced version ([[https://github.com/lewang/rebox2/blob/master/rebox2.el][source]] and [[http://youtube.googleapis.com/v/53YeTdVtDkU][video]]). For PopOrg, however, the needs are modest, so it includes the old Emacs Lisp version. See the very last section of the documentation for more historial context. +- Ideally, the region being edited should be /read-only/ but not /intangible/, in that the cursor could be moved into it, from where a =poporg-dwim= command would popup the associated edit buffer. This would be particularly useful when a user has many pending PopOrg edits. +- It has been suggested, and rightly so, that =C-c C-c= would be a nice keybinding for completing a PopOrg edit. The problem with this is that the edit buffer uses Org mode, where =C-c C-c= is overcrowded with many functionnalities already; some care would be needed to make sure this command, used with another intent, does not unexpectedly close the edition. ** Caveats - I do not much like to depend on Rebox, however, which is a complex piece of code compared to the reminder of PopOrg. For comments, Rebox studies the file contents to guess comment delimiters and box styles, while for strings, PopOrg rather relies the syntax analysis previously made by the programming major mode, and expressed through faces. These approaches are too different, maybe both are wrong anyway. One advantage of using Rebox, however, is that it brings PopOrg closer to the capability of editing Org mode comments in complex boxing cases. - Once the string and comment is back into the programming buffer, we loose Org mode highlighting and presentation details, which is unfortunate. Multiple editing modes in Emacs are not able to properly highlight sections of a file according to the intended mode for each section: there is a single mode for the whole buffer in fact. Org mode, on the other hand, has the virtue of properly highlighting the code snippets it contains, so surely, there is a way to do things properly, that might be understood and recycled, I'm not sure. - PopOrg should ideally be accompanied by a set of conventions and some tools for proper extraction of an Org file out of program sources. +** History +PopOrg recycles a few ideas from two previous Emacs projects: + +- my PO mode ([[http://git.savannah.gnu.org/cgit/gettext.git/tree/gettext-tools/misc/po-mode.el][source]] and [[http://www.gnu.org/software/gettext/manual/html_node/PO-Mode.html][documentation]]), for the idea of using separate buffers for edition. For PO files, the need is quite clear: =msgstr= strings use escaping which is easy to get wrong, so the idea of a separate buffer is a way to remove that concern from the user, PO mode unquotes before presenting the string to the user, and requotes it once the editing is completed. This was also solving the problem that =msgid= and =msgstr= fields, and the reminder of the PO file, could be using different character sets. + +- my Rebox tool ([[https://github.com/pinard/Pymacs/blob/master/contrib/rebox/rebox.el][source]] and [[https://github.com/pinard/Pymacs/blob/master/contrib/rebox/README][documentation]]), for finding the boundaries of block comments. Originally in Emacs Lisp, this tool has later rewritten in Python at the time I was developing Pymacs, with a few minor improvements while doing so. Le Wang, starting from my old Emacs Lisp, wrote a /much/ enhanced version ([[https://github.com/lewang/rebox2/blob/master/rebox2.el][source]] and [[http://youtube.googleapis.com/v/53YeTdVtDkU][video]]). For PopOrg, however, the needs are modest, so it includes the old Emacs Lisp version. See the very last section of the Rebox documentation for more historial context.