@@ -273,18 +273,22 @@ setRequestHeader name val = modifyCommonState $ \st ->
273273setMediaBag :: PandocMonad m => MediaBag -> m ()
274274setMediaBag mb = modifyCommonState $ \st -> st{stMediaBag = mb}
275275
276+-- Retrieve the media bag.
276277getMediaBag :: PandocMonad m => m MediaBag
277278getMediaBag = getsCommonState stMediaBag
278279
280+-- Insert an item into the media bag.
279281insertMedia :: PandocMonad m => FilePath -> Maybe MimeType -> BL.ByteString -> m ()
280282insertMedia fp mime bs = do
281283 mb <- getMediaBag
282284 let mb' = MB.insertMedia fp mime bs mb
283285 setMediaBag mb'
284286
287+-- Retrieve the input filenames.
285288getInputFiles :: PandocMonad m => m [FilePath]
286289getInputFiles = getsCommonState stInputFiles
287290
291+-- Set the input filenames.
288292setInputFiles :: PandocMonad m => [FilePath] -> m ()
289293setInputFiles fs = do
290294 let sourceURL = case fs of
@@ -299,21 +303,27 @@ setInputFiles fs = do
299303 modifyCommonState $ \st -> st{ stInputFiles = fs
300304 , stSourceURL = sourceURL }
301305
306+-- Retrieve the output filename.
302307getOutputFile :: PandocMonad m => m (Maybe FilePath)
303308getOutputFile = getsCommonState stOutputFile
304309
310+-- Set the output filename.
305311setOutputFile :: PandocMonad m => Maybe FilePath -> m ()
306312setOutputFile mbf = modifyCommonState $ \st -> st{ stOutputFile = mbf }
307313
308−setResourcePath :: PandocMonad m => [FilePath] -> m ()
309−setResourcePath ps = modifyCommonState $ \st -> st{stResourcePath = ps}
310−
314+-- Retrieve the resource path searched by 'fetchItem'.
311315getResourcePath :: PandocMonad m => m [FilePath]
312316getResourcePath = getsCommonState stResourcePath
313317
318+-- Set the resource path searched by 'fetchItem'.
319+setResourcePath :: PandocMonad m => [FilePath] -> m ()
320+setResourcePath ps = modifyCommonState $ \st -> st{stResourcePath = ps}
321+
322+-- Get the POSIX time.
314323getPOSIXTime :: PandocMonad m => m POSIXTime
315324getPOSIXTime = utcTimeToPOSIXSeconds <$> getCurrentTime
316325
326+-- Get the zoned time.
317327getZonedTime :: PandocMonad m => m ZonedTime
318328getZonedTime = do
319329 t <- getCurrentTime
@@ -445,6 +455,8 @@ translateTerm term = do
445455runIO :: PandocIO a -> IO (Either PandocError a)
446456runIO ma = flip evalStateT def $ runExceptT $ unPandocIO ma
447457
458+-- | Evaluate a 'PandocIO' operation, handling any errors
459+-- by exiting with an appropriate message and error status.
448460runIOorExplode :: PandocIO a -> IO a
449461runIOorExplode ma = runIO ma >>= handleError
450462
@@ -457,6 +469,7 @@ newtype PandocIO a = PandocIO {
457469 , MonadError PandocError
458470 )
459471
472+-- | Utility function to lift IO errors into 'PandocError's.
460473liftIOError :: (String -> IO a) -> String -> PandocIO a
461474liftIOError f u = do
462475 res <- liftIO $ tryIOError $ f u
@@ -600,6 +613,7 @@ downloadOrRead s = do
600613 convertSlash '\\' = '/'
601614 convertSlash x = x
602615
616+-- Retrieve default reference.docx.
603617getDefaultReferenceDocx :: PandocMonad m => m Archive
604618getDefaultReferenceDocx = do
605619 let paths = ["[Content_Types].xml",
@@ -634,6 +648,7 @@ getDefaultReferenceDocx = do
634648 Nothing -> foldr addEntryToArchive emptyArchive <$>
635649 mapM pathToEntry paths
636650
651+-- Retrieve default reference.odt.
637652getDefaultReferenceODT :: PandocMonad m => m Archive
638653getDefaultReferenceODT = do
639654 let paths = ["mimetype",
@@ -760,6 +775,7 @@ extractMedia dir d = do
760775 mapM_ (writeMedia dir media) fps
761776 return $ walk (adjustImagePath dir fps) d
762777
778+-- Write the contents of a media bag to a path.
763779writeMedia :: FilePath -> MediaBag -> FilePath -> PandocIO ()
764780writeMedia dir mediabag subpath = do
765781 -- we join and split to convert a/b/c to a\b\c on Windows;
@@ -778,6 +794,8 @@ adjustImagePath dir paths (Image attr lab (src, tit))
778794 | src `elem` paths = Image attr lab (dir ++ "/" ++ src, tit)
779795adjustImagePath _ _ x = x
780796
797+-- | The 'PureState' contains ersatz representations
798+-- of things that would normally be obtained through IO.
781799data PureState = PureState { stStdGen :: StdGen
782800 , stWord8Store :: [Word8] -- should be
783801 -- inifinite,
@@ -863,6 +881,7 @@ newtype PandocPure a = PandocPure {
863881 , MonadError PandocError
864882 )
865883
884+-- Run a 'PandocPure' operation.
866885runPure :: PandocPure a -> Either PandocError a
867886runPure x = flip evalState def $
868887 flip evalStateT def $