Can doc/ contain documentation independently of source/

[Joseph Wright]

On 03/02/2020 21:40, jfbu wrote:
> 
> Le 3 févr. 2020 à 17:02, Joseph Wright <joseph.wright at morningstar2.co.uk> a écrit :
> 
>> 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'.
> 
> 
> Replying sort of simultaneously to all paragraphs: I think Linux distros would really enjoy a "texdoc" which would compile on the fly the needed documentation.
> 
> Currently I have 2,1G from /usr/local/texlive/2019/texmf-dist/doc (on my TL2019 install which is not a full one). I am certainly not using more than 100MB at maximum out of it. (I am a great defender of reading documentation but I, like most people, have some familiarity only with a minority of contributed packages).
> 
> If there was a more or less standardized way for package authors to lay out the process to build the PDFs, then a "super texdoc" could build the needed PDFs only when requested.
> 
> With such system in place, size of TeX install would decrease by an order of magnitude.
> 
> I understand the frailty of this, but now if you agree the process above has no robustness, then we whouls agree then that the Linux distros insisting on having text sources is disputable as it is not guaranteed one can always with certainty build out of them. What is the point of sources which one can not be guaranteed to build out of them, not only now but also next year?
>   
> My above suggestion is thus very unlikely to ever happen; because it would require adding to the TeX ecosystem a real standardized procedure of dependencies. I believe the permanent evolution of contributed packages makes it impossible to guarantee one can build a package documentation during the full year of a TeXLive life span. I would be surprised to hear that there is a single Linux distro TeX packaging which goes through the process of building from source the documentations of thousands of packages.
> 
> Thus my conclusion is that the Linux distros requirement is incoherent. Either they should have insisted that each documentation is distributed as text files with a complete and working recipe to build to binary format, not only working on the first day of TeXLive release but also on day + 364 or they should accept that documentation is not software and as such there is little logic into requiring text format sources; which nobody ever compiles apart from upstream package authors.
> 
> Best,
> 
> Jean-François
> 

Hello Jean-François,

By far the most likely requirement for 'build the PDF on the fly' is to 
have a more-or-less *complete* TeX system installed. That's fine for 
devs, MacTeX users, ..., but for a lot of Linux distros, 
"texlive-recommended" or whatever is probably what people have. That 
leaves them open to the 'which packages do people pick' issue. The only 
way one could have such a set up would be to have a much more rigid 
approach to the entire ecosystem: CTAN are very very laid back compared 
to some other archives, so it's really a non-starter.

The LaTeX team are providing some standard tools (l3build) and do try to 
give guidance on approaches, classes, etc. But then there is 
flexibility, and people have their preferred approaches. I very much 
double one could get *enough* people to buy in.

There's also the whole business of time: it takes several minutes to 
build source2e even on a fast machine, and of course we need multiple 
runs, indexing, etc.

Joseph