I recommend putting a link in the POD to the PDF on a web site. A 4X increase in the size of the distribution is a pretty expensive way to publish. How about a short synopsis in the POD with the link for more detail if needed---unless, of course, the Marpa::XS is not usable without reading the PDF?
--Chris On Sun, Jul 17, 2011 at 12:43 PM, Jeffrey Kegler <jeffreykeg...@mac.com> wrote: > I'd like feedback on a question. My feeling is that internals documentation > is important, that disk is relatively cheap, and that I should include the > PDF file that contains Marpa's internal documentation with the CPAN > distribution. But I'd like to know if others agree. > > Marpa::XS, my XS version of Marpa is now nearing completion. marpa.pdf, the > file that contains the internals documentation is 3M -- 3 times the size of > the rest of the distribution, including marpa.pdf's own sources. marpa.pdf > is not necessary as user documentation, but it is essential for > understanding the internals. Disk is fairly cheap, and I'd like to upload > the PDF with the distribution. > > The sources of the PDF are already in the Marpa::XS distribution, but Cweb > and TeX are required to build the PDF. Cweb and Tex can be complicated to > install -- it's a lot to ask of someone taking a first look at the code. > Even if you already have Tex, it can save a lot of trouble if the PDF is > already built. > > In answer to those asking why Cweb and TeX, Marpa::XS's internals are in C > and very mathematical. Anyone who looks at the PDF will realize that it > does a job POD was not designed to do, and cannot do. > > Thanks, jeffrey kegler >
