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.
