From 30ba5437f87c1b1a0cfc36821f9996c5566b197d Mon Sep 17 00:00:00 2001 From: Matthew Peveler Date: Wed, 10 Feb 2021 20:43:54 -0500 Subject: Add small blurb on legacy nature of AsciiDoc.py (#175) Signed-off-by: Matthew Peveler --- README.md | 23 +++++++++++++++-------- doc/asciidoc.txt | 9 +++++++++ website/index.txt | 11 +++++++++-- 3 files changed, 33 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index dfc4c73..1186cc8 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ -AsciiDoc -======== +AsciiDoc.py +=========== [![Build Status](https://github.com/asciidoc/asciidoc-py3/workflows/Test/badge.svg?branch=master)](https://github.com/asciidoc/asciidoc-py3/actions?query=workflow%3ATest+branch%3Amaster) @@ -11,20 +11,27 @@ articles, books, ebooks, slideshows, web pages, man pages and blogs. AsciiDoc files can be translated to many formats including HTML, PDF, EPUB, man page. -AsciiDoc is highly configurable: both the AsciiDoc source file syntax +AsciiDoc.py is a legacy processor for this syntax, handling an older +rendition of AsciiDoc. As such, this will not properly handle the +[current AsciiDoc specification](https://projects.eclipse.org/projects/technology.asciidoc). +It is suggested that unless you specifically require the AsciiDoc.py +toolchain, you should find a processor that handles the modern AsciiDoc +syntax. + +AsciiDoc.py is highly configurable: both the AsciiDoc 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. ## Prerequisites -AsciiDoc is written in Python so you need a Python interpreter +AsciiDoc.py is written in Python so you need a Python interpreter (version 3.5 or later) to execute asciidoc(1). You can install Python using the package manager for your OS or by downloading it from the official Python website http://www.python.org. -## Obtaining AsciiDoc +## Obtaining AsciiDoc.py -Documentation and installation instructions are on the AsciiDoc website +Documentation and installation instructions are on the AsciiDoc.py website https://asciidoc.org/. Additionally, for 10.x, you can install it using pip: ``` @@ -33,7 +40,7 @@ pip3 install asciidoc ## Tools -Current AsciiDoc version tested on Ubuntu 18.04 with: +Current AsciiDoc.py version tested on Ubuntu 18.04 with: - Python 3.6.5 - DocBook XSL Stylesheets 1.76.1 @@ -45,7 +52,7 @@ Current AsciiDoc version tested on Ubuntu 18.04 with: ## Copying Copyright (C) 2002-2013 Stuart Rackham. -Copyright (C) 2013-2021 AsciiDoc Contributors. +Copyright (C) 2013-2021 AsciiDoc.py Contributors. Free use of this software is granted under the terms of the GNU General Public License version 2 (GPLv2). diff --git a/doc/asciidoc.txt b/doc/asciidoc.txt index fe204fa..0721022 100644 --- a/doc/asciidoc.txt +++ b/doc/asciidoc.txt @@ -14,6 +14,15 @@ AsciiDoc 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. +[WARNING] +This user guide is for AsciiDoc.py, which is a legacy processor for +this syntax, handling an older rendition of AsciiDoc. As such, this +will not properly handle the +https://projects.eclipse.org/projects/technology.asciidoc[current AsciiDoc specification]. +It is suggested that unless you specifically require the AsciiDoc.py +toolchain, you should find a processor that handles the modern +AsciiDoc syntax. + .This document ********************************************************************** This is an overly large document, it probably needs to be refactored diff --git a/website/index.txt b/website/index.txt index d7c89a3..c1d5db1 100644 --- a/website/index.txt +++ b/website/index.txt @@ -22,11 +22,18 @@ Introduction ------------ {description} -AsciiDoc is highly configurable: both the AsciiDoc source file syntax +AsciiDoc.py is a legacy processor for this syntax, handling an older +rendition of AsciiDoc. As such, this will not properly handle the +https://projects.eclipse.org/projects/technology.asciidoc[current AsciiDoc specification]. +It is suggested that unless you specifically require the AsciiDoc.py +toolchain, you should find a processor that handles the modern AsciiDoc +syntax. + +AsciiDoc.py is highly configurable: both the AsciiDoc 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. -AsciiDoc is free software and is licensed under the terms of the 'GNU +AsciiDoc.py is free software and is licensed under the terms of the 'GNU General Public License version 2' (GPLv2). TIP: The pages you are reading were written using AsciiDoc, to view -- cgit v1.2.1