Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

A Scholarly Markdown

scholarlymarkdown.com

Post reply on HN
Print view View original

11–20 of 97 posts

Re: A Scholarly Markdown

#11

Post by aaren »

kazagistar wrote: post #9
_-_-_-_ wrote: post #5

I'm still skimming the documentation so I apologize if the answer is obvious, but does anyone know offhand why this is implemented as a fork of Pandoc? Pandoc already has extended markdown features and the creator of pandoc is very much an academic ( http://johnmacfarlane.net/ ), so is there are a reason why these contributions aren't part of pandoc proper?

This was my first thought as well. Pandoc has a rather excellent infrastructure in place to let you extend and build on it, so if you instead choose to fork, there better be a good reason...

Pandoc filters let you do a lot of things provided you stick to the defined types. If you want to add new types of element, like this does, then the only practical way is a fork.

(except for really simple cases)

Re: A Scholarly Markdown

#12

Post by ivansavz »

A similar effort of introducing math/figures/refs into markdown is the `softcover markdown` syntax. It's basically markdown, with latex commands allowed:

https://raw.githubusercontent.com/softcover/softcover_book/m...

The beautiful idea in markdown is that it allows you to mix (non-container) HTML tags in with the .md and it just works. Softcover markdown is in the same vein, allowing the more readable markdown for main copy, and intermix LaTeX tags as required. Beautiful if you ask me. Or at least beautifuler than ```math ... ```math.

The "backward compatibility" of ScholarlyMarkdown with basic markdown is a cool feature as many tools/plarforms exist that "support" .md now, but to preview you'll still need something that renders the equations, so strictly speaking ScholarlyMarkdown is a new markup langauge.

Re: A Scholarly Markdown

#13

Post by aaren »

_-_-_-_ wrote: post #5

I'm still skimming the documentation so I apologize if the answer is obvious, but does anyone know offhand why this is implemented as a fork of Pandoc? Pandoc already has extended markdown features and the creator of pandoc is very much an academic ( http://johnmacfarlane.net/ ), so is there are a reason why these contributions aren't part of pandoc proper?

This is a fork because making these changes to pandoc itself needs a lot of consideration.

Internal referencing and attributes on figures are two things that are currently being discussed for pandoc. The discussion has been going on for quite a while though - hence people making forks.

Discussion on internal referencing: https://github.com/jgm/pandoc/issues/813

Discussion on image attributes: https://github.com/jgm/pandoc/issues/261

Re: A Scholarly Markdown

#14

Post by dllu »

I created a similar thing for my personal website:

http://www.dllu.net/programming/dllup/

which handles math using svgtex instead of clientside MathJax for faster rendering. It also compiles to both html5 and LaTeX. However, dllup is overall less polished, missing some features (labelling equations, sections).

Re: A Scholarly Markdown

#15

Post by samatman »

Interesting to see this come up. I've been migrating a couple projects to babel, the emacs org-mode literate programming style. Starting with the hello-world of babel, my emacs config file.

Babel and Org have clunky syntax but the mode takes care of that. The combination isn't perfect but it's very powerful, in particular the ability to chain several languages together in flexible ways.

Coming up with more ways to combine pretty formatting with syntax highlighting is polishing a pretty smooth surface. I'm dreaming of a really slick syntax and operating environment, like babel if it wasn't tacked onto org. In the meantime, using what we have.

Re: A Scholarly Markdown

#16

Post by rhythmvs »

John MacFarlane (Pandoc’s author) is heavily committed to the Common Mark standardization effort of Markdown (in fact he’s the principal designer of the Common Mark spec).

Both Common Mark and Pandoc serve different purposes: the first is an initiative to counter fragmentation/balkanization of the Markdown ecosystem and in being so has to reckon with backward compatibility, consensus and adoption. The latter is a document conversion library, which, by design, needs to reckon with interchangeability between formats and may hence be hampered by the lowest common denominator as regards feature support. Internally, Pandoc keeps an Abstract Syntax Tree (accessible in json format), and defaults on its own flavour of Pandoc Markdown (featuring a Markdown superset of content element types).

Both the Common Mark community and John MacFarlane have made it clear their first and foremost focus is on standardization, not so much on extending the feature set. Yet, scholars and technical writers are in dire need for something more heavy-weight than the rather small set of features offered by Common Mark implementations or Pandoc Markdown. Hence the Scholarly Markdown initiative and the scholdoc reference implementation (Pandoc fork).

More on how Scholarly Markdown came about, can be read on the blog of one of it’s pacemakers, Martin Fenner; e.g. http://blog.martinfenner.org/2013/11/17/the-grammar-of-schol..., http://blogs.plos.org/mfenner/2012/12/18/additional-markdown...

Re: A Scholarly Markdown

#17

Post by droque »

JetSpiegel wrote: post #4

Why? This really feels like cramming a square peg into a round hole. Anytime anyone wants something more complex than simply lightly formatted text they will have to use other tool (LaTeX), so why not just use LaTeX in the first place?

The way I see it, the main feature is being able to plug math formulas in, rather than formatting documents. It allows you to focus on your content (one feature of Markdown) while still being able to write mathematics.

Re: A Scholarly Markdown

#18

Post by xiaq »

If you want to write scientific documents with markdown, beware that pandoc already supports inline TeX (math with $$ and TeX commands starting with \) when doing md -> latex conversion. That has been my setup for quite some time.

Re: A Scholarly Markdown

#19

Post by _-_-_-_ »

aaren wrote: post #13
_-_-_-_ wrote: post #5

I'm still skimming the documentation so I apologize if the answer is obvious, but does anyone know offhand why this is implemented as a fork of Pandoc? Pandoc already has extended markdown features and the creator of pandoc is very much an academic ( http://johnmacfarlane.net/ ), so is there are a reason why these contributions aren't part of pandoc proper?

This is a fork because making these changes to pandoc itself needs a lot of consideration. Internal referencing and attributes on figures are two things that are currently being discussed for pandoc. The discussion has been going on for quite a while though - hence people making forks. Discussion on internal referencing: https://github.com/jgm/pandoc/issues/813 Discussion on image attributes: https://github.com/jgm/p…

Thank you for the information.

This raises a couple more questions for me.

First, when searching I was able to find Martin Fenner's very interesting blog posts about ideas for a "Scholarly Markdown" and, as those issues and the first link on the scholarlymarkdown.com site reference, he appears to be associated with a separate "scholmd" project, also called "Scholarly Markdown," which is apparently a related project that itself is a fork of the Python markdown science project:

scholmd:

http://scholmd.org/

https://github.com/scholmd

Markdown Science:

https://github.com/karthik/markdown_science

However, it's unclear what all of the relationships are between all of these projects and forks.

Secondly, since some (or all?) of the changes are being discussed in the Pandoc issue tracker, are these changes intended to be submitted to Pandoc in pull requests? I don't currently see any.

Re: A Scholarly Markdown

#20

Post by aaren »

_-_-_-_ wrote: post #19
aaren wrote: post #13

Earlier quoted context omitted.

This is a fork because making these changes to pandoc itself needs a lot of consideration. Internal referencing and attributes on figures are two things that are currently being discussed for pandoc. The discussion has been going on for quite a while though - hence people making forks. Discussion on internal referencing: https://github.com/jgm/pandoc/issues/813 Discussion on image attributes: https://github.com/jgm/p…

Thank you for the information. This raises a couple more questions for me. First, when searching I was able to find Martin Fenner's very interesting blog posts about ideas for a "Scholarly Markdown" and, as those issues and the first link on the scholarlymarkdown.com site reference, he appears to be associated with a separate "scholmd" project, also called "Scholarly Markdown," which is apparently a related project t…

First: I'm not sure of the exact origins of things. The way I see it, academic markdown is more of an ecosystem of tools with a lot of overlap. There is no one single markdown workflow right now when you want to do do academic writing. I think this is because no one is sure what the final spec should look like and people are trying things out and seeing what sticks. I feel that there has been some convergence in the last 2/3 years though.

Second: The PR for image attributes is here: https://github.com/jgm/pandoc/pull/1806

There isn't a PR for internal referencing yet because the implementation hasn't been worked out yet and it isn't a simple change (should there be a native representation, should it be a filter, which syntax should we use, what about the existing citation syntax...).

Post reply on HN