View in action with GitHub Pages

Renumber-Textile-References

Automatically renumber explicitly numbered references in the Textile markup language by order of their appearance in text.

Table of Contents

1. Introduction
2. Example
3. Features
4. Rationale
5. Terminology
6. Use Instructions
7. Installation
8. Configuration
9. Limitations
10. Technologies

Introduction

This project is currently designed for a <textarea> on a webpage. Click here for a live webpage using the project's functions.

Example

Before	After
h2. Section Lorem.[2][3] ipsum.[1] h2. External References fn2. First Ref fn1. Third Ref fn3. Second Ref	h2. Section Lorem.[1][2] ipsum.[3] h2. External References fn1. First Ref fn2. Second Ref fn3. Third Ref

Features

• Automatically renumber explicitly numbered Textile references by their order of appearance in text
• User formatting errors are detected and highlighted to prevent incorrect usage
• References can be placed almost anywhere in text (for limits, see Limitations)

Rationale

This project solves a problem with explicitly numbered references in the Textile markup language. When a user alters the reference order or inserts a new reference in a body of text, the references' order by appearance may be compromised. To preserve the references' order by appearance, a user may have to renumber the references manually. This project does that automatically.

Note that Textile already provides a solution to this with auto-numbered notes.

This project is suited for:

• Anyone using Textile who has text already containing explicitly numbered references
• Websites where auto-numbered notes are not supported

Terminology

This project was developed using different terminology than the Textile markup language, as seen below. This terminology may be subject to future change.

Appearance in text	Project	Textile
[1]	In-text citation / Citation	Reference
fn1. Author - "Sample Text":https://www.example.com	Reference	Footnote

Use Instructions

A live version of project can be used with GitHub Pages. The project can also be used offline by downloading or cloning it from GitHub.

Requirements

To use this project locally, Node.js and npm must be installed. See installation instructions for Node.js for details. A short video on how to install Node.js can also be viewed here.

Installation

This part assumes the requirements have been fulfilled.

1. Click the green Code button on the project's GitHub repository page and download the project as a ZIP file
2. Unzip the file
3. Open your system's terminal
4. In the terminal, navigate to the project's directory (folder). If you are unfamiliar with terminal navigation, enter cd [filePathToProjectDirectory] without the brackets in the terminal (ex: cd C:\Users\user\Downloads\Renumber-Textile-References-master\Renumber-Textile-References-master). The directory navigated to should contain the project's lib folder
5. In the terminal, enter npm install to download the npm packages required for the project

The project's HTML document opened in most browsers should work locally after these instructions.

Configuration

The project is configured by modifying the variable values in the config.js file. See configuration instructions for more details. See important details for a better understanding of how the program works.

Configuration Instructions

This part assumes the project has been downloaded or cloned. To update config.js, follow these instructions

• Locate the config.js file on your system
• Open config.js and update the variable values to the desired values (ex: referenceSection: "changeTheValueInQuotes")
• Save config.js to preserve any changes made
• See steps 3-5 from the Installation section for instructions on opening the system's terminal, navigating to the project directory, and downloading npm packages
• In terminal, enter the command npm run build (if interested, see npm commands for what this does)
• Open index.html in a browser. The webpage should use the values in config.js when updating any provided text

Important Details

• referenceSection - a variable in config.js, it is assumed to be the last heading / a unique last section in a text. The program places all references under the referenceSection after it is finished renumbering them
  • As seen in the example, referenceSection's default value is h2. External References. This can be changed by following the configuration instructions
  • All references are placed under the referenceSection, regardless of where they are in the <textarea> (for limits see limitations). Note that with the current implementation, any text after the referenceSection that is not a reference may be lost

Limitations

(Using Textile terminology): The project currently does not support references that don't link to the footnote or footnotes with a backlink.

Compatibility with Internet Explorer is untested.

Bugs

To view inputs known to cause errors, open testCases.yaml and search for "Failing" without quotes.

Technologies

Technologies used for this project include:

• Node.js as a runtime environment
• npm for package management
• Jest for testing
• webpack for bundling
• Visual Studio Code for development

npm Commands

• npm install - install the required packages for the project
• npm run build - updates bundle.js to use the latest versions of the renumberReferences.js, renumberTextarea.js, and config.js files. index.html will use the updated version of bundle.js
• npm test - run the tests for the project with Jest