311–320 of 349 posts
Earlier quoted context omitted.
Asciidoc
what, recommending just one more format to learn? I don't think that's what the parent post is looking for : )
Plaintext OrgMode notebooks exhibit every benefit listed in Minimaxir's [0] post, and have the additional advantage of powerful editor integration beyond R code. Here is an example of using the IPython kernel to evaluate inline Python code within an OrgMode document.[1][2] More information on how to create multi-language notebooks with OrgMode Babel here[3] [0] http://minimaxir.com/2017/06/r-notebooks/ [1] http://kit…
Org format is great, but the designs of many of its more advanced features rely heavily on the Emacs editor's ability to collapse metadata. Once you've built a file that uses drawers, tags, some spreadsheets, and several levels of nesting, the resulting file can be too cluttered with metadata to be easily understandable in other plaintext editors.
This is basically why I switched to Asciidoc. And if you need to collaborate with others you can point to different editors that people can use, there is even AsciidocFX which is made specifically for new users.
Plaintext certainly seems more attractive the more docs I write. Over the years, with both work and personal projects, I've used every format from: - Notepad - Microsoft Word - PDF - Twiki - Various proprietary WSYWIG that compiles to HTML - JIRA - Raw HTML - Markdown (several flavors) With nearly every kind of migration, there are numerous pain points. The "raw" formats are a nightmare to edit and update, and the co…
AsciiDoc seems the way to go then. It's like DocBook with Markdown like syntax
I must say that I agree - to a certain extent. They (lecture notes) actually already are (at least in HE Physics education) as everything is written in LaTeX. They are just not distributed that way. I've been working on hacking together a demo of some stuff that turns those original LaTeX documents into a little (static) website. We've had pretty positive reviews from students so far - it's searchable (which is key),…
This site looks and feels amazing! Great work. Please share your conversion demo once it's available!
Here are the associated repos:
https://github.com/JBorrow/latex-pandoc-preprocessor (pandoc does not handle cross-references from LaTeX -> markdown correctly at the moment. Can be installed with pip install ltmd)
https://github.com/JBorrow/lectures-in-the-middle (the website & dodgy compilation script). The docs for this are pretty rubbish at the moment but the configuration file (litm.cfg) is pretty verbose.
If you are interested in setting it up and need more info, it's probably best to chat via email. It should work just fine already, and as I said students love it, but I'm not completely happy with middleman and the huge number of dependencies.
Also: if you're interested in contributing to the new frontend then let me know, I'm looking for contributors.
Earlier quoted context omitted.
Or the student could be a visual learner.
But there's a reason scientific books aren't very rich in illustrations.
I also don't want to come off as knocking video games. I had an Atari in the 80s. Super fun. I would have played that thing 8 hours a day if my parents had let me. They put a cap on it, along with a rule that I also spend some time with this odd object involving black letters printed on a series of white pages if I wanted to play the video game.
The Atari is long gone (though you could say it's as present as ever, in a greatly enhanced form). But those black letters on white pages are still pretty excellent, and are identical to how they were 30+ years ago.
Earlier quoted context omitted.
It's the Unix/text fetishizing developers who aren't the smart enough ones I think...
yet it is the unix/text fetish that forms the foundation for toasters, smartphones/watches, clouds, and supercomputers you'd think that a superior alternative would be overtaking this clearly inferior symbolic text system makes you think, don't it? not like people haven't been trying, but why is it so persistent? do you blame the fetish? why can't some other technically superior system win? WHY?
Earlier quoted context omitted.
what, recommending just one more format to learn? I don't think that's what the parent post is looking for : )
Asciidoc/Asciidoctor is non-ambiguous (unlike Markdown), works with different workflows and unlike org mode you can use different editors, easy to learn (unlike LaTeX). ReStructured text is the second closest but there you have to have Python in order for it to be useful, so Asciidoc is the only one plausible universal text markup as I see it.
Earlier quoted context omitted.
AsciiDoc is much more complex, in that it supports many more things. Check out the user guide[1]. Markdown takes a couple paragraphs to describe. You can know everything there is to know about using markdown within a couple minutes at most. 1: http://asciidoc.org/userguide.html
Isn't that comparison unfair, given that AsciiDoc gives you more functionality in a curated whole? Nobody forces you do use all of them. If you just want to use AsciiDoc as "Markdown with more coherent syntax", stick to a small subset that is equally trivial to learn. And if you need more, AsciiDoc's comprehensive user guide is a huge advantage. In Markdown, you'll have to look around for all kinds of forks. And god…
I don't see how it's unfair. I think AsciiDoc is much more complex, by just about any metric you want to use. I'm not saying it's necessarily worse by many metrics, just that by the particular metric of getting average people to use it, and not just a random subset of it, Markdown's simplicity is beneficial.
> Nobody forces you do use all of them.
No, but for random internet user there's a real trade-off between what you're trying to accomplish and what it takes to accomplish it, when you're just trying to write a simple comment. Reddit has a link that says "formatting help" below the comment box, and when you click it, it shows every option you have for special formatting with examples in a table with nine rows and two columns, including the header. They could have chosen AsciiDoc, but then they would have to make a decision about what features to elevate to the quick help and which not to, and very possibly which to disallow for their use case.
Markdown is simple for users to use, simple for user to understand, simple for developers to implement, and simple for developers to decide about. That simplicity is both why it was adopted by developers and why users bothered to learn and use it. As I alluded to before, AsciiDoc may have been a better choice in the end, but I don't think it's quite as simple as AsciiDoc does more stuff, so it's better. It's all about the trade-offs, and there's been plenty of discussion on that[1] before, from both sides.
1: Just google "worse is better".
Earlier quoted context omitted.
Isn't that comparison unfair, given that AsciiDoc gives you more functionality in a curated whole? Nobody forces you do use all of them. If you just want to use AsciiDoc as "Markdown with more coherent syntax", stick to a small subset that is equally trivial to learn. And if you need more, AsciiDoc's comprehensive user guide is a huge advantage. In Markdown, you'll have to look around for all kinds of forks. And god…
> Isn't that comparison unfair, given that AsciiDoc gives you more functionality in a curated whole? I don't see how it's unfair. I think AsciiDoc is much more complex, by just about any metric you want to use. I'm not saying it's necessarily worse by many metrics, just that by the particular metric of getting average people to use it, and not just a random subset of it, Markdown's simplicity is beneficial. > Nobody…
which is why so many people had to "extend" it with different "flavors", which has now created a massive mess of inconsistencies.
sometimes worse is better. and sometimes it's just plain worse. and sometimes it's the worst kind of situation you could ever imagine.