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

81–90 of 97 posts

Re: A Scholarly Markdown

#81

Post by asgard1024 »

lorddoig wrote: post #25

And for everything else, there's AsciiDoc.[0] For an extra five minutes learning you get a boatload (think container ship) more features[1] - it compiles to DocBook: a mature, actually standardised , highly structured format, and from that you get HTML, EPUB, PDF, slideshows, and man pages for free.[0] For math you get MathML, ASCIIMath, and LaTeX (along with a number of ways to render them.) It has a super nice synt…

Thanks, this is exactly what I was looking for. A simple syntax for documentation that is extensible with macros. I am glad AsciiDoc includes them, they are very useful.

Re: A Scholarly Markdown

#82

Post by sytse »

timtylin wrote: post #66
boundlessdreamz wrote: post #57

Earlier quoted context omitted.

Github does render asciidoc using asciidoctor. What is missing in that that is possible in Markdown?

Well, I did not realize Github has had AsciiDoctor integration for two years now (I've been doing most of my scientific work in GitLab during that time). I retract that comment and regret the error. Hopefully they add it to Github pages some time soon. To be honest, there was never really any conscious decision to pick Markdown over AsciiDoc. It was just serendipity that when I was looking to convert a bunch of my ex…

Just wanted to mention that GitLab supports asciidoc https://github.com/gitlabhq/gitlabhq/pull/7569

Re: A Scholarly Markdown

#84

Post by tjl »

fiddlosopher wrote: post #70
lorddoig wrote: post #25

And for everything else, there's AsciiDoc.[0] For an extra five minutes learning you get a boatload (think container ship) more features[1] - it compiles to DocBook: a mature, actually standardised , highly structured format, and from that you get HTML, EPUB, PDF, slideshows, and man pages for free.[0] For math you get MathML, ASCIIMath, and LaTeX (along with a number of ways to render them.) It has a super nice synt…

AsciiDoc is a nice project, but I think that pandoc's variant of Markdown has a lot of advantages over AsciiDoc for academic writing. Let's just compare support for math and citations, for example. Pandoc's citation support is output-format independent: you can write the citations, specify a CSL stylesheet and bibliography, and you'll get the same output in every format pandoc supports. In AsciiDoc, as I understand i…

Markdown (even this Scholarly Markdown) is a non-starter for me. It doesn't seem to support individual equation numbers for aligned equations. Plus, Scholarly Markdown oddly decided to put them at the beginning of the line rather than after. Why? The equation is more important than the number so it should be first. Plus, it's nice to have the numbers all aligned to the right margin.

You stated about the footnote support being a deal-breaker for many academics, the poor equation support is a deal-breaker for me. Most of what I write is full of equations, especially aligned equations. It's necessary to reference a specific equation that might be on a different page (or far above it on an HTML page).

It looks like Asciidoc has different ways of handling LaTeX equations for non-LaTeX output. It can render a PNG, it can use a Javascript solution, or it can output MathML.

Re: A Scholarly Markdown

#85

Post by tjl »

e12e wrote: post #60
boundlessdreamz wrote: post #58

Earlier quoted context omitted.

As @jauco said try Asciidoctor - http://asciidoctor.org/ In addition to default asciidoctor style, there are other themes available - http://themes.asciidoctor.org/preview/ (See bottom right for theme switcher). You can also take a look at Pro Git book styles - http://git-scm.com/book/en/v2 which was written in asciidoc - https://github.com/progit/progit2

Thank you so much for the pointer to the git-scm-book (in the context of asciidoc/pdf output etc). Sadly the pdf-version, isn't exactly well laid out. It suffers from similar issues that a lot of html-to-pdf-based tools (although I assume it's sgml-to-pdf in this case?) -- horrible breaks, and it also "feels" wrong wrt. some spacing/etc. Generally standard LaTeX will look (much) better than this without tweaking, IMN…

My supervisor has been writing a book (for many years now) and he has a heavily customized LaTeX style that actually works quite well for his book. He has a lot of special needs for formatting so none of the default styles really worked for him. It's actually a pretty well done dynamics textbook. I've been looking forward to the actual final published text.

Re: A Scholarly Markdown

#86

Post by e12e »

tjl wrote: post #85
e12e wrote: post #60

Earlier quoted context omitted.

Thank you so much for the pointer to the git-scm-book (in the context of asciidoc/pdf output etc). Sadly the pdf-version, isn't exactly well laid out. It suffers from similar issues that a lot of html-to-pdf-based tools (although I assume it's sgml-to-pdf in this case?) -- horrible breaks, and it also "feels" wrong wrt. some spacing/etc. Generally standard LaTeX will look (much) better than this without tweaking, IMN…

My supervisor has been writing a book (for many years now) and he has a heavily customized LaTeX style that actually works quite well for his book. He has a lot of special needs for formatting so none of the default styles really worked for him. It's actually a pretty well done dynamics textbook. I've been looking forward to the actual final published text.

You should ask him if he's considered publishing the styles under a Free/open license. Even if parts of it is very specialized, I'd surprised if it couldn't work as an interesting starting point for other projects.

Re: A Scholarly Markdown

#87

Post by timtylin »

tjl wrote: post #84
fiddlosopher wrote: post #70

Earlier quoted context omitted.

AsciiDoc is a nice project, but I think that pandoc's variant of Markdown has a lot of advantages over AsciiDoc for academic writing. Let's just compare support for math and citations, for example. Pandoc's citation support is output-format independent: you can write the citations, specify a CSL stylesheet and bibliography, and you'll get the same output in every format pandoc supports. In AsciiDoc, as I understand i…

Markdown (even this Scholarly Markdown) is a non-starter for me. It doesn't seem to support individual equation numbers for aligned equations. Plus, Scholarly Markdown oddly decided to put them at the beginning of the line rather than after. Why? The equation is more important than the number so it should be first. Plus, it's nice to have the numbers all aligned to the right margin. You stated about the footnote supp…

I really want to address the math support, because I work with a lot of mathematicians, and one of my main goals is to support most of the latex AMS math features we're used to (as much as MathJax can support outputting on the HTML side anyways), and of course that includes aligned equations. In fact one of the first things I did was to figure out how to support multiline equations.

Turns out, you just need to write consecutive expressions one after another. Put ampersands in all these consecutive expressions and ScholarlyMarkdown will turn it into one giant align environment. If there is no ampersands, it generates a gather environment instead.

I apologize for this not being in the documentation. After all, I estimate that it is only about 30% complete. It really is in a dismal state. I originally didn't expect much people to see the site until later this year when I plan to launch it. This will all be rectified eventually, promise!

Here is literally a large align-block example straight out of the thesis that I'm currently busy working on (instead of the documentation). You can inspect the Scholdoc-rendered LaTeX code to see that you can really do align blocks reliably with this syntax.

http://goo.gl/9lErxa

If you output to HTML, it will just turn this same align block into a MathJax-friendly format, and hand it off to MathJax for rendering. This is what it will look like:

http://jsfiddle.net/hzvwa139/3/

Where the equation numbering is place is entirely a non issue. Why? It's not being decided by ScholarlyMarkdown, but by MathJax. Go to the jsFiddle example above and change the line that reads

  TagSide: "left",
To now read

  TagSide: "right",
and you get it now on the left. Scholdoc simply put those default setting there for convenience; you're not tied to it at all.

Why put the number on the left side by default? Think of what happens when you have a long equation, and when you're trying to read it on a narrow screen such as a phone. If the number was on the right, it may very well be cut-off by the screen, forcing you to scroll around to find equations. Sometimes layout decisions that made sense for paper for centuries doesn't make sense for screens.

I should point out that Scholdoc is only using MathJax on the HTML side for consistency; there is no technical reason why it can't use another renderer that understands LaTeX, but so far MathJax is the only one that even comes close to supporting all standard AMS features. Note that MathJax itself does HTML/CSS, MathML, SVG, and PNG (via a node server) output, and is entirely user-configurable.

Re: A Scholarly Markdown

#88

Post by j2kun »

timtylin wrote: post #78
j2kun wrote: post #73

Earlier quoted context omitted.

In any case, my point is plain and simple: I collaborate in almost everything I do, and my collaborators are my primary concern when I choose a tool. If they use notepad and Dropbox, I need to make sure my tools don't conflict with that. There's no way in hell I would ask a collaborator to learn to use git or a new markup language just to work with me. I'd love a tool that works with this philosophy, and I feel certa…

As a thought exercise, assuming for simplicity that you can isolate the parts you're authoring, so that your changes only involve additions to other people's work: what kind of additional metainfo would you need for this workflow? All defined labels and macros? Available bib entries? What else?

I think it depends on how I'm viewing the file. If I'm just editing in SM and building the tex as usual, then I don't need anything extra. If I'm trying to convert to all sorts of other documents (which I haven't ever really done) then labels, theorem environments, one-line macros, and bib entries cover almost every tex-specific thing I use.

Here is an excerpt from a typical paper's macro section [1]. As you can see they're mostly one-liners to remove the need to keep typing textup and mathbb, simple mathoperator definitions and such.

[1]: http://pastebin.com/RL1gejEZ

Re: A Scholarly Markdown

#89

Post by tjl »

timtylin wrote: post #87
tjl wrote: post #84

Earlier quoted context omitted.

Markdown (even this Scholarly Markdown) is a non-starter for me. It doesn't seem to support individual equation numbers for aligned equations. Plus, Scholarly Markdown oddly decided to put them at the beginning of the line rather than after. Why? The equation is more important than the number so it should be first. Plus, it's nice to have the numbers all aligned to the right margin. You stated about the footnote supp…

I really want to address the math support, because I work with a lot of mathematicians, and one of my main goals is to support most of the latex AMS math features we're used to (as much as MathJax can support outputting on the HTML side anyways), and of course that includes aligned equations. In fact one of the first things I did was to figure out how to support multiline equations. Turns out, you just need to write…

I still think equation numbers on the left is a mistake. Ideally, for smaller screens it would split across multiple lines. Or, it could choose the positioning based on screen size.

For me, MathJax can't render my equations. I use some techniques to get a vector with an arrow on the bottom. Two commands I used all throughout my thesis are:

  \def \rV#1{\hbox{$#1$\kern-0.38em\lower0.85em\hbox{$\vec{}\,$}}\,}
and

  \def \Vec#1{\hbox{$#1$\kern-1.0em\lower0.4em\hbox{${\scriptstyle \rightarrow }$}}}
These won't work in MathJax (understandably).

Re: A Scholarly Markdown

#90

Post by tjl »

e12e wrote: post #86
tjl wrote: post #85

Earlier quoted context omitted.

My supervisor has been writing a book (for many years now) and he has a heavily customized LaTeX style that actually works quite well for his book. He has a lot of special needs for formatting so none of the default styles really worked for him. It's actually a pretty well done dynamics textbook. I've been looking forward to the actual final published text.

You should ask him if he's considered publishing the styles under a Free/open license. Even if parts of it is very specialized, I'd surprised if it couldn't work as an interesting starting point for other projects.

Next time I talk to him, I'll see about it. I don't talk to him that often now that I've finished my PhD.
Post reply on HN