Summer of Pandoc Figures

[tarleb]

This is an issue specifically for the "Figures" GSoC project. It is, at its core, a duplicate of #3177, but adds "summer of code" specific info. It can serve as a central starting point.

For reference:

• Project idea
• Main issue

FAQ

• What's a good way to start? Pandoc is built around a central data structure for documents, called the Pandoc type. All documents that pandoc processes flow through these types. The definitions are available in the separate pandoc-types repository. A basic understanding of these, esp. the Text.Pandoc.Definitions module, can be a good way to see what this is all about, and why this project is needed at all.

• Did someone work on this already? There is an existing PR by Christian Despres. It can be used as a starting point. There has been no work yet on pandoc readers or writers.

• Is this beginner friendly? People can mean very different things when they say beginner, so this is difficult to answer. As a data point, I'll note that the overwhelming majority of pandoc contributors had some programming experience, but had never used Haskell for anything serious before, if at all. Also, there are mentors to help you. If you read the points here and think "that sounds interesting and I'd like to learn that", then you probably know enough.

• What should I look out for? Design is often iterative, and it's a good idea to plan for that. Do something, see how it affects other parts of the project, ask for opinions, repeat. Haskell makes refactoring easy, so let's make use of that.

• The issue mentions a new Markdown syntax. Will I have to choose one, and isn't that hard? Yes and no. The syntax problem is mostly orthogonal to this project. It would be nice to find some method for users to use the feature from Markdown, but it could be based on existing syntax. Think, e.g., "image in a fenced div following special conventions". That allows to use a filter to do the conversion, which is much easier than modifying the parser. As a proof of concept, it doesn't have to be perfect. (Of course, if you enjoy the idea of extending Markdown syntax, then feel free to give it higher priority in the proposal.)

• Any Haskell topics worth checking out? The PatternSynonyms language extension could be useful.

• How about non-Haskell topics? Maybe read about the MDN page on figure elements and check how other formats handle figures. Apart from that, it would certainly be helpful to know at least a little about R Markdown: scientists will likely be one of the main groups who would benefit from better figure support.

• I'd like to get started with a "good first issue". That's great! Best to ask on the mailing list for hints if you want to go that route. "Good first issue" doesn't necessarily imply "quick and easy", although some issues certainly are.

• Is it okay if I also apply to other projects? Absolutely. Haskell projects are not quite as competitive as those of many other organizations, but applying to multiple projects can increase your chances regardless.

• Shouldn't this issue be a wiki entry instead? Well, maybe.

• I have more questions!? Please feel free to reach out and ask!

People

@tarleb @apreshill @cderv

[tarleb]

We finished this one successfully 🎉