Commits

John Lenz  committed f575719

Update command to build man page and readme, and add basic docs

  • Participants
  • Parent commits 0d5ad83

Comments (0)

Files changed (5)

+% LACANDLE LaTeX Candle User Guide
+% John Lenz
+% May 1, 2012
+
+# Name
+
+lacandle - checks TeX or LaTeX code for errors, warnings, and lint.
+
+# Synopsis
+
+lacandle [*options*] [*input-file*]...
+
+# Description
+
+The TeX engine does not provide good error messages or warnings; the messages
+are mixed in with lots of superfluous output, some errors don't have file and
+line numbers, there is no consist formatting for messages, syntax errors can
+lead to very confusing messages, errors in code using packages like tikz are
+non-intuitive.  This program checks TeX or LaTeX code for errors, warnings, and
+lint (suggestions for improving code.)
+
+# Options
+
+## Document Structure
+
+`-b`, `--only-body`
+:   If this flag is passed, the document is assumed to consit only
+    of LaTeX which is valid between the \\begin{document} and \\end{document}.
+    If neither this option nor --full-document are passed, the option is
+    detected based on the presense of a documentclass command.
+
+`-f`, `--full-document`
+:   If this flag is passed, the document is required to start with the
+    documentclass command.
+    If neither this option nor --only-body are passed, the option is
+    detected based on the presense of a documentclass command.
+
+
+
+# See Also
+
+Bugs and improvements should be reported to the project homepage at
+http://bitbucket.org/wuzzeb/latex-candle  This project also includes
+a haskell library to check LaTeX code, available at
+http://hackage.haskell.org/package/latex-candle
+
+# Authors
+
+© 2012 John Lenz (lenz at math.uic.edu).  Released  under the  GPL, version 3
+or greater.  This software carries no warranty of any kind.  (See LICENSE
+for full copyright and warranty notices.)
+

File doc/build-docs.hs

+{-
+Copyright (C) 2012 John Lenz <lenz@math.uic.edu>
+
+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
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+-}
+
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE ExtendedDefaultRules #-}
+{-# OPTIONS_GHC -fno-warn-type-defaults #-}
+
+module Main where
+
+import Shelly
+import qualified Data.Text.Lazy as TL
+import qualified Data.Text.Lazy.IO as TLIO
+default (TL.Text)
+
+isComment :: TL.Text -> Bool
+isComment t = "-- " `TL.isPrefixOf` TL.strip t
+
+-- | Extract the option comments from the given text
+extract :: TL.Text -> [TL.Text]
+extract t = nosuffix
+  where comments  = filter isComment $ TL.lines t
+        raw       = map (TL.drop 3 . TL.strip) comments
+        noprefix  = drop 1 $ dropWhile (not . TL.isPrefixOf "OPTIONS START") raw
+        nosuffix  = takeWhile (not . TL.isPrefixOf "OPTIONS END") noprefix
+
+-- | Group lines togeter into a single option
+groupOpts :: [TL.Text] -> [[TL.Text]]
+groupOpts []     = []
+groupOpts (x:xs) = (fix x:h) : groupOpts t
+  where (h, t)  = break checkend xs
+        checkend y = "| " `TL.isPrefixOf` y || "Section: " `TL.isPrefixOf` y
+        fix y | "| " `TL.isPrefixOf` y = TL.drop 2 y
+              | "Section: " `TL.isPrefixOf` y = TL.append "## " $ TL.drop 9 y
+              | otherwise = y
+
+-- | Change \ to \\
+escape :: TL.Text -> TL.Text
+escape = TL.replace "\\" "\\\\"
+
+-- | Convert a block to a pandoc definition list
+blockToDefList :: [TL.Text] -> [TL.Text]
+blockToDefList []  = []
+blockToDefList [x] = [x, ""]
+blockToDefList (x1:x2:xs) = [x1, TL.append ":   " x2] ++ indented ++ [""]
+  where indented = map (TL.append "    ") xs
+
+main :: IO ()
+main = shelly $ do
+  f <- liftIO $ TLIO.readFile "../src/Text/LatexCandle/Options.hs"
+  template <- liftIO $ TLIO.readFile "template"
+  let options = TL.concat $ map (escape . TL.unlines . blockToDefList) $ groupOpts $ extract f
+      doc = TL.replace "INPUT_OPTIONS_HERE" options template
+
+  liftIO $ TLIO.writeFile "../README.md" doc
+  setStdin doc
+  run_ "pandoc" ["-s", "-t", "man", "-o", "lacandle.1"]
+
+  return ()

File doc/lacandle.1

+.TH LACANDLE "" "May 1, 2012" "LaTeX Candle User Guide"
+.SH Name
+.PP
+lacandle - checks TeX or LaTeX code for errors, warnings, and lint.
+.SH Synopsis
+.PP
+lacandle [\f[I]options\f[]] [\f[I]input-file\f[]]...
+.SH Description
+.PP
+The TeX engine does not provide good error messages or warnings; the
+messages are mixed in with lots of superfluous output, some errors
+don\[aq]t have file and line numbers, there is no consist formatting for
+messages, syntax errors can lead to very confusing messages, errors in
+code using packages like tikz are non-intuitive.
+This program checks TeX or LaTeX code for errors, warnings, and lint
+(suggestions for improving code.)
+.SH Options
+.SS Document Structure
+.TP
+.B \f[C]-b\f[], \f[C]--only-body\f[]
+If this flag is passed, the document is assumed to consit only of LaTeX
+which is valid between the \\begin{document} and \\end{document}.
+If neither this option nor --full-document are passed, the option is
+detected based on the presense of a documentclass command.
+.RS
+.RE
+.TP
+.B \f[C]-f\f[], \f[C]--full-document\f[]
+If this flag is passed, the document is required to start with the
+documentclass command.
+If neither this option nor --only-body are passed, the option is
+detected based on the presense of a documentclass command.
+.RS
+.RE
+.SH See Also
+.PP
+Bugs and improvements should be reported to the project homepage at
+http://bitbucket.org/wuzzeb/latex-candle This project also includes a
+haskell library to check LaTeX code, available at
+http://hackage.haskell.org/package/latex-candle
+.SH Authors
+.PP
+© 2012 John Lenz (lenz at math.uic.edu).
+Released under the GPL, version 3 or greater.
+This software carries no warranty of any kind.
+(See LICENSE for full copyright and warranty notices.)
+.SH AUTHORS
+John Lenz.

File doc/template

+% LACANDLE LaTeX Candle User Guide
+% John Lenz
+% May 1, 2012
+
+# Name
+
+lacandle - checks TeX or LaTeX code for errors, warnings, and lint.
+
+# Synopsis
+
+lacandle [*options*] [*input-file*]...
+
+# Description
+
+The TeX engine does not provide good error messages or warnings; the messages
+are mixed in with lots of superfluous output, some errors don't have file and
+line numbers, there is no consist formatting for messages, syntax errors can
+lead to very confusing messages, errors in code using packages like tikz are
+non-intuitive.  This program checks TeX or LaTeX code for errors, warnings, and
+lint (suggestions for improving code.)
+
+# Options
+
+INPUT_OPTIONS_HERE
+
+# See Also
+
+Bugs and improvements should be reported to the project homepage at
+http://bitbucket.org/wuzzeb/latex-candle  This project also includes
+a haskell library to check LaTeX code, available at
+http://hackage.haskell.org/package/latex-candle
+
+# Authors
+
+© 2012 John Lenz (lenz at math.uic.edu).  Released  under the  GPL, version 3
+or greater.  This software carries no warranty of any kind.  (See LICENSE
+for full copyright and warranty notices.)
+

File extract-options.hs

-{-
-Copyright (C) 2012 John Lenz <lenz@math.uic.edu>
-
-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
-the Free Software Foundation, either version 3 of the License, or
-(at your option) any later version.
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU General Public License for more details.
-
-You should have received a copy of the GNU General Public License
-along with this program.  If not, see <http://www.gnu.org/licenses/>.
--}
-
-{-# LANGUAGE OverloadedStrings #-}
-
-module Main where
-
-import qualified Data.Text.Lazy as TL
-import qualified Data.Text.Lazy.IO as TLIO
-
-isComment :: TL.Text -> Bool
-isComment t = "-- " `TL.isPrefixOf` TL.strip t
-
-groupOpts :: [TL.Text] -> [[TL.Text]]
-groupOpts []     = []
-groupOpts (x:xs) = (fix x:h) : groupOpts t
-  where (h, t)  = break checkend xs
-        checkend y = "| " `TL.isPrefixOf` y || "Section: " `TL.isPrefixOf` y
-        fix y | "| " `TL.isPrefixOf` y = TL.drop 2 y
-              | "Section: " `TL.isPrefixOf` y = TL.append "## " $ TL.drop 9 y
-              | otherwise = y
-          
-
-extract :: TL.Text -> [TL.Text]
-extract t = nosuffix
-  where comments  = filter isComment $ TL.lines t
-        raw       = map (TL.drop 3 . TL.strip) comments
-        noprefix  = drop 1 $ dropWhile (not . TL.isPrefixOf "OPTIONS START") raw
-        nosuffix  = takeWhile (not . TL.isPrefixOf "OPTIONS END") noprefix
-
-printBlock :: [TL.Text] -> IO ()
-printBlock []  = return ()
-printBlock [x] = TLIO.putStrLn x >> TLIO.putStrLn ""
-printBlock (x1:x2:xs) = do
-  TLIO.putStrLn x1
-  TLIO.putStrLn $ TL.append ":  " x2
-  mapM_ (TLIO.putStrLn . TL.append "   ") xs
-  TLIO.putStrLn ""
-
-main :: IO ()
-main = do
-  f <- TLIO.readFile "src/Text/LatexCandle/Options.hs"
-  mapM_ printBlock $ groupOpts $ extract f