Reading and Understanding Common Lisp (HyperSpec) Documentation

Question

In trying to gather a deeper familiarity with Common Lisp's tools, I found myself struggling when reading the documentation. Namely, it is difficult to comprehend what the usage of the macro in question would look like.

For instance, consider this:

do ({var | (var [init-form [step-form]])}*) (end-test-form result-form*) declaration* {tag | statement}*

How does one interpret the parentheses? Do the round parentheses () correspond to a Lisp list? What is the vertical bar? Curly braces? Asterisk?

I can mostly read the Unix man-pages and understand their syntax well; however, it seems that something entirely different is going on here.

Kwan

Have you read 1.4.1 & specifically 1.4.1.2? – Resound

Missed it. Thanks! – Kwan

ENBF – Botel

Answer 1

This is an expansion of my comment which I think serves as an answer.

First of all remember that the CLHS is, well, a specification: it's often not terribly good introductory material, although many people have learned CL from it of course. Some of the notation is also easier to read in the paper (or PDF) versions of the spec: although the conversion to HTML is pretty good (and was heroic at the time) it's not always completely right: if you can get a paper copy it is better in some cases.

That being said: section 1.4.1 has notational conventions, and section 1.4.1.2 specifically deals with the BNF variant used in the spec.

Resound

Thanks for teaching me about the BNF! I knew I was missing something! :) – Kwan

This reference is helpful for new learners: jtra.cz/stuff/lisp/sclr/index.html – Reversion