Re: [Chicken-users] ideas

[Peter Keller]

On Wed, Aug 14, 2002 at 12:40:30PM +1200, Tony Garnock-Jones wrote:
> scribe (available via the bigloo page) has worked *very* well for me
> in recent months. Full Scheme, compiles to LaTeX or HTML... the PDF
> it generates is goodlooking (as per Tex's usual) and the HTML is at least
> acceptable...
> 
> Maybe some kind of SXML-DSSSL hybrid monster?

LaTeX is supported everywhere and has books out there that explain it
to the ends of the earth. SXML-DSSSL sounds too buzzwordy and feels
like you'd be fighting with it instead of writing the docs--but that is
a totally unsubstantiated thought.

The only problem with LaTeX, is you cannot easily generate man pages
with them, so those would have to be done in nroff or something similar.

Scribe looks like a scheme representation of LaTeX. I might be convinced
that Scribe would be ok, but honestly, LaTeX is really good at describing
things like manuals for stuff.

Things like this irk me in scribe(which I haven't used, but have poked
through the manual):

Look at section 3.13 Enumerations.

(itemize (item [A first item.])
         (item [A ,(bold "second") one.])
         (item [Lists can be nested. For instance that item contains a
           ,(tt "description"):
           ,(description (item :key (bold "foo")
                               [is a usual Lisp dummy identifier.])
                         (item :key (bold "bar")
                               [is another one.])
                         (item :key (list (bold "foo") (bold "bar"))
                               [A description entry may contain more than
                                one keyword.]))])
         (item [The last ,(tt "itemize") entry contains an ,(tt "enumerate"):
           ,(enumerate (item "One.") (item "Two.") (item "Three."))]))

The equivalent(off the cuff) LaTeX would be:

\begin{itemize}
\item A first item
\item A \bf{second} item
        \begin{itemize}
        \item 
                Lists can be nested. For instance that item contains a 
\tt{description}:
        \item[\bf{foo}]
                is a usual Lisp dummy identifier.
        \item[\bf{bar}]
                is another one.
        \item[\bf{foo bar}]
                A description may contain more than one keyword.
        \item The late \tt{itemize} entry contains an \tt{enumerate}:
                \begin{enumerate}
                        \item One.
                        \item Two.
                        \item Three.
                \end{enumerate}
        \end{itemize}
\end{itemize}

While technically these two constructs:

\begin{itemize}
\end{itemize}

and 

(itemize ... )

are the same(the ')'parenthesis is like the closing \end{itemize}),
I feel that the "look and feel" of the manual description in Scribe
gets in the way from actually writing the manual. :) In LaTeX, the first
thing they teach you is to write the content first, and then go back and
"pretty it up". I don't know if the same can be said for scribe, where
you HAVE to write the document according to the stricter parsing rules
of Scribe(as comapred to scribe) before you can even see anything at all.

That said, I'd still use Scribe because it basically is LaTeX, just with a
worse syntax for the problem domain it is representing->This is PURELY
a SUBJECTIVE view.

> I'm also interested in getting docstrings into Chicken somehow. How
> tricky do you think that might be, Felix?
> 
> (define (myfunction foo bar)
>   "Returns the result of mapping blorch over foo, followed by appending bar"
>   ...)

How does this handle multiline comments?

> (define (myfunction foo bar)
>   "Returns the result of mapping blorch over foo, followed by appending bar"
        "while sideffecting the qux object."
        
-pete