Re: [emacs-wiki-discuss] Re: Documentation

[Michael Alan Dorman]

address@hidden writes:
> Most of what I don't get is planner's relation to emacs-wiki.
> Perhaps it's my use model.  I look at the planners and wikis as
> fundamentally unrelated items.

Planner is a toolset for organizing free-form interrelated information
that (intentionally) formats its data in such a way that it may use
emacs-wiki to publish that content.

> I see planners as something personal that no one but me ever sees,
> where as documentation/wikis are specifically for publishing your
> thoughts so others can read them.

There's nothing that says you have to make your planner public.

In fact, there isn't any requirement that you even publish it to HTML
pages at all---you could exist entirely within the planner environment
within emacs very easily.

> I think I've also seen mentions of M-x remember, Muse, and BBDB here. 
> I'd be interested in how these relate to emacs-wiki and/or planner 
> also.

Muse is an alternative publishing back-end.

Remember, along with its various hooks into gnus and bbdb and so
forth, is a tool to help you easily import information into your
planner from various sources.

> One thing which I personally would find helpful, at least on the
> wiki, would be if people could explain what they're lisp code
> contributions actually do and where to put them.  For example, from
> the emacswiki site:

The piece of code you reference is simply a succinct way to define a
number of parallel wiki projects.  Rather than saying:

(setq emacs-wiki-projects ("Foo"
                           (emacs-wiki-directories "~/Wiki/Foo")
                           (emacs-wiki-home-page . "WikiIndex.html")
                           (emacs-wiki-publishing-directory . 
"~/public_html/Foo")
                           (emacs-wiki-project-server-prefix . 
"http://localhost/~mdorman/Foo/";)
                          ("Bar"
                           (emacs-wiki-directories "~/Wiki/Bar")
                           (emacs-wiki-home-page . "WikiIndex.html")
                           (emacs-wiki-publishing-directory . 
"~/public_html/Bar")
                           (emacs-wiki-project-server-prefix . 
"http://localhost/~mdorman/Bar/";)
                           ...)

where the code differs only in whether it includes the string "Foo" or
the string "Bar", you can define the function, then use it as shown on
the wiki.  It's just a way to save typing.

I guess what you've proven is that there's a reason to include
docstrings in defuns. ;)
                          
> I think there is an assumption made by many emacs users that
> everyone knows lisp, and knows how things are supposed to work wrt
> emacs.

I have been mistaken for someone who knows lisp.  Woohoo!

Actually, that bit of lisp you quoted took me far too long for what it
does, in large part because I am not at all comfortable with lisp.
I'll go further---I suck at lisp.

> Unfortunately, I seldom know where I'm supposed to put them. I tend
> not to want to blindly throw things in my .emacs file, partially out
> of fear that it will break something I don't know how to fix, but
> also because I think that my .emacs file is already too big and
> unwiedly.

Much of the code you're going to find on web pages (as opposed to
being in files you can then download) is probably intended for your
.emacs.

Certainly, stuff that sets variables (setq, etc) is probably intended
for such.

But you have a lot of flexibility---remember, emacs is a programming
language masqerading as an editor.  You could dump the function I
wrote into some file in some special directory you have for your
personal emacs extensions, and then just call it from your .emacs.  Or
you could put it directly in your .emacs.  Or whatever.

I will observe that if you are worried that including something in
your .emacs file will break other things, make a backup copy before
you make changes about which you are uncertain---that way, if
something does break, you are guaranteed to be able to fix it, by
simply restoring your backup.

Mike
-- 
Give me a Leonard Cohen afterworld -- Nirvana