[cffi-devel] Re: [patch] lots of new manual changes

[Luís Oliveira]

Stephen Compall <s11 at member.fsf.org> writes:
> I added two more broken cross-references, one to libtool, and one to
> asdf.  I'll fix gendocs.sh for libtool later, but would appreciate
> suggestions (other than host an asdf manual myself) for asdf.

My suggestion is that we should create a common-lisp.net project to host
ASDF, its manual and other ASDF-related stuff. :-)


> Details follow; patch (140k) at
> http://csserver.evansville.edu/~sc87/cffi/cffi-manual-2s11.darcs.patch

Great stuff, the manual is starting to look great.


>   - Use @sc and @result to make REPL examples pretty, and move them into
>     @example sections.

Is this really necessary? @sc doesn't play very well with colorize,
@example's aren't colorized and adding @r to the comments breaks the
colorize script.

I can be convinced that colorizing the examples is silly (specially in
this ad-hoc way), but if not I'll revert these changes to the
examples. Please let me know what do you think about this before I push
the patches.


>   - Use @unnumberedsec in dictionary nodes instead of @heading, and
>     @code the names.
>   - Use new @seealso macro for "See Also" xrefs.

I kind of prefer not to use @code in these two situtations. Looks better
to me probably because that's what both Lispworks's FLI manual and the
Texinfo version of the CLHS do. And that was the style I was going
for. Also, for some weird reason it doesn't render very well in Safari
wrt spacings.

BTW, Is there a way to write some sort of macro, say refsection{foo}
that'd expand into:

  @node foo
  @unnumberedsec @code{foo}

?

Anyway, nice job!

-- 
Luís Oliveira
luismbo (@) gmail (.) com
Equipa Portuguesa do Translation Project
http://www.iro.umontreal.ca/translation/registry.cgi?team=pt