Rendering bibliography in Markdown

[BilalM04]

While trying to render a bibliography in Markdown, I noticed it is extremely similar to the HTML render, apart from a couple minor discrepancies. The two differences I spotted are:

1. Italicized text is wrapped in <em> in HTML, but should be * in Markdown.
2. How references are rendered are different.

HTML rendered code:

[8]: Wikipedia Contributors. <em>Cartesian coordinate system</em>. June, 2019. <a href="https://en.wikipedia.org/wiki/Cartesian_coordinate_system">https://en.wikipedia.org/wiki/Cartesian_coordinate_system</a>.

What the Markdown should be rendered as:

[8]: Wikipedia Contributors. *Cartesian coordinate system*. June, 2019. <https://en.wikipedia.org/wiki/Cartesian_coordinate_system>.

---

The only modifications required in the HTML code to render as Markdown, are the following:

1. Replace the em function with a markdown specific one
2. Replace the pSpec functions calls with a markdown specific one

For example, here:

Drasil/code/drasil-printers/lib/Language/Drasil/HTML/Print.hs

Lines 426 to 456 in 85cf74d

	-- | Cite books in MLA format.
	bookMLA :: CiteField -> Doc
	bookMLA (Address s) = pSpec s <> text ":"
	bookMLA (Edition s) = comm $ text $ show s ++ sufxer s ++ " ed."
	bookMLA (Series s) = dot $ em $ pSpec s
	bookMLA (Title s) = dot $ em $ pSpec s --If there is a series or collection, this should be in quotes, not italics
	bookMLA (Volume s) = comm $ text $ "vol. " ++ show s
	bookMLA (Publisher s) = comm $ pSpec s
	bookMLA (Author p) = dot $ pSpec (rendPeople' p)
	bookMLA (Year y) = dot $ text $ show y
	--bookMLA (Date d m y) = dot $ unwords [show d, show m, show y]
	--bookMLA (URLdate d m y) = "Web. " ++ bookMLA (Date d m y) sm
	bookMLA (BookTitle s) = dot $ em $ pSpec s
	bookMLA (Journal s) = comm $ em $ pSpec s
	bookMLA (Pages [p]) = dot $ text $ "pg. " ++ show p
	bookMLA (Pages p) = dot $ text "pp. " <> foldPages p
	bookMLA (Note s) = pSpec s
	bookMLA (Number n) = comm $ text ("no. " ++ show n)
	bookMLA (School s) = comm $ pSpec s
	--bookMLA (Thesis t) = comm $ show t
	--bookMLA (URL s) = dot $ pSpec s
	bookMLA (HowPublished (Verb s)) = comm $ pSpec s
	bookMLA (HowPublished (URL l@(S s))) = dot $ pSpec $ Ref External s l
	bookMLA (HowPublished (URL s)) = dot $ pSpec s
	bookMLA (Editor p) = comm $ text "Edited by " <> foldPeople p
	bookMLA (Chapter _) = text ""
	bookMLA (Institution i) = comm $ pSpec i
	bookMLA (Organization i) = comm $ pSpec i
	bookMLA (Month m) = comm $ text $ show m
	bookMLA (Type t) = comm $ pSpec t

---

What is the best way to leverage the HTML bib renderer, while minimizing code duplication?

This is similar to the pExpr problem mentioned in a previous meeting, which is working now, but the code could definitely be improved (ongoingly looking into solutions). Right now, the functions for expression printing in markdown simply override the TeX functions if they are different, otherwise delegate to the TeX functions if they are the same. The problem with this is that differences in code may appear down a couple levels of functions, thus you must redefine all the functions in the hierarchy, even if they are identical. This is minimal with expression printing, but will be significant if done with bib rendering.

[balacij]

@JacquesCarette Bilal and I briefly spoke about this in person before deciding to move to here. Do you think a plate-based design for defining rendering functions would be helpful in solving these issues without needing to resort to more complicated recursion patterns? I only recently (briefly) read into it, but haven't practised it yet, so I can't confidently say anything about it.

[balacij]

Of course, another way to go about this one specifically is to switch to State-based renderers and to store a specific italicize function in the state to be used by the renderer.

[balacij]

There are a few ways, but a shiny new tool (plates) has caught my eye, haha.

[balacij]

I forgot about this. Another solution is to do something like the following:

1. Create a data type that carries all the functions needed for rendering general in-paragraph text:

data Typewriter = Typewriter {
  s :: Doc -> Doc, -- this one for plain strings (i.e., this one needs to be responsible for escaping special characters)
  ital :: Doc -> Doc,
  bold :: Doc -> Doc,
  italBold :: Doc -> Doc,
  underscore :: Doc -> Doc
}

2. Create an instance of the Typewriter for both flavours

mdTypewriter :: Typewriter
mdTypewriter = Typewriter { ... }

htmlTypewriter :: Typewriter
htmlTypewriter = Typewriter { ... }

3. Add Typewriter as an argument to the existing bookMLA and pSpec and use the features of the typewriter instead of a hardcoded instance specialized to HTML/Markdown, then create something like the following:

mdBookMLA :: ...
mdBookMLA = bookMLA mdTypewriter

htmlBookMLA :: ...
htmlBookMLA = bookMLA htmlTypewriter

What do you think @BilalM04 ? I think the plate approach is unneeded. This is just as good.

[BilalM04]

I like this idea, I think it will work well for the bibliography. For expressions, I'm not too sure how I would implement this, as the differences are more fine grained and hidden. I'll have to test it out and see which is the best solution for expression printing. For the other elements, such as tables, definitions, headings, etc. there isn't much code reuse across the different formats, so I think this will be unnecessary. I will be creating a draft PR for my work with mdBook in the coming days to begin receiving feedback on my implementation. I'll try to implement some of these potential solutions. I think seeing the preliminary code will help to identify any problems and areas of improvement.

[balacij]

Great! It sounds like we can give this a go then? (Does that mean we can mark this discussion as "Answered"?)

Can you explain the issue with expressions a bit more, please? For that one, a multiplate might actually be the way to go if there is some reuse we can do (@JacquesCarette will have to confirm though).

That sounds like a great idea!

[JacquesCarette]

I prefer this particular option. Which, in fact, is basically a dictionary - so could be done via a typeclass!

And that typeclass could be small, as it could have as members only the things that are different and, for now, keep the rest as plain functions.

[balacij]

We might not have any 'good' candidates for instantiating the typeclass for, because we don't have any special types for Markdown or HTML (yet, hopefully). Right now, genTeX and genHTML have mostly the same type signature.

Drasil/code/drasil-printers/lib/Language/Drasil/HTML/Print.hs

Lines 46 to 48 in 85cf74d

	-- | Generate an HTML document from a Drasil 'Document'.
	genHTML :: PrintingInformation -> String -> L.Document -> Doc
	genHTML sm fn doc = build fn (makeDocument sm doc)

Drasil/code/drasil-printers/lib/Language/Drasil/TeX/Print.hs

Lines 42 to 46 in 85cf74d

	-- | Generates a LaTeX document.
	genTeX :: L.Document -> PrintingInformation -> TP.Doc
	genTeX doc@(L.Document _ _ toC _) sm =
	runPrint (buildStd sm toC $ I.makeDocument sm $ L.checkToC doc) Text
	genTeX L.Notebook{} _ = TP.empty

[JacquesCarette]

Might need to introduce a wrapper for the purposes of knowing more about the result.