= Bugs and Known Problems

== AsciiDoc3 Version 3.2.0, April 2020

=== PyPI, venv (Windows or GNU/Linux and other POSIX OS)
Unfortunately, sometimes (not always - depends on your directory-layout, operating system etc.)
AsciiDoc3 cannot find the 'asciidoc3' module when you installed via venv and/or PyPI. +
The solution: Import the module by providing the full path:

-------------------------------------------------------------------------------
from asciidoc3api import AsciiDoc3API
asciidoc3 = AsciiDoc3API('/full/path/to/asciidoc3.py') <1>
asciidoc3.execute('mydoc.txt')
-------------------------------------------------------------------------------
<1> Example: '/home/username/venv_dir/lib/python3.7/site-packages/asciidoc3/asciidoc3.py'



=== FOP
Using Apache FOP to generate PDF's

---------- 
 a2x3 -f pdf --fop test.txt
--------- 
 
is (depending on the os) very slooooooow. +
Probably a FOP issue? See this older post: +
https://fop-users.xmlgraphics.apache.narkive.com/xoDTa3QA/fop-being-very-slow

But there are a lot of similar messages if you gugl 'FOP is slow' ...


=== Undefined control sequence \cyrchar
When processing cyrillic letters, e.g. lang uk or ru.

-----------
leading text: ...har\cyrn{}\cyrchar\cyrn{}\cyrchar\cyrya{}}
-----------

This seems to be an issue of dblatex / tex +
utf8-examples.txt and FOP are the same

See this link:

------------------------
Transformation failure might be caused by handling a cyrillic document
without the XeTeX backend
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=632967
------------------------

=== Older Downloads

[TIP]
Only versions downloaded before 2019-May-9! Workaround for error FOP-generated PDF’s show the title twice:
Do not use 'a2x3' but 'python3 a2x3.py' and option '--no-xmllint'

----------------
python3 a2x3.py -f pdf --no-xmllint --fop test.txt
---------------



== AsciiDoc3 Version 3.1.0

=== AsciiDoc3

     * Reported line numbers in diagnostic messages are sometimes wrong.
     * Attribute references in macro attribute lists can’t be unescaped
       (with the exception of attribute list entry {0}).
     * Section numbering is incorrect when outputting HTML from a
       multi-part book type document. This is not a biggy since multi-part
       books are generally processed to DocBook.
     * A row of apostrophes in an inline context throws AsciiDoc3 into an
       endless loop. The problem seems to be in the input file Reader.
       (workaround: begin the line with a space or \)       

=== dblatex

   See ./dblatex/dblatex-readme.txt.

=== AsciiDoc3 running under Windows

See https://asciidoc3.org/windows.html
