https://github.com/numberfour/asciispec
asciispec
https://github.com/numberfour/asciispec
Last synced: 29 days ago
JSON representation
asciispec
- Host: GitHub
- URL: https://github.com/numberfour/asciispec
- Owner: NumberFour
- Created: 2017-01-03T13:44:03.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2019-01-23T10:32:30.000Z (over 7 years ago)
- Last Synced: 2025-03-03T11:35:46.847Z (over 1 year ago)
- Language: Java
- Homepage: https://numberfour.github.io/asciispec
- Size: 29.1 MB
- Stars: 1
- Watchers: 8
- Forks: 2
- Open Issues: 12
-
Metadata Files:
- Readme: README.adoc
Awesome Lists containing this project
README
ifdef::env-github,env-browser[:outfilesuffix: .adoc]
A documentation toolchain based on http://asciidoctor.org/[AsciiDoctor]. It implements custom processors for technical writing, organizing documentation and task management.
== Features
*<>*: Add definitions with custom formatting. +
*<>*: Includes files using special variables. +
*<>*: Inserting links to Confluence Wiki pages. +
*<>*: Insert links to Jira and GitHub. +
*<>*: Inserting citations from a BibTeX file. +
*<>*: Inserting links to source files on GitHub. +
*<>*: Inserting math expressions. +
*<>*: Add long math formulae. +
*<>*: Add requirements with custom formatting. +
*<>*: Add a custom TODO admonition block. +
*<>*: Arbitrarily add numbered callouts.
== Prerequisites
* http://maven.apache.org/[Apache Maven]
* https://github.com/asciidoctor/asciidoctorj/tree/asciidoctorj-1.6.0[asciidoctorj-1.6.0]. There is no artifact publicly available at the moment. Please follow these steps:
.. Checkout https://github.com/asciidoctor/asciidoctorj/tree/asciidoctorj-1.6.0[asciidoctorj-1.6.0]
.. Navigate to the root of the asciidoctorj-1.6.0 project and run `./gradlew assemble`
.. Install the dependency to your local maven repository by running
[source,bash]
mvn install:install-file -Dfile=./asciidoctorj-core/build/libs/asciidoctorj-1.6.0-SNAPSHOT.jar -DgroupId=org.asciidoctor -DartifactId=asciidoctorj -Dversion=1.6.0-SNAPSHOT -Dpackaging=jar
* https://github.com/kduske-n4/snuggletex[snuggletex-1.2.3]. This is a custom fork of http://www2.ph.ed.ac.uk/snuggletex[SnuggleTex] that supports a few more LaTeX symbols in math expressions. Please follow these steps:
.. Checkout https://github.com/kduske-n4/snuggletex[snuggletex-1.2.3] and switch to branch `enfore`.
.. Navigate to the root of the snuggletex project and run `mvn package`
.. Install the dependency to your local maven repository by running
[source,bash]
mvn install:install-file -Dfile=./snuggletex-core/target/snuggletex-core-1.2.2.jar -DgroupId=uk.ac.ed.ph.snuggletex -DartifactId=snuggletex-core -Dversion=1.2.3-SNAPSHOT -Dpackaging=jar
Once installed, remember to update the project dependencies within your IDE. In Eclipse you can do this by right clicking on the project -> Maven -> Update Project. That should resolve dependency related errors.
To import Asciispec into Eclipse, install the m2e plugin and use the project import wizard.
== Build
To build the project, clone this repository, navigate to the project folder and run the following command (optionally add `-Dmaven.test.skip=true` to skip tests):
[source,bash]
mvn clean package
After maven has successfully finished building the project, a zip file containing the asciispec tool will be available under `asciispec/target/asciispec-bin.zip`
[.language-bash]
== Installation
Add AsciiSpec to your shell profile with the path to the `asciispec/bin` directory on your system:
`pass:[export PATH=$PATH:~/path/to/asciispec/bin/]`
If the AsciiSpec tool is found by your system, running AsciiSpec with the `-h` flag will print a help page:
[source,bash]
asciispec -h
== Usage
=== Convert to HTML
Generates a `sample.html` file in the current directory:
[source,bash]
asciispec sample.adoc
=== Convert to DocBook:
Generates a `sample.xml` file in the current directory.
[source,bash]
asciispec -b docbook sample.adoc
DocBook format can be further converter to *PDF* with https://github.com/NumberFour/asciidoctor-fopub[asciidoctor-fopub]. This fork of the fopub project contains some cosmetic changes.
=== Help
Running `asciispec -h` will print the AsciiDoctor help page. +
For more options, see the http://asciidoctor.org/docs/user-manual/#cli-options[CLI Options] section of the AsciiDoctor user manual.
== Documentation
[horizontal]
HTML Documentation:: *http://numberfour.github.io/asciispec*
Userguide:: https://numberfour.github.io/asciispec/userguide.html[Userguide]: Introduction to AsciiDoc syntax and some basic AsciiSpec usage tips.
Other:: *<>*: Help for getting started and debugging installation errors.