Improve the syntax of manual.lisp

[aadcg]

Our manual.lisp is hard to maintain since it's not very "comfortable" to edit a bunch of strings.

The goal is to preserve all of the functionality, while eliminating the need to surround the actual textual content with quotes (").

One possible solution would be to change the Lisp reader. There might be others.

Excribe might be a good source of inspiration to explore a solution that tames the Lisp reader. It's basically LaTeX but with a proper language (think scribble from Racket).

I played with it for a little while, but I still need to study it properly.

Generating a file with the following contents:

(document :title "Hello World!" (p[A short doc.]))

doesn't yield a full HTML document but I haven't spent enough time studying the syntax.

EXSCRIBE> (exscribe-load-document "/path/to/test.srcbl")
<table width="100%"><tr><td align="center" bgcolor="#FFDB31"><font size="10" face="sans-serif" color="black"><b>Hello World!</b
></font
></td
></tr
></table
><p>A short doc.</p
>
T

This is not a priority. It's post 3.0.

[aartaka]

Why is manual unmaintainable? What are the problems with it?

[Ambrevar]

Didn't exscribe, looks nice.

Agreed with @aartaka though, there should be a strong incentive for moving doc system.
One could be translation support.

Before moving to something else, it must pass a crucial test: Can the new doc system generate documentation dynamically depending on the browser state? For instance, bindings are updated dynamically.

[aadcg]

Why is manual unmaintainable? What are the problems with it?

The issue is that you have to write the textual content as strings. Compare writing a book in LaTeX or Org and in the way we handle our manual.

Also, in #2655, why haven't I drafted a manual section directly in manual.lisp?

[aadcg]

Agreed with @aartaka though, there should be a strong incentive for moving doc system.
One could be translation support.

We don't have a doc system. Our manual is a regular lisp program. Excribe changes the Lisp reader so that writing a manual is sane.

Translation is one incentive. Other include being able to generate HTML, Man pages, pdf and potentially other output formats from a single document.

Before moving to something else, it must pass a crucial test: Can the new doc system generate documentation dynamically depending on the browser state? For instance, bindings are updated dynamically.

Our manual will still be a Lisp program. But with the reader set to something sane. I can't think of any reason why that wouldn't work.

Still, making this change requires time and it's not a priority right now.

[aadcg]

After talking with @aartaka, he made me realize that moving to excribe is not a good idea. I didn't take into account that we use spinneret tags outside of manual.lisp (for instance, in describe.lisp).

I'll rewrite my top post.