Fork Me On GitLab
AsciiDoc3
Text based document generation using Python 3

»Home  »User Guide  »Blog  »Quickstart  »Download  »Install  »PyPI  »Docker  »Windows  »Cheatsheet  »Release Notes  »Contact / Donate  »Imprint / Impressum / Datenschutz / Privacy

Achtung [SOLVED] (see Workaround below)
SyntaxWarning: invalid escape sequence \S (and others) when using Python 3.12
Due to the change https://docs.python.org/3/whatsnew/3.12.html we encounter this warning:
>> … Other Language Changes … The parser now raises SyntaxError when parsing source code containing null bytes. … A backslash-character pair that is not a valid escape sequence now generates a SyntaxWarning, instead of DeprecationWarning. … In a future Python version, SyntaxError will eventually be raised, instead of SyntaxWarning. … <<
The same input processed with 3.11 (or before) throws only a silent DeprecationWarning.
The culprit is soon found: almost all conf-files contain at least one \S since AsciiDoc3 works with a bunch of regular expressions to detect the markup expressions, macros etc. And these regexes are still written in Python2.x-style, what now becomes to be a problem …
The brand-new Ubuntu 24.04 LTS ships with Python3.12, so this error will pop up more and more. … after all this error does not affect AsciiDoc3’s output.

Workaround:
To get rid of this message, download the enhanced asciidoc3.conf and replace the now deprecated old version - don’t forget to save your individual settings (if any). The new conf-file is a small preview of the forthcoming version 4.0.1
https://gitlab.com/asciidoc3/asciidoc3/-/blob/main/src/conf/asciidoc3.conf

AsciiDoc3 3.2.3
Highlights: (April 2024)

  • You can use asciidoc3 to produce your content with Hugo. See the latest posting in our blog.

  • Comes with a dockerized version, easing the live of Windows users, (all infos here!)

  • Even better support of DocBook v5.1,

  • Works with Windows (yes!) in a Python virtual environment (venv) - recommended, available via pip (PyPI.org),

  • A lot of tested templates,

  • Faster than ever,

  • …,

  • See Changelog here.

GNU/Linux: Unified Installer (Tarball) / Debian-Package / RPM-Package / PyPI.
Windows: zip-File (no symlinks) / PyPI.
Works seamlessly system-wide, local, or in a Python virtual environment!
No admin rights necessary when running local.
Pelican plugin for AsciiDoc3 is available, too. See our blog.

Introduction

AsciiDoc3 is a text document format for writing notes, documentation, articles, books, ebooks, slideshows, web pages, man pages and blogs. AsciiDoc3 files can be translated to many formats including HTML, PDF, EPUB, man page, dvi, ps, tex.

AsciiDoc3 is written in 100% pure Python3 - you need Python 3.8 or higher to execute. All of the onehundred and seventy testcases pass without errors. See the information given on this page for download and installation instructions.

AsciiDoc3 is highly configurable: both the AsciiDoc3 source file syntax and the backend output markups (which can be almost any type of SGML/XML markup) can be customized and extended by the user.

In consequence of the MicroSoft/GitHub deal AsciiDoc3 migrated to GitLab. You can find us here:
https://gitlab.com/asciidoc3/asciidoc3
The repo on GitHub is still open for comments, but all further development will be on GitLab.

AsciiDoc3 is a free software: licensed under the terms of the GNU Affero General Public License version 3 or later (AGPLv3+).

Overview and Examples

You write an AsciiDoc3 document the same way you would write a normal text document, there are no markup tags or weird format notations. AsciiDoc3 files are designed to be viewed, edited and printed directly or translated to other presentation formats using the asciidoc3 (and/or the coherent a2x3) command.

The asciidoc3 command translates AsciiDoc3 files to HTML, XHTML and DocBook markups. DocBook can be post-processed to presentation formats such as HTML, PDF, EPUB, DVI, LaTeX, roff, and Postscript using readily available Open Source tools.

In contrast to AsciiDoc (Python2) and asciidoc-py3 you can choose different encodings applying to the input and to the output. The default on both sides is utf-8. Perhaps you have an input-encoding gb18030 and like to see the output encoded with utf-16be? Try AsciiDoc3!

Tipp You find a lot of templates in the directories ./doc and ./tests/data of the distribution. These files help to learn more about the features of AsciiDoc3.

The pages you are reading were written using AsciiDoc3, the corresponding AsciiDoc3 sources can be found here: https://gitlab.com/asciidoc3/asciidoc3-website
The source code of page User Guide is included in the distribution files (../doc/userguide.txt), so you can test this by yourself, see here.
asciidoc3.org is a work-in-progress. Please return regularly to see the new versions of the asciidoc3-executable and the documentation.
I thank all the contributors for their awesome work.

On this page, in all related documents, and all the stuff around I make heavy use of the documents given on asciidoc.org (the end of live Python2.x implementation)

AsciiDoc3 is not asciidoc-py3

The AsciiDoc3 implementation you can find on this website asciidoc3.org is a personal project. There are other ports to Python 3.
Since all known implementations of the AsciiDoc-markup-language are open source under the terms of one of the GPL’s, every user may choose what he/she/div likes to run.

Bug reports

  • When reporting problems please illustrate the problem with the smallest possible example that replicates the issue (and please test your example before posting). This technique will also help to eliminate red herrings prior to posting.

  • Paste the commands that you executed along with any relevant outputs.

  • Include the version of AsciiDoc3 and the platform you’re running it on.

  • If you can program please consider writing a patch to fix the problem.