diff --git a/Bookshelf.cabal b/Bookshelf.cabal --- a/Bookshelf.cabal +++ b/Bookshelf.cabal @@ -1,22 +1,24 @@ name: Bookshelf -version: 0.2 +version: 0.3 synopsis: A simple document organizer with some wiki functionality description: A simple document organizer with some wiki functionality category: Text license: GPL license-file: LICENSE stability: experimental -copyright: Copyright (c) 2009-2012 Emil Axelsson +copyright: Copyright (c) 2009-2013 Emil Axelsson author: Emil Axelsson maintainer: Emil Axelsson homepage: http://www.cse.chalmers.se/~emax/bookshelf/Manual.shelf.html +bug-reports: http://hub.darcs.net/emax/Bookshelf/issues build-type: Simple -cabal-version: >= 1.6 +cabal-version: >= 1.8 tested-with: GHC==7.4.2 data-files: bookshelf.css Documentation/*.shelf + Documentation/papers.bib Documentation/Test/*.txt Documentation/Test/*.shelf @@ -24,9 +26,15 @@ source-repository head type: darcs - location: http://projects.haskell.org/Bookshelf/ + location: http://hub.darcs.net/emax/Bookshelf executable bookshelf - build-depends: base < 5, filepath, directory, parseargs, pandoc >= 1.10, pandoc-types >= 1.10 + build-depends: base < 5, citeproc-hs, directory, filepath, pandoc >= 1.10, pandoc-types >= 1.10, parseargs main-is: Bookshelf.hs + extensions: PatternGuards + +test-suite documentation + build-depends: base < 5, process + type: exitcode-stdio-1.0 + main-is: MakeDoc.hs diff --git a/Bookshelf.hs b/Bookshelf.hs --- a/Bookshelf.hs +++ b/Bookshelf.hs @@ -1,4 +1,4 @@ --- Copyright (C) 2009-2012 Emil Axelsson +-- Copyright (C) 2009-2013 Emil Axelsson -- -- This program is free software; you can redistribute it and/or modify -- it under the terms of the GNU General Public License as published by @@ -26,25 +26,44 @@ import Control.Monad import Data.List +import Data.Traversable (traverse) import System.Directory -import System.Environment import System.FilePath import System.Console.ParseArgs +import Text.CSL import Text.Pandoc +import Text.Pandoc.Shared import Types import Generate +-- | Makes a file path relative to a directory. Both supplied paths are assumed to be absolute, and +-- not including "..". Such paths are returned by 'canonicalizePath'. +makeRel + :: FilePath -- ^ Directory + -> FilePath -- ^ File + -> FilePath +makeRel dir file = joinPath $ rel (splitDirectories dir) (splitDirectories file) + where + rel [] fs = fs + rel (d:ds) (f:fs) | d==f = rel ds fs + rel ds fs = replicate (length ds) ".." ++ fs + +downPath :: FilePath -> FilePath +downPath f + | isAbsolute f = f + | isHttp f = f + | otherwise = ".." f + -- | Move down to the given directory (affects paths in `Context`). moveDown :: Context -> FilePath -> Context moveDown context dir = context { relPath_ = relPath context dir - , cssLink_ = liftM (".." ) $ cssLink context - , mathjaxLink_ = liftM (".." ) $ mathjaxLink context + , cssLink_ = fmap downPath $ cssLink context } @@ -162,39 +181,45 @@ path = rootPath context relPath context shelfInfoS name = ShelfInfo context Nothing name - shelfInfoI name = - ShelfInfo context (Just name) (replaceExtension name ".shelf") + shelfInfoI name = ShelfInfo context (Just name) (replaceExtension name ".shelf") argSpec :: [Arg String] argSpec = - [ Arg { argIndex = "CSS" + [ Arg { argIndex = "Bib" + , argName = Just "bib" + , argAbbr = Just 'b' + , argData = argDataOptional "bibliography file" ArgtypeString + , argDesc = "Path to bibliography file" + } + + , Arg { argIndex = "CSL" + , argName = Just "csl" + , argAbbr = Nothing + , argData = argDataOptional "CSL file" ArgtypeString + , argDesc = "Path to CSL style file" + } + + , Arg { argIndex = "CSS" , argName = Just "css" , argAbbr = Just 'c' , argData = argDataOptional "CSS file" ArgtypeString - , argDesc = "Path to CSS style sheet" - } - - , Arg { argIndex = "Editor" - , argName = Just "editor" - , argAbbr = Just 'e' - , argData = argDataOptional "editor command" ArgtypeString - , argDesc = "Command used for editing source files" + , argDesc = "Path or URL to CSS style sheet" } , Arg { argIndex = "MathJax" , argName = Just "mathjax" , argAbbr = Just 'm' , argData = argDataOptional "MathJax.js file" ArgtypeString - , argDesc = "Path to MathJax.js file" + , argDesc = "URL to MathJax.js file (use \"\" to get the default URL)" } - , Arg { argIndex = "NoScript" - , argName = Just "no-script" - , argAbbr = Just 'n' + , Arg { argIndex = "MathML" + , argName = Just "mathml" + , argAbbr = Nothing , argData = Nothing - , argDesc = "Do not display the edit/regenerate script" + , argDesc = "Use MathML for math rendering" } , Arg { argIndex = "Source" @@ -209,45 +234,44 @@ main :: IO () main = do - pwd <- getCurrentDirectory args <- parseArgsIO ArgsComplete argSpec tmpl <- getDefaultTemplate Nothing "html" tmpl' <- case tmpl of Left msg -> error $ show msg Right tmpl -> return tmpl - let Just path = getArg args "Source" - css = getArg args "CSS" - mathjax = getArg args "MathJax" - edit = getArg args "Editor" - script = not $ gotArg args "NoScript" - path' = pwd path - dirs = splitDirectories path' - css' = liftM (".." ) css - mathjax' = liftM (".." ) mathjax - mkContext ds = Context tmpl' css' mathjax' edit script (joinPath $ init ds) (last ds) + let bib = getArg args "Bib" + csl = getArg args "CSL" - isDir <- doesDirectoryExist path - isFile <- doesFileExist path - unless (isDir || isFile) $ err $ "Source '" ++ path ++ "' does not exist." + cStyle <- parseCSL =<< case csl of + Just cslFile -> readFile cslFile + _ -> readDataFileUTF8 Nothing "default.csl" - if isDir - then generateBookshelf (mkContext dirs) - else do - err $ "'" ++ path ++ "' is not a directory" - unless (takeExtension path == ".shelf") $ - err "Source file must have extension '.shelf'" - let dirs' = init dirs - setCurrentDirectory (joinPath $ init dirs) - convertShelfDoc (ShelfInfo (mkContext dirs') Nothing (last dirs)) - return () - where - err msg = error ("**Error: " ++ msg) + refs <- case bib of + Nothing -> return [] + Just bibFile -> readBiblioFile bibFile - -- TODO If the "not a directory" error is removed, it handles single shelf - -- files as well. In this case, it treats the parent directory as the - -- root, which is not ideal. It also ignores links to main documents, and - -- it doesn't regenerate the index (which might then become inconsistent - -- if meta information is changed). Don't forget to update the `argSpec` - -- text if this feature is reintroduced. + let Just path = getArg args "Source" + css = getArg args "CSS" + mathjax = getArg args "MathJax" + mathml = gotArg args "MathML" + + isDir <- doesDirectoryExist path + unless isDir $ error $ "**Error: Source directory '" ++ path ++ "' does not exist." + absPath <- canonicalizePath path + + let fixPath f + | isHttp f = return f + | otherwise = do + absf <- canonicalizePath f + return $ if isAbsolute path || isAbsolute f + then absf + else makeRel absPath absf + + css' <- traverse fixPath css + + let dirs = splitDirectories absPath + context = Context tmpl' cStyle refs css' mathjax mathml (joinPath $ init dirs) (last dirs) + + generateBookshelf context diff --git a/Documentation/Manual.shelf b/Documentation/Manual.shelf --- a/Documentation/Manual.shelf +++ b/Documentation/Manual.shelf @@ -20,25 +20,31 @@ This will (re-)generate the whole directory contents (see section [Operation](#operation)). -We can also supply some optional parameters: - - bookshelf --css bookshelf.css --editor gedit Shelf - -The first parameter tells Bookshelf which style sheet to use for the generated pages. The recommended style sheet for Bookshelf is [`bookshelf.css`](http://www.cse.chalmers.se/~emax/bookshelf.css). The second parameter tells what editor to use when editing the source files. This command will appear in an edit/regenerate script at the end of each generated page. - Running Bookshelf without arguments results in the following message which shows the complete usage: - bookshelf [options] + usage: bookshelf [options] + [-b,--bib ] Path to bibliography file + [--csl ] Path to CSL style file [-c,--css ] Path or URL to CSS style sheet - [-e,--editor ] Command used for editing source files - [-m,--mathjax ] Path or URL to MathJax.js file - [-n,--no-script] Do not display the edit/regenerate script + [-m,--mathjax ] URL to MathJax.js file (use "" to get the default URL) + [--mathml] Use MathML for math rendering Root directory of bookshelf to be generated -An optional parameter is provided to indicate a link where to find [MathJax](http://www.mathjax.org/) javascript file, to use it for math rendering with Pandoc. +If no CSS style sheet is provided, [bookshelf.css](http://www.cse.chalmers.se/~emax/bookshelf.css) will be used. +Pandoc (and hence Bookshelf) supports TeX math. By default, a very simple rendering is used. The `--mathjax` and `--mathml` options result in much improved math rendering, using [MathJax](http://www.mathjax.org) or [MathML](http://www.w3.org/Math) respectively. Note that MathJax requires running a script on a web server, so MathML might be preferred when the generated pages are viewed locally without access to internet or a local a web server. + The markdown syntax is described [here](http://daringfireball.net/projects/markdown/syntax), and the extensions supported by [Pandoc](http://johnmacfarlane.net/pandoc/) (the converter used internally by Bookshelf) are described [here](http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown). +Demonstration +============= + +The contents in [Documentation](.) has been generated by running + + bookshelf --css bookshelf.css --bib Documentation/papers.bib Documentation + +in the root of the [project directory](http://projects.haskell.org/Bookshelf). In addition to this manual, it contains a sub-directory [Test](Test/) with some example files in it. + Operation ========= @@ -47,8 +53,6 @@ * Converts each file `name.shelf` to the file `name.shelf.html`. In this process, any links to files of the form `name.shelf` get redirected to `name.shelf.html`. * Places a file `index.html` at each directory node. This file contains links to the directory's sub-directories and documents. The [Meta information](#meta-information) section describes how the document listing can be affected. -For convenience, each generated HTML file displays a "script" for editing/regenerating the source file at the end. This can be turned off by providing the `--no-script` flag. - It is possible to exclude files or directories from being converted and indexed by using "ignore" files. To exclude the file `name`, simply add a file `name.ignore` in the same directory. Warning: Any existing file with the extension `.shelf.html` or the name `index.html` are assumed to have been generated by previous runs of Bookshelf. Such files will first be removed[^RemovedFiles], and then possibly regenerated, so one should be careful not to have ordinary documents with such names. @@ -80,11 +84,6 @@ * etc. (The "Meta" header is also allowed to be a lower-level header.) This information will then be used when listing the ordinary document. - -Demonstration -============= - -The contents in [Documentation](.) has been generated by Bookshelf. In addition to the current manual, it contains a sub-directory [Test](Test/) with some example files in it. The source of the documentation directory can be found [here](http://projects.haskell.org/Bookshelf/Documentation/). Installation ============ diff --git a/Documentation/Test/Notes.shelf b/Documentation/Test/Notes.shelf --- a/Documentation/Test/Notes.shelf +++ b/Documentation/Test/Notes.shelf @@ -5,6 +5,8 @@ Some notes... +These are interesting references: [@tyler2001], [@hobbs2009], [@goddard2009] + Heading 2 ========= @@ -14,3 +16,7 @@ * Bullet 2.2 * Bullet 2.3 * Bullet 3 + +References +========== + diff --git a/Documentation/papers.bib b/Documentation/papers.bib new file mode 100644 --- /dev/null +++ b/Documentation/papers.bib @@ -0,0 +1,21 @@ +@article{tyler2001, + title={Paper 1}, + author={Charles Tyler, Alice Kelly, Kyle Horton}, + journal={Some journal}, + year={2001} +} + +@article{hobbs2009, + title={Paper 2}, + author={Lara Hobbs, Lauren Simmons, Edward Burgess}, + journal={Some journal}, + year={2009} +} + +@article{goddard2009, + title={Paper 3}, + author={Mason Goddard}, + journal={Some journal}, + year={2009} +} + diff --git a/Generate.hs b/Generate.hs --- a/Generate.hs +++ b/Generate.hs @@ -1,4 +1,4 @@ --- Copyright (C) 2009-2012 Emil Axelsson +-- Copyright (C) 2009-2013 Emil Axelsson -- -- This program is free software; you can redistribute it and/or modify -- it under the terms of the GNU General Public License as published by @@ -134,56 +134,12 @@ , Link (pandocStr "Main document") (name, "View main document") ] - - --- | Makes a section with commands for editing the current document and --- regenerating the bookshelf. -editRegenerate :: ShelfInfo -> String -editRegenerate shelfInfo = guard (showScript shelfInfo) >> script - where - css = cssLink shelfInfo - edit = editor shelfInfo - mathjax = mathjaxLink shelfInfo - name = shelfDocument shelfInfo - relPth = relPath shelfInfo - rootPth = rootPath shelfInfo - - edit' = case edit of - Just e -> e - Nothing -> "editor" - - file = rootPth relPth name - root = rootPth head (splitDirectories relPth) - - makeOpt (_, Nothing) = "" - makeOpt (flag, Just val) = flag ++ " " ++ show val - - opts = filter (not . null) $ map makeOpt - [ ("--editor", edit) - , ("--css", css) - , ("--mathjax", mathjax) - ] - - editCmd = edit' ++ " " ++ show file - regenCmd = unwords ("bookshelf" : opts ++ [show root]) - - script = - "


\n\ - \
\n\ - \ ➤ Edit/regenerate this document:\n\ - \ 
" ++ editCmd ++ "\n" ++ regenCmd ++ "
\n\ - \
\n" - - - bookshelfCreds :: String bookshelfCreds = "
\n\ \ Organized by Bookshelf\n\ \
\n" - - -- | Extracts title block information. extractMeta :: Pandoc -> MetaInfo extractMeta (Pandoc meta _) = MetaInfo title authors date [] [] @@ -250,18 +206,20 @@ --- | Give a css option for the template that links to the supplied CSS (if any). +-- | Give the css option for the template that links to the supplied CSS (if any). makeCss :: Context -> [(String, String)] makeCss context = case cssLink context of - Nothing -> [] - Just css - -> [("css", css)] + Just css -> [("css", css)] + _ -> [("css", "http://www.cse.chalmers.se/~emax/bookshelf.css")] --- | Give the math option to supply to the html writer +-- | Give the math option to supply to the HTML writer makeMath :: Context -> HTMLMathMethod -makeMath context = case mathjaxLink context of - Nothing -> PlainMath - Just l -> MathJax l +makeMath context + | Just l <- mathjaxLink context = if null l + then MathJax "http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML" + else MathJax l + | mathml context = MathML Nothing + | otherwise = PlainMath @@ -298,10 +256,12 @@ _ -> mainMeta rOpts = def - { readerSmart = True + { readerSmart = True + , readerReferences = references $ shelfContext shelfInfo + , readerCitationStyle = Just $ cslStyle $ shelfContext shelfInfo } - after = editRegenerate shelfInfo ++ bookshelfCreds + after = bookshelfCreds cssInclude = makeCss $ shelfContext shelfInfo mathMethod = makeMath $ shelfContext shelfInfo diff --git a/MakeDoc.hs b/MakeDoc.hs new file mode 100644 --- /dev/null +++ b/MakeDoc.hs @@ -0,0 +1,11 @@ +module Main where + +import System.Cmd +import System.Exit + +main = do + e <- system "dist/build/bookshelf/bookshelf --css bookshelf.css --bib Documentation/papers.bib Documentation" + case e of + ExitSuccess -> return () + _ -> exitFailure + diff --git a/Types.hs b/Types.hs --- a/Types.hs +++ b/Types.hs @@ -1,4 +1,4 @@ --- Copyright (C) 2009-2012 Emil Axelsson +-- Copyright (C) 2009-2013 Emil Axelsson -- -- This program is free software; you can redistribute it and/or modify -- it under the terms of the GNU General Public License as published by @@ -24,6 +24,7 @@ +import Text.CSL import Text.Pandoc @@ -39,21 +40,23 @@ data Context = Context { -- | Pandoc HTML template - htmlTemplate :: String + htmlTemplate_ :: String + -- | CSL style + , cslStyle_ :: Style + -- | List of available references + , references_ :: [Reference] -- | Optional link to CSS file - , cssLink_ :: Maybe FilePath + , cssLink_ :: Maybe FilePath -- | Optional link to MathJax.js file - , mathjaxLink_ :: Maybe FilePath - -- | Optional editor command - , editor_ :: Maybe String - -- | Show the edit/regenerate script? - , showScript_ :: Bool + , mathjaxLink_ :: Maybe FilePath + -- | Use MathML rendering? + , mathml_ :: Bool -- | Path to root of bookshelf - , rootPath_ :: FilePath + , rootPath_ :: FilePath -- | Path to current node, relative to the root - , relPath_ :: FilePath + , relPath_ :: FilePath } - deriving (Eq, Show) + deriving (Show) data ShelfInfo = ShelfInfo { -- | The document's context @@ -67,28 +70,34 @@ class HasContext a where - cssLink :: a -> Maybe FilePath - mathjaxLink :: a -> Maybe FilePath - editor :: a -> Maybe String - showScript :: a -> Bool - rootPath :: a -> FilePath - relPath :: a -> FilePath + htmlTemplate :: a -> String + cslStyle :: a -> Style + references :: a -> [Reference] + cssLink :: a -> Maybe FilePath + mathjaxLink :: a -> Maybe FilePath + mathml :: a -> Bool + rootPath :: a -> FilePath + relPath :: a -> FilePath instance HasContext Context where - cssLink = cssLink_ - mathjaxLink = mathjaxLink_ - editor = editor_ - showScript = showScript_ - rootPath = rootPath_ - relPath = relPath_ + htmlTemplate = htmlTemplate_ + cslStyle = cslStyle_ + references = references_ + cssLink = cssLink_ + mathjaxLink = mathjaxLink_ + mathml = mathml_ + rootPath = rootPath_ + relPath = relPath_ instance HasContext ShelfInfo where - cssLink = cssLink_ . shelfContext - mathjaxLink = mathjaxLink_ . shelfContext - editor = editor_ . shelfContext - showScript = showScript_ . shelfContext - rootPath = rootPath_ . shelfContext - relPath = relPath_ . shelfContext + htmlTemplate = htmlTemplate_ . shelfContext + cslStyle = cslStyle_ . shelfContext + references = references_ . shelfContext + cssLink = cssLink_ . shelfContext + mathjaxLink = mathjaxLink_ . shelfContext + mathml = mathml_ . shelfContext + rootPath = rootPath_ . shelfContext + relPath = relPath_ . shelfContext