Image attributes

README

@@ -378,12 +378,20 @@ General writer options
 `--print-default-data-file=`*FILE*
 :   Print a default data file.
 
+`--dpi`=*NUMBER*
+:   Specify the dpi (dots per inch) value for conversion from pixel
+    to inch/centimeters and vice versa. The default is 96dpi.
+    Technically, the correct term would be ppi (pixels per inch).
+
 `--no-wrap`
 :   Disable text wrapping in output. By default, text is wrapped
-    appropriately for the output format.
+    appropriately for the output format. Like the `--columns` option
+    below, this affects only the generated source, not the layout.
 
 `--columns`=*NUMBER*
 :   Specify length of lines in characters (for text wrapping).
+    For example in HTML output, this affects the generated source code,
+    not the visible line length when viewing the file in a web browser.
 
 `--toc`, `--table-of-contents`
 :   Include an automatically generated table of contents (or, in
@@ -2482,6 +2490,49 @@ nonbreaking space after the image:
 
     ![This image won't be a figure](/url/of/image.png)\
 
+#### Extension: `common_link_attributes` ####
+
+Attributes can be set on images:
+
+    An inline ![image](foo.jpg){#id .class width=30 height=20px}
+    and a reference ![image][ref] with attributes.
+
+    [ref]: foo.jpg "optional title" {#id .class key=val key2="val 2"}
+
+(This syntax is compatible with [PHP Markdown Extra] when only `#id`
+and `.class` are used.)
+
+For HTML and EPUB, all attributes except `width` and `height` (but including
+`srcset` and `sizes`) are passed through “as is”. The other writers ignore
+attributes that are not supported by their output format.
+
+The `width` and `height` attributes are treated specially. When used without
+a unit, the number’s unit is in pixels. However, one of the following unit
+identifiers can be used: `px`, `cm`, `in`, `inch` and `%` but there mustn’t
+be any spaces between the number and the unit, for example:
+
+```
+![](file.jpg){width=50%}
+```
+
+- Pixels are converted to inch for output in page-based formats like LaTeX
+  and cm. Inches are converted to pixels for output in HTML-like formats.
+  Use the `--dpi` option to specify the number of pixels per inch, the
+  default is 96dpi.
+- The `%` unit is generally relative to some available space.
+  For example the above example will render to
+  `<img href="file.jpg" style="width: 50%;" />` (HTML),
+  `\includegraphics[width=0.5\textwidth]{file.jpg}` (LaTeX), or
+  `\externalfigure[file.jpg][width=0.5\textwidth]` (ConTeXt).
+- Some output formats have a notion of a class
+  ([ConTeXt](http://wiki.contextgarden.net/Using_Graphics#Multiple_Image_Settings))
+  or a unique identifier (LaTeX `\caption`), or both (HTML).
+- When no `width` or `height` attributes are specified, the fallback is to look at
+  the image resolution and the dpi metadata embedded in the image file.
+
+Note that while attributes are also parsed on links, pandoc's internal document
+model provides nowhere to put them, so they are presently just ignored.
+
 
 Footnotes
 ---------
@@ -2730,9 +2781,15 @@ letters are omitted.
 
 #### Extension: `link_attributes` ####
 
-Parses multimarkdown style key-value attributes on link and image references.
-Note that pandoc's internal document model provides nowhere to put
-these, so they are presently just ignored.
+Parses multimarkdown style key-value attributes on link
+and image _references_. Note that while working for images, pandoc's
+internal document model provides nowhere to put these for links, so they
+are presently just ignored.
+
+    This is a reference ![image][ref] with multimarkdown attributes.
+
+    [ref]: http://path.to/image "Image title" width=20px height=30px
+           id=myId class="myClass1 myClass2"
 
 #### Extension: `mmd_header_identifiers` ####
 
@@ -2775,7 +2832,7 @@ variants are supported:
 `markdown_phpextra` (PHP Markdown Extra)
 :   `footnotes`, `pipe_tables`, `raw_html`, `markdown_attribute`,
     `fenced_code_blocks`, `definition_lists`, `intraword_underscores`,
-    `header_attributes`, `abbreviations`.
+    `header_attributes`, `common_link_attributes`, `abbreviations`.
 
 `markdown_github` (Github-flavored Markdown)
 :   `pipe_tables`, `raw_html`, `tex_math_single_backslash`,

pandoc.cabal

@@ -230,7 +230,7 @@ Library
                  xml >= 1.3.12 && < 1.4,
                  random >= 1 && < 1.2,
                  extensible-exceptions >= 0.1 && < 0.2,
-                 pandoc-types >= 1.12.4 && < 1.13,
+                 pandoc-types >= 1.13 && < 1.14,
                  aeson >= 0.7 && < 0.9,
                  tagsoup >= 0.13.1 && < 0.14,
                  base64-bytestring >= 0.1 && < 1.1,
@@ -347,7 +347,7 @@ Library
 
 Executable pandoc
   Build-Depends: pandoc,
-                 pandoc-types >= 1.12.4 && < 1.13,
+                 pandoc-types >= 1.13 && < 1.14,
                  base >= 4.2 && <5,
                  directory >= 1 && < 1.3,
                  filepath >= 1.1 && < 1.4,

pandoc.hs

@@ -187,6 +187,7 @@ data Opt = Opt
     , optDumpArgs          :: Bool    -- ^ Output command-line arguments
     , optIgnoreArgs        :: Bool    -- ^ Ignore command-line arguments
     , optReferenceLinks    :: Bool    -- ^ Use reference links in writing markdown, rst
+    , optDpi               :: Double  -- ^ Dpi
     , optWrapText          :: Bool    -- ^ Wrap text
     , optColumns           :: Int     -- ^ Line length in characters
     , optFilters           :: [FilePath] -- ^ Filters to apply
@@ -247,6 +248,7 @@ defaultOpts = Opt
     , optDumpArgs              = False
     , optIgnoreArgs            = False
     , optReferenceLinks        = False
+    , optDpi                   = 96
     , optWrapText              = True
     , optColumns               = 72
     , optFilters               = []
@@ -442,6 +444,16 @@ options =
                   "FILE")
                   "" -- "Print default data file"
 
+    , Option "" ["dpi"]
+                 (ReqArg
+                  (\arg opt ->
+                    case safeRead arg of
+                         Just t | t > 0 -> return opt { optDpi = t }
+                         _              -> err 31
+                                        "dpi must be a number greater than 0")
+                  "NUMBER")
+                 "" -- "Dpi (default 96)"
+
     , Option "" ["no-wrap"]
                  (NoArg
                   (\opt -> return opt { optWrapText = False }))
@@ -988,8 +1000,8 @@ extractMedia media dir d =
           return $ walk (adjustImagePath dir fps) d
 
 adjustImagePath :: FilePath -> [FilePath] -> Inline -> Inline
-adjustImagePath dir paths (Image lab (src, tit))
-   | src `elem` paths = Image lab (dir ++ "/" ++ src, tit)
+adjustImagePath dir paths (Image attr lab (src, tit))
+   | src `elem` paths = Image attr lab (dir ++ "/" ++ src, tit)
 adjustImagePath _ _ x = x
 
 adjustMetadata :: M.Map String MetaValue -> Pandoc -> IO Pandoc
@@ -1062,6 +1074,7 @@ main = do
               , optDumpArgs              = dumpArgs
               , optIgnoreArgs            = ignoreArgs
               , optReferenceLinks        = referenceLinks
+              , optDpi                   = dpi
               , optWrapText              = wrap
               , optColumns               = columns
               , optFilters               = filters
@@ -1279,6 +1292,7 @@ main = do
                             writerNumberOffset     = numberFrom,
                             writerSectionDivs      = sectionDivs,
                             writerReferenceLinks   = referenceLinks,
+                            writerDpi              = dpi,
                             writerWrapText         = wrap,
                             writerColumns          = columns,
                             writerEmailObfuscation = obfuscationMethod,

src/Text/Pandoc.hs

@@ -260,7 +260,7 @@ writers = [
   ,("html"         , PureStringWriter writeHtmlString)
   ,("html5"        , PureStringWriter $ \o ->
      writeHtmlString o{ writerHtml5 = True })
-  ,("icml"         , PureStringWriter writeICML)
+  ,("icml"         , IOStringWriter writeICML)
   ,("s5"           , PureStringWriter $ \o ->
      writeHtmlString o{ writerSlideVariant = S5Slides
                       , writerTableOfContents = False })