Skip to content

Latest commit

 

History

History
123 lines (80 loc) · 7.51 KB

README.md

File metadata and controls

123 lines (80 loc) · 7.51 KB
Raw

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:

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:

npm Commands