diff --git a/Shake.hs b/Shake.hs index edd475ca2..e7e10b49f 100755 --- a/Shake.hs +++ b/Shake.hs @@ -30,6 +30,9 @@ Usage: see below. Also: $ find hledger-lib hledger | entr ./Shake website # rebuild web files on changes in these dirs +Shake rule dependency graph: +file:///Users/simon/src/PLAINTEXTACCOUNTING/hledger/report.html?mode=rule-graph&query=!name(/(doc%7Cimages%7Cjs%7Ccss%7Cfonts%7Ctime%7Capi%7Cui%7Ccsv)/) + Shake wishes: just one shake import wildcards in phony rules @@ -47,22 +50,20 @@ import "safe" Safe import "shake" Development.Shake import "shake" Development.Shake.FilePath import "time" Data.Time +-- import "hledger-lib" Hledger.Utils.Debug usage = unlines ["Usage:" ,"./Shake.hs # compile this script" - ,"./Shake [help] # show commands" + ,"./Shake manuals # generate the txt/man/info manuals" + ,"./Shake website # generate the website and web manuals" ,"./Shake all # generate everything" - ,"./Shake manuals # generate the plaintext/man/info manuals" - ,"./Shake website # generate the html manuals and website" --- ,"./Shake manpages # generate nroff files for man" --- ,"./Shake txtmanpages # generate text man pages for embedding" --- ,"./Shake infomanpages # generate info files for info" --- ,"./Shake webmanpages # generate individual web man pages as markdown" --- ,"./Shake webmanall # generate all-in-one web manual as markdown" - ,"./Shake site/doc/VERSION/.snapshot # generate a versioned snapshot of the web manuals" + ,"" + ,"./Shake site/doc/VERSION/.snapshot # save the checked-out web manuals as a versioned snapshot" ,"./Shake clean # clean generated files" - ,"./Shake Clean # clean harder" + ,"./Shake Clean # clean more thoroughly" + ,"" + ,"./Shake [help] # show commands" ,"./Shake --help # show detailed Shake options, eg --color" ] @@ -85,19 +86,25 @@ main = do phony "help" $ liftIO $ putStrLn usage --- phony "compile" $ need ["Shake"] --- --- "Shake" %> \out -> do --- need [out <.> "hs"] --- unit $ cmd "./Shake.hs" -- running as stack script installs deps and compiles --- putLoud "You can now run ./Shake instead of ./Shake.hs" - phony "all" $ need ["manuals", "website"] - -- manuals + -- phony "compile" $ need ["Shake"] + -- "Shake" %> \out -> do + -- need [out <.> "hs"] + -- unit $ cmd "./Shake.hs" -- running as stack script installs deps and compiles + -- putLoud "You can now run ./Shake instead of ./Shake.hs" + + + -- MANUALS let - manpageNames = [ -- in suggested reading order + -- documentation versions shown on the website (excluding 0.27 which is handled specially) + docversions = [ "1.0" , "1.1" , "1.2" , "1.3" , "1.4" , "1.5" , "1.9", "1.10", "1.11", "1.12" ] + + -- names, files, uris: + + -- man page names (manual names plus a man section number), in suggested reading order + manpageNames = [ "hledger.1" ,"hledger-ui.1" ,"hledger-web.1" @@ -108,40 +115,27 @@ main = do ,"hledger_timedot.5" ] + -- basic manual names, without numbers manualNames = map manpageNameToManualName manpageNames - -- hledger.1 -> hledger, hledger_journal.5 -> hledger_journal - manpageNameToManualName = dropNumericSuffix - where - dropNumericSuffix s = reverse $ - case reverse s of - c : '.' : cs | isDigit c -> cs - cs -> cs - - -- hledger -> hledger.1, hledger_journal -> hledger_journal.5 - manualNameToManpageName s - | '_' `elem` s = s <.> "5" - | otherwise = s <.> "1" - - -- manuals m4 source; may include other source files (hledger/hledger.m4.md) - m4manpages = [manualDir m m <.> "m4.md" | m <- manualNames] + -- main markdown+m4 source files for manuals (hledger/hledger.m4.md) + -- These may include additional files using m4. + m4manuals = [manualDir m m <.> "m4.md" | m <- manualNames] -- manuals rendered to nroff, ready for man (hledger/hledger.1) - nroffmanpages = [manpageDir m m | m <- manpageNames] + nroffmanuals = [manpageDir m m | m <- manpageNames] - -- manuals rendered to text, ready for embedding (hledger/hledger.txt) - txtmanpages = [manualDir m m <.> "txt" | m <- manualNames] + -- manuals rendered to plain text, ready for embedding (hledger/hledger.txt) + txtmanuals = [manualDir m m <.> "txt" | m <- manualNames] -- manuals rendered to info, ready for info (hledger/hledger.info) - infomanpages = [manualDir m m <.> "info" | m <- manualNames] + infomanuals = [manualDir m m <.> "info" | m <- manualNames] - -- manuals rendered to markdown, ready for web output by pandoc (site/hledger.md) - webmanpages = ["site" manpageNameToUri m <.> "md" | m <- manpageNames] + -- manuals rendered to markdown, ready for conversion to html (site/hledger.md) + webmanuals = ["site" manpageNameToUri m <.> "md" | m <- manpageNames] - -- versions of documentation (excluding 0.27) - docversions = [ "1.0" , "1.1" , "1.2" , "1.3" , "1.4" , "1.5" , "1.9", "1.10", "1.11", "1.12" ] - - -- manuals rendered to html by pandoc + -- website html pages - all manual versions plus misc pages in site/ or copied from elsewhere. + -- All these names will have lower-case URIs on the website. webhtmlpages = map (normalise . ("site/_site" )) $ ( [ prefix manpageNameToUri mPage <.> "html" @@ -164,41 +158,43 @@ main = do ) -- manuals rendered to markdown and combined, ready for web rendering - webmanall = "site/manual.md" + webmancombined = "site/manual.md" - -- file extensions which should just be copied directly over to the website - webcopyfileexts = ["png", "gif", "cur", "js", "css", "eot", "ttf", "woff", "svg"] + -- extensions of static web asset files, to be copied to the website + webassetexts = ["png", "gif", "cur", "js", "css", "eot", "ttf", "woff", "svg"] + -- The directory in which to find this man page. -- hledger.1 -> hledger/doc, hledger_journal.5 -> hledger-lib/doc manpageDir m | '_' `elem` m = "hledger-lib" | otherwise = dropExtension m + -- The directory in which to find this manual. -- hledger -> hledger, hledger_journal -> hledger-lib manualDir m | '_' `elem` m = "hledger-lib" | otherwise = m + -- The URI corresponding to this man page. -- hledger.1 -> hledger, hledger_journal.5 -> journal manpageNameToUri m | "hledger_" `isPrefixOf` m = dropExtension $ drop 8 m | otherwise = dropExtension m + -- The man page corresponding to this URI. -- hledger -> hledger.1, journal -> hledger_journal.5 manpageUriToName u | "hledger" `isPrefixOf` u = u <.> "1" | otherwise = "hledger_" ++ u <.> "5" + -- Generate the manuals in nroff, plain text and info formats. phony "manuals" $ do need $ - nroffmanpages - ++ infomanpages - ++ txtmanpages + nroffmanuals + ++ infomanuals + ++ txtmanuals - -- man pages - - -- use m4 and pandoc to process macros, filter content, and convert to nroff suitable for man output - phony "manpages" $ need nroffmanpages - - nroffmanpages |%> \out -> do -- hledger/hledger.1 + -- Generate nroff man pages suitable for man output. + phony "manmanuals" $ need nroffmanuals + nroffmanuals |%> \out -> do -- hledger/hledger.1 let src = manpageNameToManualName out <.> "m4.md" lib = "doc/lib.m4" dir = takeDirectory out @@ -214,18 +210,17 @@ main = do "--lua-filter tools/pandoc-drop-links.lua" "-o" out - -- render man page nroffs to fixed-width text for embedding in executables, with nroff - phony "txtmanpages" $ need txtmanpages - - txtmanpages |%> \out -> do -- hledger/hledger.txt + -- Generate plain text manuals suitable for embedding in + -- executables and viewing with a pager. + phony "txtmanuals" $ need txtmanuals + txtmanuals |%> \out -> do -- hledger/hledger.txt let src = manualNameToManpageName $ dropExtension out need [src] cmd Shell groff "-t -e -mandoc -Tascii" src "| col -bx >" out -- http://www.tldp.org/HOWTO/Man-Page/q10.html - -- use m4 and pandoc to process macros, filter content, and convert to info, suitable for info viewing - phony "infomanpages" $ need infomanpages - - infomanpages |%> \out -> do -- hledger/hledger.info + -- Generate Info manuals suitable for viewing with info. + phony "infomanuals" $ need infomanuals + infomanuals |%> \out -> do -- hledger/hledger.info let src = out -<.> "m4.md" lib = "doc/lib.m4" dir = takeDirectory out @@ -241,15 +236,13 @@ main = do "-t texinfo |" makeinfo "--force --no-split -o" out - -- web site - phony "website" $ do - need $ [ "website-copy" , "website-render" ] + -- WEBSITE MARKDOWN SOURCE - -- use m4 and pandoc to process macros and filter content, leaving markdown suitable for web output - phony "webmanpages" $ need webmanpages - - webmanpages |%> \out -> do -- site/hledger.md + -- Generate the individual web manuals' markdown source, using m4 + -- and pandoc to tweak content. + phony "webmanuals" $ need webmanuals + webmanuals |%> \out -> do -- site/hledger.md let manpage = manpageUriToName $ dropExtension $ takeFileName out -- hledger manual = manpageNameToManualName manpage dir = manpageDir manpage @@ -269,47 +262,43 @@ main = do "--lua-filter tools/pandoc-demote-headers.lua" ">>" out - -- adjust and combine man page mds for single-page web output, using pandoc - phony "webmanall" $ need [ webmanall ] - - webmanall %> \out -> do - need webmanpages - liftIO $ writeFile webmanall "\\$toc\\$" -- # Big Manual\n\n -- TOC style is better without main heading, - forM_ webmanpages $ \f -> do -- site/hledger.md, site/journal.md - cmd Shell ("printf '\\n\\n' >>") webmanall :: Action ExitCode + -- Generate the combined web manual's markdown source, by + -- concatenating tweaked versions of the individual manuals. + phony "webmancombined" $ need [ webmancombined ] + webmancombined %> \out -> do + need webmanuals + liftIO $ writeFile webmancombined "\\$toc\\$" -- # Big Manual\n\n -- TOC style is better without main heading, + forM_ webmanuals $ \f -> do -- site/hledger.md, site/journal.md + cmd Shell ("printf '\\n\\n' >>") webmancombined :: Action ExitCode cmd Shell pandoc f "-t markdown-fenced_divs --atx-headers" "--lua-filter tools/pandoc-drop-toc.lua" "--lua-filter tools/pandoc-demote-headers.lua" - ">>" webmanall :: Action ExitCode + ">>" webmancombined :: Action ExitCode - -- adjust and combine recipe mds for single-page web output, using pandoc - -- build the currently checked out web docs and save as a named snapshot - "site/doc/*/.snapshot" %> \out -> do - need [ webmanall ] - let snapshot = takeDirectory out - cmd Shell "mkdir -p" snapshot :: Action ExitCode - forM_ webmanpages $ \f -> do -- site/hledger.md, site/journal.md - cmd Shell "cp" f (snapshot takeFileName f) :: Action ExitCode - cmd Shell "cp" "site/manual.md" snapshot :: Action ExitCode - cmd Shell "cp -r site/images" snapshot :: Action ExitCode - cmd Shell "touch" out -- :: Action ExitCode - phony "website-copy" $ do - orig_files <- getDirectoryFiles "site" (map ("//*" <.>) webcopyfileexts) + -- WEBSITE HTML & ASSETS + + phony "website" $ need $ [ "webassets" , "webhtml" ] + + -- copy all static asset files (files with certain extensions + -- found under sites, plus one or two more) to sites/_site/ + phony "webassets" $ do + assets <- getDirectoryFiles "site" (map ("//*" <.>) webassetexts) need [ "site/_site" file - | file <- - "files/README" : - orig_files + | file <- assets ++ [ + "files/README" + ] , not ("_site//*" ?== file) ] - phony "website-render" $ do - need webhtmlpages + -- copy any one of the static asset files to sites/_site/ + "site/_site/files/README" : [ "site/_site//*" <.> ext | ext <- webassetexts ] |%> \out -> do + copyFile' ("site" dropDirectory2 out) out - "site/_site/files/README" : [ "site/_site//*" <.> ext | ext <- webcopyfileexts ] |%> \out -> do - let input = "site" dropDirectory2 out - copyFile' input out + -- render all website pages as html, saved in sites/_site/ + phony "webhtml" $ need webhtmlpages + -- render one website page as html, saved in sites/_site/ "site/_site//*.html" %> \out -> do let source = "site" dropDirectory2 out -<.> "md" pageTitle = takeBaseName out @@ -323,12 +312,26 @@ main = do "--lua-filter" "tools/pandoc-site.lua" "--output" out - -- cleanup + + -- MISC + + -- Generate the web manuals based on the current checkout and save + -- them as the specified versioned snapshot in site/doc/VER/ . + -- .snapshot is a dummy file. + "site/doc/*/.snapshot" %> \out -> do + need $ webmancombined : webmanuals + let snapshot = takeDirectory out + cmd Shell "mkdir -p" snapshot :: Action ExitCode + forM_ webmanuals $ \f -> do -- site/hledger.md, site/journal.md + cmd Shell "cp" f (snapshot takeFileName f) :: Action ExitCode + cmd Shell "cp" "site/manual.md" snapshot :: Action ExitCode + cmd Shell "cp -r site/images" snapshot :: Action ExitCode + cmd Shell "touch" out -- :: Action ExitCode phony "clean" $ do putNormal "Cleaning generated files" - removeFilesAfter "." webmanpages - removeFilesAfter "." [webmanall] + removeFilesAfter "." webmanuals + removeFilesAfter "." [webmancombined] phony "Clean" $ do need ["clean"] @@ -341,5 +344,20 @@ main = do removeFilesAfter ".shake" ["//*"] +-- Convert numbered man page names to manual names. +-- hledger.1 -> hledger, hledger_journal.5 -> hledger_journal +manpageNameToManualName = dropNumericSuffix + where + dropNumericSuffix s = reverse $ + case reverse s of + c : '.' : cs | isDigit c -> cs + cs -> cs + +-- Convert manual names to numbered man page names. +-- hledger -> hledger.1, hledger_journal -> hledger_journal.5 +manualNameToManpageName s + | '_' `elem` s = s <.> "5" + | otherwise = s <.> "1" + dropDirectory2 = dropDirectory1 . dropDirectory1