index.txt 5.75 KB
Newer Older
asciidoc3's avatar
asciidoc3 committed
1
2
3
AsciiDoc3 Home Page
==================
// Web page meta data.
admuc's avatar
admuc committed
4
:keywords:    AsciiDoc3, Windows, AsciiDoc, Python3, DocBook 5.1, EPUB, PDF, ebooks, slideshow, slidy, man page
asciidoc3's avatar
asciidoc3 committed
5
6
7
8
:description: 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,  +
admuc's avatar
admuc committed
9
              man page. AsciiDoc3 is written in 100% pure Python3 
asciidoc3's avatar
asciidoc3 committed
10
11


admuc's avatar
admuc committed
12
13
//.{revdate}: AsciiDoc3 {revnumber} Released

asciidoc3's avatar
asciidoc3 committed
14

admuc's avatar
admuc committed
15
16
17
18
19
20
21
[WARNING]
There is a new version on PyPI.org -> AsciiDoc3 3.2.1 +
This is a bugfix release - in some cases, and when not using venv, asciidoc3_postinstall failed. This happened only on Windows. +
GNU/Linux systems are not affected, so the deb/rpm/gz files are for now unchanged and you do not need to update anyhow. +
If you install 'pip install asciidoc3' or update 'pip install asciidoc3 -U' (see link:pypi.html[here]), the fixed version is loaded automatically for you.


admuc's avatar
admuc committed
22
23
************************************************************************

admuc's avatar
admuc committed
24
25
26
27
28
29
30
31
32
Latest: *AsciiDoc3 3.2.0* +
Highlights: +

- Full (!) support of DocBook v5.1,
- Works with Windows (yes!) in a Python virtual environment (venv) - recommended, available via PyPI.org / pip, 
- A lot of tested templates to use,
- Faster than ever, 
- ...,
- See Changelog link:releasenotes.html#_changelog[here].  
admuc's avatar
admuc committed
33

admuc's avatar
admuc committed
34
GNU/Linux: Unified Installer (Tarball) / Debian-Package / RPM-Package / PyPI. +
admuc's avatar
admuc committed
35
Windows: zip-File (no symlinks) / PyPI. +
admuc's avatar
admuc committed
36
37
38
Works seamlessly system-wide, local, or in a Python https://docs.python.org/3/library/venv.html[virtual environment]! +
No admin rights necessary when running local. +
https://getpelican.com/[Pelican] plugin for AsciiDoc3 is available, too. See our https://asciidoc3.org/blog/pelican-plugin-for-asciidoc3-available.html[blog]. 
admuc's avatar
admuc committed
39

admuc's avatar
admuc committed
40
************************************************************************
asciidoc3's avatar
asciidoc3 committed
41

admuc's avatar
admuc committed
42

asciidoc3's avatar
asciidoc3 committed
43
44
45
46
== 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,
admuc's avatar
admuc committed
47
EPUB, man page, dvi, ps, tex.
admuc's avatar
admuc committed
48

admuc's avatar
admuc committed
49
AsciiDoc3 is written in 100% pure Python3 - you need Python 3.5 or higher to execute. All of the onehundred and seventy testcases defined in the AsciiDoc (Python2) distribution pass without errors and a binary identical result. See the information given on this page for download and installation instructions. +
asciidoc3's avatar
asciidoc3 committed
50
51
52
53
54

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.

admuc's avatar
admuc committed
55
56
57
In consequence of the MicroSoft/GitHub deal AsciiDoc3 migrated to GitLab. You can find us here: +
https://gitlab.com/asciidoc3/asciidoc3 +
The repo on https://github.com/asciidoc3/asciidoc3[GitHub] is still open for comments, but all further development will be on GitLab.
asciidoc3's avatar
asciidoc3 committed
58

admuc's avatar
admuc committed
59
AsciiDoc3 is a free software: licensed under the terms of the GNU General Public License version 2 or later (GPLv2+). 
asciidoc3's avatar
asciidoc3 committed
60
61
62
63
64
65

== 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
admuc's avatar
admuc committed
66
the 'asciidoc3' (and/or the coherent 'a2x3') command.
asciidoc3's avatar
asciidoc3 committed
67
68

The 'asciidoc3' command translates AsciiDoc3 files to HTML, XHTML and
admuc's avatar
admuc committed
69
DocBook markups. DocBook can be post-processed to presentation
asciidoc3's avatar
asciidoc3 committed
70
71
72
formats such as HTML, PDF, EPUB, DVI, LaTeX, roff, and Postscript
using readily available Open Source tools.

admuc's avatar
admuc committed
73
74
75
76
77
78
79
80
81
82
83
84
85
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!

[TIP]
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 link:quickstart.html[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)

admuc's avatar
admuc committed
86
87
.AsciiDoc3 is not asciidoc-py3
The 'offical community' of AsciiDoc makes a point of the following statement: the AsciiDoc3 implementation (which you can find on this website asciidoc3.org) is a personal project. You can find another port of AsciiDoc to Python 3 https://github.com/asciidoc/asciidoc-py3[here]. +
admuc's avatar
admuc committed
88
89
Commentary: AsciiDoc (Python 2) is open source under the terms of the GPLv2+. So are both AsciiDoc3 (Python 3) and asciidoc-py3. Every user may choose what he/she/div likes to run. As far as I can see any of the two programs cover all requested features.

asciidoc3's avatar
asciidoc3 committed
90
91
92
93
94
95
96
97
98
99
100
101

=== 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.