From 85f4e65adbe6f38559c905bf1290a3efbe96dda4 Mon Sep 17 00:00:00 2001 From: Matthew Peveler Date: Sat, 18 Dec 2021 11:20:45 -0500 Subject: rework documentation Signed-off-by: Matthew Peveler --- INSTALL.adoc | 169 ----------------------------------------------------------- README.md | 24 +++++++++ 2 files changed, 24 insertions(+), 169 deletions(-) delete mode 100644 INSTALL.adoc diff --git a/INSTALL.adoc b/INSTALL.adoc deleted file mode 100644 index b43b044..0000000 --- a/INSTALL.adoc +++ /dev/null @@ -1,169 +0,0 @@ -AsciiDoc Installation -===================== - -NOTE: The current version of AsciiDoc requires *Python 3.5 or later* -to run. If you don't already have an up-to-date version of Python -installed it can be downloaded from the official Python website -http://www.python.org/. - - -Prerequisites -------------- -See the link:README.html[README] page. - - -Installing from the GitHub repository -------------------------------------- -The AsciiDoc repository is hosted by https://github.com[GitHub]. -To browse the repository go to https://github.com/asciidoc/asciidoc-py3. -You can install AsciiDoc from the repository if you don't have an up to -date packaged version, or you want to get the latest version from the master -branch: - -- Make sure you have https://git-scm.com/[Git] - installed; you can check with: - - $ git --version - -- Go to the directory you want to install AsciiDoc into and download - the repository. This example gets the {revnumber} tagged release: - -[subs="attributes"] - $ cd ~/bin - $ git clone https://github.com/asciidoc/asciidoc-py3 asciidoc-{revnumber} - $ git checkout {revnumber} - -You now have two choices: you can run asciidoc locally from your -repository or you can use 'autoconf(1)' and 'make(1)' to perform a -system-wide install. - -Running asciidoc from your local copy -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Create a symlink to the AsciiDoc script in a search `PATH` directory -so it's easy to execute `asciidoc` from the command line, for example: - -[subs="attributes"] - $ ln -s ~/bin/asciidoc-{revnumber}/asciidoc.py ~/bin/asciidoc - $ ln -s ~/bin/asciidoc-{revnumber}/a2x.py ~/bin/a2x - -Use the git `pull` command to update your local AsciiDoc repository. - -Installing asciidoc for all users -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Create `configure` using 'autoconf(1)'; use `configure` to create the -`Makefile`; run 'make(1)'; build the man pages; install: - ---------------------------------------------- -$ autoconf -$ ./configure -$ make -$ sudo make install ---------------------------------------------- - -To uninstall: - ---------------------------------------------- -$ sudo make uninstall ---------------------------------------------- - - -[[X1]] -Distribution tarball installation ---------------------------------- -The distribution source tarballs can be downloaded from GitHub -releases page https://github.com/asciidoc/asciidoc-py3/releases. - -If your flavor of UNIX or Linux does not have a packaged AsciiDoc -distribution or if you prefer to install the latest AsciiDoc version -from source, use the `configure` shell script in the tarball root -directory. - -The `autoconf(1)`-generated `configure` script creates a `Makefile` -that is tailored for your system. To install: - -[subs="attributes"] - $ tar -xzf asciidoc-{revnumber}.tar.gz - $ cd asciidoc-{revnumber} - $ ./configure - $ sudo make install - -To install the documentation: - - $ sudo make docs - -To uninstall AsciiDoc: - - $ sudo make uninstall - -If Vim is installed on your system the AsciiDoc Vim syntax highlighter -and filetype detection are already installed as built into the vim runtime. - - -[[X3]] -Microsoft Windows installation ------------------------------- -AsciiDoc is developed and tested on Linux but there seem to be quite a -few people using it on Windows. To install AsciiDoc on Windows unzip -the distribution zip file contents: - -[subs="attributes"] - $ unzip asciidoc-{revnumber}.zip - -This will create the folder +asciidoc-{revnumber}+ containing the -`asciidoc.py` and `a2x.py` executables along with configuration files -and documentation. - -To generate DocBook based outputs (e.g. PDFs) you will also need a -working DocBook toolchain. Installing and configuring a DocBook -toolchain on Windows can be a challenge -- this blog post explains -http://blog.rainwebs.net/2010/02/25/how-to-create-handsome-pdf-documents-without-frustration/[How -to Create Handsome PDF Documents Without Frustration] using -http://www.cygwin.com/[Cygwin], -http://dblatex.sourceforge.net/[dblatex] and AsciiDoc. - - -Testing your installation -------------------------- -Test out asciidoc by changing to the AsciiDoc application directory -and converting the User Guide document (`./doc/asciidoc.txt`) to XHTML -(`./doc/asciidoc.html`): - - $ python3 asciidoc.py doc/asciidoc.txt - -The link:testasciidoc.html[testasciidoc] tool offers a more extensive set of -conformance tests. You can run the tests by executing this command: - - $ python3 ./tests/testasciidoc.py run - -A full battery of tests can be run from the `Makefile` script in the -distribution root directory: - - $ make test - - -[[X2]] -Prepackaged AsciiDoc installation ---------------------------------- -The following platform-specific AsciiDoc packages are available: - -*Fedora Linux*:: - AsciiDoc is included in Fedora Extras, which is available in - the default Fedora installation. To install asciidoc, execute the - following command: - - $ yum install asciidoc - -*Ubuntu / Debian*:: - AsciiDoc is included in Ubuntu / Debian package manager. To install, - execute the following command: - - $ apt install asciidoc - -*macOS Homebrew*:: - AsciiDoc has been packaged in homebrew and is installable using the - following command: - - $ brew install asciidoc - -See also link:userguide.html#X38[Packager Notes] in the 'AsciiDoc User -Guide'. diff --git a/README.md b/README.md index 8e6d322..a7572cb 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,16 @@ AsciiDoc.py is written in Python so you need a Python interpreter package manager for your OS or by downloading it from the official Python website http://www.python.org. +Additionally, you wil need: + +* DocBook XSL Stylesheets 1.76.1 +* xsltproc (libxml 20706, libxslt 10126 and libexslt 815). +* w3m 0.5.2 +* dblatex 0.3 +* FOP 0.95 + +to enable the full AsciiDoc.py toolchain. + ## Obtaining AsciiDoc.py Documentation and installation instructions are on the AsciiDoc.py website @@ -37,6 +47,20 @@ https://asciidoc.org/. Simply, you should use use pip to install it: pip3 install asciidoc ``` +## Contributing + +To contribute and test your changes, you will need to install: +* flake8 +* pytest +* pytest-mock + +To lint the codebase: `python3 -m flake8` + +AsciiDoc.py has the following types of tests: +1. doctests: `python3 -m asciidoc.asciidoc --doctest` +1. unit tests: `python3 -m pytest` +1. integration tests: `python3 tests/testasciidoc.py` + ## LICENSE Copyright (C) 2002-2013 Stuart Rackham. -- cgit v1.2.1