Can doc/ contain documentation independently of source/

[jfbu]

Hi,

So far I have mainly interpreted TDS structure as asking for source/
to contain the source not only of macro files but also of the complete
documentation.

As a result, for my packages with source distributed as .dtx files
(which is almost all my packages) I may embed into the
.dtx files things such as README.md, CHANGES or even Makefiles needed
to build documentation and reconstruct a full package.tds.zip.

I am wondering, accepting for the duraction of this discussion
that the whole .dtx concept actually continues
to make sense nowadays, whether I should not bundle things a bit
differently and consider that xint.dtx should only be a container
of the package documentation stricto sensu and macro files.

Things such as README, CHANGES, Manifest, Makefiles
being left outside and only included in doc/ but not in the dtx
which ends up in source/.  I.e. the shipped bundle would still
provide the means to both produce the complete documentation
and macro files, but this would go perhaps via using a contributed
Makefile or other means located in doc/, which to work would
of course would need to have foo.dtx available too.

But foo.dtx by itself would only be a container of macro files
and perhaps of some user-manual.

For example for xint which I updated recently, in the process
I removed some previous duplication (I had been going
quite overboard with both a CHANGES.html and CHANGES.pdf
for example). But currently the xint.dtx still contains 
CHANGES in markdown format, as well as shell scripts
which can use pandoc to produce CHANGES.html
as distributed in the doc/ section too.

I am considering removing entirely from the xint.dtx
all these things ; and distribute directly only a CHANGES.html
produced at home.

Thus CHANGES.html will qualify as its own source but be in doc/

Also a Makefile (currently extractable from xint.dtx as Makefile.mk)
would end up in doc/ but not be in the source/xint.dtx

In fact source/ would contain only xint.dtx (I have also dropped
xint.ins which always had been purely optional as xint.dtx
self-extracts).

And doc/ would contain Makefile, CHANGES.html, README.md,
xint.pdf and sourcexint.pdf.

The source/ would thus only contain the source for xint.pdf
and sourcexint.pdf production, and of course of the macros files xint*.sty
but not for the other stuff (which nevertheless are an indispensible
part of the user documentation).

In the longer term, I think the whole concept of stripping xint*.sty files
is somewhat dated and I would prefer an approach à la Python
where the macro files have their docstrings and the CTAN uploads
do not included a bulky PDF documentation byt only the 
macro files and the user has means to consult the docstrings.

This would not preclude having some dedicated xint.pdf user manual,
but at least in the case of code documentation would include it
in only one place, not duplicated in a "dtx" and in a "pdf".

I even wonder after all why one should include the TeX source
of a pdf documentation at all and why not directly the PDF ?

Then what would actually source/ serve to ? There would be
only tex/ for the macro files containing docstrings
and doc/ for extra documentation including the means
to extract the docstrings.

That TeX would mean a bit more time to load the macro files
looks irrelevant nowadays.

For my package polexpr I distributed the documentation as
an html file polexpr.html which is produced via DocUtils
from reStructuredText source, polexpr.txt, but also there
I wonder why distribute at all this "source" and not uniquely
the html ?

In brief, shouldn't there be some project about reducing
duplication in the TDS trees?

Please, if replying CC my address as I don't subscribe to the list,

Jean-François