Comments on ElispCookbook

This page needs more cleanup. And it should be broken up, its content moved to different pages.

DrewAdams 2013-01-27 19:46 UTC


I agree!

AlexSchroeder 2013-01-27 20:46 UTC


Whoa. If you do that you need an index. this is so useful in it’s current form.

NicFerrier 2013-01-27 21:48 UTC


There already is an index: the TOC. This page would become essentially the intro plus a list of links to what are currently the main sections, each become a separate page. Some tiny sections could alternatively be left here.

But perhaps also some stuff here could be removed altogether, or replaced by something better, during cleanup. One criterion should be whether material truly “demonstate[s] basic elisp programming operations in the spirit of the o’reilly cookbook series”.

Anyway, I’m probably not going to be the one who cleans this up anymore or reorganizes it. Just giving my 2 cents. If I were a novice (or not so novice) looking for an Elisp cookbook, this would not be it (so far). I pulled out a bit of stuff that was inappropriate, but it still needs some cleanup, IMHO. – Drew

DrewAdams 2013-01-28 00:16 UTC


No, that’s not an index. That’s a TOC.

I often go to the cookbook page and hit Ctrl-F to find something. That’s what an index would do. The TOC doesn’t do the same job at all.

NicFerrier 2013-01-28 00:54 UTC


True, splitting the page would not allow searching all of this material together.

It’s unclear to me how searching here would be very useful for the mix of topics that are here, however. Can you give an example (hypothetical or real) of searching for something here across the sections?

I don’t doubt that you have a use case, but I don’t really see it yet. There is no crying need to split the page, if there is really some good case for keeping it together. More info, please, if possible.

DrewAdams 2013-01-28 06:05 UTC


Actually, you could split the content up into multiple pages A, B and C and use transclusion.

Each page would follow this pattern:

== A ==
([Self:action=edit class="comment">;id=A Edit Section A])

... A!

We then replace the main page with the following:

<include "A">
<include "B">
<include "C">

The result would be:

A
(Edit section A)
… A!
B
(Edit section B)
… B!
C
(Edit section C)
… C!

The table of contents may or may not work with the included elements, I haven’t tried.

AlexSchroeder 2013-01-28 07:32 UTC


Sounds interesting. I’ll leave it to someone else to decide and to make the changes if decided. Where are such things as ([Self:action=edit;id=A Edit Section A]) documented?

DrewAdams 2013-01-28 14:01 UTC


A while back, I started working on splitting up this page – ElispStrings, ElispKillRegion, ElispKillLine, ElispNumbers, ElispLists, ElispVectors, ElispHashes, ElispFileOps, ElispDatesAndTimes, ElispRegularExpression – but didn’t finish. I was going to keep ElispCookbook but make it an index linking to those pages.

AaronHawley 2013-01-28 14:44 UTC


Drew, ([Self:action=edit;id=A Edit Section A]) isn’t documented anywhere. It’s standard wiki markup I’d add such that readers get the impression that they can edit the various sections of the page. Otherwise they won’t know what to edit. (The “Self:” prefix is from InterMap.)

AlexSchroeder 2013-01-28 15:20 UTC


What Aaron describes is what I had in mind. Alex: thx for the info.

DrewAdams 2013-01-28 16:11 UTC


I think my approach would be to write a plugin that could index a namespace, eg: ElispCookbook-* could be indexed, so if you had ElispCookbook-Strings and ElispCookbook-Lists it would index those.

NicFerrier 2013-02-02 16:35 UTC


The cookbook needs to show how to define basic functions. Because Lisp.

mcandre 2013-02-22 00:34 UTC


The cookbook shuold contain Emacs Lisp programming recipes presented in a special Problem/Solution/Discussion format, just as the O’Reilly? cookbook series of books.

XueFuqiao 2013-02-22 02:26 UTC


Unfortunately I don’t know the series… Maybe you can change one piece of the page to provide an example?

AlexSchroeder 2013-02-22 06:36 UTC


The following two recipes are quoted from chapter 1 and chapter 7 from “R Cookbook”, HTH:

1.1 Downloading and Installing R

Problem
You want to install R on your computer.

Solution
Windows and OS X users can download R from CRAN, the Comprehensive R Archive
Network. Linux and Unix users can install R packages using their package management
tool:

Windows
  1. Open http://www.r-project.org/ in your browser.
  2. Click on “CRAN”. You’ll see a list of mirror sites, organized by country.
  3. Select a site near you.
  4. Click on “Windows” under “Download and Install R”.
  5. Click on “base”.
  6. Click on the link for downloading the latest version of R (an .exe file).
  7. When the download completes, double-click on the .exe file and answer the
  usual questions.

OS X
  1. Open http://www.r-project.org/ in your browser.
  2. Click on “CRAN”. You’ll see a list of mirror sites, organized by country.
  3. Select a site near you.
  4. Click on “MacOS X”.
  5. Click on the .pkg file for the latest version of R, under “Files:”, to download it.
  6. When the download completes, double-click on the .pkg file and answer the
  usual questions.

Linux or Unix
  The major Linux distributions have packages for installing R. Here are some
  examples:
  | Distribution      | Package name |
  | Ubuntu or Debian  | r-base       |
  | Red Hat or Fedora | R.i386       |
  | Suse              | R-base       |
  Use the system’s package manager to download and install the package. Normally,
  you will need the root password or sudo privileges; otherwise, ask a system ad-
  ministrator to perform the installation.

Discussion
Installing R on Windows or OS X is straightforward because there are prebuilt binaries
for those platforms. You need only follow the preceding instructions. The CRAN Web
pages also contain links to installation-related resources, such as frequently asked
questions (FAQs) and tips for special situations (“How do I install R when using Win-
dows Vista?”) that you may find useful.

Theoretically, you can install R on Linux or Unix in one of two ways: by installing a
distribution package or by building it from scratch. In practice, installing a package is
the preferred route. The distribution packages greatly streamline both the initial in-
stallation and subsequent updates.

On Ubuntu or Debian, use apt-get to download and install R. Run under sudo to have
the necessary privileges:

  $ sudo apt-get install r-base

On Red Hat or Fedora, use yum:

  $ sudo yum install R.i386

Most platforms also have graphical package managers, which you might find more
convenient.

Beyond the base packages, I recommend installing the documentation packages, too.
On my Ubuntu machine, for example, I installed r-base-html (because I like browsing
the hyperlinked documentation) as well as r-doc-html, which installs the important R
manuals locally:

  $ sudo apt-get install r-base-html r-doc-html

Some Linux repositories also include prebuilt copies of R packages available on CRAN.
I don’t use them because I’d rather get my software directly from CRAN itself, which
usually has the freshest versions.

In rare cases, you may need to build R from scratch. You might have an obscure, un-
supported version of Unix; or you might have special considerations regarding per-
formance or configuration. The build procedure on Linux or Unix is quite standard.
Download the tarball from the home page of your CRAN mirror; it’s called something
like R-2.12.1.tar.gz, except the “2.12.1” will be replaced by the latest version. Unpack
the tarball, look for a file called INSTALL, and follow the directions.

See Also
R in a Nutshell (O’Reilly) contains more details of downloading and installing R, in-
cluding instructions for building the Windows and OS X versions. Perhaps the ultimate
guide is the one entitled R Installation and Administration, available on CRAN, which
describes building and installing R on a variety of platforms.

This recipe is about installing the base package. See Recipe 3.9 for installing add-on
packages from CRAN.

And:

7.1 Getting the Length of a String

Problem
You want to know the length of a string.

Solution
Use the nchar function, not the length function.

Discussion
The nchar function takes a string and returns the number of characters in the string:
  > nchar("Moe")
  [1] 3
  > nchar("Curly")
  [1] 5
If you apply nchar to a vector of strings, it returns the length of each string:
  > s <- c("Moe", "Larry", "Curly")
  > nchar(s)
  [1] 3 5 5
You might think the length function returns the length of a string. Nope—it returns
the length of a vector. When you apply the length function to a single string, R returns
the value 1 because it views that string as a singleton vector—a vector with one element:
  > length("Moe")
  [1] 1
  > length(c("Moe","Larry","Curly"))
  [1] 3

I’d be glad to help improve this page, but I can’t understand some recipes (my elisp level sucks).

XueFuqiao 2013-02-22 12:23 UTC


That again would work better if we had a single page per recipe with some combination system to combine the cookbook pages into a single page.

The single page would contain the overview (first h2 of the detail page, say) and a link to the detail page. The detail page could contain much more detail, including probably several “How do I?” type examples.

If one overview could be built then another overview could be built, possibly collecting all the “How do I?” type examples into a summary with links back to the detail pages.

Of course, this is a lot more programming. But programming is fun.

NicFerrier 2013-02-23 14:51 UTC


As far as I can tell, no programming is necessary at the moment?

AlexSchroeder 2013-02-23 14:59 UTC


That’s right, it would take lots of text hacking at the moment and I think you’d end up with something less usable.

The programming would be in building a more complex system.

NicFerrier 2013-02-23 15:03 UTC


PS the stuff above is surely O’Reilly (C)?

NicFerrier 2013-02-23 15:07 UTC


Before spending any time on it, I’d prefer it if the text got written first: split up the page, decide upon a page naming convention or link to the child pages from the main page, that sort of stuff. Nothing more annoying than coding and testing stuff that isn’t going to be used.

AlexSchroeder 2013-02-23 15:16 UTC


Well, I wasn’t about to do it since I think until we can do it there is no point in breaking up the page and as you know I’m busy.

My point above still holds, the page works right now because you can search through it. So breaking it up without doing what I’m talking about will be a backward step.

What could be done, I guess, is adding detail pages for each section in the style of Q&A.

NicFerrier 2013-02-23 15:27 UTC


Please make sure you contribute only your own work. IP numbers are made available via the page history. If you want to keep it a secret, you need to use Tor. See TextFormattingRules for how to format text. See StyleGuide for the suggested writing style on this wiki.

Please answer this captcha: