Re: [racket-dev] [plt] Push #26372: master branch updated

2013-02-27 Thread Norman Gray

Greetings.

On 2013 Feb 27, at 01:14, Matthew Flatt  wrote:

> I think part of the problem is distinguishing "module declarations"
> (which don't have a phase) from "module instantiations" (which are
> normally phase-specific).

If 'which don't have a phase' is the key phrase, how about:

phase-neutral
phase-independent
unphased
phase-exempt

'phase-invariant' prompts (to me) the question '...under what transformation?'; 
'phase-independent', like 'phase-neutral', in contrast suggests that the phase 
isn't relevant to them.

Norman


> 
> I want an adjective for a declaration that describes a treatment of its
> instances. "Phaseless" is bad, because no module declaration has a
> phase, but "all-phase" has the same problem.
> 
> "Phase-invariant" could work, although that sounds like a property that
> module declarations might have even if they're not treated specially.
> 
> How about "phase-collapsing"? That suggests more (to me) that something
> special is happening.
> 
> At Tue, 26 Feb 2013 17:53:14 -0500, Ray Racine wrote:
>> all-phase modules
>> static modules
>> static-phase modules
>> phase-invariant modules
>> 
>> 
>> 
>> 
>> On Tue, Feb 26, 2013 at 5:31 PM, Vincent St-Amour 
>> wrote:
>> 
>>> At Tue, 26 Feb 2013 16:59:01 -0500,
>>> mfl...@racket-lang.org wrote:
>>>> 899a327 Matthew Flatt  2013-02-26 14:14
>>>> :
>>>> | add experimental support for "phaseless" modules
>>>> |
>>> 
>>> After reading the docs, I find the name "phaseless" confusing. IIUC,
>>> these modules are not special because they have no phase, but rather
>>> because they're the same at all phases.
>>> 
>>> Would "pan-phase", "omni-phase" or "cross-phase" be an accurate
>>> description?
>>> 
>>> Vincent
>>> _
>>>  Racket Developers list:
>>>  http://lists.racket-lang.org/dev
>>> 
> _
>  Racket Developers list:
>  http://lists.racket-lang.org/dev

-- 
Norman Gray  :  http://nxg.me.uk
SUPA School of Physics and Astronomy, University of Glasgow, UK


_
  Racket Developers list:
  http://lists.racket-lang.org/dev


Re: [racket-dev] Documentation lacuna?

2013-01-22 Thread Norman Gray

Jay, hello.

On 2013 Jan 22, at 14:24, Jay McCarthy  wrote:

> I've pushed this change:

The example makes it very clear, and is more direct than what I wrote.

I did notice "then @racket[mime] is add as a", which should be "added", but I 
think my inner copy-editor needs a holiday

All the best,

Norman


-- 
Norman Gray  :  http://nxg.me.uk
SUPA School of Physics and Astronomy, University of Glasgow, UK


_
  Racket Developers list:
  http://lists.racket-lang.org/dev


Re: [racket-dev] Documentation lacuna?

2013-01-21 Thread Norman Gray

Jay, hello.

On 2013 Jan 21, at 16:12, Jay McCarthy  wrote:

> I don't understand your concern.
> 
> The response structure, which is the only actual structure (everything
> else is an interface on it)...
> 
> a) Allows #f as the mime type

...but the documentation doesn't say what #f means here.  Does it mean 'dunno, 
you work it out', or 'there is no content', or 'use some default'? In fact it 
means "I promise there isn't any output, so so I don't have to tell you a MIME 
type", but that can only be discovered from experiment or inspecting the source.

> b) Has you provide an 'output' function that does the output. If you
> don't want there to be any output, then don't write any:
> 
> (response 304 #"304" (current-seconds) #f empty void)

When I read the documentation for RESPONSE, I thought 'oh dear, it doesn't know 
about no-content responses', because it reads as if it assumes (and implements) 
that every HTTP response has a message-body.  Reading "output produces the 
body" suggests that there's always supposed to be a body, especially because it 
seems to suggest that it _always_ produces a Content-Type header.  I don't 
think this is an outrageously wrong reading of the paragraph.

> So, what exactly is it that you want, if not what is already provided?

How about a second paragraph after "An HTTP response..." which reads:

> Certain HTTP responses (with status 1xx, 204 and 304) have no content.  These 
> are correctly generated with a response structure which has #f for 'mime' and 
> 'void' for 'output'.  Such responses have no message-body, and no 
> content-length or content-type headers.

An alternative interface would be to have the response structure let output be 
(or/c false/c (-> output-port? void?)), and indicate that output:#f produces no 
output, ignores any MIME type and produces no Content-Type header.  That's 
potentially clearer (easier to guess the effect of) in the no-output case.

(response
  304 #"Not Modified"
  (current-seconds)
  #"IGNORED"
  (list (make-header #"Location" #"http://racket-lang.org/download";))
  #f)

Finally: Re-reading what I first wrote, I suspect I was becoming slightly 
fixated on response/full over response, which meant I was a good bit less clear 
than I should have been.  Sorry about that.

Best wishes,

Norman


-- 
Norman Gray  :  http://nxg.me.uk
SUPA School of Physics and Astronomy, University of Glasgow, UK


_
  Racket Developers list:
  http://lists.racket-lang.org/dev


Re: [racket-dev] Documentation lacuna?

2013-01-21 Thread Norman Gray

Sorry, an addendum...

On 2013 Jan 21, at 12:23, Norman Gray  wrote:

> In the web server, the documentation for RESPONSE and, by implication, 
> RESPONSE/FULL does not explain how to avoid including a message-body in the 
> response, as is required for 1xx, 204, 304 statuses (and those alone).
> 
> By experiment, giving RESPONSE/FULL a 'body' argument of #"" produces the 
> right effect, but:
> 
>  (a) it would be reassuring if this case was mentioned in the documentation;
> 
>  (b) this still produces a content-length:0 header.

The other thing (ahem...) is that without such an explanation, it's not clear 
what to put as the MIME type.

Since there's no content, it's tempting to conclude that the 'mime' argument is 
ignored.  If, however, one gives this argument as #"" (on the grounds that it 
doesn't matter what it is), this is faithfully send down the wire as a 
"Content-Type: " header, which is invalid.  Giving 'mime' as #f (which is 
allowed in the contract of RESPONSE but not otherwise documented) _does_ 
suppress the content-type header, even though the documentation for RESPONSE 
states that the server will automatically add a Content-Type header if one is 
not present.

That is, one can produce the correct behaviour here, even though the 
documentation seems to suggest that no-body responses will be problematic.

Best wishes,

Norman


-- 
Norman Gray  :  http://nxg.me.uk
SUPA School of Physics and Astronomy, University of Glasgow, UK


_
  Racket Developers list:
  http://lists.racket-lang.org/dev


[racket-dev] Documentation lacuna?

2013-01-21 Thread Norman Gray

Greetings.

In the web server, the documentation for RESPONSE and, by implication, 
RESPONSE/FULL does not explain how to avoid including a message-body in the 
response, as is required for 1xx, 204, 304 statuses (and those alone).

By experiment, giving RESPONSE/FULL a 'body' argument of #"" produces the right 
effect, but:

  (a) it would be reassuring if this case was mentioned in the documentation;

  (b) this still produces a content-length:0 header.

A problem is that without reassurance in (a), giving an empty 'body' feels 
slightly like a hack.  It might be that allowing an 'output' or 'body'' 
argument of #f would communicate the intent more clearly.

Regarding (b), RFC 2616 Sect. 4.4 doesn't say that a Content-Length header is 
invalid in one of these responses, but it does imply (point 1 in that section) 
that the Content-Length header should be ignored in that case.  This means that 
it's slightly unsightly (no more) that the header appears in a RESPONSE/FULL 
response.

So, suggestion: either support an 'output' (for RESPONSE) or 'body' (for 
RESPONSE/FULL) argument of #f, which is documented to be appropriate only for 
certain statuses, and which suppresses the content-length; or document that 
giving a 'body' of #"" is indeed the approved way of giving a no-body response 
for these statuses, and that the content-length is generated but redundant.

Best wishes,

Norman


-- 
Norman Gray  :  http://nxg.me.uk
SUPA School of Physics and Astronomy, University of Glasgow, UK


_
  Racket Developers list:
  http://lists.racket-lang.org/dev


Re: [racket-dev] OS X 10.8 includes new restrictions on running apps

2012-02-22 Thread Norman Gray

John, hello.

On 2012 Feb 22, at 21:52, John Clements wrote:

> FWIW: actually, I don't see Jens saying that signed apps will by default run 
> in a mode that enforces privilege checking, and I just spent a few minutes 
> digging, and didn't find anything saying that. Are you really sure that 
> Gatekeeper's "level 2"--code must be signed, but not app-store-ready--will 
> enforce access restrictions? Pointers gladly appreciated, and maybe I'm just 
> not reading carefully enough.

I had formed that impression, and it seems consistent with what I've read, but 
now I'm not so sure.

I've found two (good as usual) Ars Technica discussions of Gatekeeper in 
general [1], plus a reasonably detailed account of the sandboxing mechanism and 
how Apple expect people to use it [2].  It seems that the expectation is that 
different threads might have different entitlements, depending on what they do, 
so that a thread which is decoding a PDF is denied access to the filesystem; 
and that certain user actions, such as saving a file, will be handed over (if 
necessary) to a privileged 'Powerbox' daemon.

All very entertaining, but it doesn't actually answer your question.  I'm 
afraid I can find neither chapter and verse, nor exegesis, which makes it clear 
what the default will be.

So I'd appreciate pointers, too!

Best wishes,

Norman


[1] 
http://arstechnica.com/apple/news/2012/02/developers-gatekeeper-a-concern-but-still-gives-power-users-control.ars
http://arstechnica.com/apple/news/2011/11/apple-pushes-back-sandboxing-deadline-as-devs-struggle-with-tradeoffs.ars
[2] http://arstechnica.com/apple/reviews/2011/07/mac-os-x-10-7.ars/9

-- 
Norman Gray  :  http://nxg.me.uk
SUPA School of Physics and Astronomy, University of Glasgow, UK


_
  Racket Developers list:
  http://lists.racket-lang.org/dev


Re: [racket-dev] OS X 10.8 includes new restrictions on running apps

2012-02-22 Thread Norman Gray

Greetings.

On 2012 Feb 22, at 20:03, Jens Axel Søgaard wrote:

> The tech press reports that the default is to "medium" i.e. applications
> downloaded from the mac app store and from identified developers (that is
> signed applications) are allowed to run.

For those who haven't chased this up already (I haven't gone into much detail), 
there are some interesting links at Daring Fireball[1], including a piece which 
highlights some of the likely problems[2].

The short version appears to be that, as Jens says, Gatekeeper will by default 
run in a mode which enforces MAC on applications, and the principal problem -- 
voiced at length and at high volume -- is that the currently available set of 
'entitlements' (where the application declares what set of resources it wishes 
to have access to) is too small for a significant minority of applications.

For what it's worth, it seems to me that MAC is a Good Thing for me as a user 
-- there are some applications that really have no business wandering all over 
my system, poking around (no, you may _not_ have access to my address book!) -- 
but I can see this potentially being a right pain in the tender bits for me as 
a developer, and a user of scripting environments such as Racket.  It all 
depends on the details of the entitlements DSL, and who gets to declare what, 
when.

All the best,

Norman
(currently with no plans to move from 10.6)

[1] http://daringfireball.net/linked/2012/02/21/sandboxing
[2] http://www.red-sweater.com/blog/2324/fix-the-sandbox

-- 
Norman Gray  :  http://nxg.me.uk
SUPA School of Physics and Astronomy, University of Glasgow, UK


_
  Racket Developers list:
  http://lists.racket-lang.org/dev


Re: [racket-dev] Formlets and POST

2012-02-20 Thread Norman Gray

Jay, hello.

On 2012 Feb 20, at 17:51, Jay McCarthy wrote:

> I just pushed something to address this.
> 
> It adds a keyword argument to send/formlet to control the method and
> defaults it to POST.

That sounds like an excellent solution.

Best wishes,

Norman


-- 
Norman Gray  :  http://nxg.me.uk
SUPA School of Physics and Astronomy, University of Glasgow, UK

_
  Racket Developers list:
  http://lists.racket-lang.org/dev


[racket-dev] Formlets and POST

2012-02-19 Thread Norman Gray

Greetings.

Web-server formlets currently send their form input back to the server via an 
HTTP GET request.  They should probably generate a form which uses HTTP POST 
instead.

There are two problems with using GET for this.

1. If there's any sensitive information in the form, such as a password, then 
it's very obviously exposed in the URL and stored in logs, which wouldn't be 
the case if the form contents are in the HTTP request body instead.  The latter 
would provide at least a little bit of obscurity, rather than serious security. 
 This is of course not a great way to do authentication (to say the least), but 
if one trusts the network or one is talking to localhost, then it's good enough 
for some applications.  The problem isn't just confined to passwords, obviously.

2. HTTP defines GET to be side-effect free, and cacheable.  Therefore if 
there's an intermediary server between the client and the server, and it sees a 
GET request being made, it is (a) permitted to send a cached version if the URL 
is one it has seen before, and (b) permitted to make the GET request to the 
origin server multiple times (for example if there is or appears to be a 
failure), and send only one response to the client.  Either of these might mess 
up the form-mediated client-server interaction, and there's nothing anyone can 
do about it.  This is probably more of a theoretical problem than a common 
practical one.  POST is not defined to be side-effect free, and is not 
automatically cacheable.

Of course (again), the point of continuation-based forms is that they're 
functional, just like GET, but many people implement services using GET forms 
which are intended to have side-effects.

Simply defining (and using) a send/formlets/post which is identical to 
send/formlets but with a [method "POST"] added, seems to work fine, because 
formlet-process uses request-bindings/raw, which handles both GET and POST 
requests.  Therefore, I think that should probably be the default.

Best wishes,

Norman


-- 
Norman Gray  :  http://nxg.me.uk
SUPA School of Physics and Astronomy, University of Glasgow, UK


_
  Racket Developers list:
  http://lists.racket-lang.org/dev


Re: [racket-dev] new logo

2012-02-15 Thread Norman Gray

Greetings.

On 2012 Feb 14, at 20:37, Neil Toronto wrote:

> Here's the deal, though. This one, even just the "lambda r." in a circle, is 
> pushing complexity. We've been approaching logo design too much like language 
> design, trying to cram as much semantic content as possible into a small 
> space or into the fewest shapes. A logo exists primarily to make a good 
> impression on outsiders. Filling it with too much meaning works actively 
> against this.

That's very true.

Also, there's quite a lot of visually arresting features in that banner -- the 
lambda in a circle, the artfully mismatched brackets, the shape of the letters, 
the margins on the letters, the colours -- each one of which would be 
distinctive by itself.

Here's another banner-shaped suggestion: <http://nxg.me.uk/temp/lambdas.html>.  
Perhaps I just like white space, but this seems to say quite a lot, and be 
distinctive, without looking busy (the 'r' is different from the previous 
suggestions, being Optima rather than Gill Sans).

Scheme is all about letting a little say a lot, and so it seems to me that 
really pared-back minimalism is a great look for Racket.  Logos should be 
designed not by piling feature on top of feature, but by removing

Best wishes,

Norman


-- 
Norman Gray  :  http://nxg.me.uk
SUPA School of Physics and Astronomy, University of Glasgow, UK




_
  Racket Developers list:
  http://lists.racket-lang.org/dev


Re: [racket-dev] new logo

2012-02-13 Thread Norman Gray

Greetings.

On 2012 Feb 13, at 17:03, Matthias Felleisen wrote:

> I do actually like the combination of lambda and r, though I am sure the 
> color scheme could benefit from some variation. 

Less might be more, but <http://nxg.me.uk/temp/lambda-r6.pdf> shows an 
adjustment.  The blue is a bit too light, the red a bit too pink, and the text 
could perhaps be a shade bigger, but the shape is not, I think, unpleasing.

All the best,

Norman


> On Feb 13, 2012, at 10:25 AM, Norman Gray wrote:
> 
>> 
>> On 2012 Feb 13, at 14:54, Philippe Meunier wrote:
>> 
>>> For some reason it slightly reminds me of a symbol for some religious
>>> cult or political party, which might or might not be a good thing.
>> 
>> Whoa!  Doesn't it just!
>> 
>> Another thing that occurred to me, on the same model as before, is to go for 
>> an almost completely typographical logo.  At 
>> <http://nxg.me.uk/temp/lambda-r5.pdf> is a possibility.  It's just '\r.', 
>> really, but with the lambda in a cursive font, the 'r.' in a modern one 
>> (Gill Sans), and some pretty aggressive tracking to make it into a unit.
>> 
>> That doesn't have the shinies of other suggestions, but it's obviously very 
>> adaptable and (to my aesthetic at least) matches the chiselled restraint of 
>> a Scheme.
>> 
>> I think that's exhausted my visual creativity for the day, so I'll shut up 
>> now
>> 
>> All the best,
>> 
>> Norman
>> 
>> 
>> -- 
>> Norman Gray  :  http://nxg.me.uk
>> SUPA School of Physics and Astronomy, University of Glasgow, UK
>> 
>> 
>> _
>> Racket Developers list:
>> http://lists.racket-lang.org/dev
> 

-- 
Norman Gray  :  http://nxg.me.uk
SUPA School of Physics and Astronomy, University of Glasgow, UK


_
  Racket Developers list:
  http://lists.racket-lang.org/dev


Re: [racket-dev] new logo

2012-02-13 Thread Norman Gray

On 2012 Feb 13, at 14:54, Philippe Meunier wrote:

> For some reason it slightly reminds me of a symbol for some religious
> cult or political party, which might or might not be a good thing.

Whoa!  Doesn't it just!

Another thing that occurred to me, on the same model as before, is to go for an 
almost completely typographical logo.  At <http://nxg.me.uk/temp/lambda-r5.pdf> 
is a possibility.  It's just '\r.', really, but with the lambda in a cursive 
font, the 'r.' in a modern one (Gill Sans), and some pretty aggressive tracking 
to make it into a unit.

That doesn't have the shinies of other suggestions, but it's obviously very 
adaptable and (to my aesthetic at least) matches the chiselled restraint of a 
Scheme.

I think that's exhausted my visual creativity for the day, so I'll shut up 
now

All the best,

Norman


-- 
Norman Gray  :  http://nxg.me.uk
SUPA School of Physics and Astronomy, University of Glasgow, UK


_
  Racket Developers list:
  http://lists.racket-lang.org/dev


Re: [racket-dev] new logo

2012-02-13 Thread Norman Gray

Greetings.

I've no real standing here -- this is an observation from the sidelines

On 2012 Feb 13, at 06:05, SF wrote:

> Another way to combine lambda and capital R:
> http://i.imgur.com/PuGTE.png

Combining the lambda and the R in this way looks like a very good idea to me.

I can see the point to the original 'r' logo -- it picks up the previous PLT 
colours, it looks nicely informal (though that particular example perhaps went 
a little too far, and could look childish), and of course it picks up the 'r' 
of Racket.  I'm also one of those who thinks it'd be a shame to lose the 
lambdas, and I think that SF's suggestion here marries several of these 
desiderata.

With that in mind, I'll suggest a variant of it (born analogue, I'm afraid, 
rather than as pixels)

http://nxg.me.uk/temp/lambda-r.png

The first three seem to be tending towards the florid, but some more rhythmic 
version of the other three -- variants of 'λr.' -- might be worth closer 
examination.  I'm aware the last one of the six is starting to look more like 
lambda-tau.

Best wishes,

Norman


-- 
Norman Gray  :  http://nxg.me.uk
SUPA School of Physics and Astronomy, University of Glasgow, UK


_
  Racket Developers list:
  http://lists.racket-lang.org/dev


Re: [racket-dev] Racket home page proposal

2011-12-20 Thread Norman Gray

Greetings.

On 2011 Dec 20, at 05:34, Asumu Takikawa wrote:

> Currently, the Racket home page is really nice, but it leaves a
> significant amount of vertical space unused that could be used to
> communicate information.

...or which could be used, as now, to project authority and decisiveness.

The white space below the text currently on the Racket page says "this is all 
that has to be said at this point; follow the links above for more 
information".  That makes me at least pay more attention to it.

If there's more text on the page, as in the sample page, I read less of it, and 
I don't imagine I'm alone in that.

I can feel my eyes gliding over the page, trying to find some way of parsing 
it.  I alight on the 'Download Racket' link, and on the 'About', 'Download', 
'Documentation', ... headlines, and they end up being the only things I see at 
all.

Best wishes,

Norman


-- 
Norman Gray  :  http://nxg.me.uk
SUPA School of Physics and Astronomy, University of Glasgow, UK


_
  For list-related administrative tasks:
  http://lists.racket-lang.org/listinfo/dev


Re: [racket-dev] Missing pregexp syntax in Racket

2011-11-29 Thread Norman Gray

On 2011 Nov 29, at 18:14, Neil Van Dyke wrote:

> 1. Everyone should acknowledge the JWZ quote, "Some people, when 
> confronted with a problem, think 'I know, I'll use regular expressions.' 
> Now they have two problems."  Regular expressions are Perl's hammer that 
> makes most problems look like a nail.

What Neil said! 

> 2. Before someone spends too much time putting the finishing touches on 
> old Unix/Perl regular expression syntax, they might want to look at Olin 
> Shivers's SREs.  Sexp-based regular expression syntax can be a big 
> readability win when your regexps get complicated.  
> http://www.ccs.neu.edu/home/shivers/citations.html#sre


What Neil said _and_ what Shivers said!

Implementing Shivers-style SREs would be a much bigger win than any alternate 
pregexp syntax with differently funky backslash rules from everything else.

Norman


-- 
Norman Gray  :  http://nxg.me.uk
SUPA School of Physics and Astronomy, University of Glasgow, UK


_
  For list-related administrative tasks:
  http://lists.racket-lang.org/listinfo/dev


[racket-dev] PLaneT and proxies

2011-10-08 Thread Norman Gray

Greetings.

A while ago, there was a discussion on users, which moved to dev, about 
PLaneT's support for HTTP proxies.

http://lists.racket-lang.org/users/archive/2010-June/039949.html
http://lists.racket-lang.org/dev/archive/2010-June/003496.html

Reading through that thread now, I see that it included some code, some 
pointers to 'specs', lamentations on the general awfulness of proxies, and 
ended with the (good) suggestion that the problem could often be avoided by 
using DrRacket to install PLaneT packages.  That last suggestion may have taken 
the wind out of anyone's enthusiasm to add support for proxy configuaration.

One can of course install PLaneT packages using raco, but that rapidly becomes 
quite fiddly when a package has a network of dependencies.

This problem has cropped up again for me, and in a context (ssh-only access to 
a machine) where I can't use DrRacket to avoid the problem.

Can I therefore take this opportunity to raise this as a possible project for 
anyone with some Copious Free Time needing used?  There were a few plausible 
fragments of code in the above threads, which might make this quite a small 
project.

Best wishes,

Norman


-- 
Norman Gray  :  http://nxg.me.uk
SUPA School of Physics and Astronomy, University of Glasgow, UK


_
  For list-related administrative tasks:
  http://lists.racket-lang.org/listinfo/dev


Re: [racket-dev] PLaneT and proxies

2010-09-29 Thread Norman Gray

Robby, hello.

Back around 2010 June 20, there was a discussion about PLaneT and proxies.  It 
ended with:

On 2010 Jun 21, at 09:43, Norman Gray wrote:

>> Oh-- Eli pointed out something offlist: did you try starting up
>> drracket, setting its proxy preferences and then trying to install
>> something from planet?
> 
> I didn't try that -- it didn't occur to me, I'm afraid.  I imagine that would 
> work fine (if I need to do this again, and it doesn't work, I'll shout).

I just have now needed to do this again, and it it works fine, once DrRacket 
has its proxy settings correct.

Best wishes,

Norman


-- 
Norman Gray  :  http://nxg.me.uk

_
  For list-related administrative tasks:
  http://lists.racket-lang.org/listinfo/dev


Re: [racket-dev] Scribble in-source documentation documentation

2010-06-28 Thread Norman Gray

Greetings.

On 2010 Jun 26, at 20:47, Norman Gray wrote:

> Greetings.
> 
> Section 4.5 of the Scribble docs, 'In-Source Documentation' refers to the 
> file/gif.rkt source as a useful example of this practice. 
[...]

Looking at this message again, it strikes me that it's rather rambling.  Sorry 
'bout that -- it started off as a quick report, and grew.

The point was that there seemed two places within the scribble docs where the 
docs seemed not to match reality (ie, apparent documentation bugs), and a third 
place where the scribble system didn't behave as the docs suggested (ie, a bug 
in the implementation, or rather opaque docs).

Should this instead have gone to the users list?

Best wishes,

Norman


-- 
Norman Gray  :  http://nxg.me.uk

_
  For list-related administrative tasks:
  http://lists.racket-lang.org/listinfo/dev


[racket-dev] Scribble in-source documentation documentation

2010-06-26 Thread Norman Gray

Greetings.

Section 4.5 of the Scribble docs, 'In-Source Documentation' refers to the 
file/gif.rkt source as a useful example of this practice.  However, probably 
due to version changes, that file now looks different from what's described in 
the section it purportedly exemplifies.

Namely (noting docs -> gif.rkt):

  * '#reader scribble/reader' -> '#lang at-exp scheme/base'

  * '(require/doc scribble/base scribble/manual)' -> '(require/doc scheme/base 
scribble/manual)'



Separately, the documentation for proc-doc/names shows the structure of the 
form as

(proc-doc/names id contract ((arg-id ...) ((arg-id default-expr) ...)) 
desc-expr)

I read that as requiring two subforms within the third proc-doc/names argument, 
even if there are zero (arg-id default-expr) forms.  Thus this seems to suggest 
that a procedure with one mandatory and no optional arguments would be declared 
as 

(proc-doc/names foo (-> type type) ((arg1) ()) @{Description})

I appreciate there isn't really a formal grammar here, but adding a further 
exemplar line without the default-expr forms might be clearer -- is there 
perhaps a missing template

(proc-doc/names id contract (arg-id ...) desc-expr)

As it was, it took some grepping through collects/* before I worked out why I 
was getting errors with my first attempt (no tragedy, of course, but it slows 
one down...).



Separately (again), the discussion in section 4.5.2 might benefit from some 
attention.  The description of provide-extracted mentions that "the 
documentation is packaged and exported as exported, instead of left inline."  I 
think I can see the intention here, but the phrase 'exported as exported' seems 
terribly important without being at all transparent as to meaning.  This 
paragraph suggests that provide-extracted should go in the scribble file, while 
the next one seems to suggest that it should instead go in the module file.  
Then I look around and find framework/main.scrbl, which refers to 
main-extracts.ss, and ... I'm starting to get a bit confused.  I think I may 
now see which (third!) file the provide-extracted form should go into, but it's 
definitely getting a bit voodoo, now.

I can't just flail around and experiment, because the module I'm trying to 
document doesn't appear to work in an expected way with include-extracted.  In 
my scribble file I have 

% cat rdf.scrbl
#lang scribble/manual
@(require scribble/extract)
@title{The rdf library, wrapping librdf.org}
If you give a mouse a cookie, he's going to ask for a glass of milk.
@(include-extracted "../src/build/rdf.ss")
%

In the rdf.ss I have a line '(require "librdf-extn.rkt")', and in ../src/build 
I have rdf.ss and compiled/native/i386-macosx/3m/librdf-extn_rkt.dylib (ie, an 
extension, with no associated .rkt or .ss file).  Running scribble then gives:

% scribble --html rdf.scrbl
default-load-handler: cannot open input file: 
"/checkouts/me/code/plt-librdf/doc/librdf-extn.rkt" (No such file or directory; 
errno=2)

 === context ===
/Data/LocalApplications/Racket/Racket 
v5.0/collects/racket/private/map.rkt:18:11: map
/Data/LocalApplications/Racket/Racket v5.0/collects/scribble/run.rkt: [running 
body]
% pwd
/checkouts/me/code/plt-librdf/doc
%

That is, the processing of include-extracted seems to be searching for required 
modules in an unexpected way.

Thanks for any illumination.  Best wishes,

Norman


-- 
Norman Gray  :  http://nxg.me.uk



_
  For list-related administrative tasks:
  http://lists.racket-lang.org/listinfo/dev


Re: [racket-dev] PLaneT and proxies

2010-06-21 Thread Norman Gray

Eli, hello.

On 2010 Jun 20, at 22:53, Eli Barzilay wrote:

> [Moving the thread to dev.]

I've subscribed for the moment.

> What about specifications of conditional proxies?  Ones that apply
> only to some domain patterns.  And I can't think of a good way to do
> this if instead of name patterns the specs are for a numeric range --
> doing an explicut DNS lookup in these cases seem like a bad idea.

[and]

> I think it's important to find where it's documented.  I looked around
> and didn't see anything official-looking.  It's especially important
> to find out the preference of this over other facilities (as in the
> OSX case).

My impression is that it's _not_ documented, but instead just part of unix lore.

Libcurl says <http://curl.haxx.se/libcurl/c/curl_easy_setopt.html> that 
"libcurl respects the environment variables http_proxy, ftp_proxy, all_proxy 
etc, if any of those are set", without saying what it respects them to say; 
Lynx 
<http://lynx.isc.org/lynx2.8.5/lynx2-8-5/lynx_help/keystrokes/environments.html#proxy>
 gives the nearest thing to a specification, and since it's been around for a 
long time, it probably gets to win.

The description there is pretty simple-minded, but probably elaborate enough, 
in the sense that if any organisation sets up a network environment which has 
proxy requirements which can't be handled by this configuration framework, then 
it's clear it's their stupid fault for being fussy, and they can sort it out 
themselves (by getting out their router manuals and doing it transparently, at 
the correct layer).  Short version: proxies are supposed to be quick and dirty, 
so there's no need for complication here.

The following logic might be adequate:

#lang racket

(define getenv
  ;; trashy little getenv simulator
  (let ((table '()))
(λ (k . rest)
  (cond ((pair? rest)
 (set! table (cons (cons k (car rest)) table)))
((assoc k table) => cdr)
(else #f)

;; RETRIEVE-URL-WITH-PROXY? : string -> boolean
;; Given a host name as a string, determine whether HTTP URLs at this
;; host should be retrieved via a proxy, respecting the settings
;; in http_proxy and no_proxy.
(define (retrieve-url-with-proxy? host-string)
  (let ((proxy (getenv "http_proxy"))
(no_proxy (cond ((getenv "no_proxy") => (λ (s) (regexp-split #rx", *" 
s)))
(else #f
(cond ((not proxy) #f)
  (no_proxy
   (let loop ((vetos no_proxy))
 (cond ((null? vetos) #t)
   ((regexp-match? (regexp (string-append (car vetos) "$")) 
host-string) #f)
   (else (loop (cdr vetos))
  (else #t


(printf "without anything: ~a~%" (retrieve-url-with-proxy? 
"www.racket-lang.org"))
(getenv "http_proxy" "cache.example.org")
(printf "with proxy: ~a~%" (retrieve-url-with-proxy? "www.racket-lang.org"))
(getenv "no_proxy" "localhost, racket-lang.org, example.com")
(printf "with no_proxy, too: ~a~%" (retrieve-url-with-proxy? 
"www.racket-lang.org"))

Possible improvements: 

1. Support ftp_proxy, etc, too (though note that no_proxy applies to all 
protocols) -- does this matter?

2. Numeric hosts in the no_proxy field.  Perhaps parse "129.10." as 129.10/16, 
and then, if and only if there's a numeric spec in the no_proxy list, do the 
hostname lookup within retrive-url-with-proxy? and compare it.  The lookup is 
going to have to happen at some point anyway, and this way, it'll be in the DNS 
cache when the HTTP connection is subsequently opened

>>  * On OS X, I think that http_proxy will typically not be set
>>(it'll only be set by people who use the command-line a lot).
>>Instead, the system-wide proxy information can be obtained by
>>using system APIs, or by parsing the output of /usr/sbin/scutil.
>>That has to be reasonably dynamic, since someone might change
>>the 'location' on a laptop, say, from 'at home' to 'at work',
>>with consequent changes to the proxy.
>> [...]
>>  * ...plus whatever windows requires.
> 
> Yeah, the OS-specific defaults should be consulted too.  IIRC, I
> looked at Windows once, and ran into some mess of a "standard" way to
> get the proxy settings for a machine.

I think I remember hearing about that once.  I've managed to forget it.

Separately, Robby said:

> So, going forward, what is the right thing? Is there something simple
> we can do for now so that Norman can use planet on his school's
> network, or should we wait for the net/url rewrite?

I'll leave my hack in my local r