Re: New version of todo-mode.el (announcement + user guide)

[Stephen Berman]

On Mon, 10 Jun 2013 20:20:18 -0400 Stefan Monnier <address@hidden> wrote:

>> I'd consider doing that if the Emacs maintainers decide not to accept
>> this package, but my hope is that they will accept it and then
>
> I don't see any problem with you switching to this new fancier
> todo-mode.el, with the only request that you try to preserve some
> compatibility with todo files made with the old mode.

Thank you for the vote of confidence.  Regarding compatibility, as
explained in the last section of the user guide I posted, the way the
new and old todo file formats treat the item date header makes them
practically incompatible.  However, I've provided a command which
converts a copy of an old-style todo file into new-style one and a copy
of an old-style `todo-file-done' file into a new-style todo archive
file.  I've tested this with the default value of the date/time header
string used by the old version, and it should also work with custom
values that satisfy certain conditions, but this would need more testing
and it's not unlikely that some manual post-editing would be necessary.
I hope this is an acceptable approach.  If so, then I have a number of
questions about how to proceed:

- The first thing to decide is where and under what name to install the
  new version.  Should I simply replace the old version?  This would
  essentially force users of the old version to convert to and learn to
  use the new version.  In principle, that should not be a problem, but
  since I'm the only one who's used the new version so far, there are
  certain to be use cases and configurations I didn't test well enough
  or even think of at all, so there could well be a period of
  instability for these users.
- Alternatively, I could install the new version alongside the old
  version.  In fact, the code I posted is ready for this, since the file
  is called todos.el and it uses the prefix "todos-", so it can be
  loaded without interfering with the old version.  This would allow
  people to test the new version while still being able to use the old
  version.  The disadvantage of this is inertia: since people wouldn't
  have to use the new version, it may get less testing.
- A third alternative is to install the new version as posted with the
  new name and prefix in place of the old version and move that to
  lisp/obsolete/, so people could still use it but would have more
  incentive to use the new version.

- Although I eliminated, changed or reimplemented almost all the code in
  the old version, there are bits here and there that I've retained, as
  well as the basic concepts and UI of handling todo lists.  So should
  the original author, Oliver Seidel, still be listed as an author, or
  is it sufficient to acknowledge him in the commentary (as I do in the
  code I posted)?

- If Glenn Morris approves, can I install the patch I included for
  diary-lib.el?  Without this, if a todo file is included in the Emacs
  diary, then when a todo item appears as an entry in the Fancy Diary
  display and you click on it, you may not jump to the right item in the
  todo file.  It's not a showstopper, but should be supported for proper
  integration with the diary.  But maybe there's a better way of getting
  the right behavior than this patch.  (BTW, I think this issue already
  exists for the current version of todo-mode.el.)

- The code makes use of a powerset function, which Emacs doesn't have.
  I tried but couldn't come up with my own algorithm but found a
  recursive Common Lisp implementation and an iterative one in C on a
  website whose content is licensed under the GFDL.  I reimplemented the
  latter in Elisp, so at least the code is not literally copied.  Is
  this a cause for concern with respect to copyright assignment?

- I've tried to follow the Emacs coding conventions and used checkdoc,
  but one of the things I'm uncertain about is the new "<prefix>--"
  convention.  Since this is not a general-purpose library, basically
  every function and variable in it is not meant for use by other
  packages.  On the other hand, some clearly internal functions, such as
  the powerset function, could be used by other packages, but more
  likely they would be redefined using the package prefix.  So for the
  time being I haven't applied this convention but I'd be happy to do so
  in specific cases, or if the guidelines for using it can be spelled
  out more precisely.

- I also have a question about documentation.  The user guide I posted
  is certainly too long and detailed for the commentary section of the
  source code, and I guess also for the Emacs manual.  Should I try to
  destill it down to a reasonable manual entry, added to the diary
  chapter?  If so, I'd be grateful for suggestions about what to omit or
  how to make it otherwise suitable.  Alternatively, if it is deemed
  worthwhile including all the information, it could be added as
  separate manual.

Steve Berman