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

[Stephen Berman]

On Tue, 11 Jun 2013 17:48:34 -0400 Stefan Monnier <address@hidden> wrote:

>> 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.
>
> Too bad, but not surprising.
>
>> 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.
>
> That's not sufficient for people who use the same TODO file on various
> machines whereas those machines don't all have the same Emacs version
> (hence some will have the old todo-mode and others will have the new one).

I was kind of hoping todo-mode users would be so wowed by the new
version that they'd convert their old files and not look back... but I
didn't consider the use-case you mention.  I'll try to write a command
that converts from the new to the old format, but this may not be so
straightforward, because the new format has structure at all three
organizational levels (item, category, and file) for which there's no
correspondence in the old format.  (Likewise, there's nothing in the new
format corresponding to use of todo-prefix in the old format, but I
consider that difference to be one of the main advantages of the new
version.  In fact, I think the way the old version interacts with the
Emacs diary is rather buggy, at least for my usage, and the fact that
there have been no bug reports about that leads me to believe that few
if any todo-mode users include the todo file in the diary -- or they
have a very different pattern of use from mine (which is what lead to me
work on the new version).)

>> - 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.
>
> That sounds like the better solution.  Even better if the old and the
> new code can be both in use at the same time (e.g. if you have
> converted some of your todo files but not all).

I want to be sure what you're saying here: are you saying there's
something better than making the old version obsolete?  Or are you
saying it is ok to make it obsolete?  (Your parenthetical example is a
bit confusing, because the old version only supports using one todo file
at a time.  I guess you could have several todos files, but to switch
between them you'd have to unload todo-mode.el, change the value of
todo-file-do and reload the package.  The fact that you can
simultaneously use multiple todo files is another big advantage of the
new version -- and probably also the main stumbling block in converting
from the new to the old format.)

>> - 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)?
>
> I don't see why we shouldn't keep him in the list of authors.

Ok.

>> - If Glenn Morris approves, can I install the patch I included for
>>   diary-lib.el?
>
> I'm OK with whatever he agrees with in this respect.

I agree with him that a hook would be better, but if I can't figure out
how to do it that way, I'll probably use the patch as a fallback.  (I
just saw your response to Glenn as I was about to post this; see my
response to him about the problems I see with adding a hook, though that
could well just be my lack of insight.)

>> - 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?
>
> It sounds borderline.

That's a bit intimidating.  Maybe the code Wolfgang Jenkner posted in
this thread could be used instead -- even better if it were just added
to Emacs.  Juri Linkov also posted one a little while ago, which was
actually essentially the same as the Common Lisp recursive definition.
Is this really subject to copyright?

>> - 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>--"
>
> Lots of packages don't follow this convention.  It's not a problem.

Ok.

>> - 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.
>
> Either way is fine by me, but a separate todo-mode Texinfo manual sounds
> perfectly acceptable.

I'll probably do that then, since it should be easier than trying to
pare it down.

Steve Berman