Can doc/ contain documentation independently of source/

[jfbu]

Hi Joseph

> Hello Jean-François,
>> 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.
> 
> I think that's the usual reading.

Ok,

> 
>> ...
>> 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/.  ...
> 
> For small packages, there is an attraction in having a single source. However, the LaTeX team's idea with .dtx files is rather more toward them being the source for the code + code docs, with other files separate.

This looks quite sensible to me indeed,

> For example, all of the core team stuff has README files, scripts, etc. as separate files, and the scripts or whatever don't even go to CTAN. (Makefiles or whatever depend on having some known development set up, so are likely useful more in a source repository for a small number of devs than on CTAN for users.)

Yes, I have two layers: my own private environment and the actual final step when the upload to CTAN is prepared. Then the dtx may include a Makefile not for my own usage but for end user usage who would like to rebuild all the docs (assuming the environment provides some non TeX things such as pandoc). I am not including my own shell scripts and Makefile in the distributed dtx. This actually caused in a bug in xint.zip production where "tex" not "etex" ended up being used for doc-stripping causing a problem in changes file in markdown then html. My everyday routine never saw it as it was using non public production methods.

I now wonder if I have should worry at all about providing ways to distros or users to actually build in an automatized manner a TDS ready hierarchy.

Not providing this simply means for me removing contribution of a Makefile (or a texlua based system like the LaTeX team develops).

Later in your message you mention pgf/TikZ and indeed I had noticed they used standard TeX comments and I actually found that rather more readable than distracting macrocode environment end and start tags all over the place.

However I wonder if one can build the TikZ manual from the actual material end user end up having in their TeXLive (or MikTeX) trees.  I think I tried once but quickly dropped it.


> 
>> But foo.dtx by itself would only be a container of macro files
>> and perhaps of some user-manual.
>> [...]
>> 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".
> 
> One can take various views with code documentation. Again, the approach of the team has been to aim for one foo.tex file as the source for *user* documentation, and one foo.dtx as the source for documented code.

I think this is definitely reasonable. I never work with my "user" documentation in a dtx with code source, but have a script doing the fusion at build time only. I am now starting to think it is even better to not create humongous dtx at all indeed.

> One can skip typesetting the latter, particularly for smaller, simpler packages, but the source misses things like cross-refs, indexing, etc. So there it very much depends how you imagine people using your sources. (For the LaTeX kernel, things are quite possibly different from a one-file .dtx of a few 10s of lines.)

as I have an inkling for local table of contents I do imagine my users happy with PDF format and I care about that with dedicated headers for navigation. I myself use my own PDF often for navigating in my source, but I dropped all index production as PDF search has always been enough of a help if somehow the local table of contents are not enough.

> 
>> I even wonder after all why one should include the TeX source
>> of a pdf documentation at all and why not directly the PDF ?
> 
> Without the source, the PDF can't go into TeX Live as the ability to build binary files like PDFs is a key part of the requirements for e.g. Debian.

I don't want to be too much of a non-compliant guy, but here I seriously doubt that documentation should fall into same requirements as actual binary files representing software. For me a Unicode document in Chinese is as unreadable as a compressed PDF file representing French text.



> If you are worried about space/size, the PDFs are also where the hit is: the sources will always be much smaller.

I use latex+dvipdfmx for size issues.

> 
>> 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.
> 
> One approach taken by some authors is to put the code docs at the end of the .sty, thus avoiding the load time issue. But you are right that the time hit for simply having comments in a .sty or similar is today trivial. (Things like pgf are documented that way without obvious impact.)

Large codebase can probably not have code comments too far from actual code. Yes the pgf files are rather pleasant to visit. But I don't think one can produce from them a cross-linked reference PDF like you do at LaTeX3?

> 
>> 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?
> 
> Well, 'duplication' depends what you mean: a PDF is not really 'duplication' of a source, having the source file twice on the other hand is.


This is where the whole dtx concept is a problem (in my original post I started saying I was accepting it but I realize now I had started questioning it by the end of my post).
Because it means the source code is present at least twice if not thrice:

- actual source code in tex/latex/ or tex/generic or etc...
- commented source code in text format in source/
- commented source code in PDF format in doc/

Best,

Jean-François