[plt-scheme] Re: SRFI documentation

From: Eli Barzilay (eli at barzilay.org)
Date: Tue Jun 30 12:42:05 EDT 2009

On Jun 30, Hugh Myers wrote:
> Little point? Using SRFI-13 as an example, printed, it runs to 30
> pages. Printed duplex, runs to 15.
> 
> 1. you dislike trees?
> 2. you disdain manuals (printed that is)?
> 
> I understand that 'real' scheme programmers don't need documentation,
> but this seems a little extreme.

You forgot the "within the context of PLT" part...  In general, of the
two documentation formats, the HTML one is important in this context
because it is used by the help system -- so it made sense to work on
making those index wrappers so that help works with these manuals too.
A side benefit is that these external documents are already in HTML
form so they're viewable alongside the rest of the plt documentation
when used from the help system.

We would probably have had to work more if, for example, the srfi
documents were all in PDF -- then we'd need to work on converting the
PDFs into html.  Another option is if we'd use PDFs for our help
system, and then it would make a lot of sense to work on converting
the srfi documents to PDF.

But as things stand now, converting them is putting work into PDF
formats that are not used in the help system and not distributed with
the plt installers -- which is why I said that there is little point
in doing so.  If printed papers are the main medium that you're using
to read the manuals, then obviously it makes a lot of sense for you.
Also, if there is some relatively painless way to convert a directory
of random HTML (and they *are* random, since AFAICT, the pages come
directly from srfi authors that can do whatever they) into better
looking PDFs on Linux then we can integrate that into our nightly
build and create PDFs for them too.  I don't know of any such tool.


> On Tue, Jun 30, 2009 at 10:24 AM, Eli Barzilay<eli at barzilay.org> wrote:
> > On Jun 30, Hugh Myers wrote:
> >> The process of converting from HTML to PDF is not a 'new' problem---
> >> so yes it could magically be done.
> >
> > Most of the manuals are written in scribble form, which has rendering
> > backends for latex and for html.  The srfi and r6rs documentations are
> > used "as is" -- directly from the respective sources, and there is a
> > thin wrapper that arranges the index.  There is little point in
> > turning them into PDF form within the context of PLT.
> >
> > --
> >          ((lambda (x) (x x)) (lambda (x) (x x)))          Eli Barzilay:
> >                    http://barzilay.org/                   Maze is Life!
> >
> _________________________________________________
>   For list-related administrative tasks:
>   http://list.cs.brown.edu/mailman/listinfo/plt-scheme

-- 
          ((lambda (x) (x x)) (lambda (x) (x x)))          Eli Barzilay:
                    http://barzilay.org/                   Maze is Life!


Posted on the users mailing list.