Commits

John Lenz  committed cd9e434

Update doc builder to use pandoc directly instead of shelly. Also, update the docs slightly.

  • Participants
  • Parent commits f575719

Comments (0)

Files changed (5)

-% LACANDLE LaTeX Candle User Guide
-% John Lenz
-% May 1, 2012
+Overview
+========
 
-# Name
+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 package implements a LaTeX
+checker that uses parsec for great error messages while parsing while
+also implementing many lint style checks. The ambitious goal is to check
+the majority of TeX errors so that these errors can be discovered in a
+common format and loaded into editors like Vim. Also, provide much
+better error messages which are understandable by the user.
 
-lacandle - checks TeX or LaTeX code for errors, warnings, and lint.
+Usage
+=====
 
-# Synopsis
+The checker can be used in one of two ways: through a command line
+program *lacandle* and through a [haskell
+library](http://hackage.haskell.org/package/latex-candle). Basic usage
+of *lacandle* is
 
-lacandle [*options*] [*input-file*]...
+    lacandle [options] [filenames]
 
-# Description
+The options are described in detail below and are mostly options to
+enable or disable certian warnings and lint checks. Any errors,
+warnings, or lint found by the checker is written to standard output.
+The format for messages is the following.
 
-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.)
+    file:line:col: message
+    file:line:col-col: a message spanning multiple columns
+    file:line:col:+ first message line
+          second message line
+          another message line
+    file:line:col-col:+ a multiple column message
+          second message line
 
-# Options
+Vim Integration
+---------------
 
-## Document Structure
+The plan is to integrate with
+[syntastic](https://github.com/scrooloose/syntastic), although this
+still needs to be written.
+
+See Also
+========
+
+Similar packages include lacheck
+(<http://www.ctan.org/tex-archive/support/lacheck>) and chktex
+(<http://baruch.ev-en.org/proj/chktex/>), but neither of these programs
+are actively developed anymore.
+
+Option Details
+==============
+
+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.
+  ~ 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
+  ~ 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.
-    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

 -}
 
 {-# LANGUAGE OverloadedStrings #-}
-{-# LANGUAGE ExtendedDefaultRules #-}
-{-# OPTIONS_GHC -fno-warn-type-defaults #-}
 
 module Main where
 
-import Shelly
+import Control.Applicative ((<$>))
+import Text.Pandoc
 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
   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"
+main = do
+  -- Load the options
+  f <- TLIO.readFile "../src/Text/LatexCandle/Options.hs"
   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"]
+  -- build the man page
+  pandocTemplate <- either (error . show) id <$> getDefaultTemplate Nothing "man"
+  mantemplate <- TLIO.readFile "man-template"
+  let manpage     = TL.unpack $ TL.replace "INPUT_OPTIONS_HERE" options mantemplate
+      manoptions  = defaultWriterOptions { writerStandalone = True, writerTemplate = pandocTemplate }
+      manrendered = writeMan manoptions $ readMarkdown defaultParserState manpage
+  TLIO.writeFile "lacandle.1" $ TL.pack manrendered
 
-  return ()
+  -- build the readme
+  rtemplate <- TLIO.readFile "readme-template"
+  let readme    = TL.unpack $ TL.replace "INPUT_OPTIONS_HERE" options rtemplate
+      rrendered = writeMarkdown defaultWriterOptions $ readMarkdown defaultParserState readme
+  TLIO.writeFile "../README.md" $ TL.pack rrendered

File doc/lacandle.1

 code using packages like tikz are non-intuitive.
 This program checks TeX or LaTeX code for errors, warnings, and lint
 (suggestions for improving code.)
+.PP
+Any errors, warnings, or lint found are written to standard output.
+The format for messages is the following.
+.IP
+.nf
+\f[C]
+file:line:col:\ message
+file:line:col-col:\ a\ message\ spanning\ multiple\ columns
+file:line:col:+\ first\ message\ line
+\ \ \ \ \ \ second\ message\ line
+\ \ \ \ \ \ another\ message\ line
+file:line:col-col:+\ a\ multiple\ column\ message
+\ \ \ \ \ \ second\ message\ line
+\f[]
+.fi
 .SH Options
 .SS Document Structure
 .TP
 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
+.PP
+Similar packages include lacheck
+<http://www.ctan.org/tex-archive/support/lacheck> and chktex
+(<http://baruch.ev-en.org/proj/chktex/>)
 .SH Authors
 .PP
 © 2012 John Lenz (lenz at math.uic.edu).

File doc/man-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.)
+
+Any errors, warnings, or lint found are written to standard output.  The format
+for messages is the following.
+
+
+    file:line:col: message
+    file:line:col-col: a message spanning multiple columns
+    file:line:col:+ first message line
+          second message line
+          another message line
+    file:line:col-col:+ a multiple column message
+          second message line
+
+# 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
+
+Similar packages include lacheck <http://www.ctan.org/tex-archive/support/lacheck>
+and chktex (<http://baruch.ev-en.org/proj/chktex/>)
+
+# 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/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.)
-