On Fri, 08 Jan 2016 11:19:34 +0100
l...@gnu.org (Ludovic Courtès) wrote:
> Eric Bavier <ericbav...@openmailbox.org> skribis:
>
> > From c8a0086db4d78091e06326a5ffe55a7bf2543091 Mon Sep 17 00:00:00 2001
> > From: Eric Bavier <bav...@member.fsf.org>
> > Date: Fri, 18 Dec 2015 19:29:22 -0600
> > Subject: [PATCH] gnu: unison: Add "doc" output.
> >
> > * gnu/packages/ocaml.scm (unison)[source]: Use svn-fetch with snippet.
> > [outputs]: New field.
> > [native-inputs]: Add ghostscript, texlive, hevea, and lynx.
> > [arguments]: Add 'install-doc phase.
>
> [...]
>
> > + (snippet
> > + `(begin
> > + ;; The svn revision in the release tarball appears to be
> > + ;; artificially manipulated in order to set the desired point
> > + ;; version number. Because the point version is calculated
> > during
> > + ;; the build, we can offset pointVersionOrigin by the desired
> > + ;; point version and write that into "Rev: %d". We do this
> > rather
> > + ;; than hardcoding the necessary revision number, for
> > + ;; maintainability.
>
> Fun. :-)
>
> > + (with-atomic-file-replacement "src/mkProjectInfo.ml"
> > + (lambda (in out)
> > + (let ((pt-ver (string->number (third (string-split
> > ,version #\.))))
> > + (pt-rx (make-regexp "^let pointVersionOrigin =
> > ([0-9]+)"))
> > + (rev-rx (make-regexp "Rev: [0-9]+")))
> > + (let loop ((pt-origin #f))
> > + (let ((line (read-line in 'concat)))
> > + (cond
> > + ((regexp-exec pt-rx line)
> > + => (lambda (m)
> > + (begin
>
> ‘begin’ can be omitted here…
>
> > + ((regexp-exec rev-rx line)
> > + => (lambda (m)
> > + (begin
>
> … and here.
>
> > + (for-each (lambda (f)
> > + (install-file f doc))
> > + (map (lambda (ext)
> > + (string-append
> > + "doc/unison-manual." ext))
> > + '("ps" "pdf" "dvi" "html")))
>
> What about installing only HTML?
>
> I find that HTML (and Info, and man) is more convenient to read on-line
> than PDFs. We rarely include PDF documentation in packages.
I sometimes find PDF documentation more visually appealing, but only if
they having functioning hyperlinks. Which unison's pdf docs lack,
so yes, I think we can install just the HTML.
> Of course, avoiding PDF/PS/DVI allows us to remove the dependency on
> TeX Live. Last, from discussions I heard at the Reproducible Build
> Summit, I think DVIs and maybe PS/PDFs are not bit-reproducible
> out-of-the-box.
However, it appears the unison-manual.tex needs to be run through LaTeX
at least once in order to get a TOC for hevea to include in the html
output. So it seems we can't remove TeX Live. Sigh...
> WDYT?
I don't want to spend much more time on this, so I think I'll push a
slight modification of this patch that just doesn't install the pdf,
ps, and dvi output for the sake a reproducibility.
> Maybe we should have a policy on how to choose the installed
> documentation formats.
Info > HTML > man > txt > PDF > PS ?
> Thanks for finding out how to build documentation from source!
No problem; kinda fun. :)
`~Eric
