doc.rkt
#lang racket/base
;; For legal info, see file "info.rkt".

(require (planet neil/mcfly))

(doc (section "Introduction")

     (para (italic "This is an alpha-quality release.  Not for general use yet."))

     (para (italic "Privacy/Security Warning: McFly Tools makes frequent
requests to the PLaneT server, and these requests might reveal to the server
the package names of Racket packages that you are working on.  So don't use
McFly Tools for trade-secret packages named "
                   (code "secret-social-media-startup-based-on-rocks")
                   " just yet.  Probably this little information leak isn't a
problem for you, but we mention it on principle.  An eventual later version of
McFly Tools will likely improve this situation."))

     (para "McFly Tools is a collection of developer tools for Racket
programmers, oriented towards supporting and encouraging the sharing of Racket
code libraries as reusable PLaneT packages.")

     (para "Some things McFly Tools does are:")

     (itemlist

      (item "Supports the embedding of documentation directly in source files,
together with the "
            (hyperlink "http://www.neilvandyke.org/mcfly/"
                       "McFly Runtime")
            " package.")

      (item "Maintains PLaneT development links, based on metadata in "
            (filepath "info.rkt")
            ", information from the PLaneT server, and current activity using
McFly Tools.")

      (item "Programmatically updates "
            (filepath "info.rkt")
            " files to add any missing definitions.  (This uses the "
            (hyperlink "http://www.neilvandyke.org/racket-progedit/"
                       (code "progedit"))
            " package.)")

      (item "Automates building PLaneT archive files for upload to the PLaneT server."))

     (para "Note that McFly Tools is a development tool used only by those who
choose to use it.  Packages developed using McFly depend only on the McFly
Runtime package."))

(doc (section "Usage")
     
     (para "The interface to McFly Tools is the "
           (code "raco mcfly")
           " command.")

     (para "Someday this will be documented.")

     (para "Note: If using McFly Tools with Racket nightly builds or Git from
shortly prior to 2012-06-13, some versions have an erroneous error of "
           (code "raco setup: nothing to do")
           " in response to "
           (code "raco setup -P")
           " with development links, which breaks McFly Tools.  This was fixed on 2012-06-12 in "
           (hyperlink "https://github.com/plt/racket/commit/af9d11bfce8673fa2d72cec77651ba771e1971fe"
                      "commit af9d11bfce8673fa2d72cec77651ba771e1971fe")
           "."))

(doc (section "Known Issues")

     "McFly Tools is not yet feature-complete, nor fully tested.")

(doc history

     (#:planet 1:3 #:date "2012-06-13"
               (itemlist
                (item "Fixed one problem that might have caused "
                      (code "raco mcfly")
                      " to run at install time.")
                (item "Enabled adding "
                      (racket repositories)
                      " to "
                      (filepath "info.rkt")
                      ".")
                (item "Added documentation note about recent Racket nightly
builds breaking McFly Tools.")))
     
     (#:planet 1:2 #:date "2012-06-12"
               (itemlist
                (item "Now, "
                      (racket mcfly-subtitle)
                      " isn't added to "
                      (filepath "info.rkt")
                      " if "
                      (racket mcfly-title)
                      " is defined.")
                (item "Documentation changes.")))
               
     (#:planet 1:1 #:date "2012-06-11"
               (itemlist
                (item (code "raco mcfly planet-archive")
                      " now sets "
                      (racket force-package-building?)
                      " to "
                      (racket #f)
                      " rather than "
                      (racket #t)
                      ".  (Thanks to Robby Findler and Eli Barzilay.)")))

     (#:planet 1:0 #:date "2012-06-11"
               (itemlist
                (item "Initial alpha-quality release.  Not for general use."))))