Best practice to include non-tex documentation in a CTAN package

[Reinhard Kotucha]

On 2020-11-20 at 12:37:27 +0100, Denis Bitouzé wrote:

 > Le 20/11/20 à 11h27, Zdenek Wagner a écrit :
 > 
 > >> > The point is that it is not a (La)TeX package byt a python package. If
 > >> > you want to use it, you need a third party tool (python) anyway.
 > >>
 > >> Sorry, I don't what you mean: what is not a (La)TeX package but a python
 > >> package?
 > >
 > > Louis has uploaded a python program and it is documented by means of
 > > python tools (Sphinx).
 > 
 > Okay but suppose someone uploads /a LaTeX package/ documented with
 > a `.pdf` file by means of, say, Sphinx (through a `.tex` file requiring
 > only packages available with the TeX Live).
 > 
 > Since Sphinx can export the `.rst` as `.tex` files before they are
 > compiled as `.pdf` files, what would be:
 > 
 > 1. required by the CTAN/TeX Live team as source file(s),
 > 2. the most convenient for the user who would like to modify the
 >    documentation: 
 > 
 > - just the `.tex` file?
 > - just the `.rst` file?
 > - both the `.tex` and the `.rst` files?

If the .rst files are written by the author and are not part of any
Python package then, and only then, it makes sense to upload them to
CTAN.

The most likely reasons why users want to modify the document sources
are

 * adapt paper size
 * disable hyperref's "colorlinks" before printing
 * fix typos

etc.  

This all can be done by modifying the .tex files.

The files needed to create the .tex files should be available too, one
way or another.

It's important that the author's workflow is reproducible.  This means
that the .rst files should be either part of the Python distribution
or the TeX Live distribution.  They shall never be part of both
distributions for reasons I already explained.

To résumé:

  If the .rst files are written by the author and are too specific to
  be part of the the Python distribution they should be part of TeX
  Live.

Regards,
  Reinhard

-- 
------------------------------------------------------------------
Reinhard Kotucha                            Phone: +49-511-3373112
Marschnerstr. 25
D-30167 Hannover                    mailto:reinhard.kotucha at web.de
------------------------------------------------------------------