[racket] 18 scribble-created files

Ah, I misread the your original question as "can an installed package
have fewer files?".

For rendering a document independent of a package installation, I think
we're pretty close to a good answer with

 #lang racket
 (require scribble/render
          (prefix-in html: scribble/html-render)
          setup/xref)

 (render (list (dynamic-require ....scrbl... 'doc))
         (list ...name...)
         #:render-mixin (compose html:render-multi-mixin
                                html:render-mixin)
         #:dest-dir "/tmp/page"
         #:xrefs (list (load-collections-xref))
         #:redirect
         "http://pkg-build.racket-lang.org/doc/local-redirect/index.html")

The "pkg-build.racket-lang.org" URL (as opposed to
"docs.racket-lang.org") is because the rendered document might contain
links to other packages that are not in the in the main distribution.
We plan to eventually make the "pkg-build" docs be the ones at "docs.".


That still leaves "manual-fonts.css", etc., in the output. It turns out
that there's a way to redirect those, but the interface has three
problems: it's not properly documented, the configuration is
inconvenient to pass through `render`, and and you still have to list
the individual files.

But, for now, you can replace the `#:render-mixin` argument above with

         #:render-mixin (compose replace-support-files-mixin
                                 html:render-multi-mixin
                                 html:render-mixin)

using this `replace-support-files-mixin` definition:

 (define shared-style-files
   (list "scribble.css"
         "scribble-style.css"
         "racket.css"
         "manual-style.css"
         "manual-racket.css"
         "manual-racket.js"
         "manual-fonts.css"
         "scribble-common.js"))

 (define (replace-support-files-mixin %)
   (class %
     (super-new [alt-paths (for/list ([f (in-list shared-style-files)])
                             (cons (collection-file-path f "scribble")
                                   (url->string
                                    (combine-url/relative
                                     (string->url
                                      "http://pkg-build.racket-lang.org/doc/")
                                     f))))])))


At Sun, 23 Nov 2014 22:28:00 -0500, Neil Van Dyke wrote:
> Thanks, Matthew.  I have to rework McFly and my package release setup 
> for the new package system soon, and I plan to work around the 18 files 
> then.
> 
> I don't know that my plan is relevant to anyone else, but here it is:
> 
> * Make distributions (and packages?) include the documentation files 
> however they're generated by the current release version of Racket at 
> the time the package version is released.
> 
> * Host the package version distributions (with versions in URLs) on my 
> Web site.  Probably URLs like 
> "http://example.com/racket/<PACKAGENAME>/<VERSIONSTRING>/".
> 
> * Change how I make the Web home page for each package.  Currently, each 
> home page is a verbatim copy the Scribble-produced files for the latest 
> released version of the package.  How I plan to change this is, instead 
> of using the Scribble-produced 18 files verbatim, a script will take 
> only the generated `.html` file and any image files, and tweak the HTML 
> slightly to fit into the Web site without all the dependencies.  That 
> works around the 18 files bloat for me, although I have to do upfront 
> work, and I might have to do maintenance work some of the times that a 
> new Racket version changes the HTML.
> 
> * Change the package home page urls (e.g., 
> "http://example.com/racket-charterm/") to fit within the same URL tree 
> that serves the new package versions (e.g., 
> "http://example.com/racket/charterm/").
> 
> Basically, I'm trying to get back to good-quality package version 
> releases being quick&easy to do.  The overhead of additional upfront and 
> ongoing maintenance work on tools is not entirely consistent with 
> quick&easy productivity on the packages, but hopefully I'll find time 
> around Christmas.
> 
> Neil V.