Re: [racket-users] scribble namespace landgrab & embedded package documentation
Matthew Flatt wrote on 05/07/2015 02:44 PM: I have no problem with these names --- the `scribble` exports are unlikely to ever collide, since we rarely resort to capital letters --- but I can't help thinking that the language of the metadata should specified explicitly. Regarding `#lang mcfly racket/base`, an additional reason I want to do three-semicolon comments is to *not* have each package depend on the documentation package. It's practically simpler sometimes. (I'm not the only one who doesn't fully like the dependency I had on the `mcfly` package; I've seen multiple other people copy my package code and strip out the McFly `doc` forms, so that they didn't have that dependency.) If someone else wants to put something other than embedded Scribble in three-semicolon comments, the fact that I'm using three-semicolon in a particular way won't break them, and they won't break me. Or, if someone in the future wants to scrape my three-semicolon stuff in the future, nothing's stopping them, and I'll even give them a small package to do that. I think I understand what you're saying about languages, but in this case, I'm pretty sure how I want to do this, and I'm comfortable with the longevity of the pragmatic simplifications right now. (Aside: I think the main advantage to the dependency on the `mcfly` PLaneT package was actually sneaky advertising or self-propagation. McFly is not a good example, but let's say there's a non-core package X that is used by various other packages. When a person uses a package that uses X, directly or indirectly, then documentation for X was added to the person's Racket documentation page, for them to stumble upon through documentation search and browsing. Then, the theory goes, that person is then more likely to add a new use of that package in packages that they write. So, if we get an ecology of lots of small packages using lots of small packages, and package X depends directly and indirectly on packages A, B, C, D, E, and F... the package X author doesn't even have to mention in documentation all those supporting packages (they often wouldn't even know all of the indirect ones), but the supporting packages still get a small bit of fame and propagation advantage each time. This is decentralized, with no authority declaring X to be a good package to do the things that X does, but just the little documentation-adding mechanism gives the memetics a boost.) Neil V. -- You received this message because you are subscribed to the Google Groups "Racket Users" group. To unsubscribe from this group and stop receiving emails from it, send an email to racket-users+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
Re: [racket-users] scribble namespace landgrab & embedded package documentation
How does this really differ from literate programming?
Deren
On May 4, 2015 7:39 PM, "Neil Van Dyke" wrote:
> For purposes of embedding docs for a package in its Racket source file(s),
> anyone care whether I landgrab some names in the Scribble namespace (for
> package metadata)?
>
> I'm thinking the names will generally one-word generic terms, but with
> capitalization.
>
> Example package source file with said metadata:
>
> BEGIN
>
> #lang racket/base
> ;;; @Package{duckling}
> ;;; @Version{0.1}
> ;;; @Subtitle{Small-Footprint Web Server in Racket}
> ;;; @Author{Neil Van Dyke}
> ;;; @Author{Alyssa P. Hacker}
> ;;; @License{LGPLv3}
> ;;; @Legal{Copyright 2015 Neil Van Dyke. This program is Free Software;
> ;;; you can redistribute it and/or modify it under the terms of the
> ;;; GNU Lesser General Public License as published by the Free
> ;;; Software Foundation; either version 3 of the License, or (at your
> ;;; option) any later version. This program is distributed in the
> ;;; hope that it will be useful, but without any warranty; without
> ;;; even the implied warranty of merchantability or fitness for a
> ;;; particular purpose. See http://www.gnu.org/licenses/ for details.
> ;;; For other licenses and consulting, please contact the author.}
>
> (require (for-syntax racket/base))
>
> ;;; @section{Introduction}
>
> [CODE INTERSPERSED WITH THREE-SEMICOLON SCRIBBLE GOES HERE]
>
> ;;; @History{
> ;;;
> ;;; @Release["0.1" "2014-12-31"]{
> ;;; Initial release.}
> ;;; }
>
> END
>
> Rationale:
>
> * I'm thinking of using the Racket reader for metadata, instead of some
> special-cased text kludge for the metadata, for simplicity/elegance of
> implementation.
>
> * I'm using three-semicolon comments instead of McFly's `doc` forms, to
> simplify evaluation, and to make visually distinguishing between doc and
> code easier without special editor support.
>
> * I've moved the metadata from `info.rkt` back into source file, to make
> only one file you have to edit per package (the redundant bits of
> `info.rkt`, like package name and description, can be updated automatically
> using "http://www.neilvandyke.org/racket-progedit/";). Also, when packages
> were forked under McFly, the legal notice in `mcfly-legal` variable in
> `info.rkt` tended to get lost, and lawyers like you to put the notice on
> the actual file anyway (rather than my old ";; See file info.rkt for legal
> info." kludge comment at the tops of key files).
>
> Incidentally, if you paste that example code into Emacs with Quack, you
> should see remnants of 13-year-old support for my earlier embedded Texinfo
> format: http://postimg.org/image/wuwy376od/
> (Though I preferred the look of comments when they were light blue, like
> in DrScheme v103, instead of the modern yellow-snow. :)
>
> Neil V.
>
> --
> You received this message because you are subscribed to the Google Groups
> "Racket Users" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to racket-users+unsubscr...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>
--
You received this message because you are subscribed to the Google Groups
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Re: [racket-users] scribble namespace landgrab & embedded package documentation
Additionally if it were it's own lang extension, the tool using this
information wouldn't need to do the parsing. The reader could extract all the
;;; definitions into a submodule that the tool requires.
On Thursday, May 7, 2015 at 11:44:59 AM UTC-7, Matthew Flatt wrote:
> I have no problem with these names --- the `scribble` exports are
> unlikely to ever collide, since we rarely resort to capital letters ---
> but I can't help thinking that the language of the metadata should
> specified explicitly.
>
> Concretely, instead of
>
> #lang racket/base
>
> maybe the file should start
>
> #lang mcfly racket/base
>
> ... or some suitable word if `mcfly` isn't it ... to indicate that
> ";;;" is being treated in a particular way. The `mcfly` name both
> specifies the special parsing of comments and the initial/default
> language of those comments, so that either of those are free to evolve
> in the future through a different name.
>
> At Mon, 04 May 2015 19:39:19 -0400, Neil Van Dyke wrote:
> > For purposes of embedding docs for a package in its Racket source
> > file(s), anyone care whether I landgrab some names in the Scribble
> > namespace (for package metadata)?
> >
> > I'm thinking the names will generally one-word generic terms, but with
> > capitalization.
> >
> > Example package source file with said metadata:
> >
> > BEGIN
> >
> > #lang racket/base
> > ;;; @Package{duckling}
> > ;;; @Version{0.1}
> > ;;; @Subtitle{Small-Footprint Web Server in Racket}
> > ;;; @Author{Neil Van Dyke}
> > ;;; @Author{Alyssa P. Hacker}
> > ;;; @License{LGPLv3}
> > ;;; @Legal{Copyright 2015 Neil Van Dyke. This program is Free Software;
> > ;;; you can redistribute it and/or modify it under the terms of the
> > ;;; GNU Lesser General Public License as published by the Free
> > ;;; Software Foundation; either version 3 of the License, or (at your
> > ;;; option) any later version. This program is distributed in the
> > ;;; hope that it will be useful, but without any warranty; without
> > ;;; even the implied warranty of merchantability or fitness for a
> > ;;; particular purpose. See http://www.gnu.org/licenses/ for details.
> > ;;; For other licenses and consulting, please contact the author.}
> >
> > (require (for-syntax racket/base))
> >
> > ;;; @section{Introduction}
> >
> > [CODE INTERSPERSED WITH THREE-SEMICOLON SCRIBBLE GOES HERE]
> >
> > ;;; @History{
> > ;;;
> > ;;; @Release["0.1" "2014-12-31"]{
> > ;;; Initial release.}
> > ;;; }
> >
> > END
> >
> > Rationale:
> >
> > * I'm thinking of using the Racket reader for metadata, instead of some
> > special-cased text kludge for the metadata, for simplicity/elegance of
> > implementation.
> >
> > * I'm using three-semicolon comments instead of McFly's `doc` forms, to
> > simplify evaluation, and to make visually distinguishing between doc and
> > code easier without special editor support.
> >
> > * I've moved the metadata from `info.rkt` back into source file, to make
> > only one file you have to edit per package (the redundant bits of
> > `info.rkt`, like package name and description, can be updated
> > automatically using "http://www.neilvandyke.org/racket-progedit/";).
> > Also, when packages were forked under McFly, the legal notice in
> > `mcfly-legal` variable in `info.rkt` tended to get lost, and lawyers
> > like you to put the notice on the actual file anyway (rather than my old
> > ";; See file info.rkt for legal info." kludge comment at the tops of key
> > files).
> >
> > Incidentally, if you paste that example code into Emacs with Quack, you
> > should see remnants of 13-year-old support for my earlier embedded
> > Texinfo format: http://postimg.org/image/wuwy376od/
> > (Though I preferred the look of comments when they were light blue, like
> > in DrScheme v103, instead of the modern yellow-snow. :)
> >
> > Neil V.
> >
> > --
> > You received this message because you are subscribed to the Google Groups
> > "Racket Users" group.
> > To unsubscribe from this group and stop receiving emails from it, send an
> > email
> > to racket-users+unsubscr...@googlegroups.com.
> > For more options, visit https://groups.google.com/d/optout.
--
You received this message because you are subscribed to the Google Groups
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Re: [racket-users] scribble namespace landgrab & embedded package documentation
I have no problem with these names --- the `scribble` exports are
unlikely to ever collide, since we rarely resort to capital letters ---
but I can't help thinking that the language of the metadata should
specified explicitly.
Concretely, instead of
#lang racket/base
maybe the file should start
#lang mcfly racket/base
... or some suitable word if `mcfly` isn't it ... to indicate that
";;;" is being treated in a particular way. The `mcfly` name both
specifies the special parsing of comments and the initial/default
language of those comments, so that either of those are free to evolve
in the future through a different name.
At Mon, 04 May 2015 19:39:19 -0400, Neil Van Dyke wrote:
> For purposes of embedding docs for a package in its Racket source
> file(s), anyone care whether I landgrab some names in the Scribble
> namespace (for package metadata)?
>
> I'm thinking the names will generally one-word generic terms, but with
> capitalization.
>
> Example package source file with said metadata:
>
> BEGIN
>
> #lang racket/base
> ;;; @Package{duckling}
> ;;; @Version{0.1}
> ;;; @Subtitle{Small-Footprint Web Server in Racket}
> ;;; @Author{Neil Van Dyke}
> ;;; @Author{Alyssa P. Hacker}
> ;;; @License{LGPLv3}
> ;;; @Legal{Copyright 2015 Neil Van Dyke. This program is Free Software;
> ;;; you can redistribute it and/or modify it under the terms of the
> ;;; GNU Lesser General Public License as published by the Free
> ;;; Software Foundation; either version 3 of the License, or (at your
> ;;; option) any later version. This program is distributed in the
> ;;; hope that it will be useful, but without any warranty; without
> ;;; even the implied warranty of merchantability or fitness for a
> ;;; particular purpose. See http://www.gnu.org/licenses/ for details.
> ;;; For other licenses and consulting, please contact the author.}
>
> (require (for-syntax racket/base))
>
> ;;; @section{Introduction}
>
> [CODE INTERSPERSED WITH THREE-SEMICOLON SCRIBBLE GOES HERE]
>
> ;;; @History{
> ;;;
> ;;; @Release["0.1" "2014-12-31"]{
> ;;; Initial release.}
> ;;; }
>
> END
>
> Rationale:
>
> * I'm thinking of using the Racket reader for metadata, instead of some
> special-cased text kludge for the metadata, for simplicity/elegance of
> implementation.
>
> * I'm using three-semicolon comments instead of McFly's `doc` forms, to
> simplify evaluation, and to make visually distinguishing between doc and
> code easier without special editor support.
>
> * I've moved the metadata from `info.rkt` back into source file, to make
> only one file you have to edit per package (the redundant bits of
> `info.rkt`, like package name and description, can be updated
> automatically using "http://www.neilvandyke.org/racket-progedit/";).
> Also, when packages were forked under McFly, the legal notice in
> `mcfly-legal` variable in `info.rkt` tended to get lost, and lawyers
> like you to put the notice on the actual file anyway (rather than my old
> ";; See file info.rkt for legal info." kludge comment at the tops of key
> files).
>
> Incidentally, if you paste that example code into Emacs with Quack, you
> should see remnants of 13-year-old support for my earlier embedded
> Texinfo format: http://postimg.org/image/wuwy376od/
> (Though I preferred the look of comments when they were light blue, like
> in DrScheme v103, instead of the modern yellow-snow. :)
>
> Neil V.
>
> --
> You received this message because you are subscribed to the Google Groups
> "Racket Users" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email
> to racket-users+unsubscr...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
--
You received this message because you are subscribed to the Google Groups
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
[racket-users] scribble namespace landgrab & embedded package documentation
For purposes of embedding docs for a package in its Racket source
file(s), anyone care whether I landgrab some names in the Scribble
namespace (for package metadata)?
I'm thinking the names will generally one-word generic terms, but with
capitalization.
Example package source file with said metadata:
BEGIN
#lang racket/base
;;; @Package{duckling}
;;; @Version{0.1}
;;; @Subtitle{Small-Footprint Web Server in Racket}
;;; @Author{Neil Van Dyke}
;;; @Author{Alyssa P. Hacker}
;;; @License{LGPLv3}
;;; @Legal{Copyright 2015 Neil Van Dyke. This program is Free Software;
;;; you can redistribute it and/or modify it under the terms of the
;;; GNU Lesser General Public License as published by the Free
;;; Software Foundation; either version 3 of the License, or (at your
;;; option) any later version. This program is distributed in the
;;; hope that it will be useful, but without any warranty; without
;;; even the implied warranty of merchantability or fitness for a
;;; particular purpose. See http://www.gnu.org/licenses/ for details.
;;; For other licenses and consulting, please contact the author.}
(require (for-syntax racket/base))
;;; @section{Introduction}
[CODE INTERSPERSED WITH THREE-SEMICOLON SCRIBBLE GOES HERE]
;;; @History{
;;;
;;; @Release["0.1" "2014-12-31"]{
;;; Initial release.}
;;; }
END
Rationale:
* I'm thinking of using the Racket reader for metadata, instead of some
special-cased text kludge for the metadata, for simplicity/elegance of
implementation.
* I'm using three-semicolon comments instead of McFly's `doc` forms, to
simplify evaluation, and to make visually distinguishing between doc and
code easier without special editor support.
* I've moved the metadata from `info.rkt` back into source file, to make
only one file you have to edit per package (the redundant bits of
`info.rkt`, like package name and description, can be updated
automatically using "http://www.neilvandyke.org/racket-progedit/";).
Also, when packages were forked under McFly, the legal notice in
`mcfly-legal` variable in `info.rkt` tended to get lost, and lawyers
like you to put the notice on the actual file anyway (rather than my old
";; See file info.rkt for legal info." kludge comment at the tops of key
files).
Incidentally, if you paste that example code into Emacs with Quack, you
should see remnants of 13-year-old support for my earlier embedded
Texinfo format: http://postimg.org/image/wuwy376od/
(Though I preferred the look of comments when they were light blue, like
in DrScheme v103, instead of the modern yellow-snow. :)
Neil V.
--
You received this message because you are subscribed to the Google Groups "Racket
Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
