raco pkg install .. and now where are the docs?

[Thomas Lynch]

So apparently my new 'liquid' package is installed locally:

§lambda1:/usr/share/doc/racket> raco link -l | grep liquid
 root  path: "/home/deep/liquid-lib"
 root  path: "/home/deep/liquid-doc"
 root  path: "/home/deep/liquid"

§lambda1:/usr/share/doc/racket> raco pkg show
Installation-wide:
 Package              Checksum                                    Source
 main-distribution    f07e2d4bf2708c1085be38eca18aa9eb6755e547    (catalog main-distribution)
 racket-lib           41c7b3221006758c5a840a18dcc0d265632f14c2    (catalog racket-lib)
 [175 auto-installed packages not shown]
User-specific for installation "6.1":
 Package    Checksum    Source
 liquid     #f          (link ../../../../deep/liquid)
 [2 auto-installed packages not shown]

So then I open /usr/share/doc/racket/index.html in a browser and naively expect to find a link to the local "catalog" which would have a links to the docs for my new package.  Ah but alas no.  Even grep -r  finds no reference to my new package in my /home/twl/.racket directory,  in /usr/share/doc or even in the /home/deep directory that holds the package data.  Come to think of it,  raco install was run with just user privileged though it didn't complain.  Is that right?  Ok so let me try with supervisor privilege:

§lambda1:/home/deep/liquid#  raco pkg install
raco pkg install: missing dependencies;
 specify `--deps search-auto' to install them, or
 specify `--deps search-ask' to be asked about installing them
  for package: /home/deep/liquid/
  missing packages:
   liquid-lib
   liquid-doc

Oh gosh, we are back to that again!  Running it as user:

§lambda1:/home/deep/liquid> raco pkg install
raco pkg install: package is already installed
  package: liquid

Ok, ah .. so where are the docs?

[Jay McCarthy]

When it is installed installation-wide, it will go in the
/usr/share/doc/racket directory, but if you have it only
user-specific, then it will go in ~/.racket/doc (or
~/.racket/<something related to 6.1>/doc) and you'll have to use the
index.html that is in that directory. This of course assumes that your
liquid-doc collection info.rkt has a line like (define scribblings
'(("scribblings/liquid.scrbl" ())))

Jay

> --
> You received this message because you are subscribed to the Google Groups
> "Racket Developers" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to racket-dev+...@googlegroups.com.
> To post to this group, send email to racke...@googlegroups.com.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/racket-dev/b8775fa1-b77c-411f-bfcf-0cbb50ee0631%40googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.



--
Jay McCarthy
http://jeapostrophe.github.io

"Wherefore, be not weary in well-doing,
for ye are laying the foundation of a great work.
And out of small things proceedeth that which is great."
- D&C 64:33

[Thomas Lynch]

situation looks like this:

§lambda1:/home/deep> ls
...  liquid  liquid-doc  liquid-lib  ...

§lambda1:/home/deep> cat liquid-doc/info.rkt
#lang info

(define collection 'multi)
(define deps '("base"))
(define build-deps '("scheme-lib"
                     "racket-doc"
                     "syntax-color-doc"
                     "liquid-lib"
                     "scribble-lib"))

(define pkg-desc "documentation part of \"liquid\"")

(define pkg-authors '(twlynch))

§lambda1:/home/deep> cat liquid-doc/liquid/info.rkt
#lang info

(define scribblings '(("liquid.scrbl" (multi-page) (deep-web-search-framework))))

And in my home directory:

§lambda1:/home/deep> ls -1 ~/.racket/6.1/doc/
blueboxes.rktd
docindex.sqlite
doc-site.css
doc-site.js
index.html
in.sxref
local-redirect
manual-fonts.css
manual-racket.css
manual-racket.js
manual-style.css
out0.sxref
out1.sxref
provides.sxref
racket.css
release
scribble-common.js
scribble.css
scribble-style.css
search
stamp.sxref
synced.rktd

I did run scribble -htmls inside of liquid-doc/liquid/doc  and created the documentation so I can now work on formatting and editing it. 

no index.html in ~/.racket/6.1/doc or subdirs for the liquid package.  Have I messed up the info.rkt files? 

When this is done right, will there be a way to navigate from the ~/racket/6.1/doc/index.html and get to the package doc pages?  Or will one always pull out the package docs from a file:///~/.racket/doc/liquid/index.html  url?

One other source of confusion, the scribble docs described the option of putting the scribble in with the source code.  However the /usr/share/racket/pkgs were not done this way.  Is this a preferred approach, or just a separate feature from the way the usual libs are done?  Seems it would be difficult to write docs that way, but sure would make it easier to keep usage examples in sync.

[Neil Van Dyke]

Thomas Lynch wrote on 04/20/2015 06:23 AM:
> One other source of confusion, the scribble docs described the option
> of putting the scribble in with the source code. However the
> /usr/share/racket/pkgs were not done this way. Is this a preferred
> approach, or just a separate feature from the way the usual libs are
> done? Seems it would be difficult to write docs that way, but sure
> would make it easier to keep usage examples in sync.

If you're asking about API docs embedded inline in Racket source code
files, IMHO, it's the preferable way to go for most reusable third-party
packages. Though not everyone's needs and preferences/strengths/tools
would agree.

The following is not the best example (just the first one I found that
the PLaneT server pretty-prints), but you can see how you can pretty
much maintain a package from one source file, including documentation,
known issues, and release history.
http://planet.racket-lang.org/package-source/neil/sudo.plt/1/1/sudo.rkt

(Separately, once there is `(module info ...)` submodule support, you
can have convenient single-file reusable packages, with no explosion of
IDE/generator BS files bloat. But for now, my tools mostly maintain
`info.rkt` for you, using `progedit`, but you still need to distribute a
package as a pile of files.)

The format of embeded documentation I use might be changing soon. I'm
throwing out McFly, due to the new package system, so I might take the
opportunity to switch the embedded documentation format from Scribble
sexp, back to 3-semicolon like I had with the earlier Funcelit (but
using Scribble-in-at-exp or some Markdown-like format, not going back to
Texinfo). One reason I'm leaning towards the 3-semicolon again is that
3-semicolon visually distinguishes code and docs nicely (especially with
very simple regexp-based editor coloring that changes the background
color and mutes the semicolons like Quack does), and is actually
pleasing to look at in context. By comparison, the existing Scribble
sexp format like you see in the above file looks too much like one's
library code, unless perhaps you have some tricky editor support (which
Quack's successor, Meow, can do, but I haven't released that). Going
back to a 3-semicolon format would also mean that I can ditch the need
to `require mcfly` in each file that uses the `doc` syntax. (The
`require mcfly` dependency has also prompted multiple people to delete
the embedded documentation out of my packages when they copy and modify
my package source files, which, among other problems, leads to volunteer
work of maintainable embedded docs being thrown away as other people
start from those forked versions ).

BTW, I'm actually happy that there's not an official way to embed API
documentation that is being pushed. In the case of my own needs, and of
my research theories and practical goals regarding reuse ecology, I'm in
the best position to design something that fits those.

Neil V.

[Alexander D. Knauth]

If you want to see it in the docs, I think you have to do one of these things:

 - raco pkg install —link path-to/liquid-lib path-to-liquid-doc path-to/liquid

or

 - raco pkg install ; in the directory of first liquid-lib, then liquid-doc, then liquid

or

 - do what you just did, but for each of the three packages, and then run raco setup liquid

[Robby Findler]

Also, the command "raco docs" with no arguments takes you to the
starting point for the documentation. This starting point can move
based on what packages you have installed, I believe (it can move from
a file that comes with a distribution into a user-specific place when
you have installed user-specific pkgs), so if you want to check what
Racket thinks the current starting point is, that's a good way to do
it.

Robby

> https://groups.google.com/d/msgid/racket-dev/5C9EE29E-5B46-474F-87BA-410C1DFA159A%40knauth.org.

[Thomas Lynch]

Actually, the libraries can't be reached either.  Tried installing from both the level above and the dir with the sources:

§lambda1:/home/deep/liquid-lib/liquid> raco pkg install

raco pkg install: package is already installed from a different source

  package: liquid

  installed source: (link ../../../../deep/liquid)

  given source: (link ../../../../deep/liquid-lib/liquid)

But in the REPL, using one of the modules defined in liquid-lib/liquid

Welcome to Racket v6.1.

racket@> (require realtime.rkt)

stdin::356: realtime.rkt: bad module path

  in: realtime.rkt

  context...:

   standard-module-name-resolver

   /usr/share/racket/collects/racket/private/misc.rkt:87:7

Realtime.rkt is defined in the new lib.  Anyway, and FYI to tie off the last open thread here.

[Alexander D. Knauth]

On May 6, 2015, at 11:07 PM, Thomas Lynch <thomas...@reasoningtechnology.com> wrote:

Actually, the libraries can't be reached either.  Tried installing from both the level above and the dir with the sources:

§lambda1:/home/deep/liquid-lib/liquid> raco pkg install

raco pkg install: package is already installed from a different source

  package: liquid

  installed source: (link ../../../../deep/liquid)

  given source: (link ../../../../deep/liquid-lib/liquid)

If you had it installed from the wrong source and you want to reinstall it from the correct source, you should probably raco pkg remove it before installing it again?

Or you could do raco pkg update new-specified-source.

But it looks like what you really want to do is run raco pkg install within deep/liquid-lib, not within deep/liquid-lib/liquid.

I personally prefer using the DrRacket package manager for this kind of thing, but that’s just my preference. I think it’s less confusing.

But in the REPL, using one of the modules defined in liquid-lib/liquid

Welcome to Racket v6.1.

racket@> (require realtime.rkt)

stdin::356: realtime.rkt: bad module path

  in: realtime.rkt

  context...:

   standard-module-name-resolver

   /usr/share/racket/collects/racket/private/misc.rkt:87:7

Realtime.rkt is defined in the new lib.  

You probably want (require liquid/realtime), not (require realtime.rkt).

By the way do you have a github repository for this or something like that?

[Thomas Lynch]

But it looks like what you really want to do is run raco pkg install within deep/liquid-lib, not within deep/liquid-lib/liquid.

ok

 

I personally prefer using the DrRacket package manager for this kind of thing, but that’s just my preference. I think it’s less confusing.

ah I've been using emacs and command line tools and no shortage of confusion .. so should have yes.

 

You probably want (require liquid/realtime), not (require realtime.rkt).

yes! thank you  (require liquid/realtime)  works.   

Other variations do not work, such as (require liquid/realtime.rkt)   or (require realtime)  or (require realtime.rkt).   The second install from the liquid directory did not take.  Just did it while trying variations in the magic incantation.

 

By the way do you have a github repository for this or something like that?

Yeah the original plan was to put all the code up on github and make a package etc. I did put a test case up there, but alas for the time being I've run out of time for working on the project..  just getting the examples running again.