= Who am I?

* Barrie Slaymaker (barries@slaysys.com)

* Systems Design Consultant

* An engineer with an itch

= What does Safari do?

* A web front-end for RCSs and SCMs

* Other hierarchical file stores (like C</usr/lib/perl5>)

* Use a browser for browsing, not RCS + editor + tools

* on-the-fly documentation extraction, code analysis, etc.

* on-the-fly tarballs

* on-the-fly syntax highlighting, rendering

= How does it work?

* External translators: any hierarchy of files that can be HTTP browsable

* It's C<cgi-bin> or C<mod_perl> application that calls B<GNU Make>

* Back-ends for different RCSs, SCMs, hierarchical file stores.

* Easy to integrate external tools

* Open Source: Perl & GNU Make

* L<http://public.perforce.com/guest/barrie_slaymaker/safari/index.html>


= Backends

* Perforce (used by perl pumpkings) (works)

* local file system (works)

* C</usr/lib/perl5> (works)

* PVCS, CVS (almost underway)

* MKS Source Integrity planned

* Anything & everything, as people need / develop them

* Contributors welcome


= Translators: Filters and Tools

Take one or more backend files and create one or more output files.

* Filters

Translate 'in place'.  Relative links 
between files output by a translator still work.

* Tools

Summarize input files or metadata. Any links are generally back
to specific places in specific filters.


= Filters

* Syntax highlighters

=over

* C<code2html> (multi-lingual code syntax highlighter) (works)

=back

* Documentation extractors


=over

* C<pod2html> and C<podtohtml> (works)

* C<Cocoon> (C++, planned)

* C<javadoc>

=back

* C<xyz2html>, C<xyz2gif>, C<xyz2pdf>

= Tools

* Linters

=over

* C<perl -c>, C<perl -cw>, C<perl -MO=Lint,all> 

* C<gcc -c -Wall>

=back

* Code Metrics (uh....)

=over

* C<wc> (word count)

=back

* C<tar> & C<gzip>: on-thy-fly tarballs

* File revision history / change log


= Possible Filters & Tools

* B<Any command line tool>

* plotting utils (C<gplot>, etc.)

* rendering (C<xfig/fig2dev>)

* spelling checkers

* downloaders

* emailers

* subscribe / unsubscribe to change notifications


= The Safari Project

* Open Source: GPL or AL

* Homepage:

L<http://public.perforce.com/guest/barrie_slaymaker/safari/index.html>

* Mailing list: safari-dev@egroups.com

* Status: about v. 0.9

* Conception, Gestation, Birth, Growth

= Safari: Conception

* Initially a system for integrating disparate tools

* Built to check files out of MKS' Source Integrity SCM and extract C<Cocoon> comments

* Built as a cgi-bin app, since Cocoon generates HTML

* Hierarchy navigation and source code browsing as means to an end

= Feeping Creaturism

* Grew in to large, monolithic script 

* Syntax highlighting, numbered lines (thanks, lxr)

* Browsing by label, project, directory and revision (now change #)

* Markup of filenames to be links to the right files

* C<pod2html> on-the-fly conversion

* Searching within a file (search query URLs don't rot like line #s)

= Still in use

* Browsers are often better for browsing

* C<Cocoon> was never run by more than two or three, and then intermittently.
Now it's run as needed by anyone.

* Code research

Turnover and time mean code must be researched

* Code reviews

It's easier if you don't need to check it
out. URLs can be emailed / posted.

= Now Handles Design Documentation

Make it part of the source archive with the code: a /design directory.

=over

* Stays synchronized to the code

* More likely to be maintained (but still gets left out in the rain)

* Can link to the code using search query URLs

* Can link to output from documentation extractors

* Add 'notes' later: just check 'em in

=back

= Safari: Gestation

Clearly Safari filled a need. Plus, I hold the copyright. So it seemed like
a good open source project.

* Rewrite to be modular, extensible

* Keep & Improve: User interface, URL design, low admin overhead

* Use GNU Make to reduce bugs and make it easier for non-Perl speakers to
integrate tools

= URL Design

C<http://a.com/project/rev/filter/dir/dir/file?query>
C<http://a.com/perl/_head/Default/perl/av.c>
C<http://a.com/perl/_head/Default/perl/av.c?filter=wc>

* Scheme & Server: C<http://a.com>

* Project: C<perl>

* Revision: C<_head>, C<@3425>, C<@5.005_56> C<#27>

* Filter: C<Default>, C<pretty>, C<plain>, C<HTML>

* File: C<perl/av.c>, C<perl/README>

* Tool: C<?filter=wc>, C<?filter=lint>, C<?rev=_head&filter=filelog>

= GNU Make Pros

* Accessible by non-Perl progammers

* Optimizes build process

* Use C<.PRECIOUS>, C<.SECONDARY> to control caching of intermediate files

* Faster at calculating dependancies, out of date-ness than perl code

* Pretty darn reliable and stable

= GNU Make Cons

* Not multi-user: doesn't give a flock

C<cgimake> does locking by target or globally.

* C<.SECONDARY> not as powerful as it could be

Use C<.PRECIOUS> and have scripts & commands not leave bogus output around.
On GNU Make's TODO list.

* Can't query modern RCSs / SCMs all that well

= GNU Make Cons (cont'd)

* Tricky to implement content-based decisions, like which filter for C<Default>

Use C<$(shell)>, recursive make

* Can't force the entire check-out to HTTP process to re-occur

C<--unconditional> is on GNU Make's TODO list

= Make.pm

* Make.pm has been rewritten to be very GNUish

GNU Make's good enough for now, don't want to debug two complex systems
at once. 

* C<$(perl )> function to insert code to be C<eval()>ed

* C<m@a/(.*).foo@: b/$1.bar> rules

* Can add locking, lazy variable interpolation

* Will stay in mod_perl memory, but executes slower


= Modular, Extensible

* C<cgimake> and C<pfile> designed to stand alone

* Need to improve abstraction

* Make lets us glue backends, converters, and logic together to make
a navigable, consistent site

= Safari: Birth

* v 0.9: YAPC 1999

* New (primitive) web site, new mailing list

* Already a contributor, more expected soon

* Features almost complete for v 1.0, need to clean up guts, HTML a bit

= Safari: Growth

* Indexing, searching, and markup (like lxr)

Needs to be pluggable, though, so as to
support different source languages (C, C++, Java, Perl, Python. Lisp :-?)

* Library of back ends

Mostly direct calls to command line interface, some need for Perl programs.
Collected on a central web site, available on CPAN.

* Library of tools and Makefiles

Help keep people from reinventing the wheel, so they can focus on improving
existing wheels.

= More Growth

* Partial parsing of source code languages

Improves indexing, searching, markup. Can also aid research if we can
display partially preprocessed files (suggested last night).

* Alternate user interfaces

Safari's GUI is Least Common Denominator HTML. Javascript and Java could add
a lot of nice features. Applications for X? Win32?

= Blue Sky

* Check-in / Check-out ?

* Ties to bug tracking systems?

* B<User markup of pages via browser>. Very powerful feature.


= Summary

* Use Safari to Open your Source today!

* Go out and scratch that itch: contribute or invent!

* Safari could use you!

* Thanks for coming.