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 <david.sto...@gmail.com> 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.
