update contribution guidelines

CONTRIBUTING.md

@@ -2,113 +2,74 @@
 
 <PageHeader />
 
-Please note, this is a WIP!
-
-Formatting specifications for Markdown documents
-
-A typical Markdown document which will now include "PageHeader" and "PageFooter" markers. These have been commented out here:
+Zumasys writes all product documentation in [Markdown](https://www.markdownguide.org/). You can find a template [here](/assets/downloads/README.txt) or described below:
 
 ````markdown
-# ENCRYPT
+# Put Your Title Here
+
+<PageHeader />
 
-# <PageHeader />
+General description goes here. You can also include a badge tag like so:
 
 **Tags:**
 <badge text='encryption' vertical='middle' />
 
-## Description
+Other notes:
 
-This function encrypts strings. It takes the general form:
+- There should only be one `#` section in an article. 
+- Leave the `<PageHeader/>` and `<PageFooter/>` tags where they are. 
+- This file should be left as `README.md` and you should place it inside a folder that represents the article name. 
+- Any images that you want to include inline should be placed in that folder too.
 
 ```
-ENCRYPT(string, key, method)
-```
-
-Where:
-
-- **string** specifies the string to be encrypted.
-- **key** is the value used to encrypt the string. Its use depends on **method**.
-- **method** is a value which indicates the encryption mechanism to use.
-
-The **ENCRYPT** and [DECRYPT](./../decrypt) functions that are part of jBASE BASIC now support the following cipher methods (Defined in **JBC.h**)
-
-- JBASE_CRYPT_GENERAL General-purpose encryption scheme
-- JBASE_CRYPT_AES algorithm (AES256)
-- JBASE_CRYPT_AES_BASE64 algorithm (AES256, BASE64 encoded)
-- JBASE_CRYPT_ROT13 Simple ROT13 algorithm. (Key not used)
-- JBASE_CRYPT_XOR11 XOR MOD11 algorithm. Uses the first character of a key as a seed value.
-- JBASE_CRYPT_RC2 RC2 algorithm
-- JBASE_CRYPT_DES DES algorithm
-- JBASE_CRYPT_3DES Three Key, Triple DES algorithm
-- JBASE_CRYPT_BLOWFISH Blowfish algorithm
-- JBASE_CRYPT_BASE64 (See below)
-
-BASE64 is not really an encryption method, but more of an encoding. The reason for this is that the output of an encryption often results in a binary string. It allows binary data to be represented as a character string. BASE64 operation is not required but is performed in addition to the primary algorithm. e.g. JBASE_CRYPT_RC2_BASE64
-
-**ENCRYPT** with this method is the same as a [DECRYPT](./../decrypt) with method JBASE_CRYPT_RC2 followed by [DECRYPT](./../decrypt) with method JBASE_CRYPT_BASE64.
-
-[DECRYPT](./../decrypt) with this method is the same as a [DECRYPT](./../decrypt) with method JBASE_CRYPT_BASE64 followed by [DECRYPT](./../decrypt) with method JBASE_CRYPT_RC2.
-
-- JBASE_CRYPT_RC2_BASE64 RC2 algorithm
-- JBASE_CRYPT_DES_BASE64 DES algorithm
-- JBASE_CRYPT_3DES_BASE64 Triple DES algorithm
-- JBASE_CRYPT_BLOWFISH \_BASE64 Blowfish algorithm.
-
-An example of use may be as follows:
-
+* article-name (this is the folder)
+  * image1.png (an image for the article)
+  * image3.png (another image for the article)
+  * README.md (this file/the article you just made)
 ```
-INCLUDE JBC.h
 
-cipher = JBASE_CRYPT_BLOWFISH_BASE64
+If your article needs to reference a file for download like a `.docx` or a `.pdf`, please place it into the `site/.vuepress/public/assets/downloads` directory and link to it like so:
 
-key = "Thunderbirds 2086"
-str = "This is the string to be encrypted"
-enc = ENCRYPT(str, key, cipher)
+`[link-text](/assets/downloads/file-to-download.pdf)`
 
-CRT "Encrypted: " : enc
+## Descriptive Sub Section
 
-CRT "Decrypted: " : DECRYPT(enc, key, cipher)
-```
+More information here. You can have as many `##` sections as you'd like.
 
-The above will display as output:
+### Sub Sub Section
 
-```
-Encrypted: bjrngdlVNjSsY6iUVhn8pA9WD2cYo7HB8at0QhwvjvApc8Gih8PQ/A==
-Decrypted: This is the string to be encrypted
-```
-
-See also: [DECRYPT](./../decrypt).
-
-Go back to [jBASE BASIC](./../README.md)
+- You can nest `##`-`######` for up to six levels of sub-sections.
+- You can _italicize_ by wrapping text like `_italicize_` or `*italicize*`
+- You can __bold__ by wrapping text like `__bold__` or `**bold**`
+- For more commands a great cheat sheet on Markdown can be found at [https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet).
+- It is highly recommended and encouraged that you use VS Code and:
+  - [Markdown All in One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one)
+  - [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint)
 
-# <PageFooter />
+<PageFooter />
 
 ````
 
-Do:
+## How to Write Documentation
 
-1. Use mixed case for headings, except for the main heading within the main categories such as jBC, jQL.
-2. Do not use line numbers is example code, as the code blocks will automatically be numbered in Markdown.
-3. Make the code look interesting by using mixed-case variables where possible.
-4. In code examples, use “CRT” rather than “PRINT” except where it is relevant to actual printing.
-5. Highlight keywords, i.e. **string**, **key** and **method** in this case.
-6. Also highlight the statement/function plus any relevant connectors, i.e. IF, THEN, ELSE
-7. Where possible, make sure that there is a link back to the page on level up.
-8. Remove extraneous and trailing blanks, except where relevant, i.e. two spaces at the end of a line to cause a line-break.
-9. With code examples, space out the code so that people can see what is going on, i.e.:
+1. Do not use line numbers is example code, as the code blocks will automatically be numbered in Markdown.
+2. Use `backticks (``)` to format variable names (single backtick) and code blocks (triple backtick).
+3. Highlight keywords, i.e. **string**, **key** and **method** in this case.
+4. Where possible, make sure that there is a link back to the page on level up.
+5. Remove extraneous and trailing blanks, except where relevant, i.e. two spaces at the end of a line to cause a line-break.
+6. With code examples, space out the code so that people can see what is going on, i.e.:
 
-```
+``` mvbasic
 IF chr >= 32 AND chr < 128 THEN CRT CHAR(chr) "#2" : ELSE CRT " " :
 ```
 
-10. Write URLs as links with Markdown syntax.
-11. A pet peeve, please remember that it is and always has been “jBASE” and not “JBASE” or “Jbase”.
+7. Write URLs as links with Markdown syntax.
 
-Don’t:
+## How Not to Write Documentation
 
-1. SHOUT. We are trying to present a modern look and should be encouraging users to move away from everything in capital letters.
-2. Use HTML except where necessary.
-   a. Most tables can be constructed using Markdown “syntax”, although some complex tables such at those in the jBC “FMT” page (../docs/jbase/jbc/fmt/README.md) will need the assistance of some HTML code in order to appear correctly on the web page.
+1. NO SHOUTING. We are trying to present a modern look and should be encouraging users to move away from everything in capital letters.
+2. Avoid using HTML except where necessary.
+   a. Most tables can be constructed using Markdown syntax so try that first before opting for HTML tables.
    b. It is permissible to embed video content with HTML.
 
 <PageFooter />

site/.vuepress/public/assets/downloads/README.txt

@@ -0,0 +1,42 @@
+# Put Your Title Here
+
+<PageHeader />
+
+General description goes here. You can also include a badge tag like so:
+
+**Tags:**
+<badge text='encryption' vertical='middle' />
+
+Other notes:
+
+- There should only be one `#` section in an article. 
+- Leave the `<PageHeader/>` and `<PageFooter/>` tags where they are. 
+- This file should be left as `README.md` and you should place it inside a folder that represents the article name. 
+- Any images that you want to include inline should be placed in that folder too.
+
+```
+* article-name (this is the folder)
+  * image1.png (an image for the article)
+  * image3.png (another image for the article)
+  * README.md (this file/the article you just made)
+```
+
+If your article needs to reference a file for download like a `.docx` or a `.pdf`, please place it into the `site/.vuepress/public/assets/downloads` directory and link to it like so:
+
+`[link-text](/assets/downloads/file-to-download.pdf)`
+
+## Descriptive Sub Section
+
+More information here. You can have as many `##` sections as you'd like.
+
+### Sub Sub Section
+
+- You can nest `##`-`######` for up to six levels of sub-sections.
+- You can _italicize_ by wrapping text like `_italicize_` or `*italicize*`
+- You can __bold__ by wrapping text like `__bold__` or `**bold**`
+- For more commands a great cheat sheet on Markdown can be found at [https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet).
+- It is highly recommended and encouraged that you use VS Code and:
+  - [Markdown All in One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one)
+  - [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint)
+
+<PageFooter />