# presciidoc (WIP)

Preprocessing AsciiDoc for other tools.

The goal of this program is to partially parse an AsciiDoc file, remove certain non-paragraph elements, and present the document as a syntax tree. Other tools can later analyze or further process the representation.

**Warning:** This tool is a work in progress and an experiment. It cannot parse the vast majority of AsciiDoc syntax.

## Installation

You can install `presciidoc` on various operating systems using several package managers.

### Fedora and CentOS Stream

1. Enable the Copr repository:

    ```
    # dnf copr enable mareksu/presciidoc
    ```

2. Install `presciidoc`:

    ```
    # dnf install presciidoc
    ```

    The Copr repository distributes packages only for *supported* releases of Fedora. If you have enabled the repository but the package fails to install, check if your Fedora is still supported.

### From source on any platform

1. Install the Rust toolchain: see <https://rustup.rs/>.

2. Install `presciidoc`:

    ```
    $ cargo install --git https://github.com/msuchane/presciidoc.git
    ```

## Usage

`presciidoc` reads a single AsciiDoc file, either from the specified file path or from the standard input (`stdin`) if you provide no file.

* By default, it performs no actions on the document and prints it back to the terminal (`stdout`). For example:

    ```
    $ presciidoc proc_configuring-thing.adoc
    
    // The document starts here.
    [id="configuring-thing"]
    = Configuring thing
    
    ////
    Enter a module introduction here.
    ////
    An introduction...
    ```

* You can use the `--no-comments` (`-c`) option to remove all line comments and comment blocks. `presciidoc` replaces them with blank lines so that all line numbers still match the original file:

    ```
    $ presciidoc --no-comments proc_configuring-thing.adoc
    
    
    [id="configuring-thing"]
    = Configuring thing
    
    
    
    
    An introduction...
    ```

* To remove the comments completely, rather than replacing them, add the `--remove-lines` (`-r`) option:

    ```
    $ presciidoc --no-comments --remove-lines proc_configuring-thing.adoc
    
    [id="configuring-thing"]
    = Configuring thing
    
    An introduction...
    ```

* To calculate how many lines in the file are comments or literals, use the `--fraction` (`-f`) option. This calculates the percentage of the lines that would otherwise get removed:

    ```
    $ presciidoc --no-comments --fraction proc_configuring-thing.adoc

    27.8%
    ```

* To save the changes, you can overwrite the original file or create a new file by redirecting the output:

    ```
    $ presciidoc -c -r proc_configuring-thing.adoc > modified.adoc
    
    [id="configuring-thing"]
    = Configuring thing
    
    An introduction...
    ```