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.
--
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+unsubscr...@googlegroups.com.
To post to this group, send email to racket-dev@googlegroups.com.
To view this discussion on the web visit
https://groups.google.com/d/msgid/racket-dev/5534E027.8050704%40neilvandyke.org.
For more options, visit https://groups.google.com/d/optout.
