I like #AsciiDoc, but my main concern with it is how well the tooling handles multiple books.

If I have, say, 12 books of one-chapter-per-file documentation, can I generate:

- An AsciiDoc version where a book is one file (I assume this is pretty easy)
- A web version with each chapter separate, BUT can also link between books (and maybe offers an entire-book-in-a-file version, too)
- EPUB and PDF versions of books that don't link between other books (unless there's a way to cleanly do that)

Book(s) will probably need to be added for subject areas that aren't covered by the SDK but don't "fit" into an existing book. For example, the FEFS filesystem format and various file formats. Some of these are covered in the Psionics Files, so they could be included in their own book.

I'm pretty settled on #AsciiDoc, which will make it easy to generate HTML, PDF and EPUB versions.

Original versions of the documentation will be made available, of course.

#Psion #RetroComputing

Earlier today, after some hunting, I found the text version of the #OPL Programming Manual that came with the Series 3a. So, while I was sitting in front of the TV this evening, I thought I'd start converting it to #AsciiDoc.

First chapter is pretty much done.

I think (hope) I've got a paper copy in a box somewhere, so I can compare it to the original.

#Psion #RetroComputing #Documentation

La questione "strumenti per scrivere e mantenere la documentazione" è praticamente chiusa. Alla fine ho optato per #asciidoc che è una favola da usare e fa tutto quello che ci serve (grazie ad #asciidoctor). Il team ha approvato e gradito e io mi sono divertito un mondo a fare prove, creare temi e piccoli script in #bash per facilitarne la conversione. Ho imparato un bel po' di cose e mi sono divertito. Vorrei che fosse sempre così!

Grazie a TUTTI per i suggerimenti! ❤️

#techDocs #docs

Interesting poll results. Most people have either tried #AsciiDoc and like it, or never heard of it before.

#AsciiDoc question:

Some time ago while I was working on a very different project, someone suggested that I try #AsciiDoc instead of Markdown.

It looks interesting: the tooling looks good, and (very important over Markdown) there's only one standard.

I'm coming back to it now as I look at documentation solutions for Psion docs.

Do you use AsciiDoc? What do you think of it?

Is there any #blogging or #activitypub-oriented publishing #software for writing a larger collection of pages in #asciidoc?

The best writing tip I learned as an adult is to write one sentence per line.

It's such a simple but powerful thing that I've memorized the URL of an essay where I first heard about it:

https://sive.rs/1s

Check it out!

(The #AsciiDoctor people also recommend this practice. https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line)

#writing #LifeHack #ProTip #AsciiDoc

Algumas pessoas gostam de colecionar canetas, eu, por outro lado, gosto de testar e colecionar sistemas de processamento de documentos. A primeira vez que utilizei #LaTeX a sério foi em 2012 ou 2014, desde então, sempre que posso, evito processadores de texto convencionais (até gosto do #TextMaker, mas documentos longos e técnicos precisam de sistemas mais robustos, ainda que pouco ou nada visuais). Recentemente, passei um tempo lendo sobre #AsciiDoc e #ConTeXt também. E agora conheci o #Quarto.

I am very pleased with what I can get from three simple plain text files written in #asciidoc, plus an equally simple theme file...

... compared to, like, 50 files and 1-2 gigabytes of LaTeX software.

Because reasons, I'm updating my CV.

Switching from LaTeX to #asciidoc and #asciidoctor has been a big win.

Probably the best illustrations of this:

* Went from 43 files (42 of which confused me) to 9 (all of which I understand).

* I just need asciidoctor-pdf; no need to worry about which LaTeX packages I need, and how different OSes name them.

* I actually understand how to change the appearance of the CV now.

The end result doesn't look as fancy, but I think it's easier to read and it's certainly much easier to produce.

Všechna má snaha naučit se #TeX a #LaTeX během studia přišla vlastně úplně vniveč, protože poslední roky pracuji stejně jen s #asciidoc a #markdown.

Tak snad v budoucnu. 🤠

@alexl Is there a comparison with #asciidoc somewhere?

Learning #asciidoc

Because i set my #gentoo pc to be #wayland only without X. . . i felt need to have strong alternative to word processor.

Now i think #minimal environment can be really useful. Not having access to libreoffice forces me to find decent replacement for everyday life doc writing.

Ofc. i could go easy way and install word processor on old laptop ... but that means no real gain... without need, or any other motivation it's hard to learn anything.

less is more.

#thoughts

#release asciidoctor-go v0.5.0 (2023-06-04)

The [asciidoctor-go](https://sr.ht/~shulhan/asciidoctor-go/) is the Go module to parse the #AsciiDoc markup and convert it into HTML5.

=== New features

* all: add support for unordered list with '-'

=== Bug fixes

* all: fix rendering blockquote without attribution
* all: handle custom marker in between unordered list

Today I am going to be learning #asciidoc and working on #TheOdinProject. Moving a little slow this morning but I will gain#momentum. Just. Need. More. #coffee.

@lelibreedu J'utilise AsciiDoctor avec bonheur depuis 6 ans, pour mes rapports, cahiers des charges, sites web statics (comme https://grimoire.d12s.fr ). Ce format est une évolution du Markdown avec une meilleure gestion des tableaux, du placement des images... #Asciidoc #AsciiDoctor et puis c'est entre autre le format des commentaires du noyau Linux :-)

@tbroyer I had fun implementing this asciidoctor.js PDF solution. Perfectly valid if you convert all your sources to #asciidoc first (#pandoc, #kramdown) and want an ‘offline’ solution

https://matklad.github.io/2019/05/19/consider-using-asciidoctor-for-your-next-presentation.html

#asciidoctor

#asciidoctor-vscode just received a major upgrade!

https://github.com/asciidoctor/asciidoctor-vscode/releases/tag/v3.0.5

Using the #asciidoc language in a #vscode / #vscodium workflow for #NoteTaking AND #Documenting AND plain #Writing stuff down has never been this much fun!

So, what do people use nowadays to make slideshows from Markdown, Asciidoc, or HTML that can ideally render to PDF in addition to HTML?
(if it doesn't do PDF, don't hesitate to suggest anyway!)

#slides #presentation #html #markdown #asciidoc #asciidoctor