1. 13

From the site:

This is Common Lisp UltraSpec, a community project to create a contemporary and unified documentation file for the whole modern Common Lisp universe.

Ok, so what’s going on here? New sites for Common Lisp? Are these going to be kept up and be awesome, or is this yet another short lived attempt?

  1.  

  2. 2

    Looks interesting; the Hyperspec could really use a refresh. Unfortunately, my other feeling is that I’ll believe it when I see it.

    Here are some random thoughts:

    I would love if this project ignored the library ecosystem and the implementations and just focused on documenting the standard language with an easy to use and pretty interface, with a CC license.

    I think using TeX for online documentation is a probably a bad idea. It’s not the best tool for the job, and it’s going to block a lot of potential contributors from helping out.

    I kind of feel the site author is disregarding and ignoring all of the existing efforts to do a similar thing. Sites like Cliki, QuickDocs, CommonLisp.net, Articulate Lisp, etc. aren’t that bad, and they are all well known in the CL community and would love to have contributors. It also sends out a bad vibe to go into the community saying, “I thought all of your stuff was bad, so you all should use my new thing instead.”

    QuickDocs is auto-generated from the projects in QuickLisp (doc strings, READMEs, etc.), so contributing documentation to each project improves both the project and QuickDocs.

    It’s easy to register on Cliki.net, and it’s easy to add your own projects to it. It’s also easy to update or fix info for other projects.

    1. 2

      Looks interesting; the Hyperspec could really use a refresh.

      I’m not using the HyperSpec as a source. While I’m essentially creating another hyperlink work based on the work of X3J13, I’m using the third draft of the standard that was put into the public domain by its authors - I do it to avoid any copyright issues from ANSI and because CLHS is provided with a license that prohibits any modification.

      Unfortunately, my other feeling is that I’ll believe it when I see it.

      CLUS was dormant for the better part of 2016. Luckily, it got a lot of traction. I found some energy and time to work on it during the past month or so (ELS2017 is a good deadline for me to finish the beta version) - so feel free to look at the TODO page where everything done so far is listed.

      I would love if this project ignored the library ecosystem and the implementations and just focused on documenting the standard language with an easy to use and pretty interface, with a CC license.

      The project’s first phase completely ignores the library ecosystem and focuses on parsing the sources of the draft standard, fixing and improving them.

      The later phases will stop ignoring the ecosystem and start integrating things from it by turning them into modules for CLUS.

      About the interface, you can mostly thank/blame DokuWiki. It’s a fun and useful displaying engine.

      The license I chose is public domain - because this is the original license of the draft standard. I do not think that I should change it.

      I think using TeX for online documentation is a probably a bad idea. It’s not the best tool for the job, and it’s going to block a lot of potential contributors from helping out.

      I think so too, but I’m not using it for online documentation. My input is TeX, because the sources for the draft standard are all LaTeX (http://quimby.gnus.org/circus/cl/). I’m converting them to much simpler and cleaner DokuWiki markup.

      I kind of feel the site author is disregarding and ignoring all of the existing efforts to do a similar thing.

      I most certainly did not want to send a message like that. A part of the reason why CLUS came to life is - I tend to get an impulse, prototype first and think second.

      Also, pardon me, but I’m not ignoring all the existing efforts to do a similar thing, because there’s nothing to ignore here. There has been NO successful effort to turn the CL specification into a hyperlinked, improved version other than CLHS. And CLHS is set in stone due to its license - it cannot be improved.

      Sites like Cliki, QuickDocs, CommonLisp.net, Articulate Lisp, etc. aren’t that bad, and they are all well known in the CL community and would love to have contributors.

      I love these sites - but they all serve slightly different roles.

      CLiki is a wiki about all things, libraries, people about Common Lisp. It’s directly editable and more or less a base of all random bits of lispy knowledge. It’s unfit for housing big bodies of documentation.

      Quickdocs is a parser for Quicklisp documentation strings. It directly depends on what people put on Quicklisp. I actually plan on making an effort to unify the style of documentation within these libraries one day, especially because it will be congruent to what I want to do inside later phases of CLUS - improving the overall quality for Common Lisp documentation.

      common-lisp.net is a website last updated in 2015, and, other than that, houses a Gitlab instance. It’s basically a home space for many CL projects.

      Articulate Lisp is more or less an article website, from what I see, more or less a Wordpresslike thing. I don’t think it is viable for holding bodies of documentation - I’d rather keep articles and tutorials like the ones on this website separate from solid bodies of documentation.

      It also sends out a bad vibe to go into the community saying, “I thought all of your stuff was bad, so you all should use my new thing instead.”

      If I may - “I thought none of your stuff fits the void that I see, so I started working on a tool to fill it.”

      I don’t want to obsolete CLHS, CLiki, Quickdocs, Common-Lisp.net, Articulate Lisp, http://lisp-lang.org/, l1sp.org or any other existing websites. If anything, notice that I’m not creating a flashy new website to rule them all and in darkness bind them - I’m creating an edition of Lisp specification in a sanitized, cleaned-up format.

      The webpage at phoe.tymoon.org is merely a visual deployment of the body of documentation that is being created at github.com/phoe/clus-data and being placed into public domain through it. It is currently displayed by DokuWiki which is a piece of software that I know, which works and is hackable enough for me to be able to customize it for CLUS. Know a different display engine? You are free to hook it up to the code. Got a completely different idea for the Lisp specification hidden in the clus-data Github project? It’s yours to take, it’s public domain.

      QuickDocs is auto-generated from the projects in QuickLisp (doc strings, READMEs, etc.), so contributing documentation to each project improves both the project and QuickDocs.

      That’s what I want to do - eventually. It is a goal for what I imagine for later phases of CLUS, but again, it’s not about slurping up everything into one monolithic UltraSpec - it’s about enforcing quality standards for various, various pieces of documentation, and only then importing them into CLUS.

      And, eh, enforcing quality standards. I imagine it as mostly uplifting existing pieces of documentation, standarizing their form and filling in the missing parts. Lots of manual and semi-manual labor.

      It’s easy to register on Cliki.net, and it’s easy to add your own projects to it. It’s also easy to update or fix info for other projects.

      Yes, CLiki is wonderful for that. I imagine a similar workflow for CLUS one day - except I don’t want it to be a wiki workflow. I want it to be a git-like workflow. You don’t edit pages - you submit pull requests.

      (Also, I never needed to register to edit CLiki. :))

      1. 2

        As the maintainer of Articulate Lisp, I appreciate the call out. I would love to take contributions and PRs.

        It’s the case that Lispers have a community identity of being individualistic, so we do like to do our own thing… a bit too much perhaps. :-)

        1. 1

          As the maintainer of Articulate Lisp, I appreciate the call out. I would love to take contributions and PRs.

          I know and I’ll most likely send an article or two your way, especially because I know what I want to write about - but CLUS is a project that I consider too different to put at your website.

          It’s the case that Lispers have a community identity of being individualistic, so we do like to do our own thing… a bit too much perhaps. :-)

          A little bit, yeah. I’ve had my share of hopes and dreams of a consolidated Lisp community. In a way, you can consider CLUS as a sign of frustration of having them crushed. If Lisp isn’t unified in the slightest and put into one place in any proper order, I’m daring to try and attempt doing so with my own hands.

          Hahaha. I’m silly sometimes.