131–137 of 137 posts
It always bothered me that these ascii processors don't use /for italics/. It just looks visually like italics.
Earlier quoted context omitted.
rST doesn't support nesting markup (bold and italic? nope. code styling in a link? nope.). It's decent for writing software docs, but not good at all (in my opinion) for writing blog posts or other prose.
Yeah, nesting inline markup is definitely something I’d want to add. Note that code styling in a link is actually possible, just convoluted: Using |foo|__. .. |foo| replace:: substitution with the ``replace`` directive __ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions Funny thing is that, from what I recollect of investigating this matter a decade ago, there was never any…
The main implementation of reStructuredText is a custom parser, which might be a hassle to modify to accomodate all cases of nesting, including duplicate ones like: A B A text b a a.
But perhaps all the difficulty in this stems from making the symbols used for starting an inline markup the same as for ending it. Otherwise it would be trivial to count opening and closing "parentheses".
Earlier quoted context omitted.
> There’s no point using latex if your book has almost no formulas... In a book one often needs to keep track of local references (to figures, tables, sections, etc). How this could be reasonably done in markdown flavors?
Asciidoc already supports that. You don’t even need to differentiate in the syntax, it knows when you are referring to a table, a figure, a section, code listing, etc.
I just wrote an entire book in asciidoc and honestly I don't like a lot of the decisions and the syntax, the tooling is also quite messy and hard to use/configure. Having said that, I'm not sure if there's really any alternative. If you need the extensibility and diff-ability of asciidoc, then you're probably going to have to use it. If you don't need it, stick with markdown. EDIT: so that people get an idea, I use a…
This question may be a bit naive, but it comes from somebody who has never used asciidoc but used a lot of LaTeX to make reports, poster, presentations, ... Why are you using asciidoc to write a book, instead of LaTeX ? I see the advantage of using this for documentation, but for an entire book ?
You use LaTeX when you have to for some specific thing, perhaps equations, but at other times, you can stick with the simpler syntax of (AsciiDoc|reStructuredText|Org-Mode).
That's what I do at least.
I really like AsciiDoc and would encourage anyone to give it a try, especially for things like software documentation (in all forms). I very much despise the trend to write sharepoint or wiki/Confluence pages as a means for software documentation. I want my documentation to reside next to my source code, not at some obscure corporate URL. The problem is simply that github, gitlab, and friends adopted Markdown and so…
Edit: Now that I think about it, the whole product palette of Atlassian seems to have issues making use of any decent markdown parser out of the myriads of parsers out there, that they could use. For example HTML in markdown on Bitbucket also does not properly work, so generating a table of contents is useless on Bitbucket as well.
Earlier quoted context omitted.
AsciiDoctor supports Unicode just fine. We've integrated it with PO4A[0] and CrowdIn.com to support a translation workflow, and so far have one document in Chinese: [1]. Another (tiny) example is [2] with an emoji star, you can "Edit this page" and see the Unicode source. [0] https://po4a.org/ [1] https://docs.gbif.org/collections-idea-paper/zh/ [2] https://ipt.gbif.org/manual/en/ipt/2.5/data-hosting-centres#...
The issue is that the name strongly implies that it doesn't. If a system is named "Doesn'tSupportImportantThingSys" don't be surprised when people don't bother to check the documentation to find that it actually does support the important thing. They'll just skip it.
ASCII is so old that I picture ANSI colour blocks as it’s successor, and both of those are firmly in the “nightmarish text encoding days”
Earlier quoted context omitted.
RestructuredText (usually used within Sphinx) is the only alternative in the same class. Unfortunately there are hardly any comparisons. Maybe there are no people who have significant experience with both.
I reckon reStructuredText is the best syntactic and semantic foundation of all the ones I’ve seen, but there are a few things it could do with changing. Most significantly, reStructuredText is designed for being written in a sane text editor, where indenting stuff is easy; but this doesn’t work well for use in a plain as web applications of it will commonly go for, where any indentation must be applied manually by th…
You might find MyST interesting! Personally I’m counting on it to succeed (after painfully realising reStructuredText never will )