[mod_gnutls-devel] DOCS

[Daniel Kahn Gillmor]

Hi Bas--

On 02/23/2014 02:42 PM, Bas van den Dikkenberg wrote:

> I suggests that we stop generating the  pdf and html during the build process, and just include them in the source.
> All the mayor distro's you can specify in build file(s) what doc files are so I think should be more than enough don't you think so.

I think i'm going to push back on this one a bit, for a couple reasons:

 (a) i want people to be able to rebuild the package -- this means i
want them to be able to rebuild the documentation as well, since that's
an important part of the package.

 (b) in general, in debian at least, there's an expectation that
anything which can be generated from source should be done during the
build process.  This helps us catch when some things can't be built on
some architectures (like the missing pandoc on s390x, as you point out)

 (c) I don't like the idea of putting generated files under revision
control, and i also don't like the idea of shipping a tarball that
differs from what's in revision control if we can help it.


That said, i don't think we need to generate a pdf from the manual, and
pandoc is pretty heavyweight for what we're doing here, though it does
make a nice table of contents and cross-referenced hyperlinks, which
other markdown interpreters don't do.

So i see a few possible ways forward:

 0) switch to markdown entirely from pandoc and just drop generation of
the pdf.  (note that /usr/bin/markdown from the markdown package doesn't
actually generate a full HTML file, so something would need to be done
about the headers and footers)

 1) drop generation of the pdf; during documentation build, detect if
pandoc exists or not, and if not, invoke markdown instead (this would
mean build-depending on pandoc | markdown, and it would have the weird
effect of having the documentation on s390x look different from the
documentation on other platforms)

 2) ship a separate architecture-independent libapache2-mod-gnutls-doc
package, so that the documentation only has to be built on one platform
to be shippable on all of them.  this seems a little weird given that
there is not a lot of content to put in this package other than the html
file and the pdf.

 3) go through the source code and insert as much of the contents of the
manual directly as comments, and generate things using doxygen, which i
think is sufficiently cross-platform.

do any of those sound plausible to you?

	--dkg

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 1010 bytes
Desc: OpenPGP digital signature
URL: </pipermail/attachments/20140224/f98d63fb/attachment-0001.sig>