Can doc/ contain documentation independently of source/

[Joseph Wright]

On 03/02/2020 15:10, jfbu wrote:
> 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.

I'm not saying it's trivial: the LaTeX core sources are also somewhat 
'interesting' by hand. But the key is that the source material *for the 
docs* is there. People who want to manually build stuff will likely want 
to integrate into their own tool-chain in any case.

>>> 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.

Like I say, this is an external restriction in that sense: some projects 
require that documentation has sources it it's not plain text, and they 
won't include it otherwise.

>> 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.

Still much bigger than the sources! (LuaTeX does a better job than 
pdfTeX, a trick that Heiko has used in the past to keep things smaller.)

>>> 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?

Not, they have (that I know of) no PDF version. Perhaps the ConTeXt 
sources might be worth looking at: they are less markup-rich than the 
LaTeX ones, but do have some markup (though I am not sure if it's still 
'live').

>>> 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/

You are free to provide your files in whatever form you feel best. If 
you want to have a PDF version, you need some source to create them, but 
that could be used 'live' if you wished. For example, you could arrange 
a 'driver' stub in sources/ and have your .sty files will mark-up which 
were then loaded by the 'stub'.

Joseph