#lang racket/base
;; Copyright Neil Van Dyke.  See file "info.rkt".

(require (planet neil/mcfly))

(doc (require scriblib/footnote))

(doc (section "Introduction")

     (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.")

      (item "Creates initial "
            (filepath "info.rkt")
            " and "
            (filepath "main.rkt")
            " for a project."))
     
     (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 "Installation")

     (para "To install McFly Tools, evaluate: ")
     
     (racketblock
      (require (planet neil/mcfly-tools))))

(doc (section "Usage")

     (para "The following subsections tell how to use McFly Tools for
particular problems.")

;;      (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 (subsection "Initializing a Package")

     (para "When first starting to use McFly Tools for a package, you may wish
to do this:")

     (itemlist #:style 'ordered

      (item "Put any files you already have for the package into a directory.
Let's say you ultimately want your package to be named ``"
            (code "foo")
            ",'' so you might wish to name the directory "
            (filepath "foo")
            ".  (But you don't "
            (italic "have")
            " to name it "
            (filepath "foo")
            ".)")

      (item (para "Go into the directory, and run the command:")

            (commandline "raco mcfly init")

            (para "This does the following:")

            (itemlist (item "Creates an "
                            (filepath "info.rkt")
                            " if you don't already have one in the directory;
or modifies your existing one.")

                      (item "Creates a "
                            (filepath "main.rkt")
                            " if you don't already have one.")))

      (item (para "Look at "
                  (filepath "info.rkt")
                  ", especially all the ``"
                  (racketcommentfont ";; TODO:")
                  "'' comments.  Make any necessary changes.  Perhaps most
importantly for now:")

            (itemlist (item (para "At the very least, you'll need to edit the value for "
                                  (racket mcfly-planet)
                                  ", to set it to the PLaneT owner name, and to
check that the package name and version are correct.  If you don't yet have a
PLaneT account, you can set the owner to a placeholder that you're unlikely to
forget to change later, like ``"
                                  (racketfont "myplanetownername")
                                  "'' so that the definition might now look like:")
                      
                            (racketblock
                             (define mcfly-planet 'myplanetownername/foo:1:0)))

                      (item "If your embedded documentation "
                            (racket doc)
                            " forms will "
                            (italic "not")
                            " be in "
                            (filepath "main.rkt")
                            ", then change "
                            (racket mcfly-start)
                            " to indicate which file will have them.")))

      (item (para "If you "
                  (italic "want")
                  " to have your implementation and documentation in "
                  (filepath "main.rkt")
                  ", and if "
                  (code "raco mcfly init")
                  " just created this file for you, it should contain a skeleton file to get you started.  You actually should be able to do "
                  (code "raco mcfly view")
                  " now, to view formatted documentation in your Web browser."))

      (item (para "If you "
                  (italic "don't")
                  " want to have your implementation and documentation in "
                  (filepath "main.rkt")
                  ", but "
                  (code "raco mcfly init")
                  " just created that file for you, then, for ease of PLaneT "
                  (racket require)
                  " forms, you might wish to have a "
                  (filepath "main.rkt")
                  " anyway, that merely re-"
                  (racket provide)
                  "s definitions from some other module.  For example, if file "
                  (filepath "foo.rkt")
                  " has your implementation, you can edit "
                  (filepath "main.rkt")
                  " to look like:")
            
            (filebox "main.rkt"
              (racketblock #,(code "#lang racket/base")
                           (require "foo.rkt")
                           (provide (all-from-out "foo.rkt"))))

            (para "A reason you might want to do this comes from working with
files from multiple packages at once: many tools, including DrRacket and Emacs,
are easier to navigate when the files you're editing are named things like "
                  (filepath "foo.rkt")
                  " and "
                  (filepath "bar.rkt")
                  ", rather than "
                  (filepath "main.rkt")
                  " and "
                  (filepath "main.rkt")
                  ".")))

     "Your package is now initialized for McFly Tools, such as it is.")

(doc (subsection "Embedding Documentation")

     (para "You embed documentation with "
           (racket doc)
           " forms.  See the documentation for "
           (hyperlink "http://www.neilvandyke.org/mcfly/"
                      "McFly Runtime")
           ", which is what actually formats the documentation."))

(doc (subsection "Viewing Embedded Documentation")

     (para "To view embedded documentation, do:")
     
     (commandline "raco mcfly view")

     (para "This should update PLaneT development links and cause the formatted
documentation to be opened in your Web browser.")

     (para "You can actually leave off the subcommand of "
           (code "raco mcfly view")
           ", so this will also work:")

     (commandline "raco mcfly")

     (para "Note: If you're running this from Emacs "
           (code "M-x compile")
           ", such as with a Unix command line like:")

     (commandline "cd /home/bob/foo && raco mcfly")

     (para "and you find that sometimes the page isn't opened in your browser
because of a race condition with process killing, you might need to add a
delay:")

     (commandline "cd /home/bob/foo && raco mcfly && sleep 1"))

(doc (subsection "Setup (Compiling)")

     (para "You can update PLaneT development links and run "
           (code "raco setup")
           " for your package with:")

     (commandline "raco mcfly setup")

     (para "Or:")

     (commandline "raco mcfly s"))

(doc (subsection "Updating PLaneT Development Links")

     (para "You can update PLaneT development links with the command:")

     (commandline "raco mcfly planet-links")

     (para "Or:")
     
     (commandline "raco mcfly pl")

     (para "You may add arguments to that command line for each directory tree
you wish to scan.  If you don't specify any directory trees, the current
directory is used as the start of a tree.")

     (para (code "raco mcfly planet-links")
           " searches each directory for "
           (filepath "info.rkt")
           " files with "
           (racket mcfly-planet)
           " in them, determines whether a development link is appropriate (by,
e.g., checking the PLaneT server), and does a series of removals and adds of
PLaneT development links.  Development links for paths outside of the directory
trees that are being searched are not removed unless they are overridden by a "
           (racket mcfly-planet)
           " in one of the searched trees."))

(doc (subsection "Making a PLaneT Archive for Upload")

     (para "To make a PLaneT archive for upload to the PLaneT server and sharing with the world:")

     (itemlist

      #:style 'ordered

               (item "Check that you have added the appropriate version history entry to your "
                     (racket (doc history ...))
                     " form.  (Note that McFly Tools does not currently check
this, so check manually.)")
               
               (item "Check "
                     (filepath "info.rkt")
                     ", especially that the version number in "
                     (racket mcfly-planet)
                     " is correct for this upload.")

               (item "Do a final "
                     (code "raco mcfly setup")
                     " and double-check that whatever tests you have still
run.")

               (item (para "Do:")

                     (commandline "raco mcfly planet-archive")

                     (para "Or:")

                     (commandline "raco mcfly pa"))

               (item "Wait a minute for it to finish.  If it works, it will
create a staging directory, copy files according to "
                     (racket mcfly-files)
                     " into that directory, adjust PLaneT development links, run the "
                     (racket make-planet-archive)
                     " procedure, clean up the staging directory, re-adjust
PLaneT development links, and leave you with a "
                     (filepath (italic "packagename") ".plt")
                     " file.")

               (item "You might want to test installation with use of "
                     (code "raco planet fileinject")
                     " and manipulating your PLaneT cache and links and such.
McFly Tools doesn't yet automate this part.")

               (item "Finally, upload your "
                     (filepath (italic "packagename") ".plt")
                     " file to the PLaneT server, double-checking the version
before you click the button.")))

(doc (subsection "Easter Egg")

     (commandline "raco mcfly marty"))

(doc (section "Known Issues")

     (para "McFly Tools is not yet feature-complete, nor fully tested.  I'm
hoping that feedback from other people helps prioritize the many things that "
           (italic "could")
           " be improved.")

     (para (racket compile-omit-paths)
           " should be respected when scanning any directory for files.")

     (para "When updating PLaneT development links, links for old versions to
directories with newer versions should be removed."))

;; Note: When releasing new "mcfly-tools" version, consider whether necessary
;; to change "mcfly-minimum-compatible-planet-spec-string" in file
;; "mcfly-tools-scrbl-file.rkt".

(doc history

     (#:planet 1:12 #:date "2013-01-07"
               (itemlist
                (item "Now observes the "
                      (filepath "info.rkt")
                      " "
                      (racket compile-omit-paths)
                      " variable when searching directory trees for PLaneT
packages.")
                (item "Now uses the "
                      (hyperlink "http://www.neilvandyke.org/racket-path-misc/"
                                 (tt "path-misc"))
                      " package, for better canonicalizing of paths.")
                (item (filepath "bootstrap.sh")
                      " now uses "
                      (tt "raco planet")
                      " rather than "
                      (tt "planet")
                      ".")
                (item "Documentation tweaks.")))
     
     (#:planet 1:11 #:date "2012-11-04"
               (itemlist
                (item "May now work on Microsoft Windows, in addition to usual
Unix-like systems.  "
                      (racket current-raco-executable-string)
                      " now will look for program "
                      (filepath "raco.exe")
                      " instead of "
                      (filepath "raco")
                      ".  (Thanks to Edward Blake.)")))
                      
     (#:planet 1:10 #:date "2012-07-14"
               (itemlist
                (item "Generated files now depend on McFly Runtime version "
                      (code "1:3")
                      ", to get "
                      (tt "#lang at-exp")
                      " support.")))
                      
     (#:planet 1:9 #:date "2012-07-13"
               (itemlist
                (item "Made "
                      (racket parse-planet-symbol-string/ignore-equals)
                      " more permissive.  (Thanks to Asumu Takikawa.)")
                (item "This Scribble file generated by this version of McFly
Tools now depends on McFly Runtime version "
                      (code "1:2")
                      " rather than "
                      (code "1:1")
                      ", to be more permissive about PLaneT package names.")
                (item "Removed documentation note about "
                      (code "raco setup -P")
                      " being briefly broken in Racket Git a month earlier.")))

     (#:planet 1:8 #:date "2012-06-15"
               (itemlist
                (item "Documentation tweaks.")))
     
     (#:planet 1:7 #:date "2012-06-14"
               (itemlist
                (item "Documentation tweaks.")))
     
     (#:planet 1:6 #:date "2012-06-14"
               (itemlist
                (item "Trying to prevent install-time running.")))
     
     (#:planet 1:5 #:date "2012-06-14"
               (itemlist
                (item "Added first shot at usage documentation.")
                (item "Added "
                      (code "raco mcfly init")
                      ".")
                (item "Any "
                      (racket mcfly-planet)
                      " automatically added to "
                      (filepath "info.rkt")
                      " may include an inferred a package name.")
                (item "Any "
                      (racket mcfly-files)
                      " automatically added to "
                      (filepath "info.rkt")
                      " will include Racket files from the immediate
directory.")))
     
     (#:planet 1:4 #:date "2012-06-14"
               (itemlist
                (item "File "
                      (filepath "info.rkt")
                      " is no longer modified unless there are actual changes
to implement.  (No more Emacs complaining that file has changed out from under
it when contents are the same.)")
                (item "Each entry added to "
                      (filepath "info.rkt")
                      " is now preceded by a blank line.")
                (item "Tests fixed.")))
     
     (#: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."))))