I've seen the pattern of using :long-description #.(uiop:read-file-string (uiop:subpathname *load-pathname* "README.md")) spread among CL libraries. I see it only as a waste of kilobytes of data (quadrupled on 32-bit unicode lisps such as SBCL). I'm told it's because Quickdocs likes it this way. Since there is not (yet?) any type enforcement on the value of that field, can we instead agree for an alternate format, wherein the field would instead contain the pathname of the long-description file, relative to the (asdf:system-source-directory) ? Thus you'd use: :long-description #p"README.md" And Quickdocs and other documentation tools would do the right thing from there. Maybe I'm just an old-school code bummer but I'm always saddened by a waste of bytes. —♯ƒ • François-René ÐVB Rideau •Reflection&Cybernethics• http://fare.tunes.org I have never killed any one, but I have read some obituary notices with great satisfaction. — Clarence Darrow
Sounds good to me, but I'm possibly also an old-school code bummer. ----- Original message ----- From: "Faré" <fahree@gmail.com> To: ASDF-devel <asdf-devel@common-lisp.net>, Eitarow Fukamachi <e.arrows@gmail.com>, Didier Verna <didier@didierverna.net> Subject: long-description Date: Wednesday, February 20, 2019 8:16 PM I've seen the pattern of using :long-description #.(uiop:read-file-string (uiop:subpathname *load-pathname* "README.md")) spread among CL libraries. I see it only as a waste of kilobytes of data (quadrupled on 32-bit unicode lisps such as SBCL). I'm told it's because Quickdocs likes it this way. Since there is not (yet?) any type enforcement on the value of that field, can we instead agree for an alternate format, wherein the field would instead contain the pathname of the long-description file, relative to the (asdf:system-source-directory) ? Thus you'd use: :long-description #p"README.md" And Quickdocs and other documentation tools would do the right thing from there. Maybe I'm just an old-school code bummer but I'm always saddened by a waste of bytes. —♯ƒ • François-René ÐVB Rideau •Reflection&Cybernethics• http://fare.tunes.org I have never killed any one, but I have read some obituary notices with great satisfaction. — Clarence Darrow
Hi Faré, Probably, I'm the first one who started the custom. However, I suppose it's technically not widely used because of Quickdocs, since it also searchs README file at the project root. Perhaps, it may be because CL-Project, my project generator, has been adding the code to the new ASD file. https://github.com/fukamachi/cl-project/blob/master/cl-project.asd#L33-L35 I just thought it might be useful if it could be refer by calling 'asdf:system-long-description' from REPL, or someone would make some utility tool using long-description in the future. To be honest, I'm not a big fan of it anymore and I don't follow it in my recent products. I'm willing to delete the code from CL-Project, though I have nothing I can do for existing projects. On Thu, Feb 21, 2019 at 1:15 PM Faré <fahree@gmail.com> wrote:
I've seen the pattern of using :long-description #.(uiop:read-file-string (uiop:subpathname *load-pathname* "README.md")) spread among CL libraries.
I see it only as a waste of kilobytes of data (quadrupled on 32-bit unicode lisps such as SBCL).
I'm told it's because Quickdocs likes it this way.
Since there is not (yet?) any type enforcement on the value of that field, can we instead agree for an alternate format, wherein the field would instead contain the pathname of the long-description file, relative to the (asdf:system-source-directory) ? Thus you'd use: :long-description #p"README.md" And Quickdocs and other documentation tools would do the right thing from there.
Maybe I'm just an old-school code bummer but I'm always saddened by a waste of bytes.
—♯ƒ • François-René ÐVB Rideau •Reflection&Cybernethics• http://fare.tunes.org I have never killed any one, but I have read some obituary notices with great satisfaction. — Clarence Darrow
Eitaro Fukamachi <e.arrows@gmail.com> écrivait:
To be honest, I'm not a big fan of it anymore and I don't follow it in my recent products. I'm willing to delete the code from CL-Project, though I have nothing I can do for existing projects.
Not a big fan either. What I usually do is use the description slot as a one-liner, and the long-description one as some kind of abstract about the project. My README files are usually longer, more elaborate. Also, FYI, Quickref uses README files as an introduction section in the generated reference manuals automatically. This is a functionality that I plan to move to Declt at some point. Having a whole README file in the long-description slot would look weird in Quickref-generated documentation. -- Resistance is futile. You will be jazzimilated. Lisp, Jazz, Aïkido: http://www.didierverna.info
On 20 Feb 2019, at 22:14, Faré wrote:
I've seen the pattern of using :long-description #.(uiop:read-file-string (uiop:subpathname *load-pathname* "README.md")) spread among CL libraries.
I see it only as a waste of kilobytes of data (quadrupled on 32-bit unicode lisps such as SBCL).
I'm told it's because Quickdocs likes it this way.
Since there is not (yet?) any type enforcement on the value of that field, can we instead agree for an alternate format, wherein the field would instead contain the pathname of the long-description file, relative to the (asdf:system-source-directory) ? Thus you'd use: :long-description #p"README.md" And Quickdocs and other documentation tools would do the right thing from there.
Let me see if I understand clearly: 1. As before, if you put a string in here, you get the string itself as the value of `:long-description`. 2. If there is a pathname literal in here you get the contents of that file as the value of `:long-description`. Is this correct? I'm ok with this, but not so enthusiastic that I'll do it myself. I'd be happy to accept a pull request. I'd also like some discussion about how this change would come into being. It's not especially backward compatible, but it should not cause breakage -- people using older versions of ASDF would just see a pathname in the unlikely event that they tried to retrieve the `long-description`. Can anyone else think of any unexpected consequences?
: Faré : Robert Goldman
:long-description #p"README.md"
Let me see if I understand clearly:
As before, if you put a string in here, you get the string itself as the value of :long-description.
If there is a pathname literal in here you get the contents of that file as the value of :long-description.
Is this correct?
I'm ok with this, but not so enthusiastic that I'll do it myself. I'd be happy to accept a pull request.
I was thinking even simpler: system-long-description returns whatever you put in :long-description, whether a string or a pathname. But if it's a pathname, whichever document-generating application (Quickdocs, Declt, etc.) is responsible for looking at that file, interpreting it according to its file extension and/or self-describing content, etc. It isn't ASDF's responsibility to either read the file contents or interpret them. You've been given the raw data, now you're on your own.
I'd also like some discussion about how this change would come into being. It's not especially backward compatible, but it should not cause breakage -- people using older versions of ASDF would just see a pathname in the unlikely event that they tried to retrieve the long-description.
Can anyone else think of any unexpected consequences?
I don't believe anyone is currently using a pathname in that field, so allowing a pathname and associating some semantics to it, whether actively supported and enforced by ASDF or not, is sufficient. The main burden would be to document the convention and convince a few key players to adopt it (e.g. Eitarō, Didier, Eudoxia, and other influencers). —♯ƒ • François-René ÐVB Rideau •Reflection&Cybernethics• http://fare.tunes.org Q. Why does "philosophy of consciousness/nature of reality" seem to interest you so much? A. Take away consciousness and reality and there's not much left. — Greg Egan, interview in Eidolon 15
On 20 Feb 2019, at 22:14, Faré wrote:
I've seen the pattern of using :long-description #.(uiop:read-file-string (uiop:subpathname *load-pathname* "README.md")) spread among CL libraries.
I see it only as a waste of kilobytes of data (quadrupled on 32-bit unicode lisps such as SBCL).
I'm told it's because Quickdocs likes it this way.
Since there is not (yet?) any type enforcement on the value of that field, can we instead agree for an alternate format, wherein the field would instead contain the pathname of the long-description file, relative to the (asdf:system-source-directory) ? Thus you'd use: :long-description #p"README.md" And Quickdocs and other documentation tools would do the right thing from there.
Let me see if I understand clearly:
1.
As before, if you put a string in here, you get the string itself as the value of :long-description. 2.
If there is a pathname literal in here you get the contents of that file as the value of :long-description.
Is this correct?
I find option 2 kind of strange. What if I really just wanted the
On Thu, Feb 21, 2019 at 8:23 AM Robert Goldman <rpgoldman@sift.info> wrote: pathname as the description? Having it produce the contents of the file seems really odd. I think it's up to the developer/user to decide whether to display the file or not. My 2 cents, as someone who doesn't really use asdf all that much (because the projects are pretty much done and working.) -- Ray
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! 😉 On 25 Feb 2019, at 10:43, Raymond Toy wrote:
On Thu, Feb 21, 2019 at 8:23 AM Robert Goldman <rpgoldman@sift.info> wrote:
On 20 Feb 2019, at 22:14, Faré wrote:
I've seen the pattern of using :long-description #.(uiop:read-file-string (uiop:subpathname *load-pathname* "README.md")) spread among CL libraries.
I see it only as a waste of kilobytes of data (quadrupled on 32-bit unicode lisps such as SBCL).
I'm told it's because Quickdocs likes it this way.
Since there is not (yet?) any type enforcement on the value of that field, can we instead agree for an alternate format, wherein the field would instead contain the pathname of the long-description file, relative to the (asdf:system-source-directory) ? Thus you'd use: :long-description #p"README.md" And Quickdocs and other documentation tools would do the right thing from there.
Let me see if I understand clearly:
1.
As before, if you put a string in here, you get the string itself as the value of :long-description. 2.
If there is a pathname literal in here you get the contents of that file as the value of :long-description.
Is this correct?
I find option 2 kind of strange. What if I really just wanted the pathname as the description? Having it produce the contents of the file seems really odd. I think it's up to the developer/user to decide whether to display the file or not.
My 2 cents, as someone who doesn't really use asdf all that much (because the projects are pretty much done and working.) -- Ray
On Mon, Feb 25, 2019 at 2:32 PM Robert Goldman <rpgoldman@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. —♯ƒ • François-René ÐVB Rideau •Reflection&Cybernethics• http://fare.tunes.org The probability of the people in power being individuals who would dislike the possession and exercise of power is on a level with the probability that an extremely tender-hearted person would get the job of whipping-master on a slave plantation. — Frank H. Knight
On 25 Feb 2019, at 13:56, Faré wrote:
On Mon, Feb 25, 2019 at 2:32 PM Robert Goldman <rpgoldman@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.
On Tue, Feb 26, 2019 at 8:30 AM Will Mengarini <seldon@eskimo.com> wrote:
* Robert Goldman <rpgoldman@sift.info> [19-02/25=Mo 15:37 -0600]:
Even if so, why not just add `:documentation-pathname`, and then no one will have to worry about type errors?
+1
Because adding a new slot means a new ASDF version with its own feature and systems having to guard use of that slot with #+asdf3.4 to avoid breaking on older versions of ASDF. I don't think this feature is worth it. Actually, I'm not even sure the feature is worth this discussion that I started, that looks more and more like bikeshedding. My apologies for starting it. —♯ƒ • François-René ÐVB Rideau •Reflection&Cybernethics• http://fare.tunes.org Prior to capitalism, the way people amassed great wealth was by looting, plundering and enslaving their fellow man. Capitalism made it possible to become wealthy by serving your fellow man. ― Walter E. Williams
participants (7)
-
Didier Verna -
Eitaro Fukamachi -
Faré -
Mark H. David -
Raymond Toy -
Robert Goldman -
Will Mengarini