9 ms·

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 Do

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 syntax, is equally good at little docs and huge books, and you could theoretically write a proper academic paper in it with the LaTeX backend. And you always know what's going to happen when you try to mix bold and italic... Also endorsed by Linus.[2] [0]: http://www.methods.co.nz/asciidoc/#_overview_and_examples [1]: Well, five minutes to be able to do everything Markdown can do; everything else will take a bit longer [2]: https://plus.google.com/+LinusTorvalds/posts/X2XVf9Q7MfV (comments)

treerex 12y ago
I have yet to see a good stylesheet for AsciiDoc's DocBook output for creating a decent PDF. Do you have recommendations? I love AsciiDoc, but am only using it to generate HTML right now.
- lorddoig 12y ago
  Unfortunately not, XSL isn't really my thing. I'd probably consider trying to go via LaTeX, but that's because I like the way LaTeX looks out of the box and probably isn't appropriate for most things.
- jauco 12y ago
  Try asciidoctor and its stylesheets.
- boundlessdreamz 12y ago
  As @jauco said try Asciidoctor - http://asciidoctor.org/ http://asciidoctor.org/ In addition to default asciidoctor style, there are other themes available - http://themes.asciidoctor.org/preview/ 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 http://git-scm.com/book/en/v2 which was written in asciidoc - https://github.com/progit/progit2 https://github.com/progit/progit2
  - e12e 12y ago
    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, IMNHO. On the other hand, they also have an epub style sheet, and it appears (a little oddly) that the layout of the epub is better than the pdf. FWIW most "heavily optimized" custom LaTeX styles I've come across tend to feel like being slapped in the face with MS Word -- and I think I've yet to encounter any that actually improve on the "standard" styles in any meaningful way (with possible exception of the APA style, which is ugly, but as it has to conform to APA, it's ugly by design. And looks better than most other APA conforming styles I've seen). Still, having a starting point makes the job much easier -- so this is a great resource.
    - tjl 12y ago
      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.
      - e12e 12y ago
        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.
        tjl 12y ago
        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.
coned88 12y ago
Are there any good wiki softwares that use Asciidoc?
- boundlessdreamz 12y ago
  The github wiki software supports asciidoc and many other formats - https://github.com/gollum/gollum https://github.com/gollum/gollum
  - coned88 12y ago
    Any others?
timtylin 12y ago
I love AsciiBook. Everything but the name. If we ever get an amazing collaborative development tool like Github that has built-in AsciiBook rendering, this project would have been called "Scholarly AsciiBook (but we got Unicode support too I swear really)". Edit: I was wrong about Github not supporting AsciiDoc
- boundlessdreamz 12y ago
  Github does render asciidoc using asciidoctor. What is missing in that that is possible in Markdown?
  - timtylin 12y ago
    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 existing Markdown notes to papers, John happened to add (at Martin Fenner's urging) pretty robust support for citations to Pandoc. Being able to use an existing .bst files and Natbib author/year syntax with existing Bibtex database files, while also using CSL to format to everything else was pretty key. The syntax only worked in Markdown at the time, so I went with that. This project just simply grew into an experiment on how to get the least hack-y looking source document for what I needed. Basically, I had a bunch of existing Markdown stuff typed with both my phone and my computer using NValt (already using the double-backtick math syntax as a hack), and I was looking for a way to reuse all that. If I had to do conversions or had to start from scratch, I would have just started another LaTeX Document, and then this project wouldn't be here. As an aside aside: I personally think that one shortcoming of AsciiDoc is that Markdown ended up having a more mature application ecosystem outside of the most general purpose text-editing tools. I'm thinking of something like Scrivener/Ulysses which is really great for project writing and has robust markdown support while writing. I've also recently found out that TeXpad "mysteriously" formats Markdown syntax in the editor, and builds an in-editor TOC of it. This is in addition to with rendering support in basically every note-taking tool. Sadly AsciiDoc doesn't seem to have experienced a similar growth spurt in terms of popularity amongst developers, and as a result have a bit more friction to use.
fiddlosopher 12y ago
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 it, if you want automatic citation support you need to use LaTeX, and then you're limited to output in LaTeX and PDF. Similarly for math: pandoc actually converts your LaTeX math to MathML (for formats that like that) or to native Word equations (for docx); in AsciiDoc, as I understand it, your LaTeX math will work if you target LaTeX, but if you want MathML you need to put MathML in the source. If you want to target both, then maybe you need two different source documents? I don't have much experience with AsciiDoc, but I've encountered other limitations in writing pandoc's AsciiDoc renderer. For example, I didn't see any way to include multiple paragraphs (or other block content) in an AsciiDoc footnote. That's a deal-breaker for many academics. I also want to emphasize something that is often not mentioned in comparisons of Markdown and AsciiDoc. As John Gruber emphasizes in his Markdown documentation, Markdown emphasizes ease of reading in source format. AsciiDoc has different priorities, and it sacrifices the readability of the source document to get them. Here's an example involving nested lists, from the AsciiDoc manual: 1. List item one. + List item one continued with a second paragraph followed by an Indented block. + ................. $ ls *.sh $ mv *.sh ~/tmp ................. + List item continued with a third paragraph. 2. List item two continued with an open block. + -- This paragraph is part of the preceding list item. a. This list is nested and does not require explicit item continuation. + This paragraph is part of the preceding list item. b. List item b. This paragraph belongs to item two of the outer list. -- Markdown equivalent: 1. List item one. List item one continued with a second paragraph followed by an Indented block. $ ls *.sh $ mv *.sh ~/tmp List item continued with a third paragraph. 2. List item two continued with an open block. This paragraph is part of the preceding list item. 1. This list is nested and does not require explicit item continuation. This paragraph is part of the preceding list item. 2. List item b. This paragraph belongs to item two of the outer list. Note that the AsciiDoc is at least as easy to write, perhaps easier, because you don't need to worry about indentation. But the Markdown source is more readable; the indentation makes clear the structure of the list in a way that mirrors how it would be displayed in a browser or on the page.
asgard1024 12y ago
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.

treerex 12y ago

I have yet to see a good stylesheet for AsciiDoc's DocBook output for creating a decent PDF. Do you have recommendations? I love AsciiDoc, but am only using it to generate HTML right now.

lorddoig 12y ago
Unfortunately not, XSL isn't really my thing. I'd probably consider trying to go via LaTeX, but that's because I like the way LaTeX looks out of the box and probably isn't appropriate for most things.
jauco 12y ago
Try asciidoctor and its stylesheets.
boundlessdreamz 12y ago
As @jauco said try Asciidoctor - http://asciidoctor.org/ http://asciidoctor.org/ In addition to default asciidoctor style, there are other themes available - http://themes.asciidoctor.org/preview/ 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 http://git-scm.com/book/en/v2 which was written in asciidoc - https://github.com/progit/progit2 https://github.com/progit/progit2
- e12e 12y ago
  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, IMNHO. On the other hand, they also have an epub style sheet, and it appears (a little oddly) that the layout of the epub is better than the pdf. FWIW most "heavily optimized" custom LaTeX styles I've come across tend to feel like being slapped in the face with MS Word -- and I think I've yet to encounter any that actually improve on the "standard" styles in any meaningful way (with possible exception of the APA style, which is ugly, but as it has to conform to APA, it's ugly by design. And looks better than most other APA conforming styles I've seen). Still, having a starting point makes the job much easier -- so this is a great resource.
  - tjl 12y ago
    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.
    - e12e 12y ago
      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.
      - tjl 12y ago
        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.

coned88 12y ago

Are there any good wiki softwares that use Asciidoc?

boundlessdreamz 12y ago
The github wiki software supports asciidoc and many other formats - https://github.com/gollum/gollum https://github.com/gollum/gollum
- coned88 12y ago
  Any others?

timtylin 12y ago

I love AsciiBook. Everything but the name. If we ever get an amazing collaborative development tool like Github that has built-in AsciiBook rendering, this project would have been called "Scholarly AsciiBook (but we got Unicode support too I swear really)". Edit: I was wrong about Github not supporting AsciiDoc

boundlessdreamz 12y ago
Github does render asciidoc using asciidoctor. What is missing in that that is possible in Markdown?
- timtylin 12y ago
  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 existing Markdown notes to papers, John happened to add (at Martin Fenner's urging) pretty robust support for citations to Pandoc. Being able to use an existing .bst files and Natbib author/year syntax with existing Bibtex database files, while also using CSL to format to everything else was pretty key. The syntax only worked in Markdown at the time, so I went with that. This project just simply grew into an experiment on how to get the least hack-y looking source document for what I needed. Basically, I had a bunch of existing Markdown stuff typed with both my phone and my computer using NValt (already using the double-backtick math syntax as a hack), and I was looking for a way to reuse all that. If I had to do conversions or had to start from scratch, I would have just started another LaTeX Document, and then this project wouldn't be here. As an aside aside: I personally think that one shortcoming of AsciiDoc is that Markdown ended up having a more mature application ecosystem outside of the most general purpose text-editing tools. I'm thinking of something like Scrivener/Ulysses which is really great for project writing and has robust markdown support while writing. I've also recently found out that TeXpad "mysteriously" formats Markdown syntax in the editor, and builds an in-editor TOC of it. This is in addition to with rendering support in basically every note-taking tool. Sadly AsciiDoc doesn't seem to have experienced a similar growth spurt in terms of popularity amongst developers, and as a result have a bit more friction to use.

fiddlosopher 12y ago

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 it, if you want automatic citation support you need to use LaTeX, and then you're limited to output in LaTeX and PDF. Similarly for math: pandoc actually converts your LaTeX math to MathML (for formats that like that) or to native Word equations (for docx); in AsciiDoc, as I understand it, your LaTeX math will work if you target LaTeX, but if you want MathML you need to put MathML in the source. If you want to target both, then maybe you need two different source documents? I don't have much experience with AsciiDoc, but I've encountered other limitations in writing pandoc's AsciiDoc renderer. For example, I didn't see any way to include multiple paragraphs (or other block content) in an AsciiDoc footnote. That's a deal-breaker for many academics. I also want to emphasize something that is often not mentioned in comparisons of Markdown and AsciiDoc. As John Gruber emphasizes in his Markdown documentation, Markdown emphasizes ease of reading in source format. AsciiDoc has different priorities, and it sacrifices the readability of the source document to get them. Here's an example involving nested lists, from the AsciiDoc manual: 1. List item one. + List item one continued with a second paragraph followed by an Indented block. + ................. $ ls *.sh $ mv *.sh ~/tmp ................. + List item continued with a third paragraph. 2. List item two continued with an open block. + -- This paragraph is part of the preceding list item. a. This list is nested and does not require explicit item continuation. + This paragraph is part of the preceding list item. b. List item b. This paragraph belongs to item two of the outer list. -- Markdown equivalent: 1. List item one. List item one continued with a second paragraph followed by an Indented block. $ ls *.sh $ mv *.sh ~/tmp List item continued with a third paragraph. 2. List item two continued with an open block. This paragraph is part of the preceding list item. 1. This list is nested and does not require explicit item continuation. This paragraph is part of the preceding list item. 2. List item b. This paragraph belongs to item two of the outer list. Note that the AsciiDoc is at least as easy to write, perhaps easier, because you don't need to worry about indentation. But the Markdown source is more readable; the indentation makes clear the structure of the list in a way that mirrors how it would be displayed in a browser or on the page.

asgard1024 12y ago

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.