User Tools


Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
start [2016/05/08 11:49]
phoe [What? Why? How? When?]
start [2017/04/28 10:10] (current)
Line 1: Line 1:
 ====== Common Lisp UltraSpec ====== ====== Common Lisp UltraSpec ======
 +{{ :​clus.png?​400 |}}
 This is **Common Lisp UltraSpec**,​ a community project to create a contemporary and unified documentation file for the whole modern Common Lisp universe. This is **Common Lisp UltraSpec**,​ a community project to create a contemporary and unified documentation file for the whole modern Common Lisp universe.
  
Line 5: Line 6:
 **[[CLUS:​TODO|Click here for the things finished so far!]]** **[[CLUS:​TODO|Click here for the things finished so far!]]**
  
------------+=====I want to help/​branch/​fork/​look at the original files!===== 
 +**[[https://​github.com/​phoe-krk/clus-data|The whole CLUS data is available on GitHub.]]**
  
-=====What? Why? How? When?==== +=====I want to read the manifesto!===== 
-As for **what**: I have been growing sick of the current state of Common Lisp documentation in general. +**[[Articles:Manifesto|Click here for the manifestothen!]]**
-  * The main reference document for Common Lisp, the legendary ​[[http://​www.lispworks.com/​documentation/​lw70/​CLHS/​Front/​|CLHS]], is: +
-    * based on a standard that - although serving the Lispers well - has its textual inconsistencies and mistakes like every work of such size, +
-    * is dated, as any programming language standard from twenty years ago would be, +
-    * impossible to edit or fix, according to the license it is distributed under, +
-    * impossible to extend with new documentation ​for exactly ​the same reason, +
-    * impossible to link with new documentation for exactly the same reason, +
-    * scaring a lot of people away with its outer look straight out of 1996. +
-  * The references for many important parts of the Lisp ecosystem - implementations,​ MOP, ASDF and UIOP, Quicklisp, graphical frontends - are fragmented, in various versions. +
-  * Many libraries - both ancient and contemporary - despite being working and useful: +
-    * have their documentation located in various, various parts of the Web. [[http://​lispdoc.com/​|Various]] [[http://​quickdocs.org/​|documentation]] [[http://​l1sp.org/​html/​|aggregators]] have been designed to aid this, but the documentation they serve in this way is in no way interlinked,​ consistent or safe from suddenly disappearing,​ +
-    ​have their documentation aggregated on some of the solutions to the aforementioned problem, but they nevertheless depend on whatever the library authors put in Quicklisp, what and where they put on their websites, plus often the only (or almost only) thing available there is a link to an external website, +
-    ​often lack [[https://​blog.tymoon.eu/​article/​330|any sensible documentation]] at all, making them virtually unusable for developers which lack the time to understand or debug the code the slow way. +
-  * There is very little effective pressure towards changing this state - at least given what I saw and perceived from my very little experience with the Common Lisp community. +
-   +
-This is **why** the Common Lisp UltraSpec project appeared. +
-    +
-I know that this approach is very prone to [[http://​i.imgur.com/​tESzI0R.png|breaking]],​ therefore - about **how** - I want to make a few assertions this project is meant to be achieving at any given moment. +
-  * The whole documentation is meant to be as complete as possible given its contributors'​ time and strength, becoming the community-made reference document for the whole Common Lisp universe. +
-  * For the Common Lisp standard, I do not use any material from the CLHS - instead, I use the third draft of the ANSI CL Standard, put into public domain by its authors - members of the X3J13 itself. The standard, while being copied as close to the original as possible, will be fixed without changing its meaning wherever possible, refined, hyperlinked further +
-  * I currently use [[https://​www.dokuwiki.org/​|DokuWiki]] as the backend, which requires only PHP on the server-side,​ stores its data as a tree of directories and easily parsable and editable TXT files, and makes it possible and easy to make static HTML-only mirrors/​snapshots. +
-  * For the authors of external libraries, I plan on promoting the best documented code. Aside from storing parsed copies of the available documents as pages of the wiki, I want to give people motivation for documenting their Common Lisp libraries - for libraries which have the best external and internal documentation,​ I want to merge and hyperlink them with the whole rest of the documentation,​ creating a thought-out,​ tightly-knitted,​ well-linked and well-documented reference manual in the effect. +
-  * The whole documentation is meant to be hosted on Git for ease of cloning, mirroring, version control and cooperation,​ and released into the public domain. +
-  * I know that I __will__ need help - and therefore will be looking for contributors to help me by retrieving various Lisp documents that have a license permissible enough to be merged into the wiki, fighting for permission in case of the documents that don't, thinking the whole layout out and cooperating on the tedious work of proper parsing and hyperlinking everything to make this documentation project as usable for the Lispers in general as possible. +
-   +
-As for **when** - as of writing these words, I've finished porting Chapter 14 - about conses - of the third standard draft to the DokuWiki. It still has some minor bugs, but these will get polished along the way, as it is integrated with the upcoming rest of the standard. This has taken me about a week of somewhat intensive work. At this rate, I expect to have ported and polished the whole standard by the end of 2016 on my own, if time and luck allows. This will be faster if people help - and let me make sure that you know - you're one of the possible helpers. Money is money, it's almost always fun and helping - but what this project really needs is time, attention and love. There'​s a lot of work to be done for this to become useful, but I think it's more than possible and more than worth the time spent. +
- +
-And, before you ask - yes, I'll be giving a lightning talk about this on ELS2016. +
- +
-I hope I've answered all of your questions so far - in case I'm wrong, below is my contact information. As for now - //no to jedźmy z tym koksem//. +
- +
-<​cite>​~phoe - Cracow, Poland, 31.03.2016, 02:40 GMT+1</​cite>​+
  
 ----------- -----------
Line 45: Line 16:
 ====Reaching me==== ====Reaching me====
   * Michał //~phoe// Herda   * Michał //~phoe// Herda
-  * ''​**#​lisp**''​ at Freenode - I'm there as ''​**phoe_krk**'',​+  * ''​**#​lisp**''​ at Freenode - I'm there as ''​**phoe**'',​
   * ''​**#​lisp-pl**''​ - jeśli chcesz pogadać po polsku,   * ''​**#​lisp-pl**''​ - jeśli chcesz pogadać po polsku,
   * ''​**[[phoe@openmailbox.org]]**''​ for bigger things.   * ''​**[[phoe@openmailbox.org]]**''​ for bigger things.
Line 52: Line 23:
  
 //Please send kudos to [[http://​blog.tymoon.eu|Shinmera]] for the hosting!// //Please send kudos to [[http://​blog.tymoon.eu|Shinmera]] for the hosting!//
 +