[cl-faq] Now, with less over-engineering!!

Sat Jan 14 23:29:53 CST 2006

Peter Seibel writes:
> As I started to think about actually editing the FAQ I came to my  
> senses and realized that I was completely missing the point of my own  
> Markup library with that \faq{\question{...}\answer{...}} nonsense.  
> So I wrote some code to dump the file out in a more normal Markup  
> form, taking advantage of the support for Emacs outline mode, etc.  
> The new source file is at the usual place:
> 
>    <http://www.lispniks.com/faq/faq.txt>
> 
> and the HTML at:
> 
>    <http://www.lispniks.com/faq/faq.html>
> 
> Anyone, who's got questions and answers in the old form should send  
> them along; I'll deal with converting them. But for future the format  
> is much simpler:
> 
>    *** Question text here, all one one line.
> 
>    Answer here using Markup conventions such as:
> 
>      blockquotes indented two spaces
> 
>    And
> 
>        (code examples indented four spaces)
> 
>    And \i{internal markup} like \b{this}
> 
> This makes the file much easier to edit and will hopefully enable me  
> to get to work actually, you know, editing.

This sounds insufficient, if we judge from the old FAQs.  For example,
there are also at least lists and blockquotes and code inside list
items as formating elements. And of course, nowadays there's a lot of
_urls_, even for book references (thanks to Amazon).

Christophe Rhodes used Docbook to generate his lispfaq.html.  Perhaps
we should use a sexpr markup?  But do we need to generate several
formats?

To edit it in a collaborative effort, I feel that a wiki would be
easer.  What about the wikipedia format?  It seems smart and has a
nice look. http://www.mediawiki.org/wiki/MediaWiki
Installing it is trivial, and starting the collaborative work will be
as simple as pasting the questions under this format on the main page:

* The comp.lang.lisp newsgroup
** [[What is the purpose of the comp.lang.lisp newsgroup?]]
** [[What is on-topic on comp.lang.lisp?]]
** [[What is off-topic on comp.lang.lisp?]]
** [[Can you help me with my homework?]]
** [[What should I do if I feel victimized?]]
* Introductory Matter and Bibliography of Introductions and References
** [[What is the difference between Scheme and Common Lisp?]]
** [[Lisp books, introductions, documentation, periodicals, journals, and conference proceedings.]]
** [[How can I improve my Lisp programming style and coding efficiency?]]
** [[Where can I learn about implementing Lisp interpreters and compilers?]]
** [[What is the "minimal" set of primitives needed for a Lisp interpreter?]]
** [[Lisp Job Postings]]
* Terminology
** [[I've heard the terms "Lisp-1" and "Lisp-2" \x{2013} what do they mean?]]
** [[What does CLOS, PCL, X3J13, CAR, CDR, ... mean?]]
** [[What do all those abbreviations mean?]]
* Programming questions
** [[How do I write a "Hello, World!" programme in Lisp?"]]
** [[Does anyone actually use flet?]]
** [[How do I split a string?]]
** [[Why doesn't Common Lisp have continuations?]]
** [[How does (defun car (x) (car x)) work?]]
** [[I want an array of foos, but (make-array 10 :initial-element (make-foo)) causes strange bugs. Why?]]
** [[How do I make an executable from my programme?]]
** [[How do I run my programme as a script, then?]]
** [[What is the Lisp equivalent of the __FILE__ and __LINE__ ANSI C preprocessor macros? How do I find out where an error occurred?]]
** [[Is there a GNU-Emacs interface to Lisp?]]
** [[What is garbage collection?]]
** [[How do I save an executable image of my loaded Lisp system? How do I run a Unix command in my Lisp? How do I exit Lisp? Access environment variables?]]
** [[I'm porting some code from a Symbolics Lisp machine to some other platform, and there are strange characters in the code. What do they mean?]]
** [[History: Where did Lisp come from?]]
** [[How do I find the argument list of a function? How do I get the function name from a function object?]]
** [[How can I have two Lisp processes communicate via unix sockets?]]
** [[How can I create a stream that acts like UNIX's /dev/null (i.e., gobbles any output and immediately signals EOF on input operations)?]]
** [[Read-time conditionalization of code (#+ #- and *features*)]]
** [[What reader macro characters are used in major Lisp systems?]]
** [[How do I determine if a file is a directory or not? How do I get the current directory name from within a Lisp  program? Is there any way to create a directory?]]
** [[When should I use a hash table instead of an association list?]]
** [[What is a "Lisp Machine" (LISPM)?]]
** [[How do I tell if a symbol names a function and not a macro?]]
** [[What is the equivalent of EXPLODE and IMPLODE in Common Lisp?]]
** [[Is Lisp inherently slower than more conventional languages such as C?]]
** [[Why does Common Lisp have "#'"?]]
** [[How do I call non-Lisp functions from Lisp?]]
** [[Can I call Lisp functions from other languages?]]
** [[I want to call a function in a package that might not exist at compile time. How do I do this?]]
** [[What is CDR-coding?]]
* Common Programming Pitfalls
** [[The read-eval-print loop is just sitting there after I've typed in my]]
** [[form. What's happening?]]
** [[Why can't I apply #'AND or #'OR?]]
** [[Why are my structure contents wrong?]]
** [[Why isn't there a DEEP-COPY function in the language?]]
** [[Why does (READ-FROM-STRING "foobar" :START 3) return FOOBAR instead of BAR?]]
** [[Closures don't seem to work properly when referring to the iteration variable in DOLIST, DOTIMES, DO and LOOP.]]
** [[What is the difference between FUNCALL and APPLY?]]
** [[Miscellaneous things to consider when debugging code.]]
** [[When is it right to use EVAL?]]
** [[Why does my program's behavior change each time I use it?]]
** [[When producing formatted output in Lisp, where should you  put the newlines (e.g., before or after the line, FRESH-LINE vs TERPRI, ~& vs ~% in FORMAT)?]]
** [[I'm using DO to do some iteration, but it doesn't terminate.]]
** [[My program works when interpreted but not when compiled!]]
** [[Why can't it deduce from (READ-FROM-STRING "foobar" :START 3)]]
** [[I used a destructive function (e.g. DELETE, SORT), but it didn't seem to work.  Why?]]
** [[After I NREVERSE a list, it's only one element long.  After I SORT a list, it's missing things.  What happened?]]
** [[Why does (READ-LINE) return "" immediately instead of waiting for me to type a line?]]
** [[I typed a form to the read-eval-print loop, but nothing happened. Why?]]
** [[DEFMACRO doesn't seem to work.  When I compile my file, LISP warns me that my macros are undefined functions, or complains  "Attempt to call]]
** [[Name conflict errors are driving me crazy! (EXPORT, packages)]]
* Lisp Implementations and Mailing Lists
** [[Free Common Lisp implementations.]]
** [[Where can I get a copy of the ANSI Common Lisp standard? What is ISO Lisp?]]
** [[Commercial Common Lisp implementations.]]
** [[[4-1a] Lisp to C translators]]
** [[Scheme Implementations]]
** [[Free Implementations of Other Lisp Dialects]]
** [[Commercial Implementations of Other Lisp Dialects]]
** [[What is Dylan?]]
** [[What is Pearl Common Lisp?]]
** [[What Lisp-related discussion groups and mailing lists exist?]]
* Object-oriented Programming in Lisp
** [[What is CLOS (PCL) and where can I get it? How do you pronounce CLOS?]]
** [[What documentation is available about object-oriented programming in Lisp?]]
** [[How can I write a function that can access defstruct slots by name?  I would like to write something like  (STRUCTURE-SLOT]]
** [[How can I list all the CLOS instances in a class?]]
** [[How can I store data and CLOS instances (with possibly  circular references) on disk so that they may be retrieved at some later time? (Persistent Object Storage)]]
** [[Given the name of a class, how can I get the names of its slots?]]
** [[Free CLOS software.]]
** [[Common CLOS Blunders]]
* FTP Archives and Resources
** [[Where can I find free lisp compilers or interpreters?]]
** [[Where can I buy a professional lisp system?]]
** [[What books should I read to learn more about lisp?]]
** [[What online resources are there for lisp users?]]
** [[General information about FTP Resources for Lisp]]
** [[Repositories of Lisp Software]]
** [[Publicly Redistributable Lisp Software]]
** [[Formatting code in LaTeX (WEB and other literate programming tools)]]
** [[Where can I get an implementation of Prolog in Lisp?]]
** [[World-Wide Web (WWW) Resources]]
* Lisp Window Systems and GUIs
** [[How can I use the X Window System or other GUIs from Lisp?]]
** [[What Graphers/Browsers are available?]]
* Debunking myths
** [[When did LISP die?]]
** [[Why is LISP slow?]]
** [[How do I manipulate symbols with IMPLODE/EXPLODE?]]
** [[Why doesn't lisp have structures or arrays?]]

-- 
__Pascal Bourguignon__                     http://www.informatimago.com/

HEALTH WARNING: Care should be taken when lifting this product,
since its mass, and thus its weight, is dependent on its velocity
relative to the user.