Re: [racket-users] Examples of in-source documentation?

[David Storrs]

On Sun, Nov 26, 2017 at 12:10 AM, Greg Hendershott
 wrote:
> As another example of using scribble/srcdoc, for Frog I made a
> `define-doc` macro:
>
>   
> https://github.com/greghendershott/frog/blob/master/frog/private/define-doc.rkt
>
> Example usage:
>
>   https://github.com/greghendershott/frog/blob/master/frog/paths.rkt#L258-L268
>
> Where that gets pulled into the main frog.scrbl is the
> `include-extracted` last line here:
>
>   
> https://github.com/greghendershott/frog/blob/master/frog/frog.scrbl#L959-L975
>
> (In other words, there is still a main scribble file for "user guide"
> and module-wide documentation. Where scribble/srcdoc helps is with
> per-definition "reference" portions of the doc.)

Thanks, I appreciate the pointer.  Side benefit:  Frog looks really
useful and I may take a swing at using it.

Unfortunately, this is again something that mixes code and
documentation pretty incestuously and looks like code with some
strings sprinkled in.  The scribble file, of course, is very clear and
easy to follow but doesn't include the code and requires a specific
#lang.


This is probably just my issue and I should suck it up and get used to
the way that the new thing does it instead of expecting it to work
like the old thing.  Thanks for the feedback, everyone.

-- 
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] Examples of in-source documentation?

[David Storrs]

On Fri, Nov 24, 2017 at 9:13 PM, Neil Van Dyke  wrote:
> Does the following do something like you want?
>
> Subject: single-file packages and embedded documentation and metadata
> Date: Fri, 10 Nov 2017 23:04:39 -0500
> https://groups.google.com/forum/#!topic/racket-users/ulO8zxP46DI
>

Not really, I'm afraid.  This looks like code with strings mixed in
when I was hoping for strings with a dollop of code mixed in.  It
certainly does produce beautiful output, though.

-- 
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] Examples of in-source documentation?

[Greg Hendershott]

As another example of using scribble/srcdoc, for Frog I made a
`define-doc` macro:

  
https://github.com/greghendershott/frog/blob/master/frog/private/define-doc.rkt

Example usage:

  https://github.com/greghendershott/frog/blob/master/frog/paths.rkt#L258-L268

Where that gets pulled into the main frog.scrbl is the
`include-extracted` last line here:

  https://github.com/greghendershott/frog/blob/master/frog/frog.scrbl#L959-L975

(In other words, there is still a main scribble file for "user guide"
and module-wide documentation. Where scribble/srcdoc helps is with
per-definition "reference" portions of the doc.)

-- 
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] Examples of in-source documentation?

[Neil Van Dyke]

Does the following do something like you want?

Subject: single-file packages and embedded documentation and metadata
Date: Fri, 10 Nov 2017 23:04:39 -0500
https://groups.google.com/forum/#!topic/racket-users/ulO8zxP46DI

--
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] Examples of in-source documentation?

[Philip McGrath]

For an example of scribble/srcdoc, you can see
.../pkgs/gui-lib/framework/main.rkt and the corresponding Scribble files in
.../pkgs/gui-doc/scribblings/framework/

(I haven't really used scribble/srcdoc, I just happen to know that
framework uses it.)

-Philip

On Fri, Nov 24, 2017 at 4:59 PM, David Storrs 
wrote:

> The docs on Scribble
> (https://docs.racket-lang.org/scribble/srcdoc.html) show that I can
> put docs directly in with my code, and it suggests looking at the
> gif.rkt file in the 'files' collection, along with the 'gif.scrbl'
> file for an example. A quick 'find' gets me:
> ...share/pkgs/draw-lib/file/gif.rkt
> ...share/pkgs/gui-doc/mrlib/scribblings/gif.scrbl
>
> Unfortunately, gif.rkt includes nothing that seems relevant to
> scribbling and gif.scrbl contains nothing that seems to match what's
> in gif.rkt
>
> What I'd like to be able to do is Perl-style POD documentation:
>
> --- contents of foo.pl (separate docs/code)
> =head1 NAME coolness
>
> =over 4
>
> =item frobnicate
>
> Frobnicate a foo
>
> =cut
>
> sub frobnicate { print "I frob!\n" }
>
> =item zorch
>
> Zorch a thing
>
> =cut
>
> sub zorch { print "I zorch!\n" }
>
> =back
> --- /end contents of foo.pl
>
>
> Alternatively, I could write it with docs and code separated:
>
>
> --- contents of foo.pl (separate docs/code)
> =head1 NAME coolness
>
> =over 4
>
> =item frobnicate
>
> Frobnicate a foo
>
> =item zorch
>
> Zorch a thing
>
> =back
>
> =cut
>
> sub frobnicate { print "I frob!\n" }
> sub zorch { print "I zorch!\n" }
>
> --- /end contents of foo.pl
>
> Note that in this system the documentation and code are side-by-side
> (so they are more likely to stay in sync) but distinct -- there are no
> documentation commands tangled in with the actual code.
> Alternatively, I can keep them separate if that seems better.
>
> Either way, I can then run one of the pod translators (e.g. pod2text,
> pod2html, etc) and it extracts the docs for me:
>
> $ pod2text foo.pl
>
> NAME coolness
> frobnicate
> Frobnicate a foo
>
> zorch
> Zorch a thing
>
>
> I see the 'literate programming' section in the Scribble docs, but
> that requires mixing documentation and code pretty incestuously as
> well as using the scribble/lp2 #lang.  Is there a way to do Perl-style
> intermingled documentation with Scribble while still leaving me free
> to use whatever #lang I'd like within my file?
>
> --
> 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] Examples of in-source documentation?

[David Storrs]

The docs on Scribble
(https://docs.racket-lang.org/scribble/srcdoc.html) show that I can
put docs directly in with my code, and it suggests looking at the
gif.rkt file in the 'files' collection, along with the 'gif.scrbl'
file for an example. A quick 'find' gets me:
...share/pkgs/draw-lib/file/gif.rkt
...share/pkgs/gui-doc/mrlib/scribblings/gif.scrbl

Unfortunately, gif.rkt includes nothing that seems relevant to
scribbling and gif.scrbl contains nothing that seems to match what's
in gif.rkt

What I'd like to be able to do is Perl-style POD documentation:

--- contents of foo.pl (separate docs/code)
=head1 NAME coolness

=over 4

=item frobnicate

Frobnicate a foo

=cut

sub frobnicate { print "I frob!\n" }

=item zorch

Zorch a thing

=cut

sub zorch { print "I zorch!\n" }

=back
--- /end contents of foo.pl


Alternatively, I could write it with docs and code separated:


--- contents of foo.pl (separate docs/code)
=head1 NAME coolness

=over 4

=item frobnicate

Frobnicate a foo

=item zorch

Zorch a thing

=back

=cut

sub frobnicate { print "I frob!\n" }
sub zorch { print "I zorch!\n" }

--- /end contents of foo.pl

Note that in this system the documentation and code are side-by-side
(so they are more likely to stay in sync) but distinct -- there are no
documentation commands tangled in with the actual code.
Alternatively, I can keep them separate if that seems better.

Either way, I can then run one of the pod translators (e.g. pod2text,
pod2html, etc) and it extracts the docs for me:

$ pod2text foo.pl

NAME coolness
frobnicate
Frobnicate a foo

zorch
Zorch a thing


I see the 'literate programming' section in the Scribble docs, but
that requires mixing documentation and code pretty incestuously as
well as using the scribble/lp2 #lang.  Is there a way to do Perl-style
intermingled documentation with Scribble while still leaving me free
to use whatever #lang I'd like within my file?

-- 
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.