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.

Reply via email to