packages feed

HaTeX 3.6 → 3.6.0.1

raw patch · 7 files changed

+163/−47 lines, 7 filesPVP ok

version bump matches the API change (PVP)

API changes (from Hackage documentation)

Files

HaTeX.cabal view
@@ -1,5 +1,5 @@ Name: HaTeX
-Version: 3.6
+Version: 3.6.0.1
 Author: Daniel Díaz
 Category: Text
 Build-type: Simple
@@ -10,12 +10,12 @@ Bug-reports: https://github.com/Daniel-Diaz/HaTeX/issues
 Synopsis: The Haskell LaTeX library.
 Description: The LaTeX project site states: \"LaTeX is a high-quality typesetting system\". This library provides
-             a bridge between that system and Haskell (i.e. it is a LaTeX DSL).
+             a bridge between LaTeX and Haskell (i.e. it is a LaTeX DSL).
              .
              Write LaTeX documents with all the advantages you already have in Haskell (recursion,
              type system, high order functions, ...), create a LaTeX backend for your own program,
-             make analysis of LaTeX code through its Abstract Syntax Tree (AST), find another way
-             to pretty-printing values, ...
+             make analysis of LaTeX code through its Abstract Syntax Tree (AST), pretty-print Haskell
+             values in LaTeX, generate TikZ scripts easily, ...
              .
              See the @examples@ directory in the source distribution to look some simple examples.
              It would be good to get you started. HaTeX User's Guide is available at
README.md view
@@ -10,12 +10,31 @@ 
 To install `HaTeX`, use [cabal-install](http://hackage.haskell.org/package/cabal-install).
 
+    $ cabal update
     $ cabal install HaTeX
 
+This will install the latest official release (recommended).
+If you want to try a newer version, use _git_ to clone the code contained
+in this repository.
+
+    $ git clone git@github.com:Daniel-Diaz/HaTeX.git
+    $ cd HaTeX
+    $ cabal install
+
+However, note that the API may be unstable and is subject to any kind of change.
+The package version follows the [_Package Versioning Policy_](http://www.haskell.org/haskellwiki/Package_versioning_policy),
+so it is unlikely to suffer from API breakages if you follow it too when importing the library.
+
 ## HaTeX User's Guide
 
 The HaTeX User's Guide lives [here](https://github.com/Daniel-Diaz/HaTeX-Guide)... and is also done in Haskell!
+It is free source and anybody can contribute to it. Doing so, you will help current and future users!
 
+A downloadable version (not necessarily the last version, but most likely)
+can be found [here](http://daniel-diaz.github.com/projects/hatex/hatex-guide.pdf).
+To be sure that you are reading the last version, go to the github repository of the guide and follow instructions
+to build it. It is fairly easy.
+
 ## Contributing
 
 To contribute to HaTeX, please, visit our code repository in GitHub:
@@ -25,11 +44,14 @@ ## TODO list
 
 * Add more examples.
-* More testing on the parser.
+* More testing on the parser (See [#15](https://github.com/Daniel-Diaz/HaTeX/issues/15)).
 * Add more documentation.
-* A more complete `AMSMath` module.
-* Implement more packages (geometry, array, ...).
 * BibTeX support.
+
+## Packages to be implemented
+
+* fancyhdr
+* geometry
 
 ## Related projects
Text/LaTeX.hs view
@@ -1,6 +1,7 @@ 
 -- | This module is a re-export of the Base module.
---   You may find it shorter to import.
+--   You may find it shorter to import. Below you can
+--   also find a short overview of HaTeX.
 --
 --   Historically, this module also exported the Packages
 --   module. But, since it's more common to import the Base
@@ -11,8 +12,91 @@ --   For this reason, the module @Text.LaTeX.Packages@ no longer
 --   exists.
 module Text.LaTeX
- ( -- * Base module
+ ( -- * Base module re-export
    module Text.LaTeX.Base
+   -- * An overview of HaTeX
+
+   -- $ove
+
+   -- ** The @LaTeX@ type
+
+   -- $type
+
+   -- ** Rendering LaTeX code
+
+   -- $rnd
+
+   -- ** Using more features
+
+   -- $pkgs
+
+   -- ** More from HaTeX
+
+   -- $bey
+
+   -- ** Using monads
+
+   -- $wrt
+
+   -- ** Examples
+
+   -- $exm
    ) where
 
 import Text.LaTeX.Base
+
+-- $ove
+-- HaTeX is a library that implements the LaTeX syntax for both rendering and parsing.
+
+{- $type
+The core type is called 'LaTeX'. Values of this type are always a syntactically correct
+piece of LaTeX code, which we call a LaTeX /block/. To append blocks, we use the 'Monoid'
+class. Thus, the operator '<>' appends blocks. To generate blocks, we use functions.
+Basic functions are defined in the "Text.LaTeX.Base.Commands" module. Roughly speaking,
+it contains functions to generate blocks containing LaTeX commands and environments that
+are always defined. In the other hand, 'LaTeX' is an instance of the 'IsString' class.
+This allow us to insert LaTeX code containing simple text by just writing it as a 'String'
+and enabling the @OverlaodedStrings@ language extension.
+-}
+
+{- $rnd
+Once you have a 'LaTeX' block built, the function 'render' will turn it into 'Text'. If
+your intention is to write the output in a file, use 'renderFile' to write the LaTeX
+code output directly into that file.
+-}
+
+{- $pkgs
+Apart from the core commands and environments, HaTeX offers more functions to generate LaTeX
+blocks containing more exotic things. These functions are categorized by LaTeX packages. For example,
+those commands and environments that come from the LaTeX @babel@ package are under the module
+"Text.LaTeX.Packages.Babel", and those that come from the @graphicx@ package are under "Text.LaTeX.Packages.Graphicx".
+Import each package individually to use them.
+This way, is easier to guess where to look for a particular function, and easier to detect
+if a particular feature is missing.
+-}
+
+{- $bey
+Beyond the implementation of existing LaTeX packages,
+HaTeX also provides some useful functions to build LaTeX code blocks from Haskell values.
+The Texy class allows you to pretty-print Haskell values to LaTeX blocks. This includes numbers, matrices,
+vectors or trees. HaTeX also features some modules dedicated to the generation of TikZ scripts
+(see "Text.LaTeX.Packages.TikZ.Simple").
+Everything you need to generate LaTeX code using Haskell should be included in this library.
+If some feature is missing, the GitHub issue list is waiting for you <https://github.com/Daniel-Diaz/HaTeX/issues>.
+-}
+
+{- $wrt
+LaTeX blocks can also be managed by the 'LaTeXT' monad transformer. Similar to the 'WriterT' monad,
+it stores and append values from a 'Monoid', in this case, the 'Monoid' of the 'LaTeX' values.
+Both interfaces are fused into one under the 'LaTeXC' class, the class of LaTeX blocks.
+Particular documentation of each feature can be found in the corresponding module.
+Further explanation of the library and its concepts can be found in the /HaTeX User's Guide/
+(<http://daniel-diaz.github.com/projects/hatex/HaTeX-Guide.pdf>).
+-}
+
+{- $exm
+Some examples can be found in the source code, under the /Examples/ directory. In particular, the example
+contained in the file @simple.hs@ is intended to be read by new users of the library.
+If you have any question regarding one of the examples, there is something you want to ask about
+HaTeX, or for anything you would like to discuss, we have a mailing list at <http://projects.haskell.org/cgi-bin/mailman/listinfo/hatex>.
+-}
Text/LaTeX/Base/Class.hs view
@@ -66,7 +66,7 @@ comm0 :: LaTeXC l => String -> l
 comm0 str = fromLaTeX $ TeXComm str []
 
--- | Like 'comm0' but using 'commS', i.e. no \"{}\" will be inserted to protect
+-- | Like 'comm0' but using 'TeXCommS', i.e. no \"{}\" will be inserted to protect
 -- the command's end.
 --
 -- > commS = fromLaTeX . TeXCommS
@@ -79,4 +79,4 @@ -- > braces = liftL TeXBraces
 --
 braces :: LaTeXC l => l -> l
-braces = liftL TeXBraces+braces = liftL TeXBraces
Text/LaTeX/Base/Commands.hs view
@@ -253,7 +253,8 @@ author = liftL $ \t -> TeXComm "author" [FixArg t]  -- | Set either an institute or an organization--- for the document.+-- for the document. It does /not/ work for+-- a document of the 'article' class. institute :: LaTeXC l => Maybe l -> l -> l institute  Nothing = liftL $ \l -> TeXComm "institute" [FixArg l] institute (Just s) = liftL2 (\l1 l2 -> TeXComm "institute" [OptArg l1,FixArg l2]) s
Text/LaTeX/Packages/Beamer.hs view
@@ -95,38 +95,39 @@ --TODO: Add a short description of each theme.
 
 -- | A 'Theme' of a presentation. See 'usetheme'.
-data Theme =
-   AnnArbor
- | Antibes
- | Bergen
- | Berkeley
- | Berlin
- | Boadilla
- | Boxes
- | CambridgeUS
- | Copenhagen
- | Darmstadt
- | Default
- | Dresden
- | Frankfurt
- | Goettingen
- | Hannover
- | Ilmenau
- | JuanLesPins
- | Luebeck
- | Madrid
- | Malmoe
- | Marburg
- | Montpellier
- | PaloAlto
- | Pittsburgh
- | Rochester
- | Singapore
- | Szeged
- | Warsaw
-   --
- | CustomTheme String
-  deriving Show
+data Theme = 
+    AnnArbor -- ^ <<http://daniel-diaz.github.io/projects/hatex/beamer/previewAnnArbor.png>>
+  | Antibes -- ^ <<http://daniel-diaz.github.io/projects/hatex/beamer/previewAntibes.png>>
+  | Bergen -- ^ <<http://daniel-diaz.github.io/projects/hatex/beamer/previewBergen.png>>
+  | Berkeley -- ^ <<http://daniel-diaz.github.io/projects/hatex/beamer/previewBerkeley.png>>
+  | Berlin -- ^ <<http://daniel-diaz.github.io/projects/hatex/beamer/previewBerlin.png>>
+  | Boadilla -- ^ <<http://daniel-diaz.github.io/projects/hatex/beamer/previewBoadilla.png>>
+  | CambridgeUS -- ^ <<http://daniel-diaz.github.io/projects/hatex/beamer/previewCambridgeUS.png>>
+  | Copenhagen -- ^ <<http://daniel-diaz.github.io/projects/hatex/beamer/previewCopenhagen.png>>
+  | Darmstadt -- ^ <<http://daniel-diaz.github.io/projects/hatex/beamer/previewDarmstadt.png>>
+  | Dresden -- ^ <<http://daniel-diaz.github.io/projects/hatex/beamer/previewDresden.png>>
+  | Frankfurt -- ^ <<http://daniel-diaz.github.io/projects/hatex/beamer/previewFrankfurt.png>>
+  | Goettingen -- ^ <<http://daniel-diaz.github.io/projects/hatex/beamer/previewGoettingen.png>>
+  | Hannover -- ^ <<http://daniel-diaz.github.io/projects/hatex/beamer/previewHannover.png>>
+  | Ilmenau -- ^ <<http://daniel-diaz.github.io/projects/hatex/beamer/previewIlmenau.png>>
+  | JuanLesPins -- ^ <<http://daniel-diaz.github.io/projects/hatex/beamer/previewJuanLesPins.png>>
+  | Luebeck -- ^ <<http://daniel-diaz.github.io/projects/hatex/beamer/previewLuebeck.png>>
+  | Madrid -- ^ <<http://daniel-diaz.github.io/projects/hatex/beamer/previewMadrid.png>>
+  | Malmoe -- ^ <<http://daniel-diaz.github.io/projects/hatex/beamer/previewMalmoe.png>>
+  | Marburg -- ^ <<http://daniel-diaz.github.io/projects/hatex/beamer/previewMarburg.png>>
+  | Montpellier -- ^ <<http://daniel-diaz.github.io/projects/hatex/beamer/previewMontpellier.png>>
+  | PaloAlto -- ^ <<http://daniel-diaz.github.io/projects/hatex/beamer/previewPaloAlto.png>>
+  | Pittsburgh -- ^ <<http://daniel-diaz.github.io/projects/hatex/beamer/previewPittsburgh.png>>
+  | Rochester -- ^ <<http://daniel-diaz.github.io/projects/hatex/beamer/previewRochester.png>>
+  | Singapore -- ^ <<http://daniel-diaz.github.io/projects/hatex/beamer/previewSingapore.png>>
+  | Szeged -- ^ <<http://daniel-diaz.github.io/projects/hatex/beamer/previewSzeged.png>>
+  | Warsaw -- ^ <<http://daniel-diaz.github.io/projects/hatex/beamer/previewWarsaw.png>>
+    --
+  | Boxes
+  | Default
+    --
+  | CustomTheme String
+    deriving Show
 
 instance Render Theme where
  render (CustomTheme str) = fromString str
Text/LaTeX/Packages/Graphicx.hs view
@@ -1,8 +1,10 @@ 
 {-# LANGUAGE OverloadedStrings #-}
 
--- | This module allows you to use the LaTeX graphicx library in order to
---   insert graphics in a document.
+-- | This module allows you to use the LaTeX /graphicx/ library in order to
+--   insert graphics in a document and perform some transformations.
+--
+--   CTAN page for graphicx: <http://ctan.org/pkg/graphicx>.
 module Text.LaTeX.Packages.Graphicx
  ( -- * Graphicx package
    graphicx
@@ -35,6 +37,7 @@ 
 -- Package options
 
+-- | Package option of the 'graphicx' package.
 dvips, dvipdfm, pdftex :: LaTeXC l => l
 dvips = "dvips"
 dvipdfm = "dvipdfm"
@@ -75,9 +78,12 @@ includegraphics opts fp = fromLaTeX $ TeXComm "includegraphics"
  [ MOptArg $ fmap rendertex opts , FixArg $ TeXRaw $ fromString fp ]
 
+-- | Rotate the content by the given angle in degrees.
 rotatebox :: LaTeXC l => Float -> l -> l
 rotatebox a = liftL $ \l -> TeXComm "rotatebox" [FixArg $ rendertex a , FixArg l]
 
+-- | Scale the content by the given factor. If only the horizontal scale is supplied,
+--   the vertical scaling will be the same.
 scalebox :: LaTeXC l =>
      Float       -- ^ Horizontal scale.
   -> Maybe Float -- ^ Vertical scale.
@@ -88,13 +94,15 @@                      ++  maybe [] ((:[]) . OptArg . rendertex) mv
                      ++ [FixArg l]
 
+-- | Reflect horizontally the content.
 reflectbox :: LaTeXC l => l -> l
 reflectbox = liftL $ \l -> TeXComm "reflectbox" [FixArg l]
 
+-- | Resize the content to match the given dimensions.
 resizebox :: LaTeXC l =>
      Measure -- ^ Horizontal size.
   -> Measure -- ^ Vertical size.
   -> l
   -> l
 resizebox h v = liftL $ \l ->
-  TeXComm "resizebox" [FixArg $ rendertex h,FixArg $ rendertex v,FixArg l]+  TeXComm "resizebox" [FixArg $ rendertex h,FixArg $ rendertex v,FixArg l]