robert-strandh/cl-reference

Reference manual for the Common Lisp programming language.

cl-reference's Issues

How should the glossary be organized?

I think the reference manual needs a glossary.

But I want the glossary to be better than that of the HyperSpec. I
often find myself looking at a glossary entry in the HyperSpec as a
result of having clicked on a link in an entry for some operator, but
then I am "stuck" on that glossary entry, because there is no link
from it to a section that explains the concept in detail.

As an example of what I am referring to, take for example a page such
as ADJUST-ARRAY. Observe that the argument named ELEMENT-TYPE is
specified to be a TYPE SPECIFIER and that TYPE SPECIFIER is a link.
Clicking on that link, one ends up in the glossary entry for TYPE
SPECIFIER as is appropriate. But it would be good to have a link from
the glossary entry that goes to section 4.2.3 that discusses in more
detail what a type specifier is.

In my latest experiment, I used the HYPERREF LaTeX package and turned
the word ATOM into a link to the SECTION that takes about atoms. What
I would really like to do is to introduce an indirection through the
glossary. In other words, I would like each glossary entry to have a
label, and I would like the link on ATOM to refer to that label. Then
I want the glossary entry to contain a link to the section on ATOMs,
with a text such as: "for more information on the type ATOM, see
section...".

I don't think I have ever created a glossary in a document like this,
so I need to figure it out, unless someone else has the time to do
so. It is important that each entry can be associated with a label so
that it can be linked to.

Why not Asciidoc?

There is a lightweight markup language which is probably superior to LaTeX in the domain of technical programming documentation, and it's AsciiDoc, in it's current incarnation called Asciidoctor. As this project is in the very beginning, maybe it's not late to change to that markup? It's a lot simpler than LaTeX and has native conversion to HTML and directly to PDF.

Dependencies to compile this?

I've been trying to compile this by calling make (mostly to have a look at what's there so far), but it keeps failing. Could you please list the dependencies needed to compile this?

Missing dependencies for make(1)ing

The README could include a recommendation to make sure fig2dev is installed, probably via transfig.