"Background" documentation

[Clemens Heuberger]

In http://trac.sagemath.org/ticket/16782, I propose a patch implementing the
Riemann Zeta function for complex intervals.

For bounding the errors, I needed some rather boring estimates, in particular
explicitly bounding errors in Taylor's theorem in my situation. These boring
estimates now exist in the form of a TeX file (translating to 2 pages PDF) on my
hard disk.

I suppose that this is not an ideal solution, because reviewers might want to
check what I did without having to do everything by themselves, and the same
holds for future extensions/bugfixes etc.

I find none of the following possibilities very appealing:

- keep it on my hard disk (that is probably the traditional approach in
mathematical papers, the boring details are somewhat buried and inaccessible).

- Moving the TeX-code into the docstring (we are speaking about 2 pages, after all).

- Moving the TeX-code as comments into the code (same problem and you'd have to
read the TeX code instead of a compiled version).

- Putting it into arxiv (way to boring content for arxiv).

- Putting it onto my web page and inserting a link to it (may be a compromise)

Is there any canonical place for such background documentation, possibly within
the sage source tree?

[Nils Bruin]

On Friday, August 8, 2014 1:48:20 AM UTC-7, Clemens Heuberger wrote:

Is there any canonical place for such background documentation, possibly within
the sage source tree?

If your work is interesting then you'll probably be doing computations with it that warrant publication. That could be a non-boring submission to ArXiv. On ArXiv you can attach supporting (data) files to your preprint, which are allowed to be boring. Now you can refer to *those* from the sage code.

[Jeroen Demeyer]

Hello,

Perhaps move the .tex file into the Sage source tree as a separate file,
in the same directory as the .py/.pyx file? That makes it accessible but
still it will not be in anybody's way.

Jeroen.

[Volker Braun]

If its <2 pages with 12pt font and normal margins then I would think its small enough to be put into a docstring. Of course could be a lot more. Putting it into  a separate file is also OK, but then I would suggest to put it into a "notes" subdirectory. There is also at least one precedent: src/sage/misc/notes/bernoulli_mod_p.tex (though I would prefer it to be in src/sage/rings/notes/bernoulli_mod_p.tex).

[mmarco]

I have seen much worse than two pages of boring computations of errir estimates that lead to potentially useful code published in arxiv. I would go for that.