51–60 of 137 posts
I much prefer Asciidoctor to Markdown when writing documents that's longer than a single A4 page, since it has the ability to combine multiple files into a single document if needed.
pandoc file1.md file2.md .... -o final.md
pandoc file1.md file2.md .... -o final.pdf
Earlier quoted context omitted.
It does tend to make one worry that all the tools will be hideously un-unicode aware and mangle any non-ASCII documents. I would like to imagine that in this day and age that isn't the case, but the name works against it.
Came here to say this. UTF-8/16 represents such a relief from the previous text-encoding nightmares that I run away from any tooling that does not use it. If anyone else was a web dev in the 90s, you know what I’m talking about.
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.
[1] https://docs.gbif.org/collections-idea-paper/zh/
[2] https://ipt.gbif.org/manual/en/ipt/2.5/data-hosting-centres#...
There's something about org-mode markup syntax that's really nice.
Have you written much using org-mode as a replacement for asciidoc/markdown etc? I should probably try to find some examples of longer-form org-mode docs and see if I can use those features.
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…
> 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 There'd a middle-ish ground we're going with at work - you have the documentation alongside the code in git, and your CI/CD also uploads it to Confluence/whatever for less technical folks/searchability/etc. ( Too…
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…
It's fine, you have to press the key right next to the backspace key plus shift. Not exactly ergonomic, but easy to discover on basically any standard QWERTZ keyboard. I'd definitely like a fenced alternative. I'm okay with indentation-based code, but somehow I really dislike using it in my writing.
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…
reStructuredText and AsciiDoc are already straddling the line between Markdown and full-featured markup languages. If you need more than this, then you should probably bite the bullet and just use LaTeX or some other markup.
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 ?
On the other hand, if you already know the gist of Markdown, then you could pick up reStructuredText or AsciiDoc in less than an hour. They're more feature-rich than markdown, without adding too much squeeze for the juice.
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…
> 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 There'd a middle-ish ground we're going with at work - you have the documentation alongside the code in git, and your CI/CD also uploads it to Confluence/whatever for less technical folks/searchability/etc. ( Too…
As you said having the dev doc on an external tool is really a plus. You can have comments, you can add tags, easier to search, and give access to non technical people
Earlier quoted context omitted.
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…
> Would you use backtick? Dunno. I hear it’s hard to access on some keyboard layouts like German. It's fine, you have to press the key right next to the backspace key plus shift. Not exactly ergonomic, but easy to discover on basically any standard QWERTZ keyboard. I'd definitely like a fenced alternative. I'm okay with indentation-based code, but somehow I really dislike using it in my writing.