long-description

[Robert Goldman]

On 25 Feb 2019, at 13:56, Faré wrote:

> On Mon, Feb 25, 2019 at 2:32 PM Robert Goldman <rpgoldman at sift.info> 
> wrote:
>>
>> The more we discuss this, the more I think it's a solution in search 
>> of a problem. Just using the standard ASDF file-inclusion 
>> capabilities (that Faré shows in his email) seems sufficient to me, 
>> and also keeps a nice uniformity -- if you want the long description, 
>> you ask for it, and you know it's a string. It also imposes a cost in 
>> complexity with only a conjectural benefit (who would consume the new 
>> pathname designations, and which library authors and maintainers 
>> would supply it?). If users are offended by the excess number of 
>> bytes, the macro facility is available.
>>
>> I prefer not to give the yak any more facial hair!
>>
> To be clear, I am not advocating any change to the ASDF source code;
> just a minor change to the ASDF documentation, to suggest users to use
> a pathname as metadata to inform documentation extracters and browsers
> to use a documentation file instead of large strings in the image.

I just grabbed the quicklisp bistro (thanks to Zach for instructions), 
and I find there are 3827 .asd files, of which only 420 use 
`:long-description` at all.

Looks like at least some of them have Markdown files slurped into them.  
These are big, but is this really a problem for anyone?  I suppose one 
loses the limited amount of metadata that one would get from having a 
pathname.

I'm still not sure how telling people to use pathnames would help any 
one.

Even if so, why not just add `:documentation-pathname`, and then no one 
will have to worry about type errors?  I'd favor that -- I bet most 
people assume that metadata is filled with strings or at least string 
designators, unless told otherwise, and I think it's reasonable to let 
them continue to do so, and have metadata that clearly says whether it's 
an external file or not.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mailman.common-lisp.net/pipermail/asdf-devel/attachments/20190225/d4fc82a8/attachment-0001.html>