Instructions for Developers

This wiki is under construction; see GitHub #57

Instructions for editing wikis

Writing and editing wikis comes with two rules:

RULE 1: If a Table of Contents is deemed necessary, then use the add_toc.sh script in the wres.wiki repository. To do so, do the following:

1. Check out the wres.wiki repository and identify the markdown to which a ToC is to be added.
2. Run add_toc.sh markdown.md for the desired markdown file.
3. Review the .new version of the file that it creates. Edit as necessary.
4. Move the .new version into place.
5. Push the changes to the wres.wiki repository.

The above process needs to be repeated whenever a section header is modified, added, or deleted in a wiki with a ToC.

RULE 2: If enumerations (i.e. numbered sections) are deemed necessary, then declare an anchor for each enumerated heading, as described below, and refer to the non-enumerated anchor instead of the raw link whenever you want to refer to the section. In this way, we are able to keep section numbers out of references so that section numbers can be modified (e.g., due to new sections or reordering) without having to update every reference.

An anchor is created by using the a HTML tag and defining a name for the anchor as an attribute. For example:

<a name="what-are-the-other-capabilities-of-the-wres"></a>
# 1.1 What are the other capabilities of the WRES?

Whenever that header/section is referenced elsewhere, the anchor must be used instead of the direct header link. In the example above, the anchor link would be referenced as, ...#what-are-the-other-capabilities-of-the-wres, where ... is the wiki containing the anchor.