Sorry but… how can we help ? Installation, dev setup

[vindarel]

Hi !
I'd like to help :) but… it isn't clear to me how this works. Could you add build/dev info on the readme maybe ? Where do you get the sources from, how do you process, build and publish them ? How do we get a local working copy ? I see it uses Dokuwiki, I see content in .txt files, but I'd like more pointers.

I tried installing Dokuwiki locally with no much success (copied to /var/www/dokuwiki and accessing localhost/dokuwiki/install.php gave a bunch of errors, looking like if php was not interpreted (apache is running) and it says that my data directory is not correctly secured). Is there an easier way ?

Thanks !

edit: allright, I got a Dokuwiki running with https://hub.docker.com/r/mprasil/dokuwiki/ Now I see folders in /var/www/dokuwiki/, but I don't know how to give it CLUS's pages…

[phoe]

I seriously lack time to work on CLUS. I will attempt to fix this next week and give some pointers as to how other people can help me with this.

[KZiemian]

@vindarel I talk with @phoe today, he is overworked so I try explain in the place of him, what that we need to do in first place.

To make it straight, this acronyms always means:
CLHS = Common Lisp HyperSpec;
CLUS = Common Lisp UltraSpec.

@Pheo edit part of CLHS and @rhmsilva creates diffs between CLHS and CLUS files, there are in diffs directory of this repository. We must that all parts that are in the Common Lisp specification are type right in CLUS, so main thing now is to check diffs, find which version is CLUS (plus or minus in diffs) which CLHS, noted differences and if we can correct it.

@phoe said that the best way that he know to find which version is which is like that. For example we have file cl:constant_variables:array-dimension-limit.diff, we google "Hyper Spec array-dimension-limit" and comper it with content of diff. For now that doesn't look to hard.

I alredy do some work on my fork, you can find it here https://github.com/KZiemian/clus-data/tree/master/diffs If you interested in doing that, I will put here guidelines about checking diffs here and we can try to work throught that files.

[KZiemian]

This is summary of information about one of biggest tasks we have to do with Common Lisp UltraSpec. I will always use two acronyms, so I stay them now
CLHS = Common Lisp HyperSpec;
CLUS = Common Lisp UltraSpec.

MAIN POINT
We must check that in current files of CLUS everything that is a part of core standard is correct by looking at diffs between CLHS and CLUS created by @rmhsilva.

NOTE
I often give examples of problems writing file names and number of lines in consideration. But when works progress this line may be shifted in they files.

1. THE MOST IMPORTANT is to mark which version in diff is CLHS and which is CLUS.

a) When there is question what should be in CLUS are gold standard is Common Lisp Standard, @xach have it on GitHub in dvi format https://github.com/xach/dpans/tree/master/dvi.

b) The easiest way check which version is which, that we know is to google "CLHS name-of-the-file" and compare it with CLHS.
EXAMPLE.
I have a file cl:constant_variables:array-dimension-limit.diff, so I google "CLHS array-dimension-limit" and I thats all.

c) My way to marks version is like this. Consider that +version is CLUS and -version is CLHS. At the top of the file I write

### Short description of differences
### +++ CLUS;
### --- CLHS.

2. Thing that you need to know at start.

a) NOTES and EXAMPLES, etc. because they are not part of CL Standard are disregarded at current stage. More on which thing are unimportant I will write later.

b) The amount of work is not as big as it may look. If I understand it, there is as many diffs as hyperlinks in CLUS, but many links point to the same file. If you find such series check first and mark all others as "Same file-name".
EXAMPLE
There are at least 16 links to cl:constant_variables:boole-1.diff. Some of this:
cl:constant_variables:boole-2.diff
cl:constant_variables:boole-clr.diff
cl:constant_variables:boole-orc1.diff

c) If you can, remove all whitespaces at the end of the line. Check if your editor can do it for you.
EXAMPLE
If you use GNU Emacs add to your init.el line
(add-hook 'before-save-hook 'delete-trailing-whitespace)
Then Emacs remove all unnesesery white spaces when you save changes to a file (as this code say).

3. My way of marking diffs. There is not guideline for checking diffs, only my way to organized this work.

a) Every line of commentary which I add to mark differences starts with ###.

b) As mentioned above, every checked diff starts in particular way.
Suppose that +version is CLUS and -version is CLHS. At the top of the file three first line are

### Short description of file.
### +++ CLUS;
### --- CLHS.

EXAMPLES
Some descriptions that I use

• File look OK = as far as I know, everything important is the same in CLHS and CLUS;
• BIG differences = we must look at this file separately in the future;
• Line missing = in one version line is missing;
• N lines missing.

c) Commentary is always just below commented part.

4. To state oblivious the code in one version can be wrong.
   a) Always note that.
   b) If you can write correct version.
   c) If you write corrected version put it below and start each line with ###.
   EXAMPLE
   cl:declarations:dynamic-extent.diff, lines 65-71.

(defun f ()
-   (flet ((g (x) (declare (dynamic-extent x)) ...))
+  (g (list 1 2 3)))
+(defun f ()
+  (flet ((g (x)
+           (declare (dynamic-extent x))
+           ...))
      (g (list 1 2 3))))

Plus version will have two defuns. Because +code is better formated corected version is

### (defun f ()
###   (flet ((g (x)
### 	   (declare (dynamic-extent x))
### 	   ...))
###     (g (list 1 2 3))))

d) I use GNU Emacs with packages aggresive-indent and rainbow-delimiters, to indent my CL code and count parenties, so when I need to check indentation deepth I past may code to some-file.lisp and trust Emacs standards od code.

e) You can change comments in GNU Emacs to ###, that can make work much easier. In Text-mode you only need type M-; and ###.

5. What note and what note note. I stay befor what is not in CL Standard we don't care. Still it is usefull to note some issues that appers to these day. I use here my standard of marking described above.

a) Text in both version may be the same, but order of paragraphs can be diffrent. Always note that.
EXAMPLE
cl:constant_variables:array-dimension-limit.diff, lines 5 and 12.
Both have the same text "The upper exclusive bound on each individual dimension of an array.", but between this lines is another paragraph.

b) If two version of code have diffrent format you only need to check that they are equivalent. If you can't mark it to future checking.

c) The same when style of code is changing.
EXAMPLE
cl:functions:adjoin.diff, lines 31-47.

- (setq slist '()) =>  NIL
- (adjoin 'a slist) =>  (A)
- slist =>  NIL
- (setq slist (adjoin '(test-item 1) slist)) =>  ((TEST-ITEM 1))
- (adjoin '(test-item 1) slist) =>  ((TEST-ITEM 1) (TEST-ITEM 1))
- (adjoin '(test-item 1) slist test 'equal) =>  ((TEST-ITEM 1))
- (adjoin '(new-test-item 1) slist key #'cadr) =>  ((TEST-ITEM 1))
- (adjoin '(new-test-item 1) slist) =>  ((NEW-TEST-ITEM 1) (TEST-ITEM 1))
-<TT>
-Affected By None.
+(defparameter *slist* '())
+→
+*SLIST*
+(adjoin 'a *slist*)

d) NOTES, EXAMPLES and COMMENTS are not part of CL Standard, so disregard it.

e) Sometime code in ASCII is diffrent, if you can change it to the best version. If you can't, mark it. Each line of Corrected code should start with ###
EXAMPLE
cl:functions:acosh.diff, lines 39-46.

-Hyperbolic sine         (e^x-e^-x)/2
-Hyperbolic cosine       (e^x+e^-x)/2
-Hyperbolic tangent      (e^x-e^-x)/(e^x+e^-x)
-Hyperbolic arc sine     log  (x+sqrt(1+x^2))
-Hyperbolic arc cosine   2 log  (sqrt((x+1)/2) + sqrt((x-1)/2))
+ Hyperbolic sine  (ex - e-x) / 2
+ Hyperbolic cosine  (ex + e-x) / 2
+ Hyperbolic tangent  (ex - e-x) / (ex + e-x)

### Hyperbolic sine         (e^x - e^-x)/2
### Hyperbolic cosine       (e^x + e^-x)/2
### Hyperbolic tangent      (e^x - e^-x)/(e^x + e^-x)
### Hyperbolic arc sine     log(x + sqrt(1 + x^2))
### Hyperbolic arc cosine   2 log(sqrt((x + 1)/2) + sqrt((x - 1)/2))

f) Like above change style of sections reference.
EXAMPLE
cl:functions:acosh.diff, lines 100-103.

-log, sqrt, Section 12.1.3.3 (Rule of Float Substitutability)
+ Function LOG
+ Function SQRT
+ {\secref\FloatSubstitutability}

### log, sqrt, Section 12.1.3.3 {\secref\FloatSubstitutability}

f) Symbol

<TT>

is often missing, don't care.
EXAMPLE
cl:constant_variables:boole-1.diff, lines 9-13.

- (boole boole-eqv 17 15) =>  -31
-<TT>
+(boole boole-ior 1 16)

g) Also disregard symbol if it appare

<A>

EXAMPLE
cl:declarations:dynamic-extent.diff, lines 7-8.

-(dynamic-extent [[var* | (function<A> fn)*]])
+ (dynamic-extent [[var* | (function fn)*]])

h) Disregard:

declare, declaim, proclaim
+Symbol DECLARE, Macro DECLAIM, Function PROCLAIM

i) Disregard line starting with:
"The following X3J13 cleanup issues"

6. Some entries are totaly the same so there diffs are empty, @rhmsilva check that. There are the list of all empty files that I found. cl:functions:hash-table.p.diff name look strange some, probably should be hash-table-p, some better check this.

List of identical files in CLUS and CLHS.
cl:functions:first_to_tenth.diff
cl:functions:hash-table.p.diff (Strange name of file, probably should by hash-table-p. To CHECK.)
cl:types:restart.diff
cl:types:satisfies.diff
cl:types:standard-class.p.diff
cl:types:standard-object.diff
cl:types:storage-condition.diff
cl:functions:setf-table.p.diff
cl:functions:setf-class-name.diff
cl:types:control-error.diff
cl:types:division-by-zero.diff
cl:types:floating-point-inexact.diff
cl:types:floating-point-invalid-operation.diff
cl:types:floating-point-overflow.diff
cl:types:floating-point-underflow.diff
cl:types:generic-function.diff
cl:types:method-combination.diff
cl:types:program-error.diff

[vindarel]

thanks for the detailed explanations.

I'd also welcome a doc on setup: how to install dokuwiki and give it the CLUS pages (see my attempts at my first comment). (I was actually thinking into putting syntax highlighting, even if it is not the core priority.)

[phoe]

Hey, I will get to you on Saturday and describe this. I will most likely create a repo containing my custom hacked DokuWiki instance that displays the CLUS markup correctly.

[KZiemian]

@vindarel Do you need any help with this project? I don't know dokuwiki at all, but in other topics maybe I can help?

[phoe]

@vindarel @KZiemian Sorry - I did not make it in time.
I will try to do this next week.

[vindarel]

@KZiemian to be honest, it's not all clear to me.

First, how where these diff files generated ?

THE MOST IMPORTANT is to mark which version in diff is CLHS and which is CLUS.

couldn't the generation script mark which is the CLHS ?
What are the CLUS changes and what is missing ?

And I suppose we can refer to this resource: http://cvberry.com/tech_writings/notes/common_lisp_standard_draft.html (the standard in nice pdf, with a TOC sidebar) (and tex sources)

---

Let's consider https://github.com/phoe/clus-data/blob/master/diffs/cl:constant_variables:array-dimension-limit.diff what do we have to do about it ?

thanks again :) and @phoe, no worries.

[KZiemian]

@vindarel Diffs was make by @rmhsilva I don't know how, but it was very big help for us. I ask him some question about marking all +content as CLUS week ago, but he didn't have time to responed. So I say to myself: ok, better to work this out, than the project stuck. Ulitmetly @phoe who is Master of All CLUS say this checking must be done, so I try do it best as I can.

"What are the CLUS changes and what is missing?" This may sound funny, but change is what @phoe say it is a change. I constatntly ask him about thigs I notice. I don't have time now, but I write in the evening more extensivly. One cleary example of thing to notice is wrong mathematical equation. In CLUS "^" is often missing, so we must note where is missing and write correct version of it. You can find it in cl:functions:acosh.diff.

Sorry for english I write in hurry.

[KZiemian]

@vindarel This is description how look my work on file cl:constant_variables:array-dimension-limit.diff.

First I try to find which is CLHS and which CLUS. Often this is very easy, this time I must google "clhs array-dimension-limit". Compering that page I find that +content is CLUS and -content is CLHS.

Second I look on red and green lines. I see that line 14 "-Description" is missing in CLUS, so I note that. Also I find that text is in diffrent order in this two version.

In CLUS this will look like
"""The upper exclusive bound on each individual dimension of an array.

Constant Value

A positive fixnum, the exact magnitude of which is implementation-dependent, but which is not less than 1024."""

In CLHS
"""A positive fixnum, the exact magnitude of which is implementation-dependent, but which is not less than 1024.
Description

The upper exclusive bound on each individual dimension of an array."""

I note that in file. It is big change in text, so it is resonable thing to do. You must ask @phoe what we will do with that.

Next I see
"""-Examples None.
+Examples
+None."""
It's only change formating, so no need to notice something like that.

Another peaces
"""-make-array
-Notes None.
\ No newline at end of file
+Function MAKE-ARRAY
+Notes
+None."""
Apart of not important change in formating "make-array" goes to "Function MAKE-ARRAY", but this is one from examples from list that I puted some time ago, that we don't mind. "\ No newline at end of file" also is not something that need to be noted.

I myself still don't understand how CLUS will be build, so I can't answer many question. Again, if you need answer @phoe is the person you should ask.

[KZiemian]

@vindarel here is a list of few things that I find to this moment that happened in CLUS with regard to CLHS. This list can be much longer, but I must look to a checked files and think what is worth mentioning and what is just pedantic precision.

• Paragraphs in diffrent order.
• Large parts of CLHS text missing.
• Wrong mathematical equations. Typical example: "e2" when should "e^2".
• Possible bad formating. E.g. Line broke in half of sentence.
• Diff was taken between diffrent topics in CLUS and CLHS.

If you need more information, give a sign to me.

[budden]

Hi! Idea of your project is very fine, but I'm not sure you're not violating Lispworks copyright. By using diffs with CLHS and changing CLUS to make them smaller, you seem to take CLHS texts indirectly. I'd be glad if someone proves me wrong.

[phoe]

@budden You're most likely right. Let me investigate the issue a bit further.

[phoe]

@budden You are right. I'll do something about the matter as soon as I finish being sick and once I can think straight about the matter.

[budden]

Sure! Get healthy! 2017-09-03 22:56 GMT+03:00, Michał Herda <[email protected]>:

…

@budden You are right. I'll do something about the matter as soon as I finish being sick and once I can think straight about the matter. -- You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub: #24 (comment)

[KZiemian]

@vindarel Did you join #clus-general at Discord? There is possible big problem with diffs, so better stay in touch.

[vindarel]

@KZiemian hey I logged in there a few times but it isn't a habit yet :) Thanks for the notice, I'll keep me informed.

[KZiemian]

@vindarel I try to clean a mess that I make with diff moving they between operating systems, do you have time and will do something with them now or not yet? If you do, I will try quickly remove that mess.

[KZiemian]

@vindarel If you want most "To do" diffs in diff cataloge need work, you can try do something with them. I apologized by mess, maybe next week that would be cleaned.

[vindarel]

sorry but the task isn't clear enough to me. I also have the impression that many things are being redesigned right now so the work to be done may change, including this.

[KZiemian]

@vindarel Yes, untile phoe don't cameback on full time, noone will know what realy need to be done. If you have more questions, I will try answer as best as I can.